Suomi.fi-palveluväylä –
Asiakasjärjestelmän liittäminen liityntäpalvelimeen

Print Friendly, PDF & Email


Tämän ohjeen avulla liitetään asiakasjärjestelmä liityntäpalvelimelle.

HUOM! Tämä ohje soveltuu liityntäpalvelimen versioille 6.9.x ja sitä uudemmille. Vanhempien versioiden ohjeet löytyvät PDF-muodossa seuraavasta linkistä:

Asiakasjärjestelmän liittäminen liityntäpalvelimelle


1 Palveluiden kutsuminen

Liityntäpalvelimen asiakasrajapinta, jonka kautta palveluväylän kautta käytettävissä olevien palvelujen kutsuminen tapahtuu, on muotoa ”https://{host}/”Osoitteen ”{host}”-osa tulee korvata oman liityntäpalvelimen host-nimellä. Liityntäpalvelimelle lähetettävien pyyntöjen Content-Type-otsikkotiedon arvon tulee olla ”text/xml” ja HTTP-metodin on oltava POST.

HUOM! IP-osoitteen käyttö kutsuissa ei ole suositeltavaa, sillä se aiheuttaa varmenteisiin liittyviä ongelmia. Ongelmia ilmenee, mikäli liityntäpalvelimen kutsussa käytetty host-nimi ei vastaa liityntäpalvelimen varmenteessa olevaa host-nimeä.
Liityntäpalvelimen osoite: https://{host}/
Method: POST
Content-Type: text/xml

2 Alijärjestelmän asetukset

Asiakasjärjestelmän (service client) liittäminen liityntäpalvelimeen tapahtuu liityntäpalvelimelle luodun alijärjestelmän (subsystem) kautta. Alijärjestelmä on käytännössä asiakasjärjestelmän yksilöivä tunnus palveluväylässä, ja sitä käytetään palveluiden kutsumisessa sekä palveluväylään liitettyjen palveluiden käyttöoikeuksien määrittelyssä. Alijärjestelmä voi olla asiakasjärjestelmäkohtainen tai vaihtoehtoisesti myös useat yhden loogisen kokonaisuuden muodostavat asiakasjärjestelmät voivat hyödyntää samaa alijärjestelmää palveluiden kutsumiseen. Palveluväylän käyttöoikeuksien määrittely tapahtuu alijärjestelmätasolla, jonka vuoksi lähtökohtaisesti tulisi aina käyttää asiakasjärjestelmäkohtaisia alijärjestelmiä. Liityntäpalvelimen ja asiakasjärjestelmän väliseen yhteyteen liittyvät asetukset löytyvät liityntäpalvelimen hallintakäyttöliittymästä.

Liityntäpalvelimen hallintakäyttöliittymän osoite on https://{host}:4000/, jossa {host}-korvataan oman liityntäpalvelimen host-nimellä.

1. Kirjaudu sisälle liityntäpalvelimen hallintakäyttöliittymään. Kirjautumisen jälkeen näytölle avautuu listaus liityntäpalvelimelle lisätyistä alijärjestelmistä (subsystem).

2. Valitse listauksesta alijärjestelmä, johon liittyviä asetuksia haluat muokata ja klikkaa rivin oikeassa reunassa olevaa Internal Servers -painiketta. HUOM! Asetukset ovat alijärjestelmäkohtaisia eli mikäli haluat muokata monen alijärjestelmän asetuksia, on asetukset muutettava jokaiselle alijärjestelmälle erikseen.

3. Oletusarvoisesti asiakasjärjestelmä voi kutsua liityntäpalvelinta HTTP- ja HTTPS-protokollaa käyttäen. HTTPS-protokollaa käytettäessä yhteyden salaamiseen käytetään liityntäpalvelimen sisäistä varmennetta (Internal Certificate). Oletuksena sisäinen varmenne on liityntäpalvelimen itsensä allekirjoittama (ns. self-signed varmenne), jonka vuoksi se on erikseen määriteltävä luotetuksi asiakasjärjestelmän puolella HTTPS-protokollaa käytettäessä. Sisäisen varmenteen voi myös vaihtaa System Parameters -näkymän Internal TLS Certificate kohdasta. Englanninkieliset ohjeet varmenteen vaihtamisesta löytyvät X-Roadin virallisesta Github repositorioista täältä. Huomaa, että varmenteen on oltava PEM formaatin muotoinen.

Liityntäpalvelimen sisäisen varmenteen lataaminen tapahtuu alijärjestelmä-asetuksien kautta Internal Servers -välilehdellä sijaitsevassa Security Server Certificate -osiossa olevaa Export -painiketta klikkaamalla.

