In the Gateway project, external systems are authenticated using “JWT client authentication“ and authorized using “OAuth 2.0 Token Exchange“.

See also:

• JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants

• OAuth 2.0 Token Exchange

Prerequisites

Authorization is done by exchanging a SAML Assertion from Kombit STS with the Authorization Server on the Gateway environment.

In order to obtain SAML Assertions, please refer to the following resources:

• Digitaliseringskataloget: Adgangsstyring for systemer

• Digitaliseringskataloget: Sikkerhed - Hent Token fra Security Token Service

The integration requires an active service agreement in the Administration Module at ‘Serviceplatformen', between the vendor’s service consumer system (anvendersystem), and the data-owning organization regarding the Care Gateway service with entity id http://ehealth.sundhed.dk/service/CareGateway/1 .

The service agreement must include the ‘Care Delivery Reporter System’ system role.

Before exchange can take place, the client system’s public key must be registered in both 'Serviceplatformen' and in the KLG Authorization server.

Getting started

To get started with authorization for KLG complete the following checklist:

When the key is registered and the service agreement is approved the client system can get access tokens for KLG by following the procedure described in the following sections.

JWT Client Authentication

Prerequisites:

• The system is in possession of a Public/Private key pair.

  • This is the same as the service consumer system’s certificate in 'Serviceplatformen'

  • The public key must be registered in Keycloak as well

• The system has a client in Keycloak with a client_id.

• The system's Public Key is registered for the client.

In order to obtain access tokens from Keycloak, the system must provide a signed JWT (i.e. JWS) on each access token request to Keycloak.

The system issues the JWS and signs it with its private key.

See also jwt.io for a comprehensive list of software libraries for token signing.

The JWS must have the following fields in the header:

• alg: Signature Algorithm

• kid: Key ID

NOTE: The Key ID is the base64url encoded, SHA-256 digest (HASH), of the encoded public key. See also SAML Assertion to JWT Exchange | Obtaining the kid from a Public key

The JWS must have the following fields in the body:

• jti: JWT ID - Unique identifier for this token.

• iss: Issuer - Who created the token? (In this case, it is the client_id)

• sub: Subject - Whom the token refers to. (In this case, it is also the client_id)

• aud: Audience - What the token is intended for. (In this case, it is the keycloak realm info URL)

• iat: Issued at - When the token was created. (seconds since UNIX epoch)

• exp: Expiration time - When the token expires (seconds since UNIX epoch)

• nbf: Not valid before - When the token validity starts (seconds since UNIX epoch)

NOTE: The JWS is single-use only.

Example:

Obtaining the kid from a Public key

Obtaining the kid from a Public key is done in 3 steps. This is demonstrated with the following example, given a Public key:

Step 1. Getting the encoded bytes.

The encoded bytes are obtained by removing the tags -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, and all line separators. Then Base64 decode the resulting line as bytes. The hex representation of this applied to the above Public key is:

NOTE: line breaks are added for readability.

Step 2. Getting the SHA256 digest.

Apply the SHA256 algorithm to the bytes obtained in step 1 (not the hex string). In this example, the hex representation of the resulting bytes is:

Step 3. Encoding the digest.

The last step is to apply base64url encoding to the bytes obtained in step 2. The final result is then:

See example of using a tool for the calculation on https://github.com/trifork/klg-docs/issues/13

Requesting Access token with Token Exchange

The token exchange request is an HTTP POST request with content-type application/x-www-form-urlencoded

Body Parameters:

• client_id: The id of the requesting client.

• client_assertion_type: Always urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

• client_assertion: The JWS described in the previous section.

• grant_type: Always urn:ietf:params:oauth:grant-type:token-exchange.

• subject_issuer: The ID of the subject token issuer e.g. kombit-sts.

• subject_token_type: Always urn:ietf:params:oauth:token-type:saml2.

• subject_token: The Base64url encoded SAML Assertion issued by subject_issuer

The response is a standard OAuth 2.0 access token response with content-type application/json

Response Fields:

• access_token: The access token used for authentication on the FUT platform.

• expires_in: The time to live of the access token in seconds

• refresh_token: The refresh token used for requesting new access tokens

• refresh_expires_in: The time to live of the refresh token in seconds

Example

Request:

Response:

Requesting Access token with Refresh Token

Using a refresh token is like the initial token exchange request an HTTP POST request with content-type application/x-www-form-urlencoded

Body Parameters:

• client_id: The id of the requesting client.

• client_assertion_type: Always urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

• client_assertion: The JWS described in the previous section.

• grant_type: Always refresh_token.

• refresh_token: A valid refresh token acquired by a previous access token request.

NOTE: Remember that the JWS is single-use.

Example: