Guia OpenID4VP: verificar i acceptar la cartera europea d'identitat digital (EUDI Wallet)
Com funciona un verificador OpenID4VP per a la EUDI Wallet: objectes de sol·licitud, consultes DCQL, modes de resposta, controls SD-JWT VC i mdoc, regles HAIP del dret de la UE, errors habituals i on provar.
En resum
OpenID4VP (OpenID for Verifiable Presentations) és el protocol que fa servir un verificador per demanar credencials a una cartera digital i rebre'n una presentació signada. La versió 1.0 va passar a ser una especificació final d'OpenID el 10 de juliol de 2025, i la cartera europea d'identitat digital (EUDI Wallet) la fa servir per a la presentació remota.[2][3]
- Envieu una sol·licitud signada amb una consulta DCQL. La cartera retorna un VP Token.
- Verifiqueu vosaltres mateixos la signatura de l'emissor, les divulgacions, la vinculació de clau i la revocació.
- Per a la cartera EUDI, el dret de la UE afegeix normes de certificats i de registre.
OpenID4VP és la manera com un lloc web o una aplicació demana a una cartera que demostri alguna cosa sobre una persona, com ara el nom o la data de naixement. El verificador indica quines credencials i quines declaracions vol, l'usuari ho aprova a la cartera i la cartera retorna una presentació que el verificador comprova criptogràficament. En paraules de la mateixa especificació, «defineix un protocol per sol·licitar i presentar credencials».[1]
Aquesta guia és per a desenvolupadors que creen un verificador OpenID4VP per a la cartera EUDI: l'objecte de sol·licitud, DCQL, els modes de resposta, els fluxos de dispositiu, les comprovacions d'SD-JWT VC i mdoc, les regles HAIP del dret de la UE, els errors habituals i on fer proves.
OpenID4VP en paraules senzilles
OpenID4VP reutilitza l'estructura d'una sol·licitud d'autorització d'OAuth 2.0. El verificador demana el tipus de resposta vp_token, i una resposta correcta ha d'incloure un paràmetre vp_token que conté les presentacions.[1] No hi ha cap codi ni cap token d'accés per intercanviar: les dades arriben a la resposta.
La cartera autentica la part usuària, comprova que no demani més del que té registrat, recull l'aprovació de l'usuari i signa la presentació. Després, la part usuària verifica la signatura de l'emissor, l'estat de revocació i la vinculació amb el dispositiu.[3] Les dades d'identificació de la persona (PID) s'emeten en dos formats, SD-JWT VC i ISO/IEC mdoc, i tots dos fan servir hashos amb sal perquè l'usuari pugui compartir alguns atributs i amagar la resta.[5][3]
- 10 de juliol de 2025Especificació finalOpenID4VP 1.0 aprovat.
- 22 de juliol de 2026PublicacióCIR 2026/1731 (adoptat el 15 de juliol de 2026) al Diari Oficial.
- 23 de juliol de 2026ARF v3.0.0Versió actual de l'arquitectura.
- 24 de desembre de 2026CarteresAlmenys una per estat membre.
- 24 de desembre de 2027AcceptacióParts usuàries privades regulades.
De l'especificació final a la data d'acceptació pel sector privat.[2][3][4][5]
Com funciona un intercanvi amb un verificador OpenID4VP
OpenID4VP publica un disseny de referència per al mode de resposta direct_post, en què la cartera envia la resposta per POST a un endpoint del servidor en lloc d'enviar-la a través del navegador.[1]
La cartera comprova el verificador i l'usuari dona el consentiment
El disseny de referència direct_post d'OpenID4VP 1.0, secció 13.3, simplificat.[1]
- Generar un nonce de «com a mínim 16 bytes nous i criptogràficament aleatoris» per a cada sol·licitud.
- Enviar a la cartera el request-id del punt final de resposta com a
state. - Retornar un URI de redirecció amb un
response_codenou quan la cartera faci l'enviament. - Obtenir el VP Token amb el transaction-id i aquest codi, i després comprovar el nonce.
El response_code impedeix la fixació de sessió, en què un atacant retransmet la vostra sol·licitud a la cartera d'una víctima. L'especificació indica que no ajuda entre dispositius i hi recomana mecanismes addicionals.[1]
Vídeo pendent: flow-eudi-openid4vp
Una presentació OpenID4VP des d'una cartera europea d'identitat digital (EUDI Wallet), de principi a fi.
L'objecte de sol·licitud d'OpenID4VP i els identificadors de client
El client_id comença amb un prefix d'identificador de client (Client Identifier Prefix) que indica a la cartera com ha d'autenticar el verificador.[1] Les sol·licituds grans viatgen per referència: la cartera obté l'objecte de sol·licitud signat d'un request_uri. Per als codis QR, l'especificació recomana direct_post amb request_uri, ja que la sol·licitud «potser no cap en un codi QR».[1]
| Prefix | Com autentica la cartera el verificador | Sol·licitud signada |
|---|---|---|
redirect_uri | L'identificador és l'URI de redirecció o de resposta | No es pot signar |
x509_san_dns | Nom DNS al SAN del certificat d'entitat final | Obligatòria |
x509_hash | Hash SHA-256 del certificat d'entitat final | Obligatòria |
decentralized_identifier | Clau del document DID | Obligatòria |
verifier_attestation | JWT d'atestació d'un emissor en què confia la cartera | Obligatòria |
openid_federation | Cadena de confiança de la federació | Mitjançant OpenID Federation |
Prefixos d'identificador de client, OpenID4VP 1.0, secció 5.9.[1]
Per als verificadors EUDI, el dret de la UE tria el prefix: el certificat final «per utilitzar amb el prefix d'identificador de client x509_hash serà un certificat d'accés de part usuària tal com s'especifica a ETSI TS 119 475», i un element de verifier_info «inclourà el certificat de registre».[5]
Consultes DCQL: demaneu el que heu registrat
El Digital Credentials Query Language (DCQL) és la consulta JSON que indica les credencials i els atributs que voleu. Conté una matriu credentials obligatòria i una matriu credential_sets opcional. Cada consulta de credencial necessita un id, un format i un objecte meta.[1] L'exemple SD-JWT VC de l'especificació:[1]
{ "credentials": [ { "id": "my_credential", "format": "dc+sd-jwt", "meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ] }, "claims": [ {"path": ["last_name"]}, {"path": ["first_name"]}, {"path": ["address", "street_address"]} ] } ] }
Per a un mdoc, el format és mso_mdoc i meta conté un doctype_value.[1] Per al PID, substituïu-hi el seu tipus i els noms dels atributs. Els atributs obligatoris del PID són el cognom, el nom, la data de naixement, el lloc de naixement i la nacionalitat.[7]
require_cryptographic_holder_bindingté el valor true per defecte. Manteniu-lo: fa que la cartera retorni una prova de vinculació de clau.[1]trusted_authoritiesnomés filtra el que ofereix la cartera. Els verificadors «han de verificar pel seu compte que l'emissor d'una presentació rebuda és de confiança».[1]- Les parts usuàries «no sol·licitaran als usuaris que proporcionin cap dada diferent de» la que han registrat, i la cartera ho comprova.[4][3]
Modes de resposta d'OpenID4VP
El mode de resposta determina com torna el VP Token. El valor per defecte per a vp_token és fragment, al fragment de l'URI de redirecció.[1]
| Mode de resposta | On va el VP Token | Xifrat |
|---|---|---|
fragment | Fragment de l'URI de redirecció, a través del navegador | No |
direct_post | HTTP POST a la response_uri | No |
direct_post.jwt | HTTP POST d'un JWT xifrat | Sí |
dc_api | De tornada a través de la Digital Credentials API | No |
dc_api.jwt | El mateix, xifrat | Sí |
Modes de resposta a OpenID4VP 1.0.[1]
Amb direct_post, response_uri és obligatori i redirect_uri no hi ha de ser. Si no, la cartera retorna invalid_request.[1] Per exemple, l'EVO Wallet de Moldàvia documenta OpenID4VP 1.0 amb direct_post.jwt en un flux en el mateix dispositiu, mdoc ISO/IEC 18013-5 segons el perfil d'OpenID4VC HAIP 1.0 i una IETF Token Status List per a la revocació.[11]
En el mateix dispositiu, entre dispositius i la Digital Credentials API
L'ARF enumera les combinacions remotes admeses. La primera és OpenID4VP amb un mecanisme de transmissió basat en redireccions i esquemes d'URI personalitzats. La segona és OpenID4VP o ISO/IEC 18013-7 amb la W3C Digital Credentials API. La tercera, opcional, és ISO/IEC 18013-7 amb redireccions i esquemes d'URI personalitzats.[3]
Mateix dispositiu
Esquema d'URI personalitzat
- El navegador passa openid4vp:// al sistema operatiu
- La cartera s'obre al mateix telèfon
ARF 4.4.3.1
Entre dispositius
Codi QR
- L'ordinador mostra un codi QR per escanejar
- Exposat al phishing i a atacs de retransmissió
ARF 4.4.3.1
API del navegador
Digital Credentials API
- El navegador transmet l'origen verificat
- Activada per defecte a Chrome 141
OpenID4VP, Apèndix A
Tres maneres com una cartera rep una sol·licitud OpenID4VP.[3][1][10]
L'ARF diu que els esquemes d'URI personalitzats «no es recomanen per a fluxos entre dispositius» i proposa la Digital Credentials API com a alternativa.[3] A través de l'API, la cartera coneix l'origen del verificador tal com l'ha autenticat el navegador, «cosa que és important per a la resistència al phishing».[1] L'especificació del W3C encara és un esborrany.[9] Això és el que veu l'usuari en un telèfon:
Verifiqueu la vostra identitat
Aquest lloc web demana les vostres dades a la vostra cartera.
1El navegador envia un URI openid4vp:// al sistema operatiu.[3]
Comprovant la sol·licitud
La cartera s'obre i es connecta a la part usuària.
2La cartera autentica la part usuària i comprova què ha registrat.[3]
Trieu què voleu compartir
- CognomCompartit
- Data de naixementCompartit
- AdreçaNo compartit
Compartir
3L'usuari aprova els atributs.[3]
Dades rebudes
4La cartera envia la resposta i retorna l'usuari.[1]
Verificació pas a pas d'una presentació SD-JWT VC
Una presentació SD-JWT VC conté el JWT signat per l'emissor, les revelacions que l'usuari ha fet i un Key Binding JWT. El verificador «HA DE validar cada Verifiable Presentation individual» i rebutjar qualsevol que tingui un nonce incorrecte.[1]
1Verificar la signatura de l'emissor
La clau s'encadena fins a un proveïdor de PID o d'atestacions de confiança.
2Comprovar cada revelació
El hash de cadascuna correspon a un resum de la càrrega útil signada.
3Verificar el Key Binding JWT
Signatura amb la clau del titular; el nonce i l'audiència coincideixen.
4Comprovar la revocació
Consultar la llista d'estat de l'emissor.
Totes les comprovacions són correctes
Utilitzar els atributs revelats
Rebutjar i oferir una altra via
Les comprovacions del verificador sobre una presentació SD-JWT VC.[1][3]
Signatura de l'emissor. L'ARF la situa en primer lloc entre les comprovacions de la part usuària. Els ancoratges de confiança provenen de les Trusted Lists (ETSI TS 119 612) i de les Lists of Trusted Entities (ETSI TS 119 602).[3]
Revelacions. La càrrega útil signada conté una matriu _sd de resums; cada revelació és una sal, un nom de declaració i un valor, com ara ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"].[1] Calculeu el hash de cadascuna i trobeu-ne el resum. Si no hi ha coincidència, l'emissor no l'ha signada.
Key Binding JWT. Quan es requereix la vinculació amb el titular, la cartera «HA DE retornar un SD-JWT amb un Key Binding JWT». El seu nonce ha de ser igual al nonce de la vostra sol·licitud i el seu aud, al vostre Client Identifier o, a través de la Digital Credentials API, al vostre origen precedit de origin:.[1] L'exemple de l'especificació:
{ "nonce": "n-0S6_WzA2Mj", "aud": "x509_san_dns:client.example.org", "iat": 1709838604, "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4" }
Revocació. La part usuària verifica que el proveïdor «no ha revocat el PID ni l'atestació».[3] L'EVO Wallet de Moldàvia, per exemple, documenta una IETF Token Status List per a aquesta finalitat.[11]
Nota
El retrat del PID només és obligatori a partir de l'11 d'agost de 2028. Per tant, no planifiqueu una comparació facial amb el retrat de la cartera abans d'aquesta data.[5]
Presentacions mdoc via ISO/IEC 18013-7, en resum
En el cas d'un mdoc, el VP Token conté un DeviceResponse de la ISO/IEC 18013-5 codificat en base64url que «conté una signatura o un MAC sobre el SessionTranscript», incloent-hi una estructura de handover d'OpenID4VP.[1] Aquest handover vincula el mdoc a la vostra sol·licitud, de la mateixa manera que el nonce i l'audience vinculen un SD-JWT VC.
Compte
El dret de la UE aplica l'«Annex C de la ISO/IEC 18013-7:2025» per a mdoc a través de la Digital Credentials API.[5] La ISO indica que l'edició de 2024 de la 18013-7 està retirada i substituïda. Comproveu quina edició implementa la vostra biblioteca.[8]
La nostra comparació entre SD-JWT VC i mdoc explica quan encaixa cada format.
Què afegeix el perfil HAIP per als verificadors EUDI
El High Assurance Interoperability Profile (HAIP) restringeix les opcions d'OpenID4VP. L'ARF ja l'exigeix per a l'emissió i afirma que el seu ús «és necessari per garantir la interoperabilitat».[3] Per a la presentació, el CIR 2026/1731 estableix un «perfil OpenID4VC-HAIP» i un «perfil ISO/IEC-mdoc».[5]
| Requisit | Per al vostre verificador | Font |
|---|---|---|
| Certificat d'accés | Signeu amb un certificat d'accés de part usuària x509_hash, ETSI TS 119 475 | CIR 2026/1731[5] |
| Certificat de registre | Incloeu-lo a verifier_info | CIR 2026/1731[5] |
| Registre | Registreu-vos on esteu establerts | eIDAS, art. 5b(1)[4] |
| Comprovacions de la cartera | Les unitats de cartera només validen els certificats de registre a partir de l'11 d'agost de 2028. No és un termini de registre | CIR 2026/1731[5] |
El certificat de registre «descriu l'ús previst de la part usuària i indica els atributs» que ha registrat, i el reglament de registre s'aplica a partir del 24 de desembre de 2026.[6] La data de l'11 d'agost de 2028 només afecta la comprovació d'aquest certificat per part de la cartera, no el registre.[5] Alemanya ho resumeix així: una organització «rep un certificat d'accés i un de registre per a l'organització i el cas d'ús».[12] La nostra guia de parts usuàries de la cartera europea d'identitat digital (EUDI Wallet) explica el registre de forma completa.
Errors habituals en construir un verificador OpenID4VP
| Error | Solució |
|---|---|
| Nonces reutilitzats o curts | Almenys 16 bytes aleatoris nous per sol·licitud[1] |
| Sense comprovació de l'audiència | Compareu aud amb el vostre Client Identifier o el vostre origen[1] |
| Demanar dades no registrades | Construïu la consulta DCQL a partir del vostre registre[4] |
| Codis QR amb URI personalitzats entre dispositius | Doneu prioritat a la Digital Credentials API[3] |
Confiar en trusted_authorities | Valideu vosaltres mateixos l'emissor amb les llistes de confiança[1] |
| Ometre la revocació | Comproveu l'estat cada vegada[3] |
Signar amb el prefix redirect_uri | No es pot signar. Utilitzeu x509_hash[1][5] |
La cartera també és voluntària: l'accés «no es restringirà ni es farà desavantatjós de cap manera» per a les persones que no la utilitzin, de manera que el vostre verificador conviu amb una altra via.[4]
Recursos de prova
Comenceu amb el programari de referència i les proves de conformitat abans de fer proves amb les carteres nacionals.
- Executeu les proves de conformitat a conformance.eudi.dev.[3]
- Llegiu la documentació de la implementació de referència a docs.eudi.dev. És documentació, no són proves.[3]
- Estudieu el verificador de demostració del Banc Nacional de Moldàvia i el seu codi font.[13]
- Consulteu l'esborrany de la Digital Credentials API abans de confiar en la via del navegador.[9]
Per a les dates en què es basa el vostre pla de proves, vegeu Terminis de la cartera europea d'identitat digital (EUDI Wallet) per al 2026 i el 2027.
Com us ajuda Didit amb la verificació amb la cartera EUDI
L'acceptació de la cartera EUDI arribarà aviat a Didit: és al nostre full de ruta, alineada amb el calendari de la cartera EUDI, en el mateix flux de treball que feu servir avui. Mentrestant, ja podeu verificar persones a distància.
- Avui funcionen a Didit cinc eID nacionals a través de les carteres d'identitat digital: MitID, BankID Sweden, Finnish Trust Network, Smart-ID i Mobile-ID. Vegeu verificació d'eID.
- Si una persona no té eID, el flux recorre a la verificació de documents amb lectura del xip NFC, prova de vida i comparació facial, configurada per país. Una comprovació KYC completa costa $0.33.
- El cribratge AML s'executa en el mateix flux per $0.20.
Les obligacions de part usuària continuen sent vostres. La documentació de les carteres mostra com s'activen les eID per país.
Didit proporciona
- Inicis de sessió amb eID nacionals i la via documental en un sol flux de treball
- L'evidència de cada comprovació
Queda a càrrec vostre
- El vostre registre com a part usuària de la cartera
- La decisió d'incorporació i les vostres polítiques
Planifiqueu amb nosaltres la vostra ruta cap a la cartera europea d'identitat digital (EUDI Wallet)
Digueu-nos els vostres països i el vostre cas d'ús, i comenceu avui amb els mitjans d'identificació electrònica nacionals i els documents.
Punts clau
- OpenID4VP 1.0 és una especificació final d'OpenID des del 10 de juliol de 2025.
- Envieu una consulta DCQL limitada pel vostre registre i amb un nonce nou.
- Verifiqueu la signatura de l'emissor, cada divulgació, el Key Binding JWT i la revocació.
- Els verificadors EUDI signen amb un certificat d'accés RP
x509_hash. - Les parts usuàries privades incloses en l'àmbit accepten la cartera com a tard el 24 de desembre de 2027.
Preguntes freqüents
Què és OpenID4VP?
OpenID for Verifiable Presentations és un protocol per sol·licitar i presentar credencials. La cartera retorna presentacions signades en un VP Token, sense cap codi d'autorització ni token d'accés per intercanviar. La versió 1.0 es va convertir en una especificació final d'OpenID el 10 de juliol de 2025.[1][2]
L'EUDI Wallet utilitza OpenID4VP?
Sí, per a la presentació remota, al costat de la ISO/IEC 18013-7. El dret de la UE estableix un perfil OpenID4VC-HAIP i un perfil ISO/IEC-mdoc.[3][5]
Què és DCQL?
El Digital Credentials Query Language és la consulta JSON que indica les credencials i les declaracions que vol un verificador. La cartera retorna les presentacions que hi coincideixen. Per a l'EUDI Wallet, demaneu només els atributs que heu registrat.[1][4]
Quin mode de resposta ha d'utilitzar un verificador EUDI?
Un verificador del costat del servidor utilitza direct_post o la variant xifrada direct_post.jwt. A través de la Digital Credentials API, els modes són dc_api i dc_api.jwt.[1]
Com verifico el Key Binding JWT?
Comproveu-ne la signatura amb la clau vinculada a la credencial i, després, comproveu-ne el nonce i l'audiència amb la vostra sol·licitud. A través de la Digital Credentials API, l'audiència és el vostre origen.[1]
Quin prefix d'identificador de client utilitzen els verificadors EUDI?
x509_hash, amb un certificat d'accés RP segons l'ETSI TS 119 475. El certificat de registre va a verifier_info.[5]
Puc utilitzar un codi QR entre dispositius?
Sí, però l'ARF no recomana esquemes d'URI personalitzats entre dispositius a causa dels atacs de phishing i de retransmissió. Indica la Digital Credentials API com a alternativa.[3]
Puc fer una comparació facial amb el retrat de la cartera?
Encara no de manera fiable. El retrat només esdevé una dada PID obligatòria a partir de l'11 d'agost de 2028.[5]
On puc provar un verificador OpenID4VP?
Executeu les proves de conformitat a conformance.eudi.dev i llegiu la documentació de la implementació de referència a docs.eudi.dev. El banc central de Moldàvia també ha publicat un verificador de demostració amb el codi font.[3][13]
Fonts
- OpenID for Verifiable Presentations 1.0, OpenID Foundation, especificació final.
- OpenID for Verifiable Presentations 1.0 Final Specification Approved, OpenID Foundation, 10 de juliol de 2025.
- Architecture and Reference Framework v3.0.0, eu-digital-identity-wallet a GitHub, versió publicada el 23 de juliol de 2026.
- Reglament (UE) 2024/1183 (eIDAS 2), EUR-Lex, Diari Oficial del 30 d'abril de 2024.
- Reglament d'execució (UE) 2026/1731 de la Comissió, EUR-Lex, Diari Oficial del 22 de juliol de 2026.
- Reglament d'execució (UE) 2025/848 de la Comissió sobre el registre de les parts usuàries de carteres, EUR-Lex, Diari Oficial del 7 de maig de 2025.
- Reglament d'execució (UE) 2024/2977 de la Comissió sobre les dades d'identificació de la persona, EUR-Lex, Diari Oficial del 4 de desembre de 2024.
- ISO/IEC 18013-7, pàgina de la norma a ISO.
- Digital Credentials, esborrany del W3C.
- Digital Credentials API shipped, Chrome for Developers.
- Guia per a desenvolupadors d'EVO Wallet, Govern de Moldàvia, egov4dev.
- Preguntes freqüents sobre la cartera europea d'identitat digital (EUDI Wallet), eudi-wallet.gov.de.
- Verificador de demostració del BNM, Govern de Moldàvia, egov4dev.
OpenID4VP és la part de la EUDI Wallet amb què més treballen els desenvolupadors, i és prou estable per desenvolupar-hi a sobre. Vegeu com aborda Didit l'acceptació de carteres a la pàgina de la solució EUDI Wallet, i el panorama general a la nostra visió general d'eIDAS 2.
Verifiqueu persones a distància mentre es despleguen les carteres
Feu servir ara els eID nacionals i la via documental, i parleu amb nosaltres sobre la EUDI Wallet.
Articles relacionats
- Integració de Cl@ve a Espanya: qui s'hi pot connectar i què fer servir en lloc seu
- Verificació PhilSys: com comproven les empreses el National ID
- Guia OpenID4VP: verificar i acceptar la cartera europea d'identitat digital (EUDI Wallet)
- Reglament eIDAS explicat: què canvia eIDAS 2 (2024/1183)
- API de Smart-ID: guia de la RP API v3 per a desenvolupadors
- Identitat digital nacional al món: models, líders i estàndards