Introduction

Before connecting to the eHealth Infrastructure, client applications must:

1. The application must be registered in the eHealth login server (Keycloak), including redirect URLs. This is done using a service request (see Contact Information).

   1. The infrastructure provider registers and configures the application in the eHealth login server (KeyCloak), give a name, and has its redirection URLs approved and configured in KeyCloak

2. The application must implement the OIDC "Authorization Code Flow" to obtain tokens. (see OpenID Connect "code flow").

3. Choose the appropriate client type: confidential (e.g., server applications) or public (e.g., mobile or web apps). Confidential clients authenticate using passwords, while public clients require PKCE (Proof Key for Code Exchange). See PKCE (pronounced "pixi"). You can find more explanations on this topic here and here.

After completing these steps, the KeyCloak Authentification Server (AS) will delegate parts of the login process to other federated servers, but this is typically transparent to the client, assuming the login is handled within a standard web browser window that can manage redirects.

Client types

There are two main client types:

• Clinical Clients / Employee Solutions:

  • Used by healthcare professionals via SEB federated login.

  • Authenticate using organizational systems or Single Sign-On (SSO).

  • Example Certificate URL:
    https://saml.exttest.ehealth.sundhed.dk/auth/realms/ehealth/protocol/openid-connect/certs

• Citizen Clients / Citizens Solution:

  • Used by citizens via NemLogin federated login.

  • Example Certificate URL:
    https://saml.exttest.ehealth.sundhed.dk/auth/realms/nemlogin/protocol/openid-connect/certs

Each type follows a separate login flow and realm, resulting in two authorization URLs (more details in the “Authorization Server” section).

Therefore, if a system handles both clinical and citizen users, its token validation must support multiple certificate URLs.

Login Flow

Clinical Login

1. The clinician logs in via an organizational or municipality-specific SSO.

2. If an active session exists, the system performs automatic SSO.

Open

Login flow for federated clinical (regional or municipality) login

Citizen Login

1. First-time users authenticate via MitID through NemLogin.

2. The session can be resumed later using a stored Request Token (RT) secured by PIN or biometric data.

Open

Federated citizen login flow

If the client system supports it, they can store the RT (Request Token) and use it later to resume an authenticated session, based on a PIN code or biometric data. More details can be found in the Key Service overview, which involves selecting a PIN, registering a user/device/PIN via the Key Service, and resuming the session based on stored data by calling the Key Service.

Authorization Server Endpoints

1. Clinical:

   • Base URL: https://saml.${environment}.ehealth.sundhed.dk/auth/realms/ehealth

   • Example:
     https://saml.exttest.ehealth.sundhed.dk/auth/realms/ehealth

   • Session lifespan: 10 hours, 30 minutes idle.

2. Citizen:

   • Base URL: https://saml.${environment}.ehealth.sundhed.dk/auth/realms/nemlogin

   • Example:
     https://saml.exttest.ehealth.sundhed.dk/auth/realms/nemlogin

   • Session lifespan: 120 days, 1200 days idle.

Example Authentication Process

Step 1: Authentication Request

Send an HTTP GET request to the authorization endpoint:

It should be sent as a single line without spaces or new lines.

Parameters:

• response_type=code: Request an authorization code.

• client_id: The registered client ID.

• redirect_uri: Indicates the URL to return the user to after authorization is complete. This must be whitelisted in KeyCloak.

• state=1234zyx – A random string generated by your application, which you’ll verify later

• code_challenge: PKCE challenge string.

• code_challenge_method=S256 – either plain or S256, depending on whether the challenge is the plain verifier string or the SHA256 hash of the string. If this parameter is omitted, the server will assume plain.

When the authentication is complete, the browser is redirected back to the given "redirect_uri" (which must be whitelisted in the AS) including a "code" as a request parameter. This code must be used when calling the token endpoint afterwards.

Step 2: Token Exchange

Exchange the authorization code for tokens using a POST request:

Parameters:

The first four parameters are required, and the remaining are optional.

• 'organization_id' and 'care_team_id' can be used individually or in combination.

• 'patient_id' and 'episode_of_care_id' can also be used individually or in combination, but requires that 'care_team_id' is also present. More details on context switching can be found at Switching Context.

Access Token Usage

Include the Access Token in the HTTP header of subsequent API requests:

User Info and System Roles

Retrieve the user's system roles and context by querying the userinfo endpoint:

Example response includes a list of roles the user holds in the current session.

User info

The list in “roles” is the KeyCloak role names which can be mapped to system roles by doing a reverse lookup from groups, see Switching Context | Mapping from Role to Privileges.

Logout Process

To end a session, use end_session_endpoint found in the openid-configuration of the environment (e.g.: openid-configuration)

End the session using the logout endpoint:

This ensures the session is terminated securely.

Client Adapters

Keycloak (being the Authentification Server) has an extensive set of client adapters (libraries) for usage on various platforms and programming languages:

• Keycloak documentation: Securing Applications and Services Guide

Additional Notes

• Use Keycloak client adapters for streamlined implementation.

• Avoid wildcard characters in redirect URLs for security.