WellData Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

User Authentication

The OIDC/SOLID-OIDC specification defines how owners of the pods need to authenticate towards an IDP and how resource servers can verify the identity of pod owners based on that authentication. The SOLID-OIDC flow is described in detail here

For the Welldata implementation we filled in the correct endpoints for our ACC environment.

User initiates login

The Solid OIDC flow is initiated by the user, triggering a login action on the Welldata Frontend application

Calling backend

In the call from the frontend to the backend the redirect url should be passed to which the user should return after the Solid OIDC flow is completed:

https://<backend>/login?redirectUrl=<front end redirecturl>

Redirect to IDP

The backend initiates a redirect of the user to the IDP which can authenticate the user:

https://authenticatie-ti.vlaanderen.be/op/v1/auth?client_id=<>&scope=openid+offline_access+webid+rrn&response_type=code&redirect_uri=<backend-url>/oidc-redirect&code_challenge<>&state=<>&code_challenge_method=S256&prompt=consent

The folowing parameters are passed in the call

• client_id: Identifies the client application that is making the request. This is assigned by the identity provider (in this case, authenticatie-ti.vlaanderen.be).
• scope: Specifies the access rights the application is requesting. In this case:
  • openid: Required for OIDC authentication.
  • offline_access: Allows obtaining a refresh token for long-term access.
  • webid: Requests the WebID of the user (used in Solid).
  • rrn: Likely requests the Belgian national registry number (Rijksregisternummer, RRN).
• response_type: Determines the type of response expected. We need to pass code , which means the request follows the Authorization Code Flow, where the authorization server returns a one-time code that must be exchanged for an access token.
• redirect_uri: The URL to which the authorization server will send the user after authentication. This must be pre-registered with the identity provider to prevent abuse.
• code_challenge: A hashed version of a secret (code_verifier) used in PKCE (Proof Key for Code Exchange). Prevents authorization code interception attacks.
• state: A random string generated by the client to maintain state between the request and response. Helps prevent CSRF (Cross-Site Request Forgery) attacks.
• code_challenge_method: Specifies how the code_challenge was generated. S256 means the SHA-256 hash of the code_verifier was used.
• prompt:Controls whether the authentication page should always prompt for user consent. consent forces the user to explicitly approve the request.

User prompt for credentials and authenticates

In the next 2 steps the user is prompted to authenticate himself using credentials.

Authorization code is exchanged with the backend

After authentication the user is redirected with a call to the Welldata backend.

https://<backend>/oidc-redirect?code=<>&state=<>

With this call 2 parameters are passed:

• code: this parameter needs to be exchanged by the backend for a real access token and id token.
• state

Exchange authorization code for tokens

Next call is a post to the IDP broker to exchange the authorization code for the right tokens

https://authenticatie-ti.vlaanderen.be/op/v1/token body {grant_type=authorization_code&code=<>&redirect_uri=<frontend>&client_id=<>&code_verifier=<>}

The following parameters in the body are required for this call:

• grant_type: this should be authorization_code, as we are doing the authorization code flow.
• code: the authorization code received from the previous call
• redirect_uri: the frontend redirect url
• client_id: the ACM/IDM clientId of the Welldata Backend.
• code_verifier

Return token and user is authenticated

The IDP broker will now return the access token and id token of the user and the user is logged in.

Example implementation in We Are Demo Application

The We Are consortium developed a demo application showcasing all the different steps necessary to read, write and share resources in a pod.

Starting an authentication flow from the frontend application is explained in the Authentication part of the front end demo application, which can be found here.

This angular front end app will then redirect the user to loginendpoint of the We Are Backend application. In order to successfully start the login flow, the right environment variables need to be set on the backend application:

CITIZEN_OIDC_CLIENT_ID
CITIZEN_OIDC_CLIENT_SECRET