3. Liity testiympäristöön

Kuva: Liity testiympäristöön -vaihe

Näytä kuva suurempana

Organisaatiosi tulee liittyä Palveluväylän testiympäristöön ennen kuin voitte siirtyä tuotantoympäristöön. Testiympäristöön liittyminen koostuu käyttölupahakemuksen lähettämisestä ja teknisestä liittymisprosessista, jonka organisaatiosi voi halutessaan ulkoistaa valitsemalleen teknisten ratkaisujen tarjoajalle.

Huomaa, että tarvitset testi- ja tuotantoympäristöihin erilliset liityntäpalvelimet. Suosittelemme, että testi- ja tuotantoympäristösi tekniset toteutukset ovat vastaavanlaiset, eli esimerkiksi liityntäpalvelin on toteutettu samalla tavalla molempiin ympäristöihin. Lue lisää liityntäpalvelinratkaisun suunnittelusta ja käyttöönotosta edellisistä osioista.

Tässä osiossa ohjeistetaan testiympäristöön liittymisen vaiheet:

1. Hallinnollinen henkilö lähettää käyttölupahakemuksen testiympäristöön.
2. Avaa palomuurit aiemmin saamiesi ohjeiden mukaan.
3. Asenna liityntäpalvelinohjelmisto. Liityntäpalvelimen asennuksen ohjeistus riippuu palvelimesi käyttöjärjestelmästä. Tämän jälkeen alustapalvelimesta tulee liityntäpalvelin, jolla yhdistät tietojärjestelmäsi Palveluväylään.
4. Määrittele liityntäpalvelin. Määrittelyn voi tehdä ohjelmallisesti tai manuaalisesti.
5. Lisää liityntäpalvelimelle alijärjestelmä. Alijärjestelmä toimii rajapintana Palveluväylään tiedon hakemista ja jakamista varten.
6. Liitä asiakasjärjestelmä liityntäpalvelimelle. Näin tieto siirtyy tietojärjestelmistäsi Palveluväylälle ja toisin päin.
7. Jos tarjoat palveluita muille organisaatioille Palveluväylässä, lisää palvelusi liityntäpalvelimelle. Palvelut lisätään jollekin aiemmin lisätylle alijärjestelmälle.
8. Jos tarjoat palveluita muille organisaatioille Palveluväylässä, ota sovitinpalvelu tarvittaessa käyttöön. Tarvitset sovitinpalvelun, jos tarjoat Palveluväylän kautta SOAP-palveluita, joita ei ole räätälöity Palveluväylän vaatimusten mukaisiksi.
9. Hallinnollinen henkilö kuvailee organisaation sekä mahdolliset palvelut Testiliityntäkatalogiin.

HUOM! Teknisen liittymisprosessin (vaiheet 2–8) tekee joko teknisten ratkaisujen tarjoaja tai oma organisaatiosi, riippuen siitä oletko ulkoistanut liityntäpalvelinratkaisun vai et. Jos käytät jaettua liityntäpalvelinta, voit ohittaa vaiheet 2–4.

1. Hallinnollinen henkilö lähettää käyttölupahakemuksen testiympäristöön

Kun liityntäpalvelinratkaisu on valittu sekä alustapalvelin on asennettu ja määritelty, organisaatiosi hallinnollinen vastuuhenkilö lähettää sähköisen käyttölupahakemuksen Digi- ja väestötietovirastolle. Tarkista siis, että seuraavat asiat on tehty:

1. Liityntäpalvelin on nimetty ohjeiden mukaisesti.

• Katso ohjeet liityntäpalvelimen nimeämiseen

2. Liityntäpalvelimelta löytyy RHEL 7, RHEL 8 tai Ubuntu 18.04 LTS, Ubuntu 20.04 LTS -käyttöjärjestelmä tai kontitetun liityntäpalvelimen tapauksessa jokin Linux-alusta, jolle on asennettu Docker.

• Lue RHEL-liityntäpalvelimen asentamisesta
• Lue Ubuntu-liityntäpalvelimen asentamisesta
• Lue kontitetusta liityntäpalvelinvaihtoehdosta

Kun käyttölupahakemus on hyväksytty, organisaatiosi tekninen yhteyshenkilö saa sähköpostitse asennusohjeet testiympäristöön liittymistä varten. Ohjeet tulevat käyttölupahakemuksessa ilmoitettuun sähköpostiosoitteeseen osoitteesta palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan.. Saat sähköpostitse seuraavat materiaalit:

