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

All applications who are registered in the We Are IDP, can make use of the HTI token flow. The flow is show below:

All applications are first directed to the We Are login flow. There the user needs to choose a valid IDP. For now supported are ACM/IDM and NUTS via Microsoft Authenticator. When selecting an IDP the user is directed to either the NUTS OIDC flow or ACM/IDM Solid OIDC flow. Upon authentication a token will be generated and provided to the We Are Platform. There the token will be unpacked and the webId will be extracted and a new token is created: the HTI-token. This token contains the webId in the sub, which is the necessary information that the application (Welldata/Zipster/Selfcare/GG) needs to start the Access Request flow to acces the pod of the user.

We describe the complete flow with as example the Welldata application:

User initiates login

The We Are login 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 We Are

The backend initiates a redirect of the user to We Are and We Are will then redirect the user to the IDP which can authenticate the user:

redirect GET https://we-are-acc.vito.be/nl/hti/launch?client_id=&redirect_uri=
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 parameters for the HTI flow passed to We Are are:

• client_id: Identifies the client application that wants to start the We Are login flow. This client needs to be registered in the We Are IDP.
• redirect_uri: the redirect URI to which the users needs to be redirected back upon completion of authentication.

Next We Are will forward the user to the authentication endpoint of the IDP passing the following parameters:

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

We Are creates the HTI token and passes it to the Welldata application

Next step the HTI token is created with the corresponding webId in the sub of the HTI token. The token is then passed via a post to the Welldata application and directs the user back to the redirect URL of Welldata.

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