Alijärjestelmän jakaminen usean organisaation kesken

Tällä sivulla kuvataan esimerkkitoteutus, jonka alijärjestelmän jakaminen usean organisaation kesken vaatii.

Alijärjestelmät ovat yleensä organisaatiokohtaisia ja niiden kautta organisaatiot voidaan tunnistaa Palveluväylässä. Tilanteessa, jossa useampi organisaatio käyttää samaa alijärjestelmää, organisaation tunnistaminen pelkän alijärjestelmän perusteella ei ole mahdollista.

Huomioitavaa ennen jaetun alijärjestelmän käyttöönottoa

Palveluntarjoaja;

• Selvitä, voiko palvelusi sallia jaetun alijärjestelmän käytön (ratkaistavia asioita mm. autentikoinnin toteuttaminen)
• Huolehdi, että palvelusi käyttöehdoissa tarvittaessa huomioidaan jaettu alijärjestelmä sekä siihen liittyvät tietoturvavaatimukset ja vastuut

Välitoimija;

• Selvitä, salliiko käyttöönotettava palvelu jaetun alijärjestelmän käytön
• Tutustu palvelussa käytettävään autentikointitapaan
• Sovi käytännöistä palveluntarjoajan kanssa

Huom! Ennen jaetun alijärjestelmän käyttöönottoa tulee varmistaa, että Palveluväylän kautta hyödynnettävä palvelu tukee jaettua alijärjestelmää. Riippuen hyödynnettävästä palvelusta, toteutus voi erota alla olevasta esimerkistä ja huomioon otettavista asioista. Saat selville, voiko palvelua käyttää jaetulla alijärjestelmällä olemalla yhteydessä palvelua tarjoavaan organisaatioon.

Mitä jaettu alijärjestelmä tarkoittaa?

Jaettu alijärjestelmä mahdollistaa usean organisaation liittymisen Palveluväylään välitoimijan omistaman valmiin liityntäpalvelimen ja alijärjestelmän kautta. Alijärjestelmän jakaminen usean organisaation kesken on mahdollistettu, jotta esimerkiksi jokaiselle kunnalle tai hyvinvointialueelle ei tarvitse luoda omaa liityntäpalvelinta ja alijärjestelmää, kun he liittyvät Palveluväylään. Tämän toteutuksen myötä Palveluväylään liittyminen on siis helpompaa, nopeampaa ja yksinkertaisempaa.

Välitoimija edustaa jaettua alijärjestelmää käyttäviä organisaatioita Palveluväylässä.

• Palveluväylän varmenteiden hakeminen ja hallinnointi tapahtuvat liityntäpalvelimen omistavan organisaation toimesta, eivät jaettua alijärjestelmää käyttävien organisaatioiden toimesta.

Alla olevassa kuvassa on visualisoitu tilanne, jossa jaettu alijärjestelmä on otettu käyttöön.

Kuva: Kuva 1. Tilanne, jossa jaettu alijärjestelmä on käytössä.

Näytä kuva suurempana

Mitä jaetun alijärjestelmän käyttäminen vaatii?

Jaettu alijärjestelmä toimii hieman eri tavalla kuin perinteisesti toteutettu Palveluväylä-integraatio. Toteutus vaatii muutoksia, jotta organisaatiot voidaan tunnistaa muihin tietojärjestelmiin liityntäpalvelimien kautta lähetetyistä kyselyistä. Toteutus perustuu autentikoinnin käyttämiseen ja tässä tapauksessa suosittelemme JSON Web Token (JWT) (englanniksi)Avautuu uuteen ikkunaan. -autentikoinnin käyttämistä, sillä se on yleisin ja yksinkertaisin tapa toteuttaa autentikointi. Autentikointiprosessin vaiheet on visualisoitu alla olevassa kuvassa.

JWT-autentikointi on esimerkkiratkaisu. Halutessaan palveluntarjoaja voi toteuttaa autentikoinnin myös muulla tavalla.

HUOM. Testauspalveluiden osalta on hyvä huomioida, että tarjoamme niitä artikkelissa kuvatulle referenssitoteutukselle.

Kuva: Kuva 2. Autentikointiprosessin vaiheet.

Näytä kuva suurempana

Autentikointiprosessin vaiheet tulee toteuttaa täsmällisesti ohjeiden mukaan, sillä muuten toteutus ei toimi. On myös tärkeää muistaa käyttää HTTPS-yhteyttä liityntäpalvelimien ja tietojärjestelmien välisessä liikenteessä.

Autentikointiprosessissa palveluntarjoajalla ja palvelun hyödyntäjää edustavalla välitoimijalla on kummallakin omat vastuunsa.

Palveluntarjoajan vastuut

Palveluntarjoajan vastuulla ovat seuraavat asiat:

• Suosittelemme, että alijärjestelmäsi on palvelukohtainen eli yhdessä alijärjestelmässä on vain yksi palvelu
• Palvelulla on yksi API endpoint autentikointia varten
• Käyttäjätunnusten antaminen palvelun hyödyntäjää edustavalle välitoimijalle
• Käyttäjän autentikoiminen tunnistautumiskyselyssä
• JWT-tunnisteen tai muun vastaavan tunnisteen generoiminen ja sen lähettäminen osana vastaussanomaa
• JWT-tunnisteen tai muun vastaavan tunnisteen validointi, kun kutsutaan palvelua autentikoinnin jälkeen

Lue tarkemmat ohjeet sivulta Palveluntarjoajan vastuut jaettua alijärjestelmää käyttävän organisaation autentikoinnissa.

Palvelun hyödyntäjän vastuut

Palvelun hyödyntäjää edustavan välitoimijan vastuulla ovat seuraavat asiat:

• mTLS-palvelinvarmennekäytännön käyttäminen välitoimijan tietojärjestelmä ja alijärjestelmää hyödyntävän organisaation välillä
• mTLS-palvelinvarmennekäytännön käyttäminen liityntäpalvelimen ja tietojärjestelmän välillä
• Organisaation yksilöivien tietojen ja palveluntarjoajalta saadun käyttäjätunnuksen lähettäminen ensimmäisessä tunnistautumiskyselyssä
• Palveluntarjoajan palauttaman JWT-tunnisteen tai muun vastaavan tunnisteen käyttäminen jatkossa ensimmäisen tunnistautumiskyselyn jälkeen

Lue tarkemmat ohjeet sivulta Välitoimijan vastuut jaettua alijärjestelmää käyttävän organisaation autentikoinnissa.