• Konfiguraatioankkuri
• Palomuurien avausohjeet
• Ohjeet liityntäpalvelinohjelmiston asentamiseen (näihin löydät linkit myös tästä ohjeesta): Sovelluskomponenttien lisenssit

2. Avaa palomuurit

Avaa saamiesi ohjeiden perusteella tarvittavat portit palvelimeltasi, jotta yhteydet Palveluväylään toimivat. Tietoturvan kannalta on erittäin tärkeää, että vain tietyt portit ovat auki oikeisiin suuntiin. Tietoturvasyistä Palveluväylän ylläpito lähettää sinulle ohjeet porttien avaamiseen sähköpostitse. Ohjeet lähetetään käyttölupahakemuksessa ilmoitetulle tekniselle yhteyshenkilölle. Tarvittaessa voit saada ohjeet palomuuriavauksiin jo ennen käyttölupahakemuksen lähettämistä. Ota tällöin yhteyttä Palveluväylän ylläpitoon osoitteessa palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..

Katso ohjevideo muurienavausvaiheesta (Youtube)Avautuu uuteen ikkunaan..

Avattavat portit:

• Oma tietokone –portti 22 → liityntäpalvelin (oma), tietojärjestelmä (oma) [komentoriviyhteys]
• Oma tietokone –portti 4000 → liityntäpalvelin (oma) [graafinen hallintayhteys]
• Tietojärjestelmä (oma) ← portit 80,443 → liityntäpalvelin (oma) [Palveluväylästä tulevan tiedon hakua varten]
• Liityntäpalvelin (oma) –portit 80,4001 → Central Server Global Conf [keskuspalvelinyhteys 1]
• Liityntäpalvelin (oma) ← portit 5500,5577 → Central Server Global Conf [keskuspalvelinyhteys 2]
• Liityntäpalvelin (oma) –portti 80 → Central Server Global Conf [federointia varten keskuspalvelinyhteys 3]
• Liityntäpalvelin (oma) –portti 80 → OCSP Service [OCSP-yhteys]
• Liityntäpalvelin (oma) –portit 80,443 → Timestamping Service [TSA-yhteys]
• Liityntäpalvelin (oma) –portit 5500,5577 → Kohdeverkon liityntäpalvelin [getRandom testipalvelua varten]

3. Asenna liityntäpalvelinohjelmisto

Asenna liityntäpalvelinohjelmisto alustapalvelimellesi ohjeiden mukaan. Alustapalvelimesta tulee tämän jälkeen liityntäpalvelin, jonka liität Palveluväylän testiympäristöön. Asennusvaiheet riippuvat osittain käytetystä käyttöjärjestelmästä.

Katso ohjeet:

• Liityntäpalvelinohjelmiston asennusohjeet RHEL-käyttöjärjestelmälle
• Liityntäpalvelinohjelmiston asennusohjeet Ubuntu-käyttöjärjestelmälle
• Kontitetun liityntäpalvelimen (Docker) asennusohjeet

Katso ohjevideo liityntäpalvelinohjelmiston asentamisesta (Youtube)Avautuu uuteen ikkunaan..

4. Määrittele liityntäpalvelin

Asennuksen jälkeen sinulla on liityntäpalvelin, joka on valmis konfiguroitavaksi. Voit määritellä liityntäpalvelimen ohjelmallisesti automaattisilla hallintaskripteillä (X-Road Toolkit) tai manuaalisesti graafisen käyttöliittymän tai hallintarajapinnan kautta.

Ohjelmallinen konfigurointi automaattisilla hallintaskripteillä

X-Road Toolkitilla määrittelet yhden tai useamman liityntäpalvelimen automaattisesti skriptien avulla. Toolkitin haluttu toiminta ja tiedot määritellään YAML-konfiguraatiotiedostoon. Konfiguraation voi ajaa kahdessa osassa tai vaiheittain. Lue lisää X-Road Toolkitista.

Manuaalinen konfigurointi graafisessa hallintakäyttöliittymässä

Ota selaimella yhteys graafiseen hallintakäyttöliittymään osoitteella:

https://{hostname}:4000

Korvaa {hostname} asennetun liityntäpalvelimen nimellä.

Sait Palveluväylän ylläpidolta sähköpostitse ympäristökohtaisen konfiguraatiotiedoston, eli konfiguraatioankkurin. Seuraa sivua Liityntäpalvelimen liittäminen testi- tai tuotantoympäristöön ja tee seuraavat asiat ohjeen mukaan. Muista seurata testiympäristön (FI-TEST) ohjeita.

