Verificador OpenID4VP: aceitação da carteira de identidade digital europeia (EUDI Wallet)
Como funciona um verificador OpenID4VP para a EUDI Wallet: objetos de pedido, consultas DCQL, modos de resposta, verificações SD-JWT VC e mdoc, as regras HAIP no direito da UE, erros comuns e onde testar.
Em resumo
O OpenID4VP (OpenID for Verifiable Presentations) é o protocolo que um verificador utiliza para pedir credenciais a uma carteira digital e receber de volta uma apresentação assinada. A versão 1.0 tornou-se uma OpenID Final Specification a 10 de julho de 2025, e a carteira europeia de identidade digital (EUDI Wallet) utiliza-o para a apresentação remota.[2][3]
- Envia um pedido assinado com uma consulta DCQL. A carteira devolve um VP Token.
- É o próprio verificador que valida a assinatura do emissor, as divulgações, a vinculação de chave e a revogação.
- Para a EUDI Wallet, o direito da UE acrescenta regras de certificados e de registo.
O OpenID4VP é a forma como um site ou uma aplicação pede a uma carteira que prove algo sobre uma pessoa, como o nome ou a data de nascimento. O verificador indica que credenciais e atributos pretende, o utilizador aprova na carteira e a carteira devolve uma apresentação que o verificador valida criptograficamente. Nas palavras da própria especificação, esta «define um protocolo para pedir e apresentar Credenciais».[1]
Este guia destina-se a programadores que constroem um verificador OpenID4VP para a carteira europeia de identidade digital (EUDI Wallet): o objeto de pedido, a DCQL, os modos de resposta, os fluxos no mesmo dispositivo e entre dispositivos, as verificações de SD-JWT VC e mdoc, as regras HAIP no direito da UE, os erros comuns e onde testar.
O OpenID4VP em termos simples
O OpenID4VP reutiliza a estrutura de um pedido de autorização OAuth 2.0. O verificador pede o tipo de resposta vp_token, e uma resposta bem-sucedida tem de incluir um parâmetro vp_token que contém as apresentações.[1] Não há código nem token de acesso para trocar: os dados chegam na resposta.
A carteira autentica a parte utilizadora, confirma que esta não pede mais do que registou, recolhe a aprovação do utilizador e assina a apresentação. A parte utilizadora valida depois a assinatura do emissor, o estado de revogação e a vinculação ao dispositivo.[3] Os dados de identificação pessoal (PID) são emitidos em dois formatos, SD-JWT VC e ISO/IEC mdoc, e ambos utilizam hashes com salt para que o utilizador possa partilhar alguns atributos e ocultar os restantes.[5][3]
- 10 de julho de 2025Especificação finalOpenID4VP 1.0 aprovado.
- 22 de julho de 2026PublicaçãoCIR 2026/1731 (adotado a 15 de julho de 2026) no Jornal Oficial.
- 23 de julho de 2026ARF v3.0.0Versão atual da arquitetura.
- 24 de dezembro de 2026CarteirasPelo menos uma por Estado-Membro.
- 24 de dezembro de 2027AceitaçãoPartes utilizadoras privadas regulamentadas.
Da especificação final à data de aceitação pelo setor privado.[2][3][4][5]
Como funciona uma troca com um verificador OpenID4VP
O OpenID4VP publica um modelo de referência para o modo de resposta direct_post, em que a carteira envia a resposta por POST para um endpoint do servidor em vez de a enviar através do navegador.[1]
A carteira verifica o verificador e o utilizador dá o consentimento
O modelo de referência direct_post do OpenID4VP 1.0, secção 13.3, simplificado.[1]
- Gere um nonce de "pelo menos 16 bytes novos e criptograficamente aleatórios" por pedido.
- Envie à carteira o request-id do endpoint de resposta como
state. - Devolva um URI de redirecionamento com um
response_codenovo assim que a carteira enviar a resposta. - Obtenha o VP Token com o transaction-id e esse código e, depois, verifique o nonce.
O response_code impede a fixação de sessão, em que um atacante reencaminha o seu pedido para a carteira de uma vítima. A especificação refere que não ajuda entre dispositivos e recomenda mecanismos adicionais nesse caso.[1]
Vídeo pendente: flow-eudi-openid4vp
Uma apresentação OpenID4VP a partir de uma carteira europeia de identidade digital (EUDI Wallet), do início ao fim.
O objeto de pedido OpenID4VP e os identificadores de cliente
O client_id começa com um prefixo de identificador de cliente (Client Identifier Prefix) que indica à carteira como autenticar o verificador.[1] Os pedidos grandes são transmitidos por referência: a carteira obtém o objeto de pedido assinado a partir de um request_uri. Para códigos QR, a especificação recomenda direct_post com request_uri, uma vez que o pedido "pode não caber num código QR".[1]
| Prefixo | Como a carteira autentica o verificador | Pedido assinado |
|---|---|---|
redirect_uri | O identificador é o URI de redirecionamento ou de resposta | Não pode ser assinado |
x509_san_dns | Nome DNS no SAN do certificado folha | Obrigatório |
x509_hash | Hash SHA-256 do certificado folha | Obrigatório |
decentralized_identifier | Chave do DID Document | Obrigatório |
verifier_attestation | JWT de atestação de um emissor em que a carteira confia | Obrigatório |
openid_federation | Cadeia de confiança da federação | Através da OpenID Federation |
Prefixos de identificador de cliente (Client Identifier Prefixes), OpenID4VP 1.0, secção 5.9.[1]
Para os verificadores EUDI, é o direito da UE que define o prefixo: o certificado folha "para utilização com o prefixo de identificador de cliente x509_hash deve ser um certificado de acesso de parte utilizadora, conforme especificado na ETSI TS 119 475", e um elemento de verifier_info "deve incluir o certificado de registo".[5]
Consultas DCQL: peça o que registou
A Digital Credentials Query Language (DCQL) é a consulta JSON que indica as credenciais e os atributos pretendidos. Contém um array credentials obrigatório e um array credential_sets opcional. Cada consulta de credencial precisa de um id, de um format e de um objeto meta.[1] O exemplo SD-JWT VC da especificação:[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"]} ] } ] }
Para um mdoc, o formato é mso_mdoc e meta contém um doctype_value.[1] Para o PID, substitua pelo respetivo tipo e pelos respetivos nomes de atributos. Os atributos obrigatórios do PID são apelido, nome próprio, data de nascimento, local de nascimento e nacionalidade.[7]
require_cryptographic_holder_bindingtem o valor predefinido true. Mantenha-o: faz com que a carteira devolva uma prova de vinculação de chave.[1]trusted_authoritiesapenas filtra o que a carteira oferece. Os verificadores "têm de verificar, por si próprios, se o emissor de uma apresentação recebida é de confiança".[1]- As partes utilizadoras "não podem solicitar aos utilizadores que forneçam quaisquer dados além" dos que registaram, e a carteira verifica.[4][3]
Modos de resposta do OpenID4VP
O modo de resposta determina a forma como o VP Token é devolvido. O valor predefinido para vp_token é fragment, no fragmento do URI de redirecionamento.[1]
| Modo de resposta | Para onde vai o VP Token | Cifrado |
|---|---|---|
fragment | Fragmento do URI de redirecionamento, através do navegador | Não |
direct_post | HTTP POST para o response_uri | Não |
direct_post.jwt | HTTP POST de um JWT cifrado | Sim |
dc_api | Devolvido através da Digital Credentials API | Não |
dc_api.jwt | Igual, mas cifrado | Sim |
Modos de resposta no OpenID4VP 1.0.[1]
Com direct_post, o response_uri é obrigatório e o redirect_uri tem de estar ausente. Caso contrário, a carteira devolve invalid_request.[1] A EVO Wallet da Moldávia, por exemplo, documenta o OpenID4VP 1.0 com direct_post.jwt num fluxo no mesmo dispositivo, mdoc ISO/IEC 18013-5 com perfil segundo o OpenID4VC HAIP 1.0 e uma IETF Token Status List para revogação.[11]
No mesmo dispositivo, entre dispositivos e a Digital Credentials API
O ARF enumera as combinações remotas suportadas: OpenID4VP combinado com um mecanismo de transmissão baseado em redirecionamentos e esquemas de URI personalizados; OpenID4VP ou ISO/IEC 18013-7 combinado com a W3C Digital Credentials API; e, opcionalmente, ISO/IEC 18013-7 com redirecionamentos e esquemas de URI personalizados.[3]
No mesmo dispositivo
Esquema de URI personalizado
- O navegador entrega openid4vp:// ao sistema operativo
- A carteira abre no mesmo telemóvel
ARF 4.4.3.1
Entre dispositivos
Código QR
- O computador mostra um código QR para digitalizar
- Vulnerável a phishing e a retransmissão
ARF 4.4.3.1
API do navegador
Digital Credentials API
- O navegador transmite a origem verificada
- Ativada por predefinição no Chrome 141
OpenID4VP Apêndice A
Três formas de uma carteira receber um pedido OpenID4VP.[3][1][10]
O ARF afirma que os esquemas de URI personalizados "não são recomendados para fluxos entre dispositivos" e indica a Digital Credentials API como alternativa.[3] Através da API, a carteira fica a conhecer a origem do verificador tal como autenticada pelo navegador, "o que é importante para a resistência ao phishing".[1] A especificação do W3C ainda é um projeto.[9] O que o utilizador vê num telemóvel:
Verifique a sua identidade
Este sítio web pede à sua carteira os seus dados.
1O navegador envia um URI openid4vp:// ao sistema operativo.[3]
A verificar o pedido
A carteira abre e liga-se à parte utilizadora.
2A carteira autentica a parte utilizadora e verifica o que esta registou.[3]
Escolha o que partilhar
- ApelidoPartilhado
- Data de nascimentoPartilhado
- MoradaNão partilhado
Partilhar
3O utilizador aprova os atributos.[3]
Dados recebidos
4A carteira submete a resposta e devolve o utilizador.[1]
Verificar uma apresentação SD-JWT VC passo a passo
Uma apresentação SD-JWT VC contém o JWT assinado pelo emissor, as divulgações que o utilizador revelou e um Key Binding JWT. O verificador "TEM DE validar cada Verifiable Presentation individual" e rejeitar qualquer uma com o nonce errado.[1]
1Verificar a assinatura do emissor
A chave encadeia até um fornecedor de PID ou de atestados de confiança.
2Verificar cada divulgação
O hash de cada uma corresponde a um digest no payload assinado.
3Verificar o Key Binding JWT
Assinatura com a chave do titular; o nonce e o destinatário coincidem.
4Verificar a revogação
Ler a lista de estado do emissor.
Todas as verificações são aprovadas
Usar os atributos divulgados
Rejeitar e oferecer outra via
As verificações do verificador sobre uma apresentação SD-JWT VC.[1][3]
Assinatura do emissor. O ARF coloca-a em primeiro lugar entre as verificações da parte utilizadora. As âncoras de confiança provêm das Listas de Confiança (ETSI TS 119 612) e das Listas de Entidades de Confiança (ETSI TS 119 602).[3]
Divulgações. O payload assinado contém um array _sd de digests; cada divulgação é um salt, um nome de atributo e um valor, como ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"].[1] Calcule o hash de cada uma e encontre o respetivo digest. Sem correspondência, o emissor não a assinou.
Key Binding JWT. Quando a vinculação ao titular é exigida, a carteira "TEM DE devolver um SD-JWT com um Key Binding JWT". O seu nonce tem de ser igual ao nonce do seu pedido e o seu aud tem de ser igual ao seu Client Identifier ou, através da Digital Credentials API, à sua origem com o prefixo origin:.[1] O exemplo da especificação:
{ "nonce": "n-0S6_WzA2Mj", "aud": "x509_san_dns:client.example.org", "iat": 1709838604, "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4" }
Revogação. A parte utilizadora verifica que o fornecedor "não revogou o PID ou o atestado".[3] A EVO Wallet da Moldávia, por exemplo, documenta uma IETF Token Status List para este fim.[11]
Nota
O retrato do PID só passa a ser obrigatório a partir de 11 de agosto de 2028, pelo que não deve planear uma correspondência facial com o retrato da carteira antes dessa data.[5]
Apresentações mdoc através da ISO/IEC 18013-7, em resumo
Para um mdoc, o VP Token contém uma DeviceResponse da ISO/IEC 18013-5, codificada em base64url, que «contém uma assinatura ou MAC sobre o SessionTranscript», incluindo uma estrutura de handover do OpenID4VP.[1] Esse handover vincula o mdoc ao seu pedido, tal como o nonce e o destinatário vinculam um SD-JWT VC.
Atenção
O direito da UE aplica o «Anexo C da ISO/IEC 18013-7:2025» ao mdoc através da Digital Credentials API.[5] A ISO indica a edição de 2024 da 18013-7 como retirada e substituída, pelo que deve verificar que edição a sua biblioteca implementa.[8]
A nossa comparação SD-JWT VC vs mdoc explica quando cada formato é adequado.
O que o perfil HAIP acrescenta para os verificadores EUDI
O High Assurance Interoperability Profile (HAIP) restringe as opções do OpenID4VP. O ARF já o exige para a emissão e afirma que a sua utilização «é necessária para garantir a interoperabilidade».[3] Para a apresentação, o CIR 2026/1731 estabelece um «perfil OpenID4VC-HAIP» e um «perfil ISO/IEC-mdoc».[5]
| Requisito | Para o seu verificador | Fonte |
|---|---|---|
| Certificado de acesso | Assinar com um certificado de acesso de parte utilizadora x509_hash, ETSI TS 119 475 | CIR 2026/1731[5] |
| Certificado de registo | Incluí-lo em verifier_info | CIR 2026/1731[5] |
| Registo | Registar-se no Estado-Membro onde está estabelecido | eIDAS, Art. 5b(1)[4] |
| Verificações da carteira | As unidades de carteira só validam certificados de registo a partir de 11 de agosto de 2028; não é um prazo de registo | CIR 2026/1731[5] |
O certificado de registo «descreve a utilização prevista da parte utilizadora e indica os atributos» que esta registou, e o regulamento relativo ao registo aplica-se a partir de 24 de dezembro de 2026.[6] A data de 11 de agosto de 2028 abrange apenas a verificação desse certificado do lado da carteira, não o registo.[5] A Alemanha resume assim: uma organização «recebe um certificado de acesso e de registo para a organização e para o caso de utilização».[12] O nosso guia para partes utilizadoras da carteira europeia de identidade digital (EUDI Wallet) aborda o registo em pormenor.
Erros comuns ao construir um verificador OpenID4VP
| Erro | Correção |
|---|---|
| Nonces reutilizados ou curtos | Pelo menos 16 bytes aleatórios novos por pedido[1] |
| Sem verificação do destinatário | Compare o aud com o seu Client Identifier ou com a origem[1] |
| Pedir dados não registados | Construa a consulta DCQL a partir do seu registo[4] |
| Códigos QR com URI personalizado entre dispositivos | Prefira a Digital Credentials API[3] |
Confiar em trusted_authorities | Valide o emissor face às listas de confiança por si próprio[1] |
| Ignorar a revogação | Verifique o estado em todas as verificações[3] |
Assinar com o prefixo redirect_uri | Não pode ser assinado; use x509_hash[1][5] |
A carteira também é voluntária: o acesso «não pode, de modo algum, ser restringido nem tornado desvantajoso» para as pessoas que não a utilizam, pelo que o seu verificador funciona ao lado de outra via.[4]
Recursos de teste
Comece pelo software de referência e pelos testes de conformidade antes de testar com as carteiras nacionais.
- Execute os testes de conformidade em conformance.eudi.dev.[3]
- Leia a documentação da implementação de referência em docs.eudi.dev, que é documentação e não testes.[3]
- Estude o verificador de demonstração do Banco Nacional da Moldávia e o respetivo código-fonte.[13]
- Consulte o projeto da Digital Credentials API antes de depender da via do navegador.[9]
Para as datas subjacentes ao seu plano de testes, consulte prazos da carteira europeia de identidade digital (EUDI Wallet) para 2026 e 2027.
Como a Didit ajuda na verificação com a EUDI Wallet
A aceitação da EUDI Wallet chega em breve à Didit: está no nosso plano de desenvolvimento, alinhada com o calendário da EUDI Wallet, no mesmo fluxo que já utiliza hoje. Entretanto, já pode verificar pessoas à distância.
- Cinco eID nacionais funcionam hoje na Didit através das carteiras de identidade digital: MitID, BankID Sweden, Finnish Trust Network, Smart-ID e Mobile-ID. Consulte verificação de eID.
- Se uma pessoa não tiver eID, o fluxo recorre à verificação de documentos com leitura do chip NFC, deteção de vivacidade e correspondência facial, configurados por país. Uma verificação KYC completa custa $0.33.
- A triagem AML é executada no mesmo fluxo por $0.20.
Mantém as suas obrigações de parte utilizadora. A documentação das carteiras mostra como as eID são ativadas por país.
A Didit fornece
- Autenticações com eID nacionais e a via documental num único fluxo
- A prova de cada verificação
Fica consigo
- O seu registo como parte utilizadora da carteira
- A decisão de aceitação de clientes e as suas políticas
Planeie connosco o seu percurso para a carteira europeia de identidade digital (EUDI Wallet)
Indique-nos os seus países e o seu caso de utilização e comece hoje com eIDs nacionais e documentos.
Pontos-chave
- O OpenID4VP 1.0 é uma especificação final da OpenID desde 10 de julho de 2025.
- Envie uma consulta DCQL limitada pelo seu registo, com um nonce novo.
- Verifique a assinatura do emissor, cada divulgação, o Key Binding JWT e a revogação.
- Os verificadores EUDI assinam com um certificado de acesso de parte utilizadora
x509_hash. - As partes utilizadoras privadas abrangidas aceitam a carteira até 24 de dezembro de 2027.
Perguntas frequentes
O que é o OpenID4VP?
O OpenID for Verifiable Presentations é um protocolo para pedir e apresentar credenciais. A carteira devolve apresentações assinadas num VP Token, sem código de autorização nem token de acesso para trocar. A versão 1.0 tornou-se uma OpenID Final Specification em 10 de julho de 2025.[1][2]
A EUDI Wallet usa o OpenID4VP?
Sim, para a apresentação remota, a par da ISO/IEC 18013-7. O direito da UE define um perfil OpenID4VC-HAIP e um perfil ISO/IEC-mdoc.[3][5]
O que é a DCQL?
A Digital Credentials Query Language é a consulta JSON que indica as credenciais e os atributos que um verificador pretende. A carteira devolve as apresentações correspondentes. Para a EUDI Wallet, peça apenas os atributos que registou.[1][4]
Que modo de resposta deve usar um verificador EUDI?
Um verificador do lado do servidor usa direct_post ou o direct_post.jwt cifrado. Através da Digital Credentials API, os modos são dc_api e dc_api.jwt.[1]
Como verifico o Key Binding JWT?
Verifique a assinatura com a chave vinculada na credencial e, depois, verifique o nonce e o destinatário face ao seu pedido. Através da Digital Credentials API, o destinatário é a sua origem.[1]
Que prefixo de identificador de cliente usam os verificadores EUDI?
x509_hash, com um certificado de acesso de parte utilizadora conforme a ETSI TS 119 475. O certificado de registo vai em verifier_info.[5]
Posso usar um código QR entre dispositivos?
Pode, mas o ARF não recomenda esquemas de URI personalizados entre dispositivos devido a ataques de phishing e de retransmissão. Indica a Digital Credentials API como alternativa.[3]
Posso fazer a correspondência facial com o retrato da carteira?
Ainda não de forma fiável. O retrato só passa a ser um dado PID obrigatório a partir de 11 de agosto de 2028.[5]
Onde posso testar um verificador OpenID4VP?
Execute os testes de conformidade em conformance.eudi.dev e consulte a documentação da implementação de referência em docs.eudi.dev. O banco central da Moldávia também publicou um verificador de demonstração com código-fonte.[3][13]
Fontes
- OpenID for Verifiable Presentations 1.0, OpenID Foundation, Especificação final.
- Aprovada a especificação final do OpenID for Verifiable Presentations 1.0, OpenID Foundation, 10 de julho de 2025.
- Architecture and Reference Framework v3.0.0, eu-digital-identity-wallet no GitHub, versão de 23 de julho de 2026.
- Regulamento (UE) 2024/1183 (eIDAS 2), EUR-Lex, Jornal Oficial de 30 de abril de 2024.
- Regulamento de Execução (UE) 2026/1731 da Comissão, EUR-Lex, Jornal Oficial de 22 de julho de 2026.
- Regulamento de Execução (UE) 2025/848 da Comissão relativo ao registo das partes utilizadoras de carteiras, EUR-Lex, Jornal Oficial de 7 de maio de 2025.
- Regulamento de Execução (UE) 2024/2977 da Comissão relativo aos dados de identificação pessoal, EUR-Lex, Jornal Oficial de 4 de dezembro de 2024.
- ISO/IEC 18013-7, página da norma na ISO.
- Digital Credentials, projeto do W3C.
- Lançamento da Digital Credentials API, Chrome for Developers.
- Guia para programadores da EVO Wallet, Governo da Moldávia, egov4dev.
- Perguntas frequentes sobre a EUDI Wallet, eudi-wallet.gov.de.
- Verificador de demonstração do BNM, Governo da Moldávia, egov4dev.
O OpenID4VP é a parte da carteira europeia de identidade digital (EUDI Wallet) com que os programadores mais lidam, e é suficientemente estável para desenvolver com base nele. Veja como a Didit aborda a aceitação de carteiras na página da solução EUDI Wallet, e o panorama mais amplo na nossa visão geral do eIDAS 2.
Verifique pessoas à distância enquanto as carteiras são implementadas
Utilize já as eID nacionais e a via documental, e fale connosco sobre a carteira europeia de identidade digital (EUDI Wallet).
Artigos relacionados
- Integração do Cl@ve em Espanha: quem se pode ligar e que alternativas usar
- Verificação PhilSys: como as empresas verificam o National ID
- Verificador OpenID4VP: aceitação da carteira de identidade digital europeia (EUDI Wallet)
- Regulamento eIDAS explicado: o que muda com o eIDAS 2 (2024/1183)
- API Smart-ID: guia para programadores da RP API v3
- Identidade digital nacional no mundo: modelos, líderes e normas