Skip to content

OID4VCI

Document Rails supports OpenID for Verifiable Credential Issuance 1.0 for issuance of digital credentials.

Underlying infrastructure for OID4VCI issuance flows is based on the recipe system, so make sure you have everything configured for regular recipe issuance.

For setting up OID4VCI, Document Rails offers the option of handling the entire flow or delegating the request acceptance to your application.

How the protocol works

The issuance flow starts by generating a credential offer that describes which recipe to use for issuance, which authorization service to use for token introspection, and other OID4VCI related data.

Credential offers are encoded as URLs, and may be shared with users in a form of QR codes, deep links, e-mail buttons, etc.

By interacting with the URL, user's wallet offers a selection of available credentials by looking up the credential issuer metadata. This metadata contains information about supported credentials (translated display data, credential type, fields).

After selecting one of the offered credentials, wallet asks user to authenticate with the supported authentication method using the authorization server provided during the credential offer initialization.

OID4VCI utilizes existing OAuth authorization servers for user identification, allowing you to connect Document Rails to existing authentication/authorization infrastructure.

Note

Document Rails, at the moment, supports only the authorization_code flow.

After authenticating and checking user authorization to access the issued credential, the user is redirected back to the wallet. The wallet, in the background, sends its access token to Document Rails either directly (in case of the regular flow), or via your application (in case of the application-delegated flow).

Document Rails will introspect the token to extract the subject claim (sub), that will be used as an external user identifier for all webhook communication.

On successful subject claim extraction, Document Rails proceeds with asynchronous credential issuance, returning the transaction identifier back to the wallet for querying the status of the process.

Webhooks configured for usage with the selected credential offer recipe will be utilized to guide the issuance process, allowing Document Rails to request information about the user and to provide your application with the issuance outcome.

Regular flow

sequenceDiagram
    participant Wallet
    participant Application
    participant Document Rails

    Application->>Document Rails: Start an OID4VCI issuance flow using the provided recipe data
    Document Rails->>Application: Encoded QR code data

    destroy Application
    Application->>Wallet: Wallet scans the QR code

    Wallet->>Document Rails: Get credential issuer metadata
    Document Rails->>Wallet: Generated credential issuer metadata

    participant Authorization server
    Wallet->>Authorization server: Start the authorization code flow
    Note over Wallet: Wallet performs the authentication flow
    Authorization server->>Wallet: Access token

    Wallet->>Document Rails: Access token
    Document Rails->>Authorization server: Introspect the token
    Authorization server->>Document Rails: `sub` claim and other data
    Note over Document Rails: Asynchronously start generating credentials
    Document Rails->>Wallet: Transaction ID

    Wallet->>Document Rails: Poll the credential readiness
    Document Rails->>Wallet: Credentials

In this flow, your application doesn't handle the OID4VCI issuance session at all, delegating all request handling to Document Rails.

To start using this flow, create a credential offer without specifying the credential issuer, convert the encoded credential offer URL to QR code and display it to the user.

Since your application cannot pass the recipe input data to Document Rails directly, it is recommended to use inbound webhooks to fetch the input data for recipes.

Issuance outcomes are passed to your outbound webhooks, if any are configured for the provided recipe.

Application-delegated flow

sequenceDiagram
    participant Wallet
    participant Application
    participant Document Rails
    participant Authorization server

    Application->>Document Rails: Start an OID4VCI issuance flow using the provided recipe data
    Document Rails->>Application: Encoded QR code data

    Application->>Wallet: Wallet scans the QR code

    Wallet->>Application: Get credential issuer metadata
    Application->>Document Rails: Generate credential issuer metadata
    Document Rails->>Application: Generated credential issuer metadata
    Application->>Wallet: Generated credential issuer metadata

    Wallet->>Authorization server: Start the authorization code flow
    Note over Wallet: Wallet performs the authentication flow
    Authorization server->>Wallet: Access token

    Wallet->>Application: Access token
    Application->>Document Rails: Access token
    Document Rails->>Authorization server: Introspect the token
    Authorization server->>Document Rails: `sub` claim and other data
    Note over Document Rails: Asynchronously start generating credentials
    Document Rails->>Application: Transaction ID
    Application->>Wallet: Transaction ID

    Wallet->>Application: Poll the credential readiness
    Application->>Document Rails: Poll the credential readiness
    Document Rails->>Application: Credentials
    Application->>Wallet: Credentials

This flow lets your application serve as a relay between the wallet and Document Rails, allowing you to precisely handle the issuance process.

Document Rails, even in this case, still handles the protocol itself, but the requests are accepted from your application instead.

By utilizing this flow, you manually invoke the recipe printing API, which allows you to pass additional parameters like input credentials, credential subject identifiers, etc.

More information about this flow is available on the application-delegated flow documentation page.