Responsibilities of the service provider in authenticating an organisation using a shared subsystem

This article describes what the service provider should do when an organisation that uses a shared subsystem is authenticated.

The identification of the service consumer is different if the organisation in question is connected to the Data Exchange Layer via an intermediary’s Security Server and shared subsystem The shared subsystem has several organisations that must be identified according to a separate authentication process. You can find a description of the entire authentication process in a separate support article.

JWT authentication is an example solution. The service provider can also implement authentication in other ways.

This article describes the authentication process that uses JWT authentication.

The service provider is responsible for the following steps in the authentication process:

1. Authenticating the user.
2. Generating a JWT or other similar identifier if the user is authenticated.
3. Generating a response message.
4. Sending a response message to the service consumer.
5. Calling the service with JWT authentication or other similar authentication method.

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

• We recommend that your subsystem is service-specific, i.e., there is only one service per subsystem. Your service cannot be utilised via a shared subsystem if it does not fulfil this condition. Authentication cannot be used to identify which service you want to use, as access is normally granted per subsystem.
• Your service has one API endpoint for authenticating the service consumer’s user IDs.
• You have created and delivered unique user IDs to the intermediary representing the service consumer using a secure connection.

Example implementation: Finnish Environment Institute as a service provider As a service provider, the Finnish Environment Institute (Syke) enables the utilisation of its services through a shared subsystem. Syke has implemented a solution that allows the service provider's own subsystem to include more than one service. Syke has built a service-specific identification and access rights management solution, which allows them as a service provider to identify the user's organisation and rights on a service-specific basis. With service-specific authentication and access authorisation management, the service provider's subsystem does not have to be service-specific, but it can contain more than one service.

Responsibilities of the service provider in the different steps of the authentication process

1. Authenticating the user

The API endpoint you have added to the service will validate the user IDs included in the query message.

For authentication, the service must provide an endpoint that validates the caller’s user ID and password and returns a JWT identifier or other similar identifier to identify the user in the service’s other endpoints.

SOAP query

In the case of a SOAP service, implement the SOAP service called “authenticate”, which receives the calling organisation’s ID and password in a SOAP message:

<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

Implement the endpoint “POST /authenticate” in the REST service, which receives the calling organisation’s user ID and password in the query’s header section, for example:

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. Generating a JWT or other similar identifier if the user is authenticated

Generate a JWT identifier or other similar identifier if the user ID is valid. Otherwise, an error message will be returned to the sender. Please note that the service provider is responsible for validating the JWT identifier or other similar identifier.

3. Generating a response message

1. Add the service consumer organisation’s identifying data to the header section of the response message

SOAP response

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

REST response

Add the following line in the header section of the response message:

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

2. Add the JWT tag or other similar identifier that you generate for the service consumer in the header section of the response message

SOAP response

Add the Security Token extension to the header section of the response message. You can find instructions for implementing this in the NIIS documentation (GitHub)Opens in a new window..

REST response

Add the following line in the header section of the response message:

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

4. Sending a response message

Below, you can find an example of what a completed response message should look like when it contains all the necessary lines. Please note that the values in the examples are random and should be replaced with the correct values.

SOAP response

...
<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 response

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

5. Calling the service with JWT authentication

When other endpoints in the service are called, the service must validate the caller’s JWT token. You can find example calls in chapter 4 of the Responsibilities of the Intermediary document, which you can find by clicking this link.

You can find additional information about JWT validation in the reference implementation as well. You can find it by clicking this link (GitHub)Opens in a new window..

The service provider can also implement authentication with a method other than JWT authentication.