Siirry suoraan sisältöön.
Suomi.fi-palveluväylä

5. Siirry tuotantoympäristöön

Käytyäsi läpi tämän osion olet

  • valmistellut uuden liityntäpalvelimen käyttöönoton
  • käyttölupahakemuksen hyväksymisen jälkeen saanut asennusohjeet tuotantoympäristöön
  • avannut palomuurit
  • asentanut liityntäpalvelinohjelmiston
  • määritellyt liityntäpalvelimen
  • lisännyt liityntäpalvelimelle alijärjestelmän
  • liittänyt asiakasjärjestelmän liityntäpalvelimelle
  • lisännyt tarjoamasi palvelut liityntäpalvelimelle
  • ottanut tarvittaessa sovitinpalvelun käyttöön

Siirry tuotantoympäristöön -vaihe

Tuotantoympäristöön liitytään samalla tavalla kuin testiympäristöön. Tuotantoympäristöön siirtyminen koostuu käyttölupahakemuksen lähettämisestä ja teknisestä liittymisprosessista, jonka organisaatiosi voi halutessaan ulkoistaa valitsemalleen teknisten ratkaisujen tarjoajalle. 

Tuotantoympäristöä varten tarvitset uuden liityntäpalvelimen. Suosittelemme, että tuotantoympäristösi tekninen toteutus vastaa testiympäristöä, eli esimerkiksi liityntäpalvelin on toteutettu samalla tavalla molempiin ympäristöihin. Älä siis poista liityntäpalvelintasi tai palveluitasi testiympäristöstä. Jos tuotantoympäristöön siirryttäessä esiintyy ongelmia, voit verrata toteutusta testiympäristön toteutukseen ja mahdollisesti selvittää ongelman syyn tällä tavoin. 

Tuotantoympäristöön voi siirtyä, kun:

  1. hallinnollinen henkilö on lähettänyt käyttölupahakemuksen tuotantoympäristöön,
  2. olet liittynyt onnistuneesti Palveluväylän testiympäristöön ja
  3. olet testannut, että palvelusi toimivat testiympäristössä ongelmitta. 

Tässä osiossa ohjeistetaan seuraavat tuotantoympäristöön liittymisen vaiheet: 

  1. Valmistele liityntäpalvelimen käyttöönotto
  2. Hallinnollinen henkilö lähettää käyttölupahakemuksen tuotantoympäristöön.
  3. Avaa palomuurit aiemmin saamiesi ohjeiden mukaan.
  4. 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.
  5. Määrittele liityntäpalvelin. Määrittelyn voi tehdä ohjelmallisesti tai manuaalisesti.
  6. Lisää liityntäpalvelimelle alijärjestelmä. Alijärjestelmä toimii rajapintana Palveluväylään tiedon hakemista ja jakamista varten.
  7. Liitä asiakasjärjestelmä liityntäpalvelimelle. Näin tieto siirtyy tietojärjestelmistäsi Palveluväylälle ja toisin päin.
  8. Jos tarjoat palveluita muille organisaatioille Palveluväylässä, lisää palvelusi liityntäpalvelimelle. Palvelut lisätään jollekin aiemmin lisätylle alijärjestelmälle.
  9. 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.
  10. Hallinnollinen henkilö kuvailee organisaation sekä mahdolliset palvelut Liityntäkatalogiin.

Vaiheista 2 ja 10 vastaa hallinnollinen henkilö, muut vaiheet kuuluvat tekniseen liittymisprosessiin. Jos käytät jaettua liityntäpalvelinta, voit ohittaa vaiheet 1 sekä 3–5.

1. Valmistele liityntäpalvelimen käyttöönotto

Tarvitset erillisen liityntäpalvelimen jokaiseen ympäristöön. Aloita siis tuotantoympäristöön siirtyminen valmistelemalla uuden liityntäpalvelinratkaisun käyttöönotto. Suosittelemme, että käytät samanlaista liityntäpalvelinta sekä testi- että tuotantoympäristössä. 

Liityntäpalvelinratkaisun valinta on ohjeistettu tarkemmin vaiheessa 2.

2. Hallinnollinen henkilö lähettää käyttölupahakemuksen tuotantoympä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.

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.

Kun käyttölupahakemus on hyväksytty, käyttölupahakemuksessa ilmoitettu tekninen yhteyshenkilö saa sähköpostitse asennusohjeet tuotantoympä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

3. 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]

4. Asenna liityntäpalvelinohjelmisto

Asenna liityntäpalvelinohjelmisto alustapalvelimellesi ohjeiden mukaan. Asennusvaiheet riippuvat osittain käytetystä käyttöjärjestelmästä. Katso ohjeet alla olevista linkeistä. 

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

5. 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 tuotantoympäristön (FI) 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 (katso sivun Liityntäpalvelimen liittäminen testi- tai tuotantoympäristöön 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: G5R
    CSR Format: PEM
  6. Luo autentikointivarmennepyyntö: Keys and Certificates > Add Key. Täytä seuraavat tiedot:
    Usage: AUTHENTICATION
    Certification Service: G5R
    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 tuotantoympä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.

6. 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 -tukiartikkelin ohjeistusta. 

7. 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 -tukiartikkelin 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.

8. 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 Asiakasjärjestelmän liittäminen liityntäpalvelimeen -sivulta Palvelun yhteysasetukset -otsikon alta.
  6. Katso seuraavana päivänä, että palvelu on näkyvillä Liityntä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ä Liityntä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.

9. 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 organisaatiosi käyttää REST-rajapintoja tiedonsiirtoon. Lue lisää eri toteutusvaihtoehdoista Palveluväylän sovitinpalvelu -sivulta. Tutustu vaihtoehtoihin ja toteuta sovitinpalvelu itsellesi sopivimmalla tavalla.

10. Hallinnollinen henkilö kuvailee organisaation sekä palvelut Liityntäkatalogiin

Hallinnollinen henkilö kuvailee lopuksi organisaationne sekä mahdollisten palveluidenne tiedot LiityntäkatalogiinAvautuu uuteen ikkunaan.. 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 

Voit nyt aloittaa Palveluväylän tuotantokäytön.

Muista myös huolehtia liityntäpalvelimesi ja tietojesi ylläpidosta.

Päivitetty: 6.5.2026

Oletko tyytyväinen tämän sivun sisältöön?