Tekninen yleiskuvaus
Suomi.fi-palveluväylä on tiedonvälityskokonaisuus, jolla palveluun liittyneet organisaatiot voivat siirtää tietoa tietojärjestelmiensä välillä. Palveluväylän tiedonvälitys perustuu alun perin Virossa toteutettuun X-Road-teknologiaan ja sen uusimpaan versioon 7.
Palveluväylässä tiedot liikkuvat salattuna julkisessa internetissä. Tietojen välitys perustuu erillisiin, fyysisiin tai virtuaalisiin liityntäpalvelimiin. Tiedot salataan tiedonsiirron ajaksi TLS (SSL) -salausprotokollalla, ja kaikki tieto allekirjoitetaan varmenteilla. X-Road-ohjelmistossa liityntäpalvelinten rajapintatoteutuksessa käytetään XML-kieleen pohjautuvaa SOAP (Simple Object Access Protocol) -tietoliikenneprotokollaa tai REST-arkkitehtuuria.
Lue lisää Palveluväylästä palveluna.
Lue lisää X-Road teknologiasta (englanniksi)Avautuu uuteen ikkunaan..
Viestinvälitys Palveluväylässä
X-Road-ohjelmiston keskeinen komponentti on liityntäpalvelin, joka on fyysinen tai virtuaalinen palvelin. Liityntäpalvelimen avulla liittyvän organisaation järjestelmät liitetään Palveluväylään. Kaikki Palveluväylään lähetettävät tai sieltä vastaanotettavat sanomat kulkevat liityntäpalvelimien kautta ja siksi jokainen liittyvä organisaatio tarvitsee liityntäpalvelimen. Se vastaa muun muassa palvelukutsujen välittämisestä järjestelmien välillä, palvelukutsujen varmennekättelystä, tietoliikenteen ja sanomien salauksesta sekä lokituksesta ja käyttöoikeuksien hallinnasta.
Liityntäpalvelimet varmistavat siis Palveluväylän tietoturvan, sillä niiden välinen liikenne on oletuksena salattua. Liityntäpalvelimen voi sijoittaa joko konesaliin tai pilviympäristöön. Palveluväylässä on mahdollista käyttää joko Linux-pohjaista RHEL- tai Ubuntu-liityntäpalvelinta tai Docker-kontitettua liityntäpalvelinta.
Liityntäpalvelimen ja tietojärjestelmän välisen yhteyden salaus sekä yleinen tietoturvallisuus on asiakasorganisaation vastuulla. Jos kaikkia yhteyksiä ei salata, liitynnän tietoturva heikentyy huomattavasti. Tämän takia suosittelemme aina käyttämään HTTPS-protokollaa liityntäpalvelimen ja asiakasorganisaation taustajärjestelmän välillä.
Varmenteet
Palveluväylässä käytetään neljänlaisia varmenteita:
- Autentikointivarmenne: Varmenteen avulla todennetaan liityntäpalvelimen aitous, eli että liityntäpalvelin on luotettu Palveluväylässä. Varmenne on liityntäpalvelinkohtainen.
- Allekirjoitusvarmenne: Varmenteen avulla todennetaan, että organisaatio on luotettu Palveluväylässä. Varmenteen avulla järjestelmien lähettämät sanomat allekirjoitetaan ja salataan. Varmenne on organisaatiokohtainen.
- TLS-asiakasvarmenne/Sisäinen varmenne: Varmenteen avulla liityntäpalvelin todentaa asiakasjärjestelmän luotetuksi. Varmenteella salataan yhteys organisaation tietojärjestelmän ja liityntäpalvelimen välillä. Varmennetta käytetään HTTPS-yhteyksissä, eli se on pakollinen, jos liityntäpalvelin on jaettu useamman organisaation kesken. Asiakasvarmenne on alijärjestelmäkohtainen.
- Liityntäpalvelimen oma varmenne: Varmenteen avulla asiakasjärjestelmä todentaa liityntäpalvelimen luotetuksi.
Autentikointi- ja allekirjoitusvarmenteissa käytetään Digi- ja väestötietoviraston myöntämiä varmenteita. Autentikointi- ja allekirjoitusvarmenteet täytyy uusia vuosittain. Näin tarkistat varmenteiden voimassaolon liityntäpalvelimelta.
Tiedonsiirto
Palveluväylään liittyminen edellyttää, että liitettävä tietojärjestelmä joko pystyy lähettämään ja vastaanottamaan SOAP-sanomia X-Roadin edellyttämässä muodossa tai noudattaa REST-arkkitehtuuria rajapintojen toteuttamiseen. Käytännössä tämä tarkoittaa sitä, että SOAP-sanomien tulee sisältää tietyt X-Road-tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan X-Road-protokollan määrittelemällä tavalla. X-Roadin versio 7 käyttää SOAP-versiota 1.1. Se käyttääkö Palveluväylän kautta käytettävä palvelu SOAP- vai REST-teknologiaa riippuu palvelua tarjoavasta organisaatiosta
SOAP-protokollaa käytettäessä X-Road edellyttää myös siihen liitettävien palveluiden kuvaamista WSDL (Web Service Description Language) -kielellä. Kysely- ja vastaussanomien rakenteen kuvaavat skeemat voidaan sisällyttää WSDL-kuvaukseen tai vaihtoehtoisesti kuvata erillisissä tiedostoissa, joihin viitataan WSDL-kuvauksessa import-määrityksen avulla. Skeemoissa tulee käyttää nimiavaruuksia sekä yksiselitteisiä nimiä elementeille. Suosittelemme, että REST-rajapintoja käytettäessä palvelut kuvataan OpenAPI 3 -määrityksen mukaisesti. Palveluväylän kautta tarjottavien palveluiden WSDL- ja OpenAPI-kuvaukset löytyvät Liityntäkatalogista.