OpenID4VCI issuance

The OpenID4VCI specification is an open standard being incubated at the OpenID Foundation and leveraging the OpenID protocol to support verifiable credentials issuance and lifecycle management. 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.

MATTR VII currently supports OpenID4VCI issuance of the following credential profiles:

This tutorial will walk you through issuing the different verifiable credentials profiles based on the OpenID4VCI specification.

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • For issuance of Compact Credentials, Compact Semantic Credentials and/or Web Credentials:

    • An issuer DID that identifies the entity who attests the claims in the credential are accurate. This could be any DID method you like but it is easier to test with a did:key. MATTR VII uses the most recently created or modified DID to issue credentials, so we recommend using a did:key for testing, and moving to did:web as you move into production.

  • For issuance of Mobile Credentials:

  • The OpenID4VCI issuance protocol supports issuing multiple credential profiles in the same issuance flow. Thus, we enabled creating did:web with multiple key types by default. Refer to create a did:web for more information.

  • Refer to create a did:web and create a did:key if you need assistance in creating DIDs.

  • Download the MATTR Wallet and have it set up.

Process outline

There are two parts to issuing a verifiable credential based on the OpenID4VCI specification:

Part 1: Configure your OpenID4VCI issuance workflow

This part comprises two mandatory and two optional steps that will configure your issuance workflow based on your unique use case and requirements:

The issuance workflow only needs to be configured once per tenant, not for every credential issuance.

  • Configure an 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. Normally, 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.

  • Configure interaction hook (optional): If you would like to integrate with any existing business logic 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 the existing ones. The interaction hook enables adding additional steps to the credential-claiming journey by bouncing users to your own web service.

  • Configure claims source (optional): Usually identity providers do not store all of 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, we have added support for retrieving data from a custom claim source via a single API call. If you have additional user information stored in a seperate database or service, add a claims source to fetch claims directly from a compatible standalone system and use these claims when issuing credentials.

  • Setup 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 identity provider, an internal user store, or claims source.

Part 2: Issue a verifiable credential

Once your issuance workflow is properly configured, you can use it to issue verifiable credentials based on the OpenID4VCI specification. This part comprises the following steps:

  • Create a credential offer: You must first create an offer that details the type of credential you are about to issue, and the claims included in it.

  • Send the credential offer: Once a credential offer is created, you will encrypt it and send it to the intended holder's digital wallet using a message, a QR code or a deep link.

  • Accept the credential offer: The intended holder receives the credential offer, and when they choose to accept it, they must authenticate with the configured authentication provider before the credential is issued to their digital wallet.

The OpenID4VCI specification supports issuing multiple credentials in a single issuance workflow. This means that when properly configured, you can use your issuance workflow to issue several credential profiles in a single workflow.