Palveluntarjoajan vastuut jaettua alijärjestelmää käyttävän organisaation autentikoinnissa

Tällä sivulla kuvataan, mitä palveluntarjoajan tulee tehdä, kun jaettua alijärjestelmää käyttävä organisaatio autentikoidaan.

Palvelun hyödyntäjän tunnistaminen tapahtuu eri tavalla tilanteessa, jossa kyseinen organisaatio on liitetty Palveluväylään välitoimijan liityntäpalvelimen ja jaetun alijärjestelmän kautta. Jaetussa alijärjestelmässä on useampi organisaatio, jotka täytyy tunnistaa erillisen autentikointiprosessin mukaisesti. Kuvaus koko autentikointiprosessista.

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

Tässä artikkelissa kuvataan autentikointiprosessi, jossa käytetään JWT-autentikointia.

Palveluntarjoajan vastuulla autentikointiprosessissa ovat seuraavat vaiheet:

1. Autentikoi käyttäjä.
2. Muodosta JWT tai muu vastaava tunniste, jos käyttäjä on autentikoitu.
3. Muodosta vastaussanoma.
4. Lähetä vastaussanoma palvelun hyödyntäjälle.
5. Palvelun kutsuminen JWT-autentikoinnilla tai muulla vastaavalla autentikointitavalla.

Huolehdi, että olet tehnyt seuraavat asiat ennen autentikointiprosessin aloittamista:

• Suosittelemme, että alijärjestelmäsi on palvelukohtainen eli yhdessä alijärjestelmässä on vain yksi palvelu. Palveluasi ei voida hyödyntää jaetusta alijärjestelmästä ilman tämän ehdon täyttymistä. Autentikoinnin avulla ei voida yksilöidä, mitä palvelua halutaan hyödyntää, sillä normaalitapauksissa käyttöoikeudet annetaan alijärjestelmäkohtaisesti.
• Palvelullasi on yksi API endpoint palvelun hyödyntäjän käyttäjätunnusten autentikointia varten.
• Olet luonut ja toimittanut uniikit käyttäjätunnukset palvelun hyödyntäjää edustavalle välitoimijalle käyttäen suojattua yhteyttä.

Esimerkkitoteutus: Suomen ympäristökeskus palveluntarjoajana Suomen ympäristökeskus (Syke) mahdollistaa palveluntarjoajana palveluidensa hyödyntämisen jaetun alijärjestelmän kautta. Syke on toteuttanut ratkaisun, jonka ansiosta palveluntarjoajan oma alijärjestelmä voi sisältää enemmän kuin yhden palvelun. Syke on rakentanut palvelukohtaisen tunnistautumis- ja käyttövaltuushallinnan ratkaisun, jonka avulla heidän on palveluntarjoajana mahdollista yksilöidä käyttäjän organisaatio ja oikeudet palvelukohtaisesti. Palvelukohtaisen tunnistautumis- ja käyttövaltuushallinnan avulla palveluntarjoajan alijärjestelmän ei tarvitse olla palvelukohtainen, vaan se voi sisältää useamman kuin yhden palvelun.

Palveluntarjoajan vastuut autentikointiprosessin vaiheissa

1. Autentikoi käyttäjä

Palveluun lisäämäsi API endpoint validoi kyselysanomassa tulevat käyttäjätunnukset.

Autentikointia varten palvelun tulee tarjota endpoint, joka validoi kutsujan käyttäjätunnuksen ja salasanan, ja palauttaa JWT-tunnisteen tai muun vastaavan tunnisteen, jolla käyttäjä tunnistetaan palvelun muissa endpointeissa.

SOAP-kysely

Jos kyseessä on SOAP-palvelu, toteuta SOAP service nimeltä "authenticate", joka ottaa vastaan SOAP-sanomassa kutsuvan organisaation tunnuksen ja salasanan:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:id="http://x-road.eu/xsd/identifiers"
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
    xmlns:xrcl="http://localhost/application-auth"
    xmlns:extsec="http://x-road.eu/xsd/security-token.xsd">
    ...
    <SOAP-ENV:Body>
        <xrcl:authenticate>
        <xrcl:username>randomuser123</xrcl:username>
        <xrcl:password>password123</xrcl:password>
        </xrcl:authenticate>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

REST-kysely

