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

Välitoimijan vastuut jaettua alijärjestelmää käyttävän organisaation autentikoinnissa

Tällä sivulla kuvataan esimerkkinä, mitä palvelun hyödyntäjää edustavan välitoimijan tulee tehdä, kun jaettua alijärjestelmää käyttävä organisaatio autentikoidaan. On hyvä pitää mielessä, että toteutus ja vastuut voivat vaihdella palveluittain.

Huom. Ennen jaetun alijärjestelmän käyttöönottoa tulee varmistaa, tukeeko Palveluväylän kautta hyödynnettävä palvelu jaettua alijärjestelmää. Riippuen hyödynnettävästä palvelusta, jaetun alijärjestelmän toteutus voi erota alla olevasta esimerkistä ja huomioon otettavista asioista.

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

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

Palvelun hyödyntäjän autentikointiprosessi on erilainen tilanteessa, jossa kyseinen organisaatio on liitetty Palveluväylään välitoimijan valmiin liityntäpalvelimen ja jaetun alijärjestelmän kautta. Kuvaus koko autentikointiprosessista.

Välitoimijan vastuulla ovat seuraavat vaiheet:

  1. Edellytä kutsuvilta organisaatioilta mTLS-yhteyttä ja tunnista organisaatiot TLS-sertifikaatin perusteella
  2. Lisää tunnistautumiskyselyyn organisaation yksilöivät tiedot
  3. Lisää tunnistautumiskyselyyn käyttäjätunnukset
  4. Lähetä tunnistautumiskysely palveluun
  5. Korvaa tunnistautumiskyselyn käyttäjätunnukset JWT-tunnisteella tai muulla vastaavalla tunnisteella
    • Riippuen palveluntarjoajan autentikointiratkaisusta, käytössä voi olla myös jokin muu kuin JWT-autentikointi

Vaiheet 1–3 koskevat ensimmäistä kyselyä (tunnistautumiskyselyä). Vaihe 4 koskee kaikkia seuraavia kyselyitä, jotka lähetetään tunnistautumiskyselyn jälkeen.

Ennen autentikointiprosessin aloittamista:

  • Määrittele liityntäpalvelin ja tietojärjestelmä käyttämään mTLS-palvelinvarmennekäytäntöä.
  • Määritä asiakasorganisaation ja välitoimijan tietojärjestelmät käyttämään mTLS palvelinvarmennekäytäntöä. Asiakasorganisaatioiden ja välitoimijan tietojärjestelmien välillä tulee käyttää mTLS-palvelinvarmennekäytäntöä (Mutual TLS convention). Tämä on tärkeää, jotta asiakasorganisaatio voidaan todentaa oikein. Lisätietoa saatavilla referenssitoteutuksen dokumentaatiossa löydät tämän linkin takaa (GitHub, englanniksi)Avautuu uuteen ikkunaan..
  • Lisäksi mTLS on suositeltavaa konfiguroida liityntäpalvelimen ja tietojärjestelmän välille, josta lisätietoa löydät erillisestä tukiartikkelista.

1. Lisää tunnistautumiskyselyyn organisaation yksilöivät tiedot

Tunnistautumiskyselyn tulee sisältää tieto palvelua käyttävän organisaation yksilöivistä tiedoista. Tarvittavat tiedot ovat organisaation tyypin ilmaiseva uniikki tunnus (member class) ja organisaation yksilöivä tunnus, eli Y-tunnus (member code).

Huomaa, että tunnistautumiskysely tulee toteuttaa ohjeiden mukaisesti, jotta monitorointi ja lokitus onnistuvat oikein.

SOAP-kysely

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

REST-kysely

Lisää REST-kyselyn header-osaan seuraava rivi:

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

2. Lisää tunnistautumiskyselyyn käyttäjätunnukset

Jokainen jaetun alijärjestelmän kautta palvelua käyttävä organisaatio tarvitsee palveluun käyttäjätunnukset, jotka palveluntarjoaja lähettää välitoimijalle. Lisää käyttäjätunnukset tunnistautumiskyselyyn ensimmäisen kyselyn yhteydessä autentikointia varten.

