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

Palvelun lisääminen liityntäpalvelimelle

Tällä sivulla kerrotaan, miten lisäät Palveluväylän liityntäpalvelimelle uuden SOAP- tai REST-palvelun ja kuinka määrittelet palvelun käyttöoikeudet. Tämä ohje on suunnattu organisaatioille, jotka tarjoavat palveluja Palveluväylän kautta.

Huomaa, että ennen kuin lisäät palvelun liityntäpalvelimelle sinun täytyy

  1. lisätä liityntäpalvelimellesi asiakasjärjestelmä ja
  2. testata asiakasjärjestelmän ja liityntäpalvelimen välinen yhteys.

Lue lisää asiakasjärjestelmän liittämisestä liityntäpalvelimeen.

Uuden palvelun lisääminen tapahtuu liityntäpalvelimen hallintakäyttöliittymän kautta. Liityntäpalvelimen hallintakäyttöliittymän osoite on

https://{host}:4000/

jossa host korvataan organisaation oman liityntäpalvelimen host-nimellä.

Voit lisätä Palveluväylään 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

Yksi WSDL-kuvaus voi sisältää yhden tai useamman palvelun rajapintakuvauksen. Liityntäpalvelimelle voidaan lisätä useita eri WSDL-kuvauksia.

Lue lisää X-Road-tiedonsiirtoprotokollasta SOAPille ja RESTille.

Lisää SOAP-palvelu

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

1. Valitse Clients-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.

Kuva 1. Alijärjestelmän valitseminen.

2. Tämän jälkeen Services-välilehti näyttää listauksen alijärjestelmään liitetyistä WSDL-kuvauksista. Lisää uusi WSDL-kuvaus valitsemalla Add WSDL.

Kuva 2. Uuden WSDL-kuvauksen lisääminen.

3. Kopioi URL-kenttään WSDL-kuvauksen URL-osoite ja valitse Add.

Kuva 3. WSDL-kuvauksen URL-osoitteen lisääminen.

4. WSDL-kuvaus on lisätty valitun alijärjestelmän palvelut näyttävään listaukseen. Lisätty kuvaus on oletuksena passiivisessa tilassa. Aktivoi WSDL-kuvaus sen kohdalla olevasta valintakytkimestä. Kun klikkaat WSDL-tekstin edessä olevaa nuolta, rivin alapuolelle avautuu listaus WSDL:n sisältämistä palveluista.

Kuva 4. WSDL-kuvauksen aktivointi.

5. Katso seuraavana päivänä, että palvelu on näkyvillä Testiliityntäkatalogissa Avautuu uuteen ikkunaan.tai Liityntäkatalogissa Avautuu uuteen ikkunaan.ympäristöstä riippuen. Jos palvelua ei näy, tarkista että kaikki edelle mainitut vaiheet on tehty ja pyydä tarvittaessa apua palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan.. Muista kuvailla lisäämäsi palvelut sivun Organisaation tietojen kuvaaminen Liityntäkatalogiin ohjeiden mukaisesti.

Lisää REST-palvelu

REST-palvelun voi lisätä käyttämällä REST API Base Path -polkua tai OpenAPI3 Description -polkua. Jos lisäät palvelusi käyttämällä REST API Base Path -polulla, palvelun tekninen rajapintakuvaus ei näy oikein Liityntäkatalogissa. Lisää tällöin rajapintakuvaus erillisenä liitetiedostona Liityntäkatalogiin. Tästä syystä suosittelemme lisäämään REST-palvelut Palveluväylään käyttämällä OpenAPI 3 Description -polkua.

Lue lisää OpenAPI 3 -määrittelystä (englanniksi)Avautuu uuteen ikkunaan..

Näin lisäät REST-palvelun:

1. Valitse Clients-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.

Kuva 5. Alijärjestelmän valitseminen.

2. Lisää REST-palvelu Services-välilehdeltä valitsemalla Add REST.

Kuva 6. Uuden REST-palvelun lisääminen.

3. Valitse osoitepolun tyypiksi joko REST API Base Path tai OpenAPI 3 Description. Täydennä kenttiin URL-osoite ja palvelun nimi (Service Code). Lisää palvelu valitsemalla Add.

Kuva 7. REST-palvelun lisääminen.

4. Aktivoi lisätty REST-palvelu sen kohdalla olevasta valintakytkimestä. Varmista ennen aktivointia, että palvelun tiedot ovat oikein. Aktivoinnin jälkeen palvelu on käyttäjien saatavilla.

Kuva 8. REST-palvelun aktivointi.

5. Katso seuraavana päivänä, että palvelu on näkyvillä TestiliityntäkatalogissaAvautuu uuteen ikkunaan. tai Liityntäkatalogissa Avautuu uuteen ikkunaan.ympäristöstä riippuen. Jos palvelua ei näy, tarkista että kaikki edelle mainitut vaiheet on tehty ja pyydä tarvittaessa apua palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan.. Muista kuvailla lisäämäsi palvelut sivun Organisaation tietojen kuvaaminen Liityntäkatalogiin ohjeiden mukaisesti.

Määrittele palveluiden käyttöoikeudet

Määrittele palveluiden käyttöoikeudet valitsemalla ensin palvelu ja klikkaamalla sitten Access Rights -painiketta.

Kuva 9. Palvelun käyttöoikeuksien määrittelyn aloittaminen.

Avautuvassa ikkunassa on listaus alijärjestelmistä, joilla on oikeudet valitun palvelun käyttöön. Lisää uusi käyttöoikeus klikkaamalla Add Subjects -painiketta.

