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:

• Compact Credentials: Represent claims of data that can be cryptographically proven as authentic while being compact enough to fit inside a QR code. Refer to the Docs section to learn more about Compact Credentials and to the Create a Compact Credential tutorial to learn how to create one.

• Compact Semantic Credentials: Similar to Compact Credentials but provide semantic context to the claims compliant with the W3C Verifiable Credentials Data Model 1.0. Refer to the Docs section to learn more about Compact Semantic Credentials.

• Web Credentials: Based on the W3C Verifiable Credential data model for expressing cryptographically secure digital credentials on the web. Refer to the Docs section to learn more about Web Credentials and to the tutorial to learn how to create one.

• Mobile Credentials: Digital identity documents designed to be stored on the holder’s mobile device, based on the ISO/IEC 18013-5:2021 standard. Mobile Credentials support a variety of advanced security features, making them an ideal choice for use cases requiring higher assurance identity credentials, such as driving licenses or national IDs.

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

Issuance of Mobile Credential to the MATTR Showcase Wallet is not supported yet. You can use the MATTR Pi Wallet SDK to issue Mobile Credentials into a digital wallet.

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:

  • Valid IACA and DSC certificates.

• 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.