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

Asiakasjärjestelmän liittäminen liityntäpalvelimeen

Tässä artikkelissa kerrotaan, miten organisaation oma asiakasjärjestelmä liitetään liityntäpalvelimeen.

Artikkelissa käsiteltävät TLS-asiakasvarmenteet ovat organisaation itse luomia sisäisiä varmenteita, eikä niiden hakeminen liity Palveluväylän varmenteiden hakemiseen Digi- ja väestötietoviraston (DVV) verkkoasioinnissa.

Asiakasjärjestelmän eli organisaation oman tietojärjestelmän (service client), liittäminen liityntäpalvelimeen tapahtuu liityntäpalvelimelle luodun alijärjestelmän kautta. Alijärjestelmä yksilöi asiakasjärjestelmän Palveluväylässä. Sitä käytetään palveluiden kutsumisessa ja Palveluväylään liitettyjen palveluiden käyttöoikeuksien määrittelyssä. Asiakasjärjestelmä liitetään alijärjestelmään lisäämällä TLS-asiakasvarmenne liityntäpalvelimelle.

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. Käytännössä organisaatioiden tulisi kuitenkin aina käyttää asiakasjärjestelmäkohtaisia alijärjestelmiä, jotta palveluiden käyttöoikeudet voidaan määritellä vain oikeille alijärjestelmille.

Huolehdi, että olet lisännyt alijärjestelmän liityntäpalvelimelle ennen kuin liität asiakasjärjestelmäsi. Lue lisää ohjeita alijärjestelmän lisäämisestä.

Tässä artikkelissa käydään läpi:

  • Tietoa liityntäpalvelimen ja asiakasjärjestelmän yhteysasetuksista
  • Asiakasjärjestelmän liittäminen liityntäpalvelimelle:
  1. Valitse yhteystyyppi
  2. Luo TLS-asiakasvarmenne ja lisää se liityntäpalvelimelle
  3. Lataa liityntäpalvelimen sisäinen varmenne ja vie se asiakasjärjestelmään
  4. Palveluiden kutsuminen
  5. Testaa asiakasvarmennetta

Tietoa liityntäpalvelimen ja asiakasjärjestelmän yhteysasetuksista

Asiakasjärjestelmä voi kutsua liityntäpalvelinta oletusarvoisesti vain HTTPS-protokollaa käyttäen.

Asiakasjärjestelmän ja liityntäpalvelimen välisessä yhteydessä tulee käyttää aina HTTPS-protokollaa, jotta yhteys oman organisaatiosi asiakasjärjestelmän ja liityntäpalvelimen välillä on salattu. HTTPS-protokollaa käytettäessä asiakasjärjestelmän on esitettävä TLS-asiakasvarmenne, joka on erikseen lisättävä liityntäpalvelimen Internal TLS Certificates -listaukseen.

HTTPS-protokollan ja asiakasvarmenteiden käyttö on lisäksi 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. 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 oma varmenne on oletuksena liityntäpalvelimen itsensä allekirjoittama (ns. self-signed). Sisäisen varmenteen voi vaihtaa Keys and Cerificates-sivun Internal TLS Certificate -kohdasta. Tutustu liityntäpalvelimen varmenteen vaihtamiseen liittyviin ohjeisiin (englanniksi)Avautuu uuteen ikkunaan.. Huomaa, että varmenteen on oltava PEM-formaatissa.

Sisäisiä varmenteita on kahdenlaisia:

  • TLS-asiakasvarmenne: Liityntäpalvelin todentaa asiakasjärjestelmän varmenteen avulla. Asiakasvarmenne on alijärjestelmäkohtainen.
  • Liityntäpalvelimen oma varmenne: Asiakasjärjestelmä todentaa liityntäpalvelimen varmenteen avulla. Suosittelemme käyttämään liityntäpalvelimen omaa varmennetta, jos organisaatiosi tarjoaa palveluita Palveluväylän kautta. Palveluväylän hyödyntäjille tämän varmenteen käyttäminen ei ole pakollista.

Varmenteilla salataan yhteys liityntäpalvelimen ja asiakasjärjestelmän välillä.

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 seuraavat:

  • HTTP: Asiakasjärjestelmä voi tehdä kutsun HTTP- tai HTTPS-protokollalla. Asiakasvarmennetta ei tarvita. Salaamaton.
  • HTTPS: Asiakasjärjestelmän täytyy tehdä kutsu HTTPS-protokollalla. Lisäksi asiakasjärjestelmän täytyy esittää TLS-asiakasvarmenne, joka on listattu Internal TLS Certificates -kohdassa. Salattu.
  • HTTPS NO AUTH: Asiakasjärjestelmän täytyy tehdä kutsu HTTPS-protokollalla. Asiakasvarmennetta ei tarvita. Salattu.

