API integration
This page contains an overview of the API requests needed for VMs to integrate with the Digidentity Trust Centre. The API requests in this integration follow the Open ID Connect authorisation code flow. For the remainder of this page, this will be referred to as the 'OIDC flow'.
For our full technical specification, please visit https://docs.digidentity.com/
Prerequisites¶
Before users can log in via the OIDC flow, they must first have registered with the CAB and created their certificate in the Digidentity app. For more information about the invitation and registration process, please see: Test Accounts.
Login options¶
Digidentity offers two different variations of the OIDC flow: Passwordless login, and Web login.
Passwordless login flow¶
This flow allows users to log in without needing to visit the Digidentity web page. This is our recommended solution, and can be used for both web apps and non-web apps.
sequenceDiagram
participant USR as End-user
participant CFE as VM<br>frontend
participant CBE as VM<br>backend
participant DBE as Digidentity<br>backend
USR -->> CFE: User requests access<br>to security-related RMI
CFE -->> CBE: Log in with Digidentity
CBE ->>+ DBE: Authorisation request (1)
DBE ->>- CBE: Login URL and<br>authorisation code
CBE -->> CFE: Convert Login URL<br>to QR code
CBE ->>+ DBE: Poll for access token<br>with authorisation code (2)
USR -->> CFE: Scan QR code
USR -->> USR: Enter PIN in<br>Digidentity app
DBE ->>- CBE: Access token
CBE ->>+ DBE: Request user info<br>with access token (3)
DBE ->>- CBE: SERMI UID attributes
CBE -->> CFE: Update frontendWeb login flow¶
This flow requires users to be redirected to the Digidentity web page to log in. This flow is only suited for web apps.
sequenceDiagram
participant USR as End-user
participant DFE as Digidentity<br>webpage
participant CFE as VM<br>webpage
participant CBE as VM<br>backend
participant DBE as Digidentity<br>backend
USR -->> CFE: User requests access to security-related RMI
CFE ->>+ DFE: Log in with Digidentity<br>via hyperlink (1)<br>(Authorisation request)
USR -->> DFE: Scan QR code
USR -->> USR: Enter PIN in<br>Digidentity app
DFE ->>- CFE: Callback with<br>authorisation code
CFE -->> CBE: Retrieve authorisation code<br>from callback params
CBE ->>+ DBE: Request access token<br>with authorisation code (2)
DBE ->>- CBE: Access token
CBE ->>+ DBE: Request user info<br>with access token (3)
DBE ->>- CBE: SERMI UID attributes
CBE -->> CFE: Update webpageAPI requests¶
The following three API requests make up the OIDC flow. These vary slightly depending on which login option is in use (Web login or Passwordless login).
1. Authorisation request¶
The authorisation request tells the Digidentity platform which VM the user is logging into and the user information the VM requires.
- Web login: This request can be embedded in the RMI portal as a hyperlink. Users click the link to redirect to the Digidentity web page and log in
- Passwordless login: This request is sent from the VM's backend to retrieve a QR code URI and its paired authorisation code. The URI is displayed to the user in the RMI portal as a QR code (or button with embedded deeplink), and the authorisation code is used for the token request
Please note
To retrieve UID attributes, the following scopes must be provided in the authorisation request:
- The product scope provided by our team during onboarding (16-character alphanumeric string)
- The openid scope for access to the user_info endpoint
- The sermi scope to retrieve the UID attributes from the user_info response
For example:
2. Token request¶
The token request exchanges the authorisation code from the user's successful login for an access token.
- Web login: Once logged in, the user is redirected to the callback endpoint (redirect_uri) at the RMI portal with an authorisation code. The token request should be configured to trigger automatically each time a user arrives at this endpoint
- Passwordless login: Once the QR code has been displayed to the user in the RMI portal, the token endpoint is polled using the authorisation code from the authorisation request. An access token is returned once the user has entered their PIN in the Digidentity app
3. User info request¶
The user info request returns a set of UID attributes representing the user without exposing their personal information. Two sets of UIDs are possible in the response:
- IOE set: Returned when an IOE logs into the RMI Portal directly. This is the most common use-case
- RSSE set: Returned when an RSSE logs into the RMI Portal with chain authorisation from an IOE. In this case, UIDs are returned for both the IOE and RSSE (the CABUID here referring to the CAB that granted the IOE authorisation)
{ "sub": "e6x3a4mp-49l2-66ps-94ef-u39455005d8o", "cabuid": "EXA/NL/1234/1EXA2MP34LE5", "iouid": "EXAMPLEIO/WALDORPSTRAAT13FTHEHAGUE2521CA/NL123456789B01", "ioeuid": "NL/EXAMPLECAB/1234567890B", "rssuid": "EXAMPLERSS/WALDORPSTRAAT13FTHEHAGUE2521CA/NL987654321B02", "rsseuid": "NL/EXAMPLECAB/9876543210D" }
Allowlisting¶
When moving to Digidentity's production environment, VMs using the Web login flow will need to have their production redirect_uri(s) allowlisted.
Allowlisting adds further security to the Trust Centre integration, ensuring that employees may only be redirected to a specific set of callback endpoints defined by the VM. Where an authorisation request contains a redirect_uri that is not allowlisted, employees logging into the RMI portal will not be redirected (remaining instead on the Digidentity webpage).
redirect_uri(s) will be requested by our Implementation team during production onboarding. Allowlisting is not required in the pre-production environment.