Katso ohjevideo liityntäpalvelimen konfiguroimisesta (Youtube)Avautuu uuteen ikkunaan..

1. Kirjaudu sisään liityntäpalvelinohjelmiston asennuksen yhteydessä luomallasi pääkäyttäjätunnuksella.
2. Asenna konfiguraatioankkuri (tukiartikkelin kohta: ”Palvelimen perusasetusten määrittely”).
3. Täytä avautuvaan ikkunaan seuraavat tiedot:
   Member Code: organisaatiosi Y-tunnus.
   Member Name: organisaatiosi nimi. Järjestelmän pitäisi täydentää tämä automaattisesti.
   Security Server Code: liityntäpalvelimen yksilöivä tunnus, tyypillisesti palvelimen nimen host-osa.
   PIN: vapaavalintainen koodi, jonka pituus on vähintään 10 merkkiä.
4. Lisää aikaleimapalvelu (TSA-palvelu): System Parameters > Timestamping Services > Add. Valitse käyttöliittymän ehdottama liityntäympäristön TSA-palvelu.
5. Luo allekirjoitusvarmennepyyntö: Keys and Certificates > Add Key. Täytä seuraavat tiedot:
   Usage: SIGNING
   Client: Y-tunnuksen perusteella oma organisaatiosi
   Certification Service: G2R
   CSR Format: PEM
6. Luo autentikointivarmennepyyntö: Keys and Certificates > Add Key. Täytä seuraavat tiedot:
   Usage: AUTHENTICATION
   Certification Service: G2R
   CSR Format: PEM
7. Lähetä luomasi allekirjoitus- ja autentikointivarmennepyynnöt Palveluväylän ylläpidon tarkistettavaksi ennen varsinaisten varmennehakemusten tekemistä. Lue tarkemmat ohjeet sivulta Liityntäpalvelimen liittäminen testi- tai tuotantoympäristöön (ks. kohta 3.3 Varmennepyyntöjen käsittely).
8. Asenna allekirjoitetut varmenteet: Keys and Certificates > Import Certificate.
9. Aktivoi autentikointivarmenne valitsemalla Activate.
10. Rekisteröi autentikointivarmenne valitsemalla Register.

Palveluväylän ylläpito hyväksyy rekisteröinnin yleensä noin yhdessä vuorokaudessa. Tarkista seuraavana arkipäivänä liityntäpalvelimen hallinnointikäyttöliittymästä, onko rekisteröinti valmis. Saat sähköpostivahvistuksen, kun rekisteröinti on valmis, mutta saat tiedon rekisteröinnin tilasta nopeammin liityntäpalvelimen hallintakäyttöliittymästä.

Olet nyt liittänyt liityntäpalvelimesi Palveluväylän testiympäristöön onnistuneesti.

Liityntäpalvelimen muistiasetusten muuttaminen

Muuta myös tarvittaessa liityntäpalvelimesi muistiasetuksia. Liityntäpalvelimen muistiasetukset riippuvat liityntäpalvelimen alustakoneen keskusmuistin koosta.

Lue liityntäpalvelimen suositelluista muistiasetuksista ja niiden muuttamisesta.

5. Lisää liityntäpalvelimelle alijärjestelmä

Lisää liityntäpalvelimelle ainakin yksi alijärjestelmä, joka mahdollistaa tiedonsiirron Palveluväylässä. Alijärjestelmä toimii rajapintana Palveluväylään tiedon hakemista ja jakamista varten.

Suosittelemme käyttämään lähtökohtaisesti asiakasjärjestelmäkohtaisia alijärjestelmiä. Asiakasjärjestelmällä tarkoitetaan organisaatiosi tietojärjestelmää, johon liityntäpalvelin yhdistetään, jotta tietojärjestelmän sisältämiä tietoja voidaan jakaa Palveluväylään tai ladata Palveluväylästä tietojärjestelmään. Joissain tapauksissa myös useat, yhden loogisen kokonaisuuden muodostavat asiakasjärjestelmät voivat hyödyntää samaa alijärjestelmää palvelujen kutsumiseen. Jos toimit palveluntarjoajana Palveluväylässä, suosittelemme, että sinulla on yksi alijärjestelmä jokaista tarjoamaasi palvelua kohden.

Lisää alijärjestelmä liityntäpalvelimen hallintakäyttöliittymän kautta. Seuraa Uuden alijärjestelmän liittäminen liityntäpalvelimeen ja sen poistaminen -sivun ohjeistusta.

