Emissione di credenziali OpenID4VCI spiegata: dall'offerta alla credenziale accettata

L'intero ciclo di vita di un'offerta di credenziale

La specifica non definisce stati nominati, ma un flusso avviato dall'issuer in cui la credenziale viene emessa subito è il più semplice da seguire, come nella sequenza qui sotto. Ogni passaggio può fallire in modo diverso, e un'implementazione del wallet deve gestire quei percorsi, non solo quello ideale.

2. Scoperta dei metadati dell'issuer

Prima di richiedere qualsiasi cosa, il wallet recupera i metadati dell'issuer per sapere cosa contiene roadworthiness_certificate e quali endpoint chiamare. I metadati non elencano authorization server separati, quindi l'issuer è anche il proprio authorization server, e il wallet legge il token endpoint dai metadati di quel server.

Metadati del credential issuer (estratto)

{
  "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"] }
        ]
      }
    }
  }
}

Metadati dell'authorization server (estratto), da /.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 di possesso

Poiché i metadati elencano un nonce_endpoint, il wallet recupera prima un c_nonce recente da lì. Dimostra quindi di possedere la chiave privata a cui la credenziale sarà vincolata, firmando un JWT di prova sull'identificatore dell'issuer e su quel c_nonce.

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

Risposta

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

Il wallet costruisce ora il JWT di prova a partire da due oggetti JSON, un header e un payload, e li firma con la chiave privata a cui la credenziale sarà vincolata.

Header: cos'è questo JWT e quale chiave lo ha firmato

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

• typ: contrassegna questo come una key proof OpenID4VCI, così non può essere scambiato per un altro tipo di JWT
• alg: l'algoritmo di firma, uno di quelli elencati dall'issuer in proof_signing_alg_values_supported
• jwk: la chiave pubblica a cui la credenziale sarà vincolata; l'issuer verifica la firma rispetto ad essa

Payload: per chi è la prova e quando è stata creata

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

• aud: l'identificatore dell'issuer, così la prova non può essere riutilizzata presso un issuer diverso
• iat: l'istante in cui la prova è stata creata, in secondi dal 1970
• nonce: il c_nonce ottenuto dal nonce endpoint, che dimostra che la prova è recente

Risultato firmato

Header e payload sono ciascuno codificati in base64url e uniti con un punto. Il wallet firma quella stringa con la propria chiave privata e aggiunge la firma codificata in base64url dopo un secondo punto. La stringa risultante è il JWT di prova che il wallet invia nella richiesta di credenziale al passaggio 5.

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

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

Quando la credenziale non è ancora pronta: emissione differita

L'esempio sopra presume che l'esito dell'ispezione sia già definitivo. Se invece l'ente di revisione deve escalare un esito dubbio a un ispettore senior, il credential endpoint non può restituire subito la credenziale, quindi ne differisce l'emissione.

Risposta differita da /credential

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

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

Interrogazione di /deferred finché non è 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.

Termini correlati

Fonti

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