OpenID4VCI Pre-authorized Code flow

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.

The Pre-authorized Code flow is only supported for mDocs.

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 performed using MATTR capabilities. 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.

Refer to Claiming credential offers for more details on how to adjust the offer URI to use specific schemes and the resulting user experience.

Accepting a Credential offer

After receiving the credential offer URI, the wallet uses it to retrieve required metadata from the .well-known endpoints:

Issuer Metadata Endpoint

https://{your_tenant_url}/.well-known/openid-credential-issuer

Authorization Server Metadata Endpoint

https://{your_tenant_url}/.well-known/oauth-authorization-server

As required by the OID4VCI specification, these endpoints must be publicly accessible. They provide the information necessary to initiate the issuance process, including the issuer’s details, the types of credentials available, and the relevant endpoints and supported parameters used throughout the workflow.

If the credential offer includes a transaction code requirement, the wallet prompts the user to enter the code before proceeding. The transaction code is validated by the issuer when the wallet calls the token endpoint as part of the token exchange. If an incorrect transaction code is entered three times, the credential offer is permanently invalidated and the wallet can no longer claim the credential.

The wallet then calls the issuer’s token endpoint, exchanging the pre-authorized code (and, where required, the transaction code) for an access token. This token endpoint is hosted by MATTR VII and is accessible only when a valid pre-authorized code is provided.

Finally, the wallet uses the returned access token to call the issuer’s credential issuance endpoint and request the credential. This endpoint, also hosted by MATTR VII, is accessible only when a valid access token is included in the request.

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 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 and are essential for establishing the issuer's identity in the credential issuance process. As the Pre-authorized Code only supports mDocs, this means creating an IACA.
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 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.

OpenID4VCI Pre-authorized Code flow

On this page