Skip to main content

OpenID4VC

Learn how to configure OpenID4VC.

Overview​

OpenID for Verifiable Credentials (OID4VC) is a protocol specification that extends OpenID Connect to enable the secure issuance and presentation of Verifiable Credentials. Built on widely-adopted OpenID Connect infrastructure, it provides standardized flows for three key parties: issuers who create credentials, holders who receive and store them, and verifiers who request and validate credentials.

The protocol defines two primary interactions: the Credential Issuance flow, which governs how credentials are securely issued to holders, and the Verifiable Presentation flow, which enables holders to present their credentials to verifiers. OID4VC supports multiple credential formats, flexible authentication methods, and privacy-preserving selective disclosure capabilities, making it a versatile solution for digital credential ecosystems.

The two flows are split into separate standards: OpenID for Verifiable Credential Issuance (OID4VCI) and OpenID for Verifiable Presentations (OID4VP). This page explains how to configure OID4VC for issuance, holding and verification.

For the full list of supported options, check the configuration reference.

Issuance​

To enable OID4VCI, ensure an instance of type: "OPENID4VCI_DRAFT13" is configured and enabled in the issuanceProtocol object of the configuration:

issuanceProtocol:
  OPENID4VCI_DRAFT13:
    display: 'exchange.openid'
    type: 'OPENID4VCI_DRAFT13'

Several components of OID4VCI can be set in the configuration:

  • Encryption key for tokens
  • Timelines for codes and tokens
  • Redirect URIs

Here's an example configuration without an encryption key, with explanations below:

issuanceProtocol:
  OPENID4VCI_DRAFT13:
    display: 'exchange.openid'
    type: 'OPENID4VCI_DRAFT13'
    params:
      public:
        preAuthorizedCodeExpiresIn: 300
        tokenExpiresIn: 86400
        refreshExpiresIn: 7776000
        redirectUri:
          enabled: true
          allowedSchemes: ['https']

Encryption key​

An encryption key must be set for each instance of OID4VCI. This key is typically put in a configuration override file or an environment variable.

See configuration override for details on providing an encryption key.

Code and token timelines​

Use the following parameters to configure elements of the pre-authorized code flow of OID4VCI:

  • preAuthorizedCodeExpiresIn: Sets how long, in seconds, a pre-authorized code remains valid for obtaining access tokens during the OpenID4VCI credential issuance flow. This window needs to be long enough for users to complete their wallet interaction, but short enough to minimize security risks.
  • tokenExpiresIn: Sets how long, in seconds, an access token remains valid for credential retrieval during the OpenID4VCI flow. This window must accommodate network latency, potential retry attempts, and your expected user interaction patterns.

Redirect URIs​

URIs can be set for holders to be redirected to when they accept your credential offer. You must specify the allowed schemes. The redirect URI is then set on a per-credential basis during the credential creation process.

OID4VCI for ISO mdoc​

For mdoc issuance, add the following parameter to your configuration:

  • refreshExpiresIn: Sets how long, in seconds, wallets can wait to renew their expired mdoc credentials without going through the full issuance process again. As long as the wallet requests a new token before this time has elapsed it will be reissued, assuming the credential has not been suspended or revoked. Consider your security requirements when setting this value - a longer window provides more convenience for users but increases the lifetime of the original issuance tokens.

The expiration duration of the mdoc credential itself is configured in credential format configuration.

Related guide: mdoc validity

Holding​

A wallet needs both an issuance protocol and a verification protocol configured and enabled to receive credentials and share presentations.

OID4VCI​

To enable OID4VCI, ensure an instance of type: "OPENID4VCI_DRAFT13" is configured and enabled in the issuanceProtocol object of the configuration:

issuanceProtocol:
  OPENID4VCI_DRAFT13:
    display: 'exchange.openid'
    order: 1
    type: 'OPENID4VCI_DRAFT13'

OID4VP​

To enable OID4VP, ensure an instance of type: "OPENID4VP_DRAFT20" is configured and enabled in the verificationProtocol object of the configuration.

Use the supportedClientIdSchemes parameter to define which Client Identifier Schemes the wallet should support when validating the authenticity of verifiers. Here's an example configuration:

verificationProtocol:
  OPENID4VP_DRAFT20:
    display: 'exchange.openid'
    order: 1
    type: 'OPENID4VP_DRAFT20'
    params:
      public:
        holder:
          supportedClientIdSchemes: [redirect_uri, verifier_attestation, did]

Configure for ISO mdoc​

Wallets can be configured to present and exchange ISO mdocs using OID4VP. A few configurations need to be set to enable this:

  • Set the URL scheme
  • Define the accepted CA certificates
  • Set the Client Identifier Scheme

Because of these differences, it is recommended to configure a second instance of the OPENID4VP_DRAFT20 verification protocol. This allows the wallet to parse incoming proof requests by their URL scheme and then use the appropriate flavor of OID4VP for the exchange.

