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.

Digidentity offers two different variations of the OIDC flow which allow users to log in in different ways:

Web login redirects users from the VM's RMI portal to the Digidentity web page to log in
Users are sent to the Digidentity web page using a static link, and are returned back to the VM with an authorisation code once they have logged in. The VM's backend then uses the authorisation code to request an access token directly from the Digidentity backend

Passwordless login allows users to log in by scanning a QR code displayed directly in the VM's RMI portal, then entering their PIN in the Digidentity app
The VM's backend requests a temporary QR code from the Digidentity backend to display to the user. Each QR code is paired with a unique authorisation code, which the VM's backend uses to poll Digidentity for an access token. Once the user scans the QR code and enters their PIN, the access token is returned

Please note

If your application requires single sign-on functionality, we advise that you work with the Web login flow, as SSO is not currently supported via Passwordless login.

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

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:

e9x4a6m254p663l4 openid sermi

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

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

{
    "sub": "e2x0a6mp-37l0-42ps-94ef-u69755438d3o",
    "cabuid": "EXA/NL/1234/1EXA2MP34LE5",
    "iouid": "EXAMPLEIO/WALDORPSTRAAT13FTHEHAGUE2521CA/NL123456789B01",
    "ioeuid": "NL/EXAMPLECAB/1234567890B"
}

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.