Skip to main content

OpenID4VP

OpenID for Verifiable Presentations (OpenID4VP) defines how a verifier requests credentials from a wallet and how the wallet presents them. It is the presentation half of the OpenID for Verifiable Credentials family; issuing credentials is covered by OpenID for Verifiable Credential Issuance (OpenID4VCI).

This page explains how to configure OpenID4VP for verifying credentials.

Enable OpenID4VP​

To verify with OpenID4VP, configure at least one enabled instance of type OPENID4VP_FINAL1 in the verificationProtocol object.

You can configure more than one instance of the same type, each with its own settings. See Verifying ISO mdocs for a common reason to do this.

Example configuration​

verificationProtocol:
  OPENID4VP_FINAL1:
    display: "exchange.openid4vpFinal1"
    order: 1
    type: "OPENID4VP_FINAL1"
    params:
      public:
        useRequestUri: true
        verifier:
          interactionExpiresInSeconds: 3600
          supportedClientIdSchemes:
            [
              x509_san_dns,
              x509_hash,
              verifier_attestation,
              decentralized_identifier,
              redirect_uri,
            ]
        redirectUri:
          enabled: true
          allowedSchemes: ["https"]
        webhookTask: "WEBHOOK1"

The sections below explain each part of this configuration.

Request URI​

When you share a proof request, the system generates a URL for the wallet. That URL can either contain the complete proof request, or a request URI that the wallet calls to fetch it. Use useRequestUri to choose:

  • true: The URL contains a request URI. This keeps the URL short, which is recommended for QR codes.
  • false (default): The URL contains the complete proof request, so the wallet doesn't need to make an extra HTTP call. Suitable for small requests shared as links.

URL scheme​

The URLs you share for proof requests use the URL scheme of the OpenID4VP instance the request is made with. Wallets use the scheme to recognize the request and choose how to handle it. OPENID4VP_FINAL1 instances use openid4vp by default.

To produce URLs with a different scheme, set urlScheme on an additional instance and reference that instance when you create the proof request. See Verifying ISO mdocs for an example.

Interaction expiration​

Use verifier.interactionExpiresInSeconds to set how long the URLs returned by /api/proof-request/v1/:id/share remain valid. After a URL expires, wallets can no longer use it. To get a new URL for the same proof request, call the share endpoint again.

If no value is set, URLs remain valid indefinitely. Setting an expiration is recommended, especially for URLs shared as QR codes.

Client Identifier Schemes​

Client Identifier Schemes (called "Client Identifier Prefixes" in OpenID4VP 1.0) define how wallets validate that a proof request really comes from you. The scheme you use determines how the wallet checks your identity.

Schemes provide different levels of trust assurance. For example, redirect_uri provides no cryptographic verification of your identity, while x509_san_dns requires you to prove control of a domain through certificate validation.

Use verifier.supportedClientIdSchemes to list the schemes your system can use. When you share a proof request, pass the clientIdScheme parameter to choose a scheme for that interaction. If you don't, the system uses the first compatible scheme in your list, so list your preferred schemes first.

For OPENID4VP_FINAL1, use decentralized_identifier for DID-based identification. It replaces the did scheme used in earlier drafts.

note

For all supported schemes, see the verification protocols reference.

Creating identifiers for specific schemes​

Redirect URIs​

You can redirect holders to a URI after they respond to your proof request. Redirects are enabled by default (redirectUri.enabled); list the URI schemes you accept in redirectUri.allowedSchemes, for example https or myapp. If no schemes are listed, all redirect URIs are rejected.

You then set the redirect URI for each proof request when you create it.

Webhooks​

To send notifications for verification events, set webhookTask to a configured WEBHOOK_NOTIFY task. See Webhooks.

Transaction data​

OpenID4VP lets you attach transaction_data to a proof request: details of a transaction, such as a document to sign or a payment to confirm, that the holder must approve before presenting a credential. The holder's approval is then bound to the presentation.

To make these requests, configure a provider for each transaction data type you use in the root-level transactionDataProvider object. The provider validates the transaction data when you create the proof request.

transactionDataProvider:
  SCA_PAYMENT_CONFIRMATION:
    type: SCA_PAYMENT_CONFIRMATION
    display:
      en: "Payment confirmation"
    order: 1
    enabled: true
    params:
      public:
        leewaySeconds: 60
        transactionDataDisplayParams:
          groupPath: "$.payload"
          attributes:
            - path: "$.payee.name"
              display: "transactionData.scaPaymentConfirmation.payee.name"
            - path: "$.execution_date"
              display: "transactionData.scaPaymentConfirmation.executionDate"
  • transactionDataDisplayParams: Required for every provider type, even if you only verify. It controls how transaction data is displayed to holders. See Display parameters.
  • leewaySeconds: Required for all SCA provider types. Sets how far in the past an executionDate can be and still be accepted as not yet past. Not used by QES_APPROVAL.

For the supported provider types, see the configuration reference. For how to make proof requests with transaction data, see Requesting Authorization for Transactions.

Verifying ISO mdocs​

ISO 18013-7 defines its own flavor of OpenID4VP for requesting mdocs, with a different URL scheme and Client Identifier Scheme. To support it, configure a second OpenID4VP instance:

verificationProtocol:
  MDOC_OPENID4VP:
    display: "exchange.mdocOpenid"
    order: 2
    type: "OPENID4VP_FINAL1"
    params:
      public:
        useRequestUri: true
        urlScheme: mdoc-openid4vp
        verifier:
          supportedClientIdSchemes: [x509_san_dns]
        redirectUri:
          enabled: true
          allowedSchemes: ["https"]
  • urlScheme: Set to mdoc-openid4vp, as specified in ISO 18013-7. Instances use openid4vp by default.
  • verifier.supportedClientIdSchemes: Set x509_san_dns as the only scheme, as specified in ISO 18013-7.
  • redirectUri: Settings are per instance, so set your redirect preferences on this instance too.

Query language​

OpenID4VP 1.0 uses the Digital Credentials Query Language (DCQL) to describe the credentials and claims a verifier requests. DCQL requires no configuration: the system generates DCQL queries from your proof schemas. See How proof schemas become DCQL queries.