Gå direkt till innehållet.
Suomi.fi-informationsled

Mellanaktörens ansvar vid autentiseringen av en organisation som använder ett delat subsystem

I den här artikeln beskrivs som exempel vad en mellanaktör som representerar användaren av en tjänst ska göra när en organisation som använder ett delat subsystem autentiseras. Det är bra att komma ihåg att genomförandet och ansvar kan variera mellan olika tjänster.

Obs! Innan man tar i bruk det delade subsystemet bör man säkerställa att tjänsten som tas i bruk via Informationsled stöder det delade subsystemet. Beroende på vilken tjänst som används kan genomförandet av det delade subsystemet skilja sig från exemplet nedan och saker som ska beaktas.

Frågor som ska beaktas innan ett delat subsystem tas i bruk

Mellanaktören;

  • Ta reda på om tjänsten som tas i bruk tillåter användning av delat subsystemet
  • Bekanta dig med det autentiseringsförfarande som används i tjänsten
  • Kom överens om praxis med tjänsteleverantören

Identifieringsprocessen för den som utnyttjar tjänsten är annorlunda i en situation där organisationen i fråga har anslutits till Informationsleden via en mellanaktörs anslutningsserver och ett delat subsystem. En beskrivning av hela autentiseringsprocessen finns i en separat stödartikel.

Mellanaktören ansvarar för följande skeden:

  1. Förutsätt att de organisationer som bjuds in har en mTLS-förbindelse och identifiera organisationerna utifrån TLS-certifikatet.
  2. Lägg till uppgifter som specificerar organisationen i identifieringsförfrågan.
  3. Lägg till användarnamn till identifieringsförfrågan.
  4. Skicka en identifieringsförfrågan till tjänsten.
  5. Ersätt användarnamnen i identifieringsförfrågan med JWT-koden eller annan motsvarande tagg.
    • Beroende på tjänsteleverantörens autentiseringslösning kan också annan autentisering än JWT-autentisering användas.

Faserna 1–3 gäller den första enkäten (identifieringsförfrågan). Fas 4 gäller alla följande enkäter som skickas efter identifieringsförfrågan.

Se till att du har gjort följande innan du inleder autentiseringsprocessen:

  • Definiera anslutningsservern och datasystemet så att de använder mTLS-servercertifikatpraxis.
  • Definiera kundorganisationens och mellanaktörens datasystem för att använda mTLS servercertifikatpraxis. Mellan kundorganisationerna och mellanaktörens datasystem ska mTLS-servercertifikatpraxis (Mutual TLS convention) användas. Detta är viktigt för att kundorganisationen ska kunna verifieras på rätt sätt. Mer information om dokumentationen av referensgenomförandet finns bakom denna länk (GitHub, på engelska)Öppnas i ett nytt fönster..
  • Dessutom rekommenderas att mTLS konfigureras mellan anslutningsservern och datasystemet. Mer information om det hittar du i den separata stödartikeln.

1. Lägg till uppgifter som specificerar organisationen i identifieringsförfrågan

I identifieringsförfrågan ska specificerande uppgifter om den organisation som använder tjänsten ingå. Nödvändiga uppgifter är en unik kod som anger organisationens typ (member class) och en kod som identifierar organisationen, dvs. ett FO-nummer (member code).

Observera att identifieringsförfrågan ska genomföras enligt anvisningarna så att monitoreringen och loggningen lyckas korrekt.

SOAP-förfrågan

Lägg till Third Party Representation-tillägget i headerdelen i SOAP-enkäten. Anvisningar för att göra detta hittar du i NIIS dokumentation (på engelskaÖppnas i ett nytt fönster.).

REST-förfrågan

Lägg till följande rad i REST-förfrågans headerdel:

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

2. Lägg till användarnamn till identifieringsförfrågan

Varje organisation som använder tjänsten via ett delat subsystem behöver användarnamn för tjänsten som tjänsteleverantören skickar till mellanaktören. Lägg i samband med den första enkäten till användarnamn till identifieringsförfrågan för autentisering.

Observera att användarnamnen ska vara korrekta i identifieringsförfrågan så att tjänsteleverantören lyckas med autentiseringen.

SOAP-förfrågan

Lägg till användarnamnen i SOAP-förfrågans body-del enligt exemplet nedan:

<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-förfrågan

Lägg till användarnamnen i REST-förfrågans header-del enligt exemplet nedan:

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. Skicka en identifieringsförfrågan till tjänsten

Nedan ser du exempel på hur en färdig identifieringsförfrågan ska se ut när den innehåller alla nödvändiga rader.

SOAP-förfrågan

<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-förfrågan

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

När tjänsteleverantören lyckas med autentiseringen av identifieringsförfrågan får du en JWT-kod eller annan motsvarande tagg i svarsmeddelandet.

4. Ersätt användarnamnen i identifieringsförfrågan med JWT-koden eller annan motsvarande tagg

Ersätt de användarnamn (Member-Username och Member-Password) som skickats i identifieringsförfrågan med JWT-koden eller annan motsvarande tagg. I fortsättningen autentiseras kundorganisationen alltid med en JWT-kod eller annan motsvarande tagg i alla förfrågningar som skickas efter den första identifieringsförfrågan.

SOAP-förfrågan

Lägg till tillägget Security Token i header-delen i SOAP-förfrågan. Den innehåller en JWT-kod eller annan motsvarande tagg från tjänsteleverantören.

I NIIS dokumentationen (på engelska)Öppnas i ett nytt fönster. finns anvisningar för hur du genomför tillägget Security Token.

REST-förfrågan

Lägg till följande rad i REST-förfrågans header-del som skickas från datasystemet. Raden innehåller den JWT-kod eller annan motsvarande tagg du fått:

Authorization: Bearer <Token received from service provider>


Observera att i alla förfrågningar som skickas efter den första identifieringsenkäten ska headerdelen i förfrågningsmeddelandet alltså innehålla
1. Uppgifter som identifierar organisationen och
2. JWT-kod eller annan motsvarande tagg

Nedan ser du exempel på liknande förfrågningar i SOAP- och REST-format.

SOAP-förfrågan

<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-förfrågan

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
Uppdaterad: 1.4.2025

Är du nöjd med innehållet på denna sida?