Kuva 10. Uuden käyttöoikeuden lisääminen.

Klikkaa Search-painiketta nähdäksesi listauksen kaikista Palveluväylään liittyneistä organisaatioista ja niiden alijärjestelmistä. Valitse listauksesta alijärjestelmä, jolle käyttöoikeus annetaan. Klikkaa sen jälkeen Add Selected to ACL -painiketta.

HUOM! Käyttöoikeuksien antaminen tulee aina tehdä alijärjestelmätasolla, ei koskaan organisaatiotasolla.

Kuva 11. Uuden käyttöoikeuden määrittely.

Valitulla alijärjestelmällä on nyt oikeudet palvelun käyttöön. Sulje ikkuna klikkaamalla Close-painiketta.

Kuva 12. Näkymä käyttöoikeuden määrittelyn jälkeen.

Valitun palvelun nimen perässä suluissa oleva numero on kasvanut yhdellä uuden käyttöoikeuden lisäämisen myötä. Jos numero on nolla, yhdelläkään alijärjestelmällä ei ole vielä oikeuksia palvelun käyttöön. Numeron päivittyminen saattaa vaatia Services-välilehden avaamisen uudelleen.

Kuva 13. Käyttöoikeuden lisäämisen varmistaminen.

Palvelun URL-osoitteen vieressä näkyvä lukkosymboli ilmaisee, käyttääkö liityntäpalvelin palvelun kutsumisessa

  • HTTP-protokollaa (avoin lukko, harmaa)
  • HTTPS-protokollaa ilman varmenteen verifiointia (suljettu lukko, keltainen)
  • HTTPS-protokollaa varmenteen verifioinnilla (suljettu lukko, vihreä).

Pääset muokkaamaan yksittäisen palvelun asetuksia valitsemalla muokattavan palvelun ja klikkaamalla Edit-painiketta. Edit Service Parameters -ikkunan kautta voit muokata palvelun URL-osoitetta ja palvelukutsujen aikakatkaisun rajaa sekä määritellä, verifioidaanko palvelun varmenne HTTPS-yhteyttä käytettäessä. Service URL -parametrin arvo luetaan oletusarvoisesti WSDL-kuvauksesta.

Kuva 14. Palvelun asetusten muokkaaminen.

Palvelun yhteysasetukset

Liityntäpalvelin voi kutsua liitettävää palvelua käyttäen HTTP- tai HTTPS-protokollaa. Jos käytät HTTPS-protokollaa ja haluat verifioida liitettävän palvelun varmenteen, varmenteen on oltava liityntäpalvelimen tiedossa. Lisää varmenne Internal Servers -välilehdellä kohdasta Internal TLS Certificates. Jos varmennetta ei verifioida, liityntäpalvelimelle kelpaa mikä hyvänsä varmenne, myös ns. self-signed.

HTTPS-protokollaa käytettäessä liitettävän palvelun varmenne on lisättävä liityntäpalvelimelle myös käyttöjärjestelmätasolla. Lisäys on tehtävä myös siinä tapauksessa, että varmennetta ei verifioida. Jos varmennetta ei lisätä liityntäpalvelimelle käyttöjärjestelmätasolla, liityntäpalvelin ei kykene hakemaan liitettävän palvelun WSDL-kuvausta. Varsinaiset palvelukutsut ja WSDL-kuvauksen haku on toteutettu eri tavoilla, minkä vuoksi varmenteen lisääminen joudutaan tällä hetkellä tekemään kahteen kertaan.

Jos liitettävä palvelu vaatii TLS-asiakasvarmennetta, liityntäpalvelin lähettää oman sisäisen varmenteensa (tarvittaessa ladattavissa kohdasta Security Server Certificate → Export).

Kuva 15. Varmenteen lisääminen.

Liityntäpalvelimen ja liitettävän palvelun 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

Voit varmistaa liityntäpalvelimen komentoriviltä seuraavalla komennolla, että liitettävä palvelu tukee liityntäpalvelimen edellyttämiä salausasetuksia:

openssl s_client -tls1_2 -cipher ’EDH+aRSA+AES:!SHA’ -connect

Jos liityntäpalvelin ei oletuksena salli tarvittavan Cipher Suiten tai protokollan käyttöä, voit konfiguroida uudet salausasetukset seuraavaan tiedostoon:

/etc/xroad/conf.d/local.ini

Tiedostoon lisätyt arvot ylikirjoittavat muissa tiedostoissa määritellyt arvot, joten ne ovat aina ensisijaisesti käytössä. local.ini-muutokset säilyvät myös liityntäpalvelimen päivityksessä, sillä tiedostoa ei korvata päivitysasennuksessa. Jos haluat palauttaa käyttöön oletusarvon, poista itse määrittelemäsi asetus local.ini-tiedostosta.

Saat tekemäsi muutokset käyttöön käynnistämällä xroad-proxy-palvelun uudelleen.

Esimerkiksi IIS-palvelinten tapauksessa liityntäpalvelinten salausasetuksia on jouduttu laajentamaan seuraaviksi:

#local.ini 
[proxy] 
client-tls-protocols=TLSv1.1,TLSv1.2 
client-tls-ciphers=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, 
TLS_RSA_WITH_AES_256_CBC_SHA256, 
TLS_RSA_WITH_AES_256_CBC_SHA, 
TLS_RSA_WITH_AES_128_CBC_SHA256, 
TLS_RSA_WITH_AES_128_CBC_SHA
Päivitetty: 14.10.2024

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