Huomaa, että käyttäjätunnusten tulee olla tunnistautumiskyselyssä oikein, jotta autentikointi onnistuu palveluntarjoajan päässä.

SOAP-kysely

Lisää käyttäjätunnukset SOAP-kyselyn body-osaan alla olevan esimerkin mukaisesti:

<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

Lisää käyttäjätunnukset REST-kyselyn header-osaan alla olevan esimerkin mukaisesti:

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

3. Lähetä tunnistautumiskysely palveluun

Alla näet esimerkit, miltä valmiin tunnistautumiskyselyn tulisi näyttää, kun se sisältää kaikki tarvittavat rivit.

SOAP-kysely

<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">
    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>MUN</repr:partyClass>
            <repr:partyCode>0000000-0</repr:partyCode>
        </repr:representedParty>
        <xrd:userId>test</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <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

POST /r1/FI-TEST/GOV/8765432-1/ProviderSubsystem/ProviderServiceCode/authenticate HTTP/1.1 
Content-Type: application/json; charset=utf-8 
Accept: application/json 
X-Road-Client: FI-TEST/COM/1234567-8/TestClient 
X-Road-Represented-Party: MUN/0000000-0 
Member-Username: randomuser123 
Member-Password: password123

Kun tunnistautumiskyselyn autentikointi onnistuu palveluntarjoajan päässä, saat vastaussanomassa JWT-tunnisteen tai muun vastaavan tunnisteen.

4. Korvaa tunnistautumiskyselyn käyttäjätunnukset JWT-tunnisteella tai muulla vastaavalla tunnisteella

Korvaa tunnistautumiskyselyssä lähetetyt käyttäjätunnukset (Member-Username ja Member-Password) JWT-tunnisteella tai muulla vastaavalla tunnisteella. Asiakasorganisaatio autentikoidaan jatkossa aina JWT-tunnisteen tai muun vastaavan tunnisteen avulla kaikissa kyselyissä, jotka lähetetään ensimmäisen tunnistautumiskyselyn jälkeen.

SOAP-kysely

Lisää tietojärjestelmästä lähtevän SOAP-kyselyn header-osaan Security Token -laajennos, joka sisältää palveluntarjoajalta saadun JWT-tunnisteen tai muun vastaavan tunnisteen.

Ohjeet Security Token -laajennoksen toteuttamiseen löydät NIIS:in dokumentaatiosta (GitHub, englanniksi)Avautuu uuteen ikkunaan..

REST-kysely

Lisää tietojärjestelmästä lähtevän REST-kyselyn header-osaan seuraava rivi, joka sisältää saamasi JWT-tunnisteen tai muun vastaavan tunnisteen:

Authorization: Bearer <Token received from service provider>

Huomaa, että kaikissa kyselyissä, jotka lähetetään ensimmäisen tunnistautumiskyselyn jälkeen, kyselysanoman header-osan tulee siis sisältää

1. Organisaation yksilöivät tiedot ja
2. JWT-tunniste tai muu vastaava tunniste

Alla näet esimerkit tällaisista SOAP- ja REST-muotoisista kyselyistä.

SOAP-kysely

<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">
    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>MUN</repr:partyClass>
            <repr:partyCode>0000000-0</repr:partyCode>
        </repr:representedParty>
        <extsec:securityToken tokenType="urn:ietf:params:oauth:token-type:jwt">eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCJ9</extsec:securityToken>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
    <!-- Below API specific request params -->
        ...
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

REST-kysely

POST /r1/FI-TEST/GOV/8765432-1/ProviderSubsystem/ProviderServiceCode/authenticate HTTP/1.1 
Content-Type: application/json; charset=utf-8 
Accept: application/json 
X-Road-Client: FI-TEST/COM/1234567-8/TestClient 
X-Road-Represented-Party: MUN/0000000-0 
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCJ9
Päivitetty: 1.4.2025

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