Excerpt
Description of how client application login to the eHealth Infrastructure.

Table of Contents

maxLevel	7
minLevel	1

Introduction

Before a client system can interface connect with the eHealth Infrastructure a set of items , several steps must be carried out and complied withfollowed:

...

The client application

...

for the eHealth Infrastructure must implement an OpenID Connect "code flow" to log in

...

and

...

obtain a set of tokens.

...

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

Info

Information on redirect URL.

These URIs specifies where client sends (redirects) their users to to after log-ins/log-outs/refresh. The URLs that the Keycloak shall redirects to shall be whitelisted. The URLs shall be specific and may not contain ’wildcards’ (*) as this can be a security risk (see Securing Applications and Services Guide (keycloak.org)). This could be pages like ‘/login', Pay attention to the redirect URLs.

The redirect URLs are the addresses where the client sends its users after they log in, log out, or refresh. These URLs must be approved, specific, and not contain wildcards (*), which could pose a security risk. Examples include the '/login' and '/login-landing' page which are used when pages where users are redirected to after logged in and logged out.

...

logging in or out. Information on redirect URL.

See Securing Applications and Services Guide (keycloak.org)).

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

Client types

Clients currently comes in two flavors. Clinical- There are two main client types: clinical and citizen clients. Each type uses follows its own login flow and realm which results , resulting in two authorization url's (see the section Authorization Server for further informationURLs (more details in the “Authorization Server” section).

As a result: If clients (and server applications) Therefore, if a system handles both clinical and citizen users, then its token validation must be able to handle support multiple certificate url'sURLs.Example

Here are examples of certificate url's URLs for the inttest 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 it is expected that , the total login flow will look somewhat typically looks like this. Details , although specifics can vary depending based on the user's organization of the user (region or municipality).

...

Federated clinical login flowFlow for federated clinical (regional or municipality) login

If there is 's already a session in SEB from the same browser, then a single sign-signon on experience can be realizedoccur.

Citizen logins (first time)

For citizens, a similar Citizen login flow could look like thismay resemble the following:

...

Client systems for citizens will in their (initial) login be met by NemID, which is presented via initially encounter NemID presented through a federated login service from NemLogin. If the client system is running on a platform that supports it, it will be possible to they can store the RT and apply this (Request Token) and use it later to resume an authenticated session, based on either pin a PIN code or biometric data. Details of this is More details can be read on found in the Key Service overview, but in essence it which involves selecting a PIN, registering a user/device/PIN via the Key Service, and resuming the session based on stored data and by calling the Key Service.

The aim of this goal is to make offer an alternative - but , simpler - "authentication" available method to citizens in a secure mannersecurely.

Authorization Server Endpoints

Current active environments:

Clinical:

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

https://saml.inttest.ehealth.sundhed.dk/auth/realms/ehealth
- openid-configuration
- Session The session lifespan is 10 hours (30 minutes idle)

Citizen:

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

https://saml.inttest.ehealth.sundhed.dk/auth/realms/nemlogin
- openid-configuration
- Session 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 newlinesnew lines.

Authentication request

Code Block

language	bash

 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

...

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 tradition traditional URL for a webapp 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

Code Block

language	bash

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):

...

Info
Access Tokens and Refresh Tokens are so-called "opaque tokens" but maybe in JWT format. Client systems must not assume this and the format of AT and RT may change without notice.

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 a 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 of eHealth for a clinical user:

...

User info

Code Block

language	js

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

Code Block

language	bash

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

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

...

Versions Compared

Old Version 27

New Version Current

Key

Introduction

Client types

Clinical logins

Citizen logins (first time)

Authorization Server Endpoints

Current active environments:

Client Adapters

Example authentication

Authentication request

Example token exchange

Authorization code exchange

Use of Access Token

Determining System Roles Available in the Current Context

User info

Logout

Page Comparison

Versions Compared

Old Version 27

New Version Current

Key

Introduction

Client types

Clinical logins

Citizen logins (first time)

Authorization Server Endpoints

Current active environments:

Client Adapters

Example authentication

Authentication request

Example token exchange

Authorization code exchange

Use of Access Token

Determining System Roles Available in the Current Context

User info

Logout