Go directly to contents.
Suomi.fi Data Exchange Layer

Responsibilities of the intermediary in authenticating an organisation using a shared subsystem

This article shows examples of what the intermediary acting on behalf of the service consumer should do when an organisation that uses a shared subsystem is authenticated. Please keep in mind that the implementation and responsibilities may vary by service.

Please note! Before introducing a shared subsystem, you must ensure that the service utilised through the Data Exchange Layer supports the shared subsystem. Depending on the service to be utilised, the implementation of a shared subsystem may differ from the example below and have different aspects to consider.

Considerations before deploying a shared subsystem

Intermediary;

• See whether the service you are deploying allows the use of a shared subsystem

• Familiarise yourself with the authentication method used in the service

• Agree on policies with the service provider

The authentication of the service consumer is different if the organisation in question is connected to the Data Exchange Layer via an intermediary’s ready-made Security Server and shared subsystem You can find a description of the entire authentication process in a separate support article.

The intermediary is responsible for the following steps:

  1. Requiring mTLS access from calling organisations and identifying organisations based on the TLS certificate.
  2. Adding the organisation’s identifying data to the identification query.
  3. Adding user IDs to the identification query.
  4. Submitting the identification query to the service.
  5. Replacing the user IDs in the identification query with a JWT identifier or other similar identifier.
  • Depending on the service provider's authentication solution, a different authentication method might be in use.

Steps 1–3 apply to the first query (identification query). Step 4 applies to all of the subsequent queries that are sent after the identification query.

Please make sure that you have done the following before starting the authentication process:

  • Configuring the Security Server and information system to use the mTLS server certificate policy.
  • Configuring the client organisation’s and intermediary’s information systems to use the mTLS server certificate policy. The mTLS server certificate policy (Mutual TLS convention) must be used between client organisations’ and the intermediary's information systems. This is important in order to authenticate the client organisation correctly. Additional information is available in the reference implementation’s documentation that you can find by clicking this link (GitHub)Opens in a new window..
  • Additionally, it is recommended to configure mTLS between the Security Server and the information system. You can find more information on this in a separate support article.

1. Adding the organisation’s identifying data to the identification query

The identification query must contain the identifying data of the organisation using the service. The required data are the unique member class of the organisation and the unique identifier of the organisation, i.e., the member code.

Please note that the identification query must be created according to the instructions so that monitoring and logging can be carried out correctly.

SOAP query

Add the Third Party Representation extension in the header section of the SOAP query. You can find instructions for implementing this in the NIIS documentationOpens in a new window..

REST query

Add the following line in the header section of the REST query:

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

2. Adding user IDs to the identification query

Each organisation using the service through a shared subsystem needs a user ID that the service provider will send to the intermediary. Add user IDs to the authentication query at the time of the first query for authentication.

Please note that the user IDs must be correct in the authentication query for the service provider to be able to authenticate themselves.

SOAP query

Add the user IDs to the body section of the SOAP query as shown below:

<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 query

Add the user IDs to the header section of the REST query as shown below:

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. Submitting the identification query to the service

Below, you can find examples of what a completed identification query should look like when it contains all the necessary lines.

SOAP query

<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 query

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

Once the identification query has been successfully authenticated at the service provider’s end, you will receive a JWT identifier or other similar identifier in a response message.

4. Replacing the user IDs in the identification query with a JWT identifier or other similar identifier

Replace the user IDs (Member-Username and Member-Password) sent in the identification query with the JWT identifier or other similar identifier. In the future, the client organisation will always be authenticated using the JWT identifier or other similar identifier. This applies to all queries sent after the initial identification query.

SOAP query

Add the Security Token extension containing the JWT identifier or other similar identifier obtained from the service provider to the header section of the SOAP query that is sent from the information system.

You can find instructions for implementing the Security Token extension in the NIIS documentation (GitHub)Opens in a new window..

REST query

Add the following line containing the JWT identifier or other similar identifier obtained from the service provider to the header section of the REST query that is sent from the information system.

Authorization: Bearer <Token received from service provider>

Please note that in all queries sent after the first identification query, the header section of the query message must contain:
1. the organisation’s identifying details and
2. the JWT identifier or other similar identifier

Below are examples of such SOAP and REST queries.

SOAP query

<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 query

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
Updated: 1/4/2025

Are you satisfied with the content on this page?