OpenID Connect

OpenID Connect (OIDC) is an authentication protocol based on the OAuth 2.0 specifications. While OAuth 2.0 is about resource access and sharing, OIDC is all about end-user authentication.

MIRACL Trust is a standards-compliant OpenID Connect provider. You can use any OIDC Relying Party Library to integrate with MIRACL Trust. For a list of certified OpenID Connect Libraries, see https://openid.net/developers/certified-openid-connect-implementations/ .

To use Custom User Verification with OpenID Connect (OIDC), you must set up a Custom Verification URL in the MIRACL Trust Portal. This Custom Verification URL is needed for the verification of the User ID after the end user starts their registration. When the end user’s User ID is verified, you must request the Verification URL to be sent from the platform (as described in Implement the Verification ).

Note: Custom Verification URL is different from Verification URL.

Custom Verification URL is the registration URL in your system that you set up in the MIRACL Trust Portal.

Verification URL is the platform-issued URL that is used to transfer the verification to the platform, finishing the verification flow.

If the registration is successful, the enrolment process is completed. End users can now authenticate using the PIN chosen for the device. They can go through the verification process for each device they want to use for authentication or use QuickCode , if enabled, to enrol additional devices using the already enrolled one.

## Implement the Verification

When the end user’s User ID is verified, you must request the Verification URL to be sent from the platform. The Verification URL is generated by making an authenticated POST request to <https://<PROJECT_DOMAIN>/verification>.

curl \
    --request POST \
    --user "${CLIENT_ID}:${CLIENT_SECRET}" \
    --data '{
        "userId": "'"${USER_ID}"'",
        "deviceName": "'"${DEVICE_NAME}"'",
        "clientId": "'"${CLIENT_ID}"'",
        "redirectURI": "'"${REDIRECT_URI}"'",
        "expiration": "'"${EXPIRATION}"'",
        "scope": ["openid", "email"],
        "delivery": "no"
    }' \
    https://${PROJECT_DOMAIN}/verification

With the following response:

{
  "verificationURL": "https://<PROJECT_DOMAIN>/verification/confirmation?user_id=<USER_ID>&code=<CODE>"
}

All values are redacted.

The end user must follow the URL from the response to enrol a new device.

See MIRACL Trust Backend API for more details.

# Flow

sequenceDiagram actor User Agent participant RPA as Relying Party Application participant MIRACL Trust User Agent ->> MIRACL Trust: Request verification MIRACL Trust -->>+ RPA: Redirect to the Custom Verification URL on record RPA ->> RPA: Verify user RPA ->>- MIRACL Trust: Provide verification MIRACL Trust -->> RPA: Return Verification URL RPA -->> User Agent: Deliver Verification URL User Agent ->> MIRACL Trust: Open Verification URL MIRACL Trust -->> User Agent: Enrol device

Relying Party Application is your application’s back end.

When a client requests access to a protected resource, the Relying Party Application redirects the end user to the MIRACL Trust Authorisation Page to begin authentication via OpenID Connect.

If the device is not yet registered, the end user is redirected to a Custom Verification URL. The Relying Party Application then handles the identity verification and sends it to the MIRACL Trust API, which returns a Verification URL. When the end user opens it, the verification is complete and the device is registered.

With the device registered, the end user can authenticate using the PIN associated with their registered device.

Once authentication is successful, the end user is directed to your OIDC Redirect URL along with the Access Code. The Relying Party Application then exchanges this Access Code for ID and Access tokens, confirming that the authentication was successful. This process may lead to creating a session on the back end, thereby granting the end user access to the protected resource.