Here's an example configuration, with explanations below:

verificationProtocol:
  MDOC_OPENID4VP:
    display: "exchange.mdocOpenid"
    order: 2
    type: "OPENID4VP_DRAFT20"
    params:
      public:
        urlScheme: mdoc-openid4vp                   // Flag this instance of OID4VC to be used when this URL scheme is encountered
        x509CaCertificate: {{CA-CERTIFICATE}}       // Define the Certificate Authority (CA) certificate used to validate verifier authenticity
        holder:
          supportedClientIdSchemes: [x509_san_dns]  // Use the Client Identifier Scheme supported by the standard

URL scheme​

By default the OID4VP verification protocol uses openid4vp as the URL scheme according to the OID4VP standard. The urlScheme parameter allows the specification of a different scheme. For the mdoc flavor of OID4VP we use mdoc-openid4vp as the URL scheme, to follow the ISO 18013-7 standard.

X.509 certificate​

The wallet validates verifier authenticity by checking that the verifier's certificate has been signed by an approved Certificate Authority. The x509CaCertificate parameter enables the wallet to define which CAs are trusted.

Exchanges with verifiers whose certificates are not signed by trusted CAs will be rejected.

Client Identifier Scheme​

The 18013-7 standard specifies the use of x509_san_dns as the Client Identifier Scheme for mdoc exchange. Set this as the only supported scheme for presenting mdocs.

Verification​

To enable OID4VP, ensure an instance of type: "OPENID4VP_DRAFT20" is configured and enabled in the verificationProtocol object of the configuration.

Several components of OID4VP can be set in the configuration:

  • Request URI enabling
  • Client Identifier Schemes
  • Redirect URI

Here's an example configuration, with explanations below:

verificationProtocol:
  OPENID4VP_DRAFT20:
    display: 'exchange.openid'
    order: 1
    type: 'OPENID4VP_DRAFT20'
    params:
      public:
        useRequestUri: true
        verifier:
          supportedClientIdSchemes: [redirect_uri, verifier_attestation, did]
          defaultClientIdScheme: verifier_attestation
        redirectUri:
          enabled: true
          allowedSchemes: ['https']

Request URI​

When you create a proof request, a URI is generated. This URI can either contain the complete proof request information within it, or it can contain a request URI instead. If it contains a request URI, the wallet must make an HTTP request to fetch the complete proof request information.

Set to true if:

  • The proof request will be shared as a QR code. Using a request URI shortens the URL significantly, making it more suitable for use with a QR code.

Set to false if:

  • The proof request is small and will be shared as a hyperlink.

Client Identifier Schemes​

Use supportedClientIdSchemes to specify which schemes are supported in interactions with wallets.

For any given interaction you can choose which scheme to use by passing the clientIdScheme param in the request body of the /api/proof-request/v1/:id/share endpoint:

{
  "params": {
    "clientIdScheme": "redirect_uri"
  }
}

If no scheme is chosen during creation of the share URL, the defaultClientIdScheme is used.

Redirect URI​

URIs can be set for holders to be redirected to when they accept your proof request. You must specify the allowed schemes. The redirect URI is then set on a per-proof request basis during the proof request creation process.

Configure for ISO mdoc​

The system can be configured to verify ISO mdocs using OID4VP. A few configurations need to be set to enable this:

  • Set the URL scheme
  • Set the Client Identifier Scheme
  • Set the redirect URI (if desired)

Because of these differences, it is recommended to configure a second instance of the OPENID4VP_DRAFT20 verification protocol. These settings enable wallets to parse incoming requests and use the appropriate flavor of OID4VP for the exchange.

Here's an example configuration, with explanations below:

MDOC_OPENID4VP:
  display: 'exchange.mdocOpenid'
  order: 2
  type: 'OPENID4VP_DRAFT20'
  params:
    public:
      useRequestUri: true
      urlScheme: mdoc-openid4vp
      x509CaCertificate: MIIC6jCCApCg...
      verifier:
        supportedClientIdSchemes: [x509_san_dns]
        defaultClientIdScheme: x509_san_dns
      redirectUri:
        enabled: true
        allowedSchemes: ['https']

URL scheme​

By default the OPENID4VP_DRAFT20 exchange protocol uses openid4vp as the URL scheme according to the OID4VP standard. The urlScheme parameter allows the specification of a different scheme. For the mdoc flavor of OID4VP we use mdoc-openid4vp as the URL scheme, to follow the ISO 18013-7 standard.

Client Identifier Scheme​

The 18013-7 standard specifies the use of x509_san_dns as the Client Identifier Scheme for mdoc exchange. Set this as the only supported scheme for verifying mdocs.

Redirect URI​

If you configure a second instance of OPENID4VP_DRAFT20 for ISO mdocs, be sure to set your redirect preferences and schemes.