OpenID4VCI Pre-authorized Code workflow

Overview

The Pre-authorized Code flow is a streamlined, user-friendly process where the credential recipient (usually a wallet) is issued a pre-authorized code by the issuer (e.g., a government or organization). This code can be used to obtain a credential without requiring the user to go through the full authentication process again.

In the pre-authorized code flow, the issuer provides a pre-authorized code directly to the wallet. The wallet uses this code to obtain an access token, which it then uses to request the issuance of a credential.

This flow is ideal for scenarios where the user has already been authenticated and authorized, and the issuer wants to simplify the credential issuance process. It is particularly useful for situations where the user needs to obtain multiple credentials or where the issuance process needs to be expedited.

Workflow

The following diagram depicts the OID4VCI Pre-authorized Code flow:

Issuer preparation

The issuer prepares the credential issuance by authenticating the user and gathering claims about them. This step is performed outside of the OID4VCI workflow and is not part of the MATTR VII workflow. The issuer can use any method to authenticate the user, such as a login page or a custom implementation. The issuer then passes the user claims to MATTR VII, which will be used later in the credential issuance process.

Creating a Credential offer

Once the issuer is ready, they initiate the creation of a credential offer by making a request that specifies:

The credential configuration to use for issuance.
The user claims to be included in the credential.
The credential’s expiry date.
Whether a transaction code is required for claiming the credential.

MATTR VII will then create a credential offer that includes a pre-authorized code, which is used to issue the credential. This code is a unique identifier that allows the wallet to claim the credential without requiring the user to go through the full authentication process again.

The MATTR VII response will include a URI that can be used by the wallet to accept the credential offer and request the credential.

The issuer can now share the credential offer with the intended holder. This is done by sending the credential offer URI to the wallet. The URI can be shared in various ways, such as a QR code, a deep link, or a push notification. The issuer can also choose to share the transaction code separately if it is required for claiming the credential.

Accepting a Credential offer

After receiving the credential offer URI, the wallet uses it to query the issuer’s .well-known endpoint (https://{your_tenant_url}/.well-known/openid-credential-issuer). This endpoint, as required by the OID4VCI specification, must be publicly accessible and provide all necessary details to start the issuance process. It describes the types of credentials available, the issuer’s information, and specifies the endpoints and parameters used in the workflow.

The wallet then sends a request to the issuer’s token endpoint, exchanging the pre-authorized code for an access token. This is a MATTR VII endpoint that is only accessible when providing the required pre-authorized code.

Finally, the returned access token is used to call the issuer’s issuance endpoint and request the credential. This is also a MATTR VII endpoint that is only accessible when providing the required access token.

Formatting and Signing the credential

When the wallet requests the credential, MATTR VII takes the data provided by the issuer and formats it into a digital credential. This credential is then cryptographically signed. The process uses a credential configuration specified in the credential offer, which acts as a template for the issued credential. The credential configuration defines how claims are mapped, the credential’s appearance in the wallet, its expiration, and whether it can be revoked.

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.

Configuration

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.

Issuer identity management (required): Set up and manage the identifiers that represent your issuer. These identifiers can include IACAs for mDocs or DIDs for JSON credentials, and are essential for establishing the issuer’s identity in the credential issuance process.
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.
Credential offer (required): This is the main component of the OID4VCI Pre-authorized Code flow. It contains the credential configuration identifier, the pre-authorized code, and other metadata. The credential offer is used to initiate the issuance process and includes all necessary information for the wallet to request and claim the credential.
Claims source (optional): While the intent of the Pre-authorized Code flow is for the issuer to provide all the required claims when creating the credential offer, there may be cases where additional claims are needed. 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.