Asiakasjärjestelmän ja liityntäpalvelimen välisessä yhteydessä on vahvasti suositeltavaa käyttää aina HTTPS-protokollaa. HTTP-protokollan käyttö on mahdollista estää asetuksista käyttämällä HTTPS-vaihtoehtoa. HTTPS-vaihtoehtoa käytettäessä on kuitenkin syytä huomioida, että tällöin asiakasjärjestelmän on esitettävä asiakasvarmenne, joka on erikseen lisättävä liityntäpalvelimen Internal TLS Certificates -listaukseen.
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. Kaikki samaa liityntäpalvelinta käyttävät organisaatiot käyttävät samaa liityntäpalvelimen kutsurajapintaa ja IP-osoitetta, jolloin palvelukutsujen tekoa toisen organisaation nimissä ei voida estää palomuuriasetusten kautta.
Liityntäpalvelimen ja asiakasjärjestelmän välisessä liikenteessä on oletuksena sallittu TLS 1.2 ja seuraavat PFS Cipher Suitet:

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256*
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256*
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384*
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384*
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

(*) ei käytössä RHEL:ssä, jos käytetään OpenJDK:ta.

Asiakasjärjestelmän ja liityntäpalvelimen välisen yhteyden tyyppi määritellään Connection type for servers in service consumer role -asetuksen kautta. Asetuksen mahdolliset arvot ovat:

  • HTTP: asiakaspalvelin voi tehdä kutsun HTTP tai HTTPS -protokollalla. Varmennetta ei tarvita.
  • HTTPS: palvelun käyttäjän täytyy esittää TLS asiakasvarmenne, joka on listattu Internal TLS Certificates -kohdassa.
  • HTTPS NO AUTH: asiakaspalvelimen täytyy esittää asiakasvarmenne, mutta liityntäpalvelin ei tarkista onko varmennetta lisätty Internal TLS Certificates -listaukseen

4. Asiakasvarmenteiden lisääminen liityntäpalvelimelle tapahtuu Internal TLS Certificates -kohdan alla olevaa Add -painiketta klikkaamalla. Tämän jälkeen käyttöliittymä ohjeistaa, kuinka asiakasjärjestelmän asiakasvarmenteen lataaminen liityntäpalvelimelle tapahtuu.

5. Kun asiakasvarmenne on onnistuneesti lisätty liityntäpalvelimelle, tulee varmenteen tiivistesumma näkyville Internal TLS Certificates -listaukseen. Liityntäpalvelimen sisäisen varmenteen lataaminen tapahtuu Security Server Certificate -osiossa olevaa Export -painiketta klikkaamalla.

3 Asiakasvarmenteen testaaminen

Asiakasvarmenteen käyttöä voidaan helposti testata kutsumalla getRandom-testipalvelua Curl-ohjelman avulla. Vaiheet 1, 2, 6 ja 7 tulee suorittaa jollakin muulla palvelimella kuin liityntäpalvelimella.

1. Luo testissä käytettävä asiakasjärjestelmän yksityinen avain.

openssl genrsa -out clientprivatekey.pem 2048

2. Luo avaimelle ns. self-signed varmenne.

openssl req -new -x509 -key clientprivatekey.pem -out clientcert.pem -days 365

3. Kirjaudu liityntäpalvelimen hallintakäyttöliittymään ja avaa sen alijärjestelmän asetukset, jota haluat käyttää palvelukutsussa.

Liityntäpalvelimen hallintakäyttöliittymän osoite on https://{host}:4000/, jossa {host}-korvataan oman liityntäpalvelimen host-nimellä.

4. Avaa Internal Servers -välilehti ja vaihda Connection type for servers in service consumer role -asetuksen arvoksi HTTPS.

5. Lisää luomasi clientcert.pem -tiedostoon tallennettu asiakasvarmenne Internal TLS Certificates -listaukseen.

6. Kutsu kehitysympäristön getRandom -testipalvelua käyttäen alijärjestelmää, jonka alle lisäsit asiakasvarmenteen. getRandom -palvelun kutsusanoma löytyy täältä.

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

7.Yritä kutsua kehitysympäristön testipalvelua myös ilman luomaasi yksityistä avainta ja varmennetta. Lopputuloksena pitäisi olla alla nähtävä virheilmoitus.

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

Virheilmoitus:

Server.ClientProxy.SslAuthenticationFailedClient (SUBSYSTEM:FI-DEV/GOV/0245437-2/TestClient) specifies SSLAUTH but did not supply SSL certificate
HUOM! Curl-komennossa on käytetty k-optiota, joka tarkoittaa, että kutsutun palvelun varmennetta ei verifioida. Lisätietoja.
VersioMitä tehty / muutettuPvm/
henkilö
1.0Dokumentti julkaistu eSuomessa.22.06.16 / HH
1.1Ohjeet päivitetty versiolle 6.9.x20.01.17 / HH
1.2Lisätty lukuun 2 linkki englanninkieliseen ohjeeseen, jonka avulla voi vaihtaa liityntäpalvelimen sisäisen varmenteen.26.01.17 / HH

Yksilöintitunnus: 12345