Identity provision via SSI

The IDP Kit supports retrieval of identity data from SSI wallets and verifiable credentials.

In this section I'm going to outline the principles of how OIDC authentication requests are translated to SSI/SIOP requests and the various options a user has to make such a request.

How it works

To understand how identity provision via SSI can be leveraged in an OIDC authentication flow, you may first want to recap on the basic principles of OIDC authentication.

OIDC via SSI

When using SSI and verifiable credentials as information source, the IDP Kit will derive the required credentials from the authentication request and redirect to the SSI wallet, requesting a presentation of the required credentials, via the OIDC/SIOPv2 presentation exchange protocol.

Once the SSI wallet responds with the requested presentation, the IDP Kit will verify the signature, challenge and compliance of the response with the requirements and optionally apply other verification policies, as defined in the IDP Kit configuration.

The verified credential data is then transformed into the response format requested by the application, which can be standard claims (name, email, etc.) or the verifiable presentation containing the raw credential data shared by the SSI wallet of the user.

This sequence diagram shows the OIDC code flow, leveraging identity provision via SSI using the OIDC/SIOPv2 protocol to obtain a credential presentation from an SSI wallet:

OIDC/SIOP code flow

Claiming vp_token

In this scenario, the client application requests the raw credential data, without mapping to standard OIDC claims, by specifying the custom vp_token claim or defining the vp_token scope in the authorization request.

vp_token Scope

By specifying the vp_token scope in the authorization request, the client application requests a verifiable presentation to be requested from the user and included in the user info response. The IDP Kit will determine the verifiable presentation request, which is sent to the SSI wallet, by the following sources in this order:

1. vp_token claim, specified by the client application as a custom claim object in the authorization request

2. Derived from vc_mappings defined in the IDP Kit claim configuration, based on the scopes and claims requested in the authorization request

3. VP token claim, configured in the default_vp_token_claim in the IDP Kit claim configuration

4. Empty verifable presentation, if none of the above applies. In this case only the user DID is verified (DID proof) and propagated into the user info as user ID.

vp_token Claim

The vp_token claim should be a presentation definition object, as defined in the specification of OIDC/SIOPv2.

The IDP simply forwards the presentation definition via the SIOPv2 protocol to a compatible SSI wallet. When the SIOP response is received, the presentation is verified and provided to the client application in the user info's vp_token property.

To use this authentication flow, the client application needs to construct the special vp_token claim and be able to interpret the presentation response. Verification of signatures, and compliance with the request is provided by the IDP Kit, such that the application can rely on the data received.

The following flow diagram outlines an OIDC code flow with vp_token claim:

Code flow with vp_token claim

Standard OIDC scopes, claims and claim mapping

In this scenario, the client application simply makes a standard OIDC authorization request, like any other OIDC compliant identity provider would expect it. E.g. the application could request the profile scope, to receive name, given name, family name, gender, date of birth, etc. of the user from the IDP Kit.

The IDP Kit maps the required claims to suitable credential types that contain the requested information and generates a SIOP request for the SSI wallet transparently, without the client application taking any notice.

Once the IDP Kit and the SSI Wallet have completed the presentation exchange and the presented credentials have been verified, the IDP Kit translates the received credential data into the standard user info claims requested by the application and provides it on the standard user info endpoint.

To use this flow, the client application needs no additional knowledge about the underlying protocol. In most cases, a simple configuration change would suffice to make an application connect to the IDP Kit and accept SSI identity data for user authentication, given that OIDC is already used as an authentication layer.

This flow diagram outlines an OIDC code flow with standard claim mapping using identity provision via SSI:

Code flow with standard claim mapping