6. Liitä asiakasjärjestelmä liityntäpalvelimelle

Kun liityntäpalvelin ja alijärjestelmät ovat kunnossa, liitä asiakasjärjestelmäsi liityntäpalvelimelle. Asiakasjärjestelmän liittäminen liityntäpalvelimeen tapahtuu liityntäpalvelimelle luomasi alijärjestelmän kautta. Tee liittäminen liityntäpalvelimen hallintakäyttöliittymässä. Seuraa Asiakasjärjestelmän liittäminen liityntäpalvelimeen -sivun ohjeistusta.

Katso ohjevideo asiakasjärjestelmän liittämisestä ja alijärjestelmän toiminnan testaamisesta (Youtube)Avautuu uuteen ikkunaan..

Suorita vaiheet 1 ja 2 jollakin muulla palvelimella kuin liityntäpalvelimellasi.

1. Luo asiakasjärjestelmän yksityinen avain komentorivikäyttöliittymässä seuraavalla komennolla: openssl genrsa -out clientprivatekey.pem 2048
2. Luo avaimelle ns. self-signed-varmenne seuraavalla komennolla: openssl req -new -x509 -key clientprivatekey.pem -out clientcert.pem -days 365
3. Kirjaudu sisään liityntäpalvelimen hallintakäyttöliittymään, ja valitse Internal Servers sen alijärjestelmän kohdalta, johon haluat liittää asiakasjärjestelmän.
4. Valitse asiakasjärjestelmän ja liityntäpalvelimen välisen yhteyden tyyppi Connection type for Servers in Service Consumer Role -valikosta. Käytä aina HTTPS-protokollaa, jotta yhteys asiakasjärjestelmän ja liityntäpalvelimen välillä on salattu. Protokolla edellyttää, että asiakasjärjestelmän on esitettävä asiakasvarmenne käyttääkseen palveluitasi. HTTPS-asetuksen ja asiakasvarmenteiden käyttö on pakollista aina, kun useat eri organisaatiot käyttävät samaa liityntäpalvelinta. Tällaisessa tilanteessa asiakasvarmenteen käyttö on ainoa tapa estää organisaatioita kutsumasta Palveluväylän palveluita toistensa alijärjestelmien kautta.
5. Lisää liityntäpalvelimelle HTTPS-protokollan vaatima asiakasvarmenne, joka on tallennettu luomaasi clientcert.pem-tiedostoon Internal TLS Certificates > Add.
6. Lataa alijärjestelmälle liityntäpalvelimen sisäinen varmenne valitsemalla Security Server Certificate > Export.

Voit testata asiakasvarmenteen helposti kutsumalla getRandom-testipalvelua Curl-ohjelman avulla. Huomaa, että tämä testaus täytyy suorittaa jollakin muulla palvelimella kuin liityntäpalvelimella. Löydät ohjeet testaukseen Asiakasjärjestelmän liittäminen liityntäpalvelimeen -sivulta Asiakasvarmenteen testaaminen -otsikon alta.

Kutsu getRandom-testipalvelua sillä alijärjestelmällä, jonka alle lisäsit asiakasvarmenteen Curl-komennolla:

curl -E ./clientcert.pem --key ./clientprivatekey.pem -k -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://{host}/

Jos asiakasvarmenne toimii oikein, kutsu palauttaa satunnaisesti generoidun luvun väliltä 0-100.

7. Jos tarjoat palveluita muille organisaatioille Palveluväylässä, lisää palvelusi liityntäpalvelimelle

Jos olet palveluntarjoaja, sinun täytyy lisätä palvelusi liityntäpalvelimelle. Kun olet lisännyt liityntäpalvelimellesi alijärjestelmän ja se on rekisteröity, lisää sen alle uusi palvelu liityntäpalvelimen hallintakäyttöliittymän kautta. Seuraa Uuden palvelun lisääminen liityntäpalvelimelle -sivun ohjeistusta.

Voit lisätä kahdenlaisia palveluja:

• SOAP-palvelu: Palvelu lisätään antamalla WSDL-kuvauksen URL-osoite.
• REST-palvelu: Palvelu lisätään antamalla: OpenAPI 3 Description -polku tai REST API Base Path -polku.

Lisää SOAP-palvelu