Toteuta REST-palveluun endpoint "POST /authenticate", joka ottaa vastaan kutsun header-osiossa kutsuvan organisaation käyttäjätunnuksen ja salasanan, esimerkiksi:

POST /r1/FI/GOV/8765432-1/ProviderSubsystem/ProviderServiceCode/authenticate HTTP/1.1
...
X-Road-Represented-Party: MUN/0000000-0
Member-Username: randomuser123
Member-Password: password123

2. Muodosta JWT tai muu vastaava tunniste, jos käyttäjä on autentikoitu

Generoi JWT-tunniste tai muu vastaava tunniste, jos käyttäjätunnukset ovat validit. Muussa tapauksessa kyselyn lähettäjälle palautuu virheviesti. Huomaathan, että JWT-tunnisteen tai muun vastaavan tunnisteen validointi on palveluntarjoajan vastuulla.

3. Muodosta vastaussanoma

1. Lisää vastaussanoman header-osaan palvelua hyödyntävän organisaation yksilöivät tiedot

SOAP-vastaus

Lisää vastaussanoman header-osaan Third Party Representation -laajennos. Ohjeet tämän toteuttamiseen löydät NIIS:in dokumentaatiosta (englanniksi)Avautuu uuteen ikkunaan..

REST-vastaus

Lisää vastaussanoman header-osaan seuraava rivi:

X-Road-Represented-Party: <Represented party member class/represented party member code>

2. Lisää vastaussanoman header-osaan JWT-tunniste tai muu vastaava tunniste, jonka generoit palvelun hyödyntäjälle

SOAP-vastaus

Lisää vastaussanoman header-osaan Security Token -laajennos. Ohjeet tämän toteuttamiseen löydät NIIS:in dokumentaatiosta (englanniksi)Avautuu uuteen ikkunaan..

REST-vastaus

Lisää vastaussanoman header-osaan seuraava rivi:

Authorization: Bearer <Token generated in the previous step if user is authenticated>

4. Lähetä vastaussanoma

Alla näet esimerkin, miltä valmiin vastaussanoman tulisi näyttää, kun se sisältää kaikki tarvittavat rivit. Huomaa, että esimerkkien arvot ovat keksittyjä ja nämä tulee korvata oikeilla arvoilla.

SOAP-vastaus

...
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:id="http://x-road.eu/xsd/identifiers"
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
    xmlns:extsec="http://x-road.eu/xsd/security-token.xsd"
    xmlns:repr="http://x-road.eu/xsd/representation.xsd">
<SOAP-ENV:Header>
    <xrd:client id:objectType="SUBSYSTEM">
        <id:xRoadInstance>FI-TEST</id:xRoadInstance>
        <id:memberClass>COM</id:memberClass>
        <id:memberCode>1234567-8</id:memberCode>
        <id:subsystemCode>TestClient</id:subsystemCode>
    </xrd:client>
    <xrd:service id:objectType="SERVICE">
        <id:xRoadInstance>FI-TEST</id:xRoadInstance>
        <id:memberClass>GOV</id:memberClass>
        <id:memberCode>8765432-1</id:memberCode>
        <id:subsystemCode>ProviderSubsystem</id:subsystemCode>
        <id:serviceCode>ProviderServiceCode</id:serviceCode>
        <id:serviceVersion>v1</id:serviceVersion>
    </xrd:service>
    <repr:representedParty>
        <repr:partyClass>COM</repr:partyClass>
        <repr:partyCode>MEMBER3</repr:partyCode>
    </repr:representedParty>
    <extsec:securityToken tokenType="urn:ietf:params:oauth:token-type:jwt">eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCJ9</extsec:securityToken>
</SOAP-ENV:Header>
</SOAP-ENV:Envelope>

REST-vastaus

HTTP/1.1 200
Content-Type: application/json; charset=utf-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCJ9
X-Road-Represented-Party: MUN/0000000-0
...

5. Palvelun kutsuminen JWT-autentikoinnilla

Kun palvelun muita muita endpointeja kutsutaan, palvelun tulee validoida kutsujan JWT-token. Esimerkkikutsuja löytyy Välitoimijan vastuut -sivun luvusta 4.

JWT-validoinnista saa lisätietoa myös referenssitoteutuksesta (GitHub, englanniksi)Avautuu uuteen ikkunaan..

Palveluntarjoaja voi toteuttaa autentikoinnin myös muulla kuin JWT-autentikoinnilla.