Emissão de credenciais OpenID4VCI explicada: da oferta à credencial aceite

O ciclo de vida completo de uma oferta de credencial

A especificação não define estados nomeados, mas um fluxo iniciado pelo issuer em que a credencial é emitida de imediato é o mais fácil de seguir, como na sequência abaixo. Cada passo pode falhar à sua maneira, e uma implementação de wallet tem de lidar com esses caminhos, não apenas com o cenário ideal.

2. Descoberta de metadados do issuer

Antes de solicitar seja o que for, a wallet obtém os metadados do issuer para saber o que o roadworthiness_certificate contém e quais os endpoints a chamar. Os metadados não listam authorization servers separados, pelo que o issuer é o seu próprio authorization server, e a wallet lê o token endpoint a partir dos metadados desse servidor.

Metadados do credential issuer (excerto)

{
  "credential_issuer": "https://issuer.fleetinspect.example",
  "nonce_endpoint": "https://issuer.fleetinspect.example/nonce",
  "credential_endpoint": "https://issuer.fleetinspect.example/credential",
  "deferred_credential_endpoint": "https://issuer.fleetinspect.example/deferred",
  "notification_endpoint": "https://issuer.fleetinspect.example/notify",
  "credential_configurations_supported": {
    "roadworthiness_certificate": {
      "format": "dc+sd-jwt",
      "vct": "https://fleetinspect.example/vct/roadworthiness",
      "cryptographic_binding_methods_supported": ["jwk"],
      "credential_signing_alg_values_supported": ["ES256"],
      "proof_types_supported": {
        "jwt": { "proof_signing_alg_values_supported": ["ES256"] }
      },
      "credential_metadata": {
        "claims": [
          { "path": ["vehicle_registration"] },
          { "path": ["inspection_result"] },
          { "path": ["valid_until"] }
        ]
      }
    }
  }
}

Metadados do authorization server (excerto), de /.well-known/oauth-authorization-server

{
  "issuer": "https://issuer.fleetinspect.example",
  "token_endpoint": "https://issuer.fleetinspect.example/token",
  "pre-authorized_grant_anonymous_access_supported": true
}

4. Prova de posse

Como os metadados listam um nonce_endpoint, a wallet obtém primeiro um c_nonce recente aí. Depois prova que possui a chave privada a que a credencial será vinculada, assinando um JWT de prova sobre o identificador do issuer e esse c_nonce.

POST /nonce HTTP/1.1
Host: issuer.fleetinspect.example

Resposta

{
  "c_nonce": "fi-nonce-77aa"
}

A wallet constrói agora o JWT de prova a partir de dois objetos JSON, um header e um payload, e assina-os com a chave privada a que a credencial será vinculada.

Header: o que é este JWT e qual chave o assinou

{
  "typ": "openid4vci-proof+jwt",
  "alg": "ES256",
  "jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
}

• typ: marca isto como uma key proof OpenID4VCI, para não poder ser confundida com qualquer outro tipo de JWT
• alg: o algoritmo de assinatura, um dos que o issuer listou em proof_signing_alg_values_supported
• jwk: a chave pública a que a credencial será vinculada; o issuer verifica a assinatura em relação a esta

Payload: para quem é a prova e quando foi criada

{
  "aud": "https://issuer.fleetinspect.example",
  "iat": 1789376400,
  "nonce": "fi-nonce-77aa"
}

• aud: o identificador do issuer, para que a prova não possa ser reutilizada noutro issuer
• iat: o momento em que a prova foi criada, em segundos desde 1970
• nonce: o c_nonce do nonce endpoint, que demonstra que a prova é recente

Resultado assinado

O header e o payload são cada um codificados em base64url e unidos com um ponto. A wallet assina essa string com a sua chave privada e junta a assinatura codificada em base64url após um segundo ponto. A string resultante é o JWT de prova que a wallet envia no pedido de credencial no passo 5.

base64url(header) . base64url(payload) . base64url(signature)

eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIs...
  .eyJhdWQiOiJodHRwczovL2lzc3Vlci5mbGVldGluc3BlY3QuZXhhbXBsZSIs...
  .<ES256 signature>

Quando a credencial ainda não está pronta: emissão diferida

O exemplo acima assume que o resultado da inspeção já é final. Se, em vez disso, a entidade de inspeção precisar de escalar um resultado duvidoso para um inspetor sénior, o credential endpoint não pode devolver a credencial de imediato, pelo que diferi a emissão.

Resposta diferida de /credential

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "transaction_id": "fi-tx-55c2",
  "interval": 900
}

Consultar /deferred até estar pronta

POST /deferred HTTP/1.1
Host: issuer.fleetinspect.example
Content-Type: application/json
Authorization: Bearer fi-at-3d91e0

{ "transaction_id": "fi-tx-55c2" }

// While the review is open: 202 with the same transaction_id and interval.
// Once approved: 200 with the credentials, optionally with a notification_id.
// If the review rejects the result: a credential_request_denied error.

Termos relacionados

Fontes

1. OpenID for Verifiable Credential Issuance 1.0
2. OpenID4VC High Assurance Interoperability Profile 1.0
3. EUDI Wallet Architecture and Reference Framework