1. Valitse Clients-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.
2. Lisää WSDL-kuvaus Services-välilehdeltä valitsemalla Add SOAP.
3. Anna WSDL-kuvauksen URL-osoite. Lisää palvelu valitsemalla Add. Yksittäinen WSDL-kuvaus voi sisältää yhden tai useamman palvelun rajapintakuvauksen.
4. Aktivoi WSDL-kuvaus sen kohdalla olevasta valintakytkimestä.
5. Määrittele palvelun yhteysasetukseksi HTTPS-protokolla. Löydät ohjeet yllä mainitusta tukiartikkelista Palvelun yhteysasetukset -otsikon alta.
6. Katso seuraavana päivänä, että palvelu on näkyvillä testiliityntäkatalogissaAvautuu uuteen ikkunaan.. Jos palvelua ei ole Liityntäkatalogissa, tarkista että kaikki edelle mainitut vaiheet on tehty ja pyydä tarvittaessa apua palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..

Lisää REST-palvelu

1. Valitse Clients-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.
2. Lisää REST-palvelu Services-välilehdeltä valitsemalla Add REST.
3. Valitse osoitepolun tyypiksi joko REST API Base Path tai OpenAPI 3 Description. Anna URL-osoite ja palvelun nimi (service code). Lisää palvelu valitsemalla Add.
4. Aktivoi REST-palvelu sen kohdalla olevasta valintakytkimestä. Varmista ennen aktivointia, että palvelun tiedot ovat oikein. Aktivoinnin jälkeen palvelu on käyttäjien saatavilla.
5. Katso seuraavana päivänä, että palvelu on näkyvillä testiliityntäkatalogissaAvautuu uuteen ikkunaan.. Jos palvelua ei ole Liityntäkatalogissa, tarkista että kaikki edelle mainitut vaiheet on tehty ja pyydä tarvittaessa apua palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..

Palveluiden käyttöoikeudet

Määrittele palvelun käyttöoikeudet niille organisaatioille, jotka saavat hyödyntää tarjoamaasi palvelua. Voit lisätä käyttöoikeuksia myös myöhemmin samasta valikosta.

1. Valitse palvelu ja sen jälkeen Access Rights.
2. Valitse Add Subjects ja valitse avautuvasta näkymästä alijärjestelmä, jolle haluat antaa käyttöoikeuden palveluun.

8. Jos tarjoat palveluita muille organisaatioille Palveluväylässä, ota sovitinpalvelu tarvittaessa käyttöön

Arvioi jo ennen käyttöönottoprosessin aloittamista, tarvitseeko organisaationne sovitinpalvelua.

Tarvitset sovitinpalvelun

• aina kun tarjoat Palveluväylän kautta SOAP-palveluita, joita ei ole luotu erikseen Palveluväylää varten Palveluväylän asettamia vaatimuksia noudattaen
• jos organisaatiosi ei käytä REST-rajapintoja tiedonsiirtoon

Et siis tarvitse sovitinpalvelua, jos SOAP-palvelu on suunniteltu Palveluväylää varten ja organisaatioisi käyttää REST-rajapintoja tiedonsiirtoon. Lue lisää eri toteutusvaihtoehdoista Palveluväylän sovitinpalvelu -sivulta. Tutustu vaihtoehtoihin ja toteuta sovitinpalvelu itsellesi sopivimmalla tavalla.

9. Hallinnollinen henkilö kuvailee organisaation sekä mahdolliset palvelut Testiliityntäkatalogiin

Hallinnollinen henkilö kuvailee lopuksi organisaatiosi sekä palveluidesi tiedot Testiliityntäkatalogiin. Palvelun kuvaukseen tarvitaan vähintään seuraavat tiedot:

• Mitä tietoja palvelun kautta voi saada käyttöönsä
• Mitä edellytyksiä ja rajoituksia palvelun käytössä on
• Miten palvelun saa käyttöönsä: käyttöönottoprosessi ja käyttöluvat

Huomioi asennuksen jälkeen

Säilytä yhteys testiympäristöön myös tuotantoympäristöön liittymisen jälkeen, jotta voit jatkossakin käyttää sitä uusien palvelujen ja yhteyksien testaamiseen. Lisäksi jos tuotantoympäristöön siirtyessä esiintyy ongelmia, voit verrata toteutusta testiympäristön toteutukseen ja mahdollisesti selvittää ongelman syyn tällä tavoin.

Kun olet liittänyt organisaatiosi testiympäristöön, varmista yhteyksiä testaamalla, että Palveluväylään liittyminen onnistui. Lue lisää testaamisesta seuraavasta osiosta.

Siirry seuraavaan vaiheeseen