Asiakasjärjestelmän liittäminen liityntäpalvelimelle

1. Valitse yhteystyyppi (Connection type: HTTPS)

Valitse asiakasjärjestelmän ja liityntäpalvelimen välisen yhteyden tyypiksi HTTPS.

Asiakasjärjestelmän ja liityntäpalvelimen välisen yhteyden tyypin valitseminen

2. Luo TLS-asiakasvarmenne ja lisää se liityntäpalvelimelle

Vaiheet 1 ja 2 kannattaa suorittaa asiakasjärjestelmällä.

  1. Luo ensin asiakasjärjestelmän yksityinen avain 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, jonka osoite on https://{host}:4000/ (korvaa {host}-osa organisaatiosi liityntäpalvelimen host-nimellä). Kirjautumisen jälkeen näytölle avautuu listaus liityntäpalvelimelle lisätyistä alijärjestelmistä (subsystem).
  4. Valitse listauksesta alijärjestelmä, johon liittyviä asetuksia haluat muokata.
  5. Lisää asiakasvarmenne liityntäpalvelimelle Internal Servers -välilehdeltä valitsemalla Add. Kun asiakasvarmenne on lisätty liityntäpalvelimelle, Internal TLS Certificates -listaukseen tulee näkyviin varmenteen tiivistesumma.

Asiakasvarmenteen lisääminen liityntäpalvelimelle

3. Lataa liityntäpalvelimen sisäinen varmenne ja vie se asiakasjärjestelmään

1. Lataa liityntäpalvelimen sisäinen varmenne Internal Servers -välilehdeltä kohdasta Information System TLS-certificate ja valitse Export.

Liityntäpalvelimen sisäisen varmenteen lataaminen

2. Vie liityntäpalvelimen varmenne lopuksi asiakasjärjestelmään.

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

4. Palveluiden kutsuminen

Soap-sanomien testaus

Liityntäpalvelimen asiakasrajapinta, jonka kautta Palveluväylän palvelujen kutsuminen tapahtuu, on muotoa https://{host}/. Osoitteen {host}-osa tulee korvata organisaation 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.

Liityntäpalvelimen osoite: https://{host}/

Method: POST

Content-Type: text/xml

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

REST-palveluiden testaus

REST-palveluita voi testata rest-test/random- ja rest-test/hello-palveluilla.

rest-test/random-palvelu

  • ei sisällä kutsuparametreja
  • palauttaa vastauksenaan satunnaisen kokonaisluvun 0:n ja 100:n väliltä

rest-test/hello-palvelu

  • palvelulle voi antaa query-parametrina name-arvon
  • palvelu palauttaa vastauksena name-parametrin arvona annetulle nimelle kohdistetun tervehdyksen

Tarkemmat testausohjeet löydät tukiartikkelista Palveluväylän testipalvelut.

5. Testaa asiakasvarmennetta

Asiakasvarmenteen käyttöä voidaan helposti testata kutsumalla getRandom-testipalvelua Curl-ohjelman avulla. Vaiheet 1 ja 2 kannattaa suorittaa asiakasjärjestelmällä.

Katso ohjevideo testaamisesta (Youtube)Avautuu uuteen ikkunaan..

  1. Kutsu kehitysympäristön getRandom-testipalvelua (ks. Palveluväylän getRandom-kutsusanomaAvautuu uuteen ikkunaan.) sillä alijärjestelmällä, jonka alle lisäsit asiakasvarmenteen: curl -E ./clientcert.pem --key ./clientprivatekey.pem -k -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://{host}/
  2. Yritä kutsua kehitysympäristön testipalvelua myös ilman luomaasi yksityistä avainta ja varmennetta seuraavalla komennolla: curl -k -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://{host}/

Curl-komennossa on käytetty k-optiotaAvautuu uuteen ikkunaan.. Tällöin kutsutun palvelun varmennetta ei verifioida.

Lopputuloksena pitäisi tulla seuraavanlainen virheilmoitus:

Server.ClientProxy.SslAuthenticationFailedClient (SUBSYSTEM:FI-DEV/GOV/0245437-2/TestClient) specifies SSLAUTH but did not supply SSL certificate

Voit myös lukea NIISin ohjeistuksia asiakasjärjestelmän liittämisestä liityntäpalvelimeen (englanniksi)Avautuu uuteen ikkunaan. ja palomuureista (englanniksi).Avautuu uuteen ikkunaan.

Päivitetty: 5.5.2026

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