OpenID4VCI Workflow

Overview

The OpenID4VCI specification is an open standard developed by the OpenID Foundation. It leverages the OpenID protocol to support verifiable credentials issuance and management. MATTR VII currently supports the OpenID4VCI workflow for issuing CWT, Semantic CWT, JSON credentials as well as mDocs.

To support a variety of use cases and implementations, this protocol supports integration with existing data systems and application of custom business logic as part of the issuance workflow.

If you are unfamiliar with OpenID Connect, the identity protocol underpinning the OpenID provisioning capability, there are many excellent guides available online such as this guide from Google, or this guide from Mozilla.

Workflow overview

Creating a Credential offer

The workflow begins when an issuer creates what is referred to as a credential offer, used to share important information with the holder’s digital wallet. This includes the credential’s issuer, what it includes and how to claim it. The OID4VCI specification defines a method for a digital wallet to discover this information in a standardised and interoperable way.

Credential offers are created by making a request to a MATTR VII endpoint that returns an offer URI. This URI is shared with the intended holder as a QR code, wallet push notification or a deep-link. The offer only includes metadata required to initiate the issuance process, and the actual credential is only created and signed later in the workflow.

Accepting a Credential offer

Once the wallet receives the credential offer, it makes a request to the issuer’s .well-known endpoint (https://{your_tenant_url}/.well-known/openid-credential-issuer). The OID4VCI specification defines that this endpoint must be publicly available and include information required to initiate the issuance workflow. This includes what type of credentials will be issued and by whom, and also details endpoints and parameters that will be used as part of the workflow.

The wallet displays relevant information from the credential offer to the holder, asking for their consent to begin the issuance workflow.

Authentication

When the holder consents they are redirected to a configured Authentication provider, used to authenticate and identify the holder. This provider can also be used as an identity provider to retrieve claims about the authenticated user. Once retrieved, these claims can be used in the issued credential.

After the holder completes authentication, they are redirected from the Authentication provider back to the issuance workflow.

Inline with the OID4VCI specification, this step includes receiving a code from the Authentication provider upon successful authentication and exchanging it with a Token that is used later in the workflow to issue the credential.

Custom components (optional)

This is where issuers can optionally add their own business logic to the workflow by configuring an Interaction hook. This is optional step enables issuers to plug in any custom experiences to interact with the holder after they have authenticated but before the credential is issued. For example, this can be used to gather additional information from the user or to add higher identity assurance components such as a liveness or biometrics checks.

Querying an external database (optional)

Following the interaction hook, issuers can configure another optional step to retrieve additional user claims from an existing databases and use it in the issued credential. This integration is referred to as a Claims source. Claims sources can query the configured endpoints with any of the user claims retrieved from the Authentication provider and/or Interaction hook. This enables the issuer to create flexible and efficient queries to retrieve the exact user claims required to issue a specific credential.

Formatting and Signing the credential

Now that all the data is available, MATTR VII will format it into a digital credential and cryptographically sign it. This is achieved using a Credential configuration that is defined as part of the credential offer. This is a template that defines how should the issued credential be constructed. It details where the credential claims are mapped from, what the credential should look like in the wallet, when and if it should expire and whether it is revocable.

Delivering the signed credential

Finally, the signed credential is delivered directly to the holder’s digital wallet and can be presented to verifying parties upon request.

The following diagram depicts the OID4VCI workflow:

Configuring the workflow

The OID4VCI workflow makes use of different components that can be configured either using direct API requests to a MATTR VII tenant or via the MATTR Self Service Portal, which offers an interface layer on top of the APIs.

Authentication provider (required): An authentication provider is used to store and manage user accounts on behalf of an organisation or service provider. The provider will be the first screen users see when trying to claim a credential as part of an OID4VCI workflow. Usually this is a login page to verify user credentials, but it could be any custom implementation as long as it follows the OpenID Connect standard.
Interaction hook (optional): If you would like to integrate with any existing components beyond a login page (e.g. MFA, biometrics checks, consent screens), you can set up an interaction hook to redirect users. You can configure the interaction hook to pass back additional user claims or modify existing ones. The interaction hook enables adding additional steps to the credential-claiming journey by bouncing users to your own web service.
Claims source (optional): Usually authentication providers do not store all the information about a user and only keep attributes like email, names or other short identifiers. When issuing credentials, you will likely need more user information and to accommodate that, the workflow enables retrieving data from a custom claim source via a single API call. If you have additional user information stored in a separate database or service, add a claims source to fetch claims directly from a compatible standalone system and use these claims when issuing credentials.
Credential configuration (required): Add your credential types, branding, claims, and other metadata. You can also mix and match where claims for the issued credentials come from - an authentication provider, an interaction hook, or a claims source.

Direct Issuance Authentication provider