Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 19 Next »

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

  • A client application to the eHealth Infrastructure must implement an OpenID Connect "code flow" in order to login and get a set of tokens.
  • A client application must be created and setup in the login server and assigned a name, and the URL's used to redirect back to the client must be whitelisted.
  • A client can be either confidential (like a server application) or public (like an app or a web application). Confidential clients authenticate themselves with a password. Public client must use PKCE (pronounced "pixi"). Explanations can be found many places, for instance here and here.

Having completed these bullets, the Authorization Server (AS) will delegate parts of the login to potentially other federated servers, but that is transparent for the client (provided the login is handled by a generic browser window that can handle redirects).

Client types

Clients currently comes in two flavors. Clinical- and citizen clients. Each type uses its own login flow and realm which results in two authorization url's (see the section Authorization Server for further information).

As a result: If clients (and server applications) handles both clinical and citizen users, then token validation must be able to handle multiple certificate url's.
Example of certificate url's for the inttest environment:

Clinical logins

For clinical client applications it is expected that the total login flow will look somewhat like this. Details can vary depending on the organization of the user (region or municipality).


Federated clinical login flow

Citizen logins (first time)

For citizens, a similar login flow could look like this:

Federated citizen login flow



Authorization Server

Current active environments:

Clinical:

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

Citizen:

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

Client Adapters

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

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

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

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.




  • No labels