Relying parties that accept credentials from digital identity wallets need a protocol that proves who is asking, gets only the data needed, and stops a captured presentation being replayed somewhere else. OpenID for Verifiable Presentations (OpenID4VP) 1.0, a Final specification of the OpenID Foundation since 9 July 2025, is that protocol for remote presentation: it is used by the EU Digital Identity Wallet, by OpenID4VC High Assurance Interoperability Profile (HAIP) deployments and by browsers through the W3C Digital Credentials API. This guide covers the request and response model, the Digital Credentials Query Language (DCQL), verifier identification, the response modes and their attacks, VP Token validation and fraud controls. It is for engineers and architects building verifiers at banks, platforms and public services, and for security teams assessing them.
Key takeaways
- OpenID4VP is OAuth-shaped but returns credentials, not tokens. The verifier sends an Authorization Request with a
dcql_query; the wallet returns avp_tokenholding one or more presentations keyed by query id. - Replay protection rests on two values. Every holder-bound presentation must be bound to the verifier's
client_id(as audience) and the requestnonce, and the verifier must reject any presentation where either is wrong. - The verifier, not the wallet, enforces policy. The specification says verifiers must not rely on the wallet to enforce DCQL constraints and must run their own checks on every credential returned.
- Cross-device flows carry the most risk.
direct_postenables QR code flows but is open to session fixation and relayed QR phishing; the Digital Credentials API reduces both by giving the wallet a browser-verified origin. - Use a profile. OpenID4VP has many options. HAIP 1.0 (Final, December 2025) fixes the choices for high assurance ecosystems such as the EUDI Wallet:
x509_hashclient identifiers, encrypted responses, DCQL and the DC API.
How OpenID4VP works
OpenID4VP extends OAuth 2.0 (RFC 6749) and JWT-Secured Authorization Requests (RFC 9101). The verifier plays the OAuth client and the wallet plays the authorisation server, but instead of an access token the response carries Verifiable Presentations. Three invocation patterns exist.
| Flow | How the wallet is reached | Response path | Main risks |
|---|---|---|---|
| Same-device redirect | Custom URI scheme (for example openid4vp://) or universal or app link | Redirect with fragment, or direct_post plus a redirect_uri back to the verifier frontend | Wallet selection by URI scheme, scheme hijacking, request tampering if unsigned |
| Cross-device QR code | QR code holding only client_id and request_uri | direct_post or direct_post.jwt to the verifier's response_uri | Session fixation, relayed QR phishing, no shared browser session |
| Digital Credentials API | navigator.credentials.get() with a digital member, or the native platform equivalent | Returned to the calling page through the API (dc_api or dc_api.jwt) | Fewer: the platform supplies the verifier origin and runs proximity checks for cross-device use |
A typical request carries response_type=vp_token, client_id, nonce, dcql_query, response_mode and, for direct_post, a response_uri. Requests are usually passed by reference: the QR code or link holds a request_uri and the wallet fetches a signed Request Object. With request_uri_method=post the wallet can send its own metadata and a wallet_nonce, which the verifier must echo inside the signed Request Object, so a pre-generated request cannot be replayed to the wallet.
Asking for data with DCQL
DCQL replaced the earlier Presentation Exchange syntax in the Final specification. A query lists credentials (required) and optional credential_sets. Each Credential Query has an id, a format such as dc+sd-jwt or mso_mdoc, a meta block (for SD-JWT VC, the accepted vct values), and a claims list of path pointers.
- Minimise by design: request named claims, not the whole credential. Wallets must not disclose selectively disclosable claims that were not selected. For SD-JWT internals see the SD-JWT and SD-JWT VC Guide.
- Alternatives with
claim_setsandcredential_sets: state preferred and fallback combinations (for example a PID or a driving licence) rather than asking for both. - Holder binding:
require_cryptographic_holder_bindingdefaults to true. Turning it off means accepting a credential that anyone holding a copy could present. - Trusted issuers:
trusted_authoritiescan name accepted issuers by Authority Key Identifier (aki), ETSI trusted list (etsi_tl) or OpenID Federation. HAIP requiresakisupport. This filters what the wallet offers; it does not replace verifier-side issuer validation. - Purpose: show the user why each attribute is needed before sending the request. In the EUDI ecosystem the wallet also checks that you asked for no more than your registration allows.
Identifying the verifier: client identifier prefixes
The wallet has to know who is asking before it shows the consent screen. OpenID4VP encodes the trust mechanism in the client_id as <prefix>:<identifier>.
| Prefix | How the wallet authenticates the verifier | Use when |
|---|---|---|
redirect_uri | Not authenticated; unsigned requests only | Low-risk testing only |
x509_san_dns | Request signed with a key whose certificate has a DNS SAN matching the identifier | Web verifiers in a PKI-based trust framework |
x509_hash | Request signed with a certificate whose hash equals the identifier | Required by HAIP 1.0 for signed requests, so EUDI-style ecosystems |
verifier_attestation | A Verifier Attestation JWT from a trusted party, plus proof of possession | Ecosystems that issue attestations to approved verifiers |
openid_federation | Trust chain resolved through OpenID Federation | Federations of many verifiers and issuers |
decentralized_identifier | Keys resolved from a DID document | DID-based ecosystems |
origin | Reserved: set by the wallet for the DC API from the browser-supplied origin; wallets must not accept it in requests | Never sent by the verifier |
| No prefix | Treated as pre-registered with the wallet | Closed ecosystems with a single wallet |
The full client identifier, including the prefix, is what goes into the presentation's audience. The specification warns that confusing a prefixed and an unprefixed identifier enables attacks, so compare the whole string. In the EUDI Wallet framework, each Relying Party Instance also holds an access certificate from its Member State's registrar ecosystem and a registration certificate describing intended uses and attributes, which the wallet checks. See the Relying Party Integration with Digital Identity Wallets Guide.
Response modes and their attacks
fragment(default): the response returns through a redirect on the same device. An attacker can relay a request to a victim, but has no way to get the resulting VP Token. Responses can exceed URL limits, which is whydirect_postexists.direct_post: the wallet POSTs the response to the verifier'sresponse_uri. Whenresponse_uriis present,redirect_urimust not be. This mode is susceptible to session fixation: the attacker starts a session on their device, relays the request to a victim, and polls until the victim's wallet completes it.- Response Code defence: on same-device
direct_post, the response endpoint returns aredirect_uricontaining a fresh secret Response Code, and the frontend must present it to fetch the result. This does not work cross-device, because the wallet's browser lacks the original session. direct_post.jwtanddc_api.jwt: the response is encrypted to the verifier (HAIP: ECDH-ES on P-256 with A128GCM or A256GCM). Encryption protects personal data in transit and in intermediaries. Because encryption uses the verifier's public key, it does not authenticate the sender; integrity still comes from the signed presentations.
Cross-device flows are the target of Cross-Device Consent Phishing, now documented in RFC 10027 (BCP 247, August 2026): the attacker places a genuine QR code in a lure and the victim approves it. Mitigations include short-lived requests, proximity checks and clear context on the consent screen; the BCP advises avoiding cross-device flows where the risk cannot be reduced. See the Cross-Device Flow Security Guide and the QR Code Phishing (Quishing) Guide.
The Digital Credentials API path
The W3C Digital Credentials API (Working Draft, 20 October 2026, Federated Identity Working Group) lets a web page call navigator.credentials.get({digital: {requests: [{protocol, data}]}}). The registered presentation protocols are openid4vp-v1-unsigned, openid4vp-v1-signed, openid4vp-v1-multisigned and org-iso-mdoc.
- Origin binding: the platform passes the verifier's origin to the wallet. For SD-JWT VC over the DC API, the KB-JWT
audmust beorigin:followed by that origin, so a presentation phished on a look-alike site is bound to the wrong audience. expected_origins: required in signed DC API requests; the wallet compares it with the browser-supplied origin by exact string match and errors on mismatch. This stops a malicious site replaying your signed request.- User activation and policy: calls need transient user activation, run only in secure contexts, and are governed by the
digital-credentials-getpermissions policy (default'self'), so cross-origin iframes need an explicitallow. - No session fixation by design: the response returns to the page that asked, and cross-device use runs over platform transports with proximity checks.
The trade-off is reach: the DC API depends on browser and operating system support, so most verifiers will run it alongside a redirect or QR fallback during transition. HAIP 1.0 requires wallets to support the DC API.
Validating the VP Token
OpenID4VP sets out the validation order; format-specific checks come from SD-JWT VC or ISO/IEC 18013-5. If any check on an individual presentation fails, discard it; if the overall response fails, reject the VP Token.
- Correlate the response: match
stateto a recent request you issued, and protect the internal interface between your response endpoint and frontend (component authentication, or separate random values for wallet state and result retrieval). - Decrypt if you requested an encrypted response, and reject plaintext responses where encryption was required.
- Check structure: the
vp_tokenobject keys must be your DCQL ids, each value an array, with exactly one presentation wheremultiplewas false. - Verify issuer signature and trust: issuer key to a trust anchor your policy allows (for EUDI, trusted lists), credential type, validity period.
- Verify holder binding: for SD-JWT VC, the KB-JWT
nonceequals your request nonce andaudequals your full client identifier (ororigin:<origin>over the DC API); for mdoc, the device signature over the SessionTranscript. - Check status (Token Status List or the mdoc mechanism) according to your policy.
- Check the result against your own query: required claims present, no surprise credentials, values within expected ranges.
- Bind identity correctly: if you authenticate a returning user from a credential claim, the claim must be stable and never reassigned, and you must combine it with the issuer identifier.
If you send transaction_data (for example to bind a payment or a qualified signature to the presentation), confirm the wallet included it in the holder-bound proof. A wallet that does not support it must refuse the request with invalid_transaction_data rather than return a VP Token.
Implementation roadmap
- Choose the profile and trust framework: HAIP 1.0 for EUDI and similar ecosystems, plus the national or sector rules that tell you which issuers and trust lists to accept.
- Register and obtain certificates: in the EUDI ecosystem, register as a relying party and obtain access and registration certificates before production. Keep request-signing keys in an HSM.
- Build with a conformant library and run the OpenID Foundation conformance tests for OpenID4VP; the specification itself points to them.
- Start same-device and DC API, then add cross-device QR with short-lived
request_urivalues,request_uri_method=postand encrypted responses. - Run in shadow mode: verify presentations alongside your existing identity check, compare outcomes and tune error handling, including
wallet_unavailableand user cancellation. - Enforce in rings (staff, pilot customers, everyone) with a rollback switch to the previous onboarding path, never to unverified acceptance.
- Review data retention: store the verification result and the claims you need, not the raw presentation, unless law requires it.
Small verifiers can usually rely on a certified verifier service and the DC API, which removes most session handling. Large banks and platforms running their own verifier must own key management, response endpoint isolation, fraud scoring and multiple wallet and issuer combinations.
Detection and measurement
- Nonce and state anomalies: responses with unknown, expired or reused
nonceorstatevalues. Target zero accepted; investigate every rejection cluster. - Audience mismatches: KB-JWT
audnot equal to your client identifier or origin, which signals relay or phishing. - Cross-device completion geography: QR sessions started in one network or country and completed from a distant device, a common sign of relayed codes.
- Request-to-completion time: sessions completed long after the QR was shown, or polled heavily before completion.
- Verification failure rate by issuer and wallet: a step change usually means an issuer key rotation or a broken wallet release.
- Claims requested versus used: each DCQL claim should map to a documented purpose.
Log the flow identifiers, outcome and failure reason without logging claim values. These map to NIST CSF 2.0 DE.CM-03 monitoring of technology usage.
Framework mapping
| Framework | Reference | How OpenID4VP relates |
|---|---|---|
| NIST CSF 2.0 | PR.AA-03 | Authenticating users from wallet credentials |
| NIST CSF 2.0 | PR.DS-02 | Encrypted responses and TLS protect data in transit |
| NIST SP 800-53 Rev. 5 | IA-8 | Identification and authentication of non-organisational users such as customers |
| NIST SP 800-53 Rev. 5 | SC-23 | Session authenticity: nonce, state and Response Code binding |
| NIST SP 800-53 Rev. 5 | SC-8 | Transmission confidentiality and integrity |
| OWASP ASVS 5.0 | V9.1.1, V9.2.3 | Signature validation and audience restriction of presented tokens |
Common failure patterns
- Accepting the wrong audience: verifiers that check the nonce but not the KB-JWT
aud, or compare only the part after the prefix, accept presentations made for another verifier. - Trusting wallet-side filtering: assuming that because the DCQL asked for a PID from a trusted issuer, whatever comes back is one. The specification says the verifier must check.
- Unprotected response endpoint: a
response_uriwhose internal lookup can be queried by guessing a transaction id leaks presentations full of personal data. - Long-lived QR codes: request URIs valid for many minutes give attackers time to relay them into phishing lures.
- Following HTTP redirects: wallets should not follow 3xx responses on
request_uriorresponse_uri; verifiers that rely on redirects there break interop and can leak data to unvalidated hosts. - Using a user-chosen claim as a login key: matching returning users on an email address in a credential without the issuer identifier lets anyone with a credential from a different issuer claim the account. See the Digital Identity Wallet Fraud Risks Guide.
Practitioner checklist
- Adopt OpenID4VP 1.0 with a named profile (HAIP 1.0 for high assurance) and record the versions of dependent drafts it pins.
- Sign all requests, use
x509_hashor your framework's prefix, and keep signing keys in an HSM. - Generate a fresh, unpredictable
nonceandstateper transaction and expire them within minutes. - Verify KB-JWT
nonceand full-stringaud(ororigin:value) on every presentation. - Require encrypted responses (
direct_post.jwtordc_api.jwt) when personal data is returned. - Implement the Response Code pattern for same-device
direct_postand short request lifetimes for QR flows. - Prefer the Digital Credentials API where available, with
expected_originsin signed requests. - Validate issuer trust, status and every DCQL constraint on the verifier side.
- Request only claims tied to a documented purpose and your registration, and do not store raw presentations by default.
- Pass the OpenID Foundation conformance tests before production and after every library upgrade.
Standards and references
- OpenID Foundation: OpenID for Verifiable Presentations 1.0
- OpenID Foundation: OpenID4VC High Assurance Interoperability Profile 1.0
- W3C: Digital Credentials API
- IETF: RFC 9901 Selective Disclosure for JSON Web Tokens
- IETF: SD-JWT-based Verifiable Digital Credentials, Internet-Draft
- IETF: Cross-Device Flows Security Best Current Practice (RFC 10027)
- European Commission: EUDI Wallet Architecture and Reference Framework
Related NHI Mgmt Group resources: Verifiable Credentials Guide · SD-JWT and SD-JWT VC Guide · OpenID for Verifiable Credential Issuance Guide · eIDAS 2.0 and the European Digital Identity Framework Guide · OAuth 2.0 and OpenID Connect Guide