Introduction

Before a client system can connect with the eHealth Infrastructure, several steps must be followed:

1. The client application for the eHealth Infrastructure must implement an OpenID Connect "code flow" to log in and obtain a set of tokens.

2. The client application needs to be created and configured in the eHealth login server (KeyCloak), given a name, and have its redirection URLs approved and configured in KeyCloak.

3. Clients can be either confidential (like a server application) or public (like apps or web applications). Confidential clients use a password for authentication, while public clients must use PKCE (pronounced "pixi"). You can find more explanations on this topic here and here.

After completing these steps, the Authorization 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 and citizen clients. Each type follows its own 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.

Here are examples of certificate URLs for the INTTEST environment:

• Clinical clients: 
  https://saml.inttest.ehealth.sundhed.dk/auth/realms/ehealth/protocol/openid-connect/certs

• Citizen clients: 
  https://saml.inttest.ehealth.sundhed.dk/auth/realms/nemlogin/protocol/openid-connect/certs

Clinical logins

For clinical client applications, the login flow typically looks like this, although specifics can vary based on the user's organization (region or municipality).

Flow for federated clinical (regional or municipality) login

If there's already a session in SEB from the same browser, a single sign-on experience can occur.

Citizen logins (first time)

Citizen login flow may resemble the following:

Client systems for citizens initially encounter NemID presented through a federated login service from NemLogin. 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.

The goal is to offer an alternative, simpler "authentication" method to citizens securely.

Authorization Server Endpoints

Current active environments:

Clinical:

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

• https://saml.inttest.ehealth.sundhed.dk/auth/realms/ehealth

  • openid-configuration

  • The session lifespan is 10 hours (30 minutes idle)

Citizen:

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

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

  • openid-configuration

  • The session lifespan is 1200 days (120  days idle)

Client Adapters

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

• Keycloak documentation: Securing Applications and Services Guide

Example authentication

If, for some reason, you can't use a keycloak client adapter - an example URL for an authentication request using HTTP GET, written in a readable format is shown below. It should be sent as a single line without spaces or new lines.

Authentication request

 http://saml.inttest.ehealth.sundhed.dk/auth/realms/ehealth/protocol/openid-connect/auth?
  response_type=code&
  client_id=<client_id>&
  redirect_uri=<redirect_uri>&
  scope=openid+profile&
  state=<state>&
  nonce=<nonce>&
  code_challenge=<challenge>&
  code_challenge_method=S256

The parameters have the following meaning:

• response_type=code – indicates that your server expects to receive an authorization code

• client_id= – A client ID that is registered on the Authorization Server

• redirect_uri= – Indicates the URL to return the user to after authorization is complete, such as org.example.app://redirect or a traditional URL for a web app https://app.example.org/redirect.

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

• code_challenge=XXXXXXXXX – The code challenge generated as previously described

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

Example token exchange

An example of the following POST request to obtain a context-aware access token is shown below.

Authorization code exchange

POST /auth/realms/ehealth/protocol/openid-connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

  grant_type=refresh_token&
  refresh_token=<refresh_token>&
  client_id=<client_id>&
  client_secret=<client_secret>&
  organization_id=<organization_id>&
  care_team_id=<care_team_id>&
  patient_id=<patient_id>&
  episode_of_care_id=<episode_of_care_id>

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.

Use of Access Token

The Access Token is sent as an HTTP header (See https://jwt.io/introduction/ for a further introduction) in all service requests in this form (where "<access token>" is replaced by the specific Access Token):

Authorization: Bearer <access token>

Determining System Roles Available in the Current Context

The list of system roles available with the currently selected context can be obtained by querying the AS using an HTTP GET with the current Access token at the path /auth/realms/ehealth/protocol/openid-connect/userinfo. The following shows an example request in the realm ehealth for a clinical user:

User info

GET https://saml.exttest.ehealth.sundhed.dk/auth/realms/ehealth/protocol/openid-connect/userinfo
Response:
{
    "sub": "...",
    "email_verified": true,
    "cpr": "...",
    "roles": [
        "Service and Logistics",
        "Incident Manager",
        "Report User",
        "Questionnaire Editor",
        "Catalogue Responsible",
        "Clinical Viewer",
        "Care Team Administrator",
        "Clinical Administrator",
        "Catalogue Annotator",
        "Terminology Administrator",
        "Monitoring Adjuster",
        "Citizen Enroller",
        "Monitoring Assistor",
        "Contract Responsible",
        "Order Placer",
        "Incident Reporter",
        "Clinical Supporter"
    ],
    "preferred_username": "...",
    ...
}

The list in “roles” is the KeyCloak role names which can be mapped to system roles by doing a reverse lookup from groups, see https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/270991361/Switching+Context#Mapping-from-Role-to-Privileges.

Logout

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

Example:

Logout

GET /auth/realms/ehealth/protocol/openid-connect/logout HTTP/1.1
Authorization: Bearer <access_token>

You can redirect the browser to /auth/realms/ehealth/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri, which logs you out if you have an SSO session with your browser.