A seconda di come l'Utente stia interagendo con il frontend dell'App di Verifica Web, usando cioè il dispositivo in cui risiede l'Unità Wallet (Same Device) oppure un altro dispositivo (Cross Device), la Relying Party DEVE supportare i seguenti flussi remoti (RPR-84):
Same Device: essa DEVE fornire un indirizzo HTTP all'Istanza del Wallet utilizzando un redirect (302) o un href HTML nella pagina web (RPR-01);
Cross Device: essa DEVE fornire un indirizzo HTTP tramite un Codice QR che l'Utente scansiona con l'Istanza del Wallet (RPR-03).
Successivamente, l'Istanza del Wallet valida la trust con la Relying Party, valuta ne la richiesta, e, se l'Utente fornisce il consenso per la divulgazione dei propri Attestati Elettronici, li invia sotto forma di Verifiable Presentation.
Authorization Request: l'Istanza del Wallet ottiene un URL nel flusso Same Device o un Codice QR nel flusso Cross Device contenente direttamente il Request Object firmato (Request Object by value) oppure un puntatore a dove il Request Object firmato è disponibile per il download (Request Object by reference). Se Request Object by reference, vengono eseguiti anche i passaggi 2 e 3.
Richiesta URI Request: l'Istanza del Wallet estrae dal payload i seguenti parametri: client_id, request_uri, request_uri_method.
Se request_uri_method è fornito e impostato con il valore post, l'Istanza del Wallet DOVREBBE trasmettere i suoi metadata all'endpoint request_uri della Relying Party utilizzando il metodo HTTP POST.
Se request_uri_method è impostato con il valore get o non è presente, l'Istanza del Wallet DEVE recuperare il Request Object firmato utilizzando una richiesta HTTP con metodo GET all'endpoint fornito nel parametro request_uri (RPR-78).
URI Request Response: la Relying Party restituisce un Request Object firmato all'Istanza del Wallet.
Controlli Istanza di Wallet: l'Istanza del Wallet:
verifica la firma del Request Object firmato utilizzando la chiave pubblica identificata nell'intestazione JWT del Request Object. Utilizzando tale riferimento, l'Istanza del Wallet è in grado di selezionare la corretta chiave pubblica della Relying Party per la verifica della firma (WP_085).
verifica che il client_id contenuto nel Request Object (Relying Party) corrisponda a quello ottenuto al passaggio 2:
Se client_id utilizza il prefisso openid_federation, DEVE corrispondere al parametro sub contenuto nella Entity Configuration della Relying Party all'interno della Trust Chain (WP_086).
Se client_id utilizza il prefisso x509_hash, l'Istanza del Wallet DEVE verificare che l'hash del certificato X.509 della Relying Party (nell'intestazione x5c della richiesta) corrisponda all'hash contenuto in client_id del passaggio 2 (come definito in OpenID4VP, Sezione 5.9.3).
valuta gli Attestati Elettronici richiesti e verifica l'idoneità della Relying Party nel richiedere questi ultimi. Ad esempio, applicando le politiche relative a quella specifica Relying Party ottenute con la Trust Chain (WP_087).
Risposta di Autorizzazione POST: l'Istanza del Wallet presenta le informazioni richieste alla Relying Party, insieme alla Wallet Attestation se richiesto.
Controlli RP: La Relying Party convalida le Credenziali presentate verificando la fiducia con i loro Fornitori di Attestati Elettronici e controlla la Wallet Attestation per garantire che il Fornitore di Wallet sia affidabile.
Risposta della Relying Party: l'Istanza del Wallet informa l'Utente dell'autenticazione riuscita con la Relying Party, e l'Utente continua la navigazione.
Di seguito è riportato un diagramma di sequenza che dettaglia le interazioni tra tutte le parti coinvolte.
I dettagli di ogni passaggio mostrato nell'immagine precedente sono descritti di seguito.
Passaggi 1-2: L'Utente richiede di accedere a una risorsa protetta della Relying Party.
Passaggio 3: La Relying Party crea un valore state legato allo user-agent (ad esempio, utilizzando un cookie HTTP contrassegnato Secure e HttpOnly) e ispeziona lo user-agent dell'utente per determinare se il flusso avviene sullo stesso dispositivo dello user-agent.
Passaggi 4-7 (Authorization Request): La Relying Party fornisce allo user-agent una pagina JavaScript che ispeziona lo state endpoint e all'Istanza del Wallet un URL contenente l'Authorization Request.
Nel Flusso Cross Device, l'URI dell'Authorization Request viene presentato attraverso un Codice QR mostrato all'Utente. L'Utente scansiona il Codice QR utilizzando l'Istanza del Wallet e recupera un URL.
Di seguito è rappresentato un esempio non normativo di un Codice QR emesso dalla Relying Party.
Nota
Il livello di correzione degli errori scelto per il Codice QR DEVE essere Q (Quartile - fino al 25%), poiché offre un buon equilibrio tra capacità di correzione degli errori e densità/spazio dei dati. Questo livello di qualità e correzione degli errori consente al Codice QR di rimanere leggibile anche se è danneggiato o parzialmente oscurato (RPR-77).
Se il Request Object viene passato per valore (by value), l'URL all'interno del codice QR contiene i parametri client_id e request.
Di seguito è rappresentato un esempio non normativo del contenuto del Codice QR per un Request Object by value:
Se invece il Request Object viene passato per riferimento (by reference), l'URL all'interno del codice QR contiene i parametri client_id, request_uri e request_uri_method (WP_076–077).
Di seguito è riportato un esempio non normativo del contenuto del codice QR per un Request Object by reference:
Mentre, nel Flusso Same Device, la Relying Party risponde tramite HTTP Response Redirect (con codice di stato impostato a 302) o mostra all'utente una pagina html con un pulsante href, aventi l'URL che fornisce le stesse informazioni del Flusso Cross Device (WP_076–077).
Di seguito è riportato un esempio non normativo per un Request Object by reference:
Passaggio 8: L'Istanza del Wallet valuta la trust con la Relying Party (WP_078–080).
Passaggi 9-11 (Richiesta URI Request): L'Istanza del Wallet verifica se la Relying Party ha fornito il request_uri_method all'interno del suo Request Object firmato (WP_083).
Se è fornito ed è uguale a post, l'Istanza del Wallet DOVREBBE fornire i suoi metadata alla Relying Party. La Relying Party aggiorna il Request Object in base alle capacità tecniche del Wallet.
Di seguito è riportato un esempio non normativo di una richiesta HTTP effettuata dall'Istanza del Wallet alla Relying Party.
Quando la Relying Party non supporta request_uri_method con valore post, l'Istanza del Wallet richiede il Request Object firmato utilizzando il metodo HTTP GET (WP_082).
Passaggio 12 (URI Request Response): La Relying Party emette il Request Object firmandolo utilizzando una delle sue chiavi crittografiche private, le cui corrispondenti chiavi pubbliche sono state pubblicate all'interno della sua Entity Configuration (metadata.openid_credential_verifier.jwks) come estratto dall'Istanza del Wallet per WP_084. L'Istanza del Wallet ottiene il Request Object firmato.
Di seguito è riportato un esempio non normativo della Risposta URI di Reindirizzamento:
{"client_id":"openid_federation:https://relying-party.example.org","response_mode":"direct_post.jwt","response_type":"vp_token","dcql_query":{"credentials":[{"id":"personal id data","format":"dc+sd-jwt","meta":{"vct_values":["urn:eudi:pid:it:1"]},"claims":[{"path":["given_name"]},{"path":["family_name"]},{"path":["personal_administrative_number"]}]},{"id":"wallet attestation","format":"dc+sd-jwt","meta":{"vct_values":["urn:eudi:WalletAttestation:it:1"]},"claims":[{"path":["wallet_link"]},{"path":["wallet_name"]}]}]},"response_uri":"https://relying-party.example.org/response_uri","nonce":"2c128e4d-fc91-4cd3-86b8-18bdea0988cb","wallet_nonce":"qPmxiNFCR3QTm19POc8u","state":"3be39b69-6ac1-41aa-921b-3e6c07ddcb03","iss":"https://relying-party.example.org","iat":1672418465,"exp":1672422065,"request_uri_method":"post"}
Passaggi 13-15 (Controlli WI): L'Istanza del Wallet verifica l'Oggetto di Richiesta, che è sotto forma di JWT firmato (WP_085–086). Quindi elabora i metadati della Relying Party e applica le politiche pertinenti per determinare quali Credenziali Elettroniche e dati dell'Utente la Relying Party è autorizzata a richiedere (WP_087).
Passaggi 16-17 (Consenso dell'Utente): L'Istanza del Wallet richiede il consenso dell'Utente per divulgare gli Attetstati Elettronici richiesti mostrando l'identità della Relying Party e gli attributi richiesti. L'Utente autorizza e acconsente alla presentazione degli Attributi Elettronici selezionando e o deselezionando i dati personali da rilasciare (WP_088).
Passaggio 18 (Authorization Response): L'Istanza del Wallet fornisce la Authorization Response alla Relying Party utilizzando una richiesta HTTP con il metodo POST (modalità di risposta direct_post.jwt).
Di seguito è riportato un esempio non normativo della Authorization Response:
Di seguito è riportato un esempio non normativo del payload decifrato del JWT contenuto nel parametro response, prima della codifica base64url. Il valore del parametro vp_token corrisponde al formato utilizzato quando il linguaggio di query DCQL viene utilizzato nella richiesta di presentazione.
{"state":"3be39b69-6ac1-41aa-921b-3e6c07ddcb03","vp_token":{"personal id data":"eyJhbGciOiJFUzI1NiIs...PT0iXX0","wallet attestation":"eyJhbGciOiJFUzI1NiIs...NTi0XG"}}
Passaggi 19-20 (Controlli RP): La Relying Party verifica la Risposta di Autorizzazione, estrae la Wallet Attestation per stabilire la fiducia con la Soluzione Wallet. Quindi estrae il vp_token che contiene una o più presentazioni di Attestati Elettronici di Attributi, e ne valida il formato complessivo. Per ogni presentazione di un Attestato, la Relying Party ne verifica l’integrità secondo i criteri della query DCQL definiti nella Richiesta di Autorizzazione. La Relying Party DEVE anche attestare la fiducia con il relativo Fornitore di Attestati Elettronici e verificare la prova di possesso dell'Istanza del Wallet per ogni Attestato presentato. Infine, la Relying Party verifica lo stato di revoca di ogni Attestato presentato come descritto in Revoca e Sospensione degli Attestati Elettronici. Se tutte le verifiche precedenti hanno dato esito positivo, la Relying Party aggiorna la sessione dell'Utente.
Passaggi 24-25 o 26 (Risposta della Relying Party): La Relying Party fornisce all'Istanza del Wallet la risposta sulla presentazione, che a sua volta informa l'Utente.
Dopo aver ricevuto e convalidato la Authorization Response al Response Endpoint, la Relying Party restituisce all'Istanza del Wallet un codice HTTP 200 OK. In particolare, nel Flusso Same Device, la Relying Party DOVREBBE anche passare il redirect_uri all'Istanza del Wallet. Dopo aver ricevuto il redirect_uri, l'Istanza del Wallet DEVE eseguire un reindirizzamento all'URL specificato dal redirect_uri. Questo reindirizzamento consente alla Relying Party di riprendere senza problemi l'interazione con l'Utente sul dispositivo che ha avviato il flusso. Quando la risposta non contiene il parametro redirect_uri, l'Istanza del Wallet non è tenuta a eseguire ulteriori passaggi. L'Utente dovrebbe chiudere manualmente l'Istanza del Wallet e aprire lo user-agent per continuare il flusso (RPR-83).
Di seguito è riportato un esempio non normativo della risposta nel Flusso Same Device.
Quando l'Istanza del Wallet ha fornito la presentazione all'endpoint response_uri della Relying Party e l'autenticazione dell'Utente ha avuto successo. La Relying Party aggiorna il cookie di sessione consentendo all'user-agent di accedere alla risorsa protetta. Viene fornito un URL di reindirizzamento che trasporta la posizione in cui l'user-agent deve navigare.
Di seguito è riportato un esempio non normativo della risposta con il redirect_uri dalla Relying Party all'user-agent.
Passaggi 29-30: Lo user-agent viene reindirizzato al redirect_uri per continuare la navigazione con la risorsa protetta resa disponibile all'Utente (WP_094).
I parametri URL contenuti nella Authorization Request della Relying Party sono descritti nella tabella seguente.
Nome
Descrizione
client_id
OBBLIGATORIO. Identificatore univoco della Relying Party. Il valore DEVE utilizzare uno dei seguenti prefissi di identificatore del Client (come definito in OpenID4VP, Sezione 5.9): openid_federation (identificatore dell’entità della Relying Party in una catena di fiducia) oppure x509_hash (hash SHA-256 codificato in base64url del certificato X.509 della Relying Party).
request
CONDIZIONALE. OBBLIGATORIO a meno che request_uri non sia presente. Contiene il Request Object firmato e codificato in base64url. Per il contenuto dell'oggetto Request, vedere la Sezione Request Object.
request_uri
CONDIZIONALE. OBBLIGATORIO a meno che request non sia presente. L'URL HTTP dove la Relying Party fornisce il Request Object firmato all'Istanza del Wallet.
request_uri_method
OPZIONALE solo se request_uri è presente. Il metodo HTTP DEVE essere impostato con get o post. L'Istanza del Wallet dovrebbe utilizzare questo metodo per ottenere il Request Object firmato all'indirizzo fornito dal request_uri. Se non fornito o uguale a get, l'Istanza del Wallet DEVE utilizzare il metodo HTTP get. Altrimenti, l'Istanza del Wallet DOVREBBE fornire i suoi metadata all'interno del body della richiesta HTTP POST codificati in application/x-www-form-urlencoded.
Nota
Le specifiche IT Wallet raccomandano l'uso di request_uri, ovvero Request Object by reference.
Avvertimento
Per motivi di sicurezza e per prevenire attacchi di tipo endpoint mix-up, il valore contenuto nel parametro request_uri DEVE essere uno di quelli attestati da una terza parte fidata, come quelli forniti nei metadata openid_credential_verifier all'interno del parametro request_uris, ottenuti dalla Trust Chain relativa alla Relying Party (WP_081 and RPR-99).
La Relying Party DOVREBBE abilitare il metodo POST nel suo Endpoint request_uri consentendo all'Istanza del Wallet di informare la Relying Party sulle sue capacità tecniche.
Questa funzionalità può essere utile quando, ad esempio, l'Istanza del Wallet supporta un insieme ristretto di funzionalità, algoritmi o un URL specifico per il suo authorization_endpoint, e qualsiasi altra informazione che ritiene necessario fornire alla Relying Party per l'interoperabilità.
Avvertimento
L'Istanza del Wallet, quando fornisce le sue capacità tecniche alla Relying Party, NON DEVE includere alcuna informazione dell'Utente o altre informazioni esplicite riguardanti l'hardware utilizzato o le preferenze di utilizzo del suo Utente.
Se sia la Relying Party che l'Istanza del Wallet supportano il request_uri_method con HTTP POST, le capacità (metadata) dell'Istanza del Wallet DEVONO essere fornite utilizzando una richiesta HTTP all'endpoint request_uri della Relying Party, con il metodo POST e il tipo di contenuto impostato su application/x-www-form-urlencoded (RPR-101 and WP_083).
La richiesta e i suoi parametri sono definiti nella Sezione 5 (Authorization Request) di OpenID4VP. Di seguito sono riportati i dettagli normativi e i riferimenti sui parametri da utilizzare dall'Istanza del Wallet nella Richiesta URI Request (WP_083a–083c).
Tabella 12.15 Parametri dell'Endpoint URI Request¶
Parametro
Descrizione
wallet_metadata
OPZIONALE. JSON Object con parametri di metadata. Vedi OpenID4VP, Sezione 10.1 e la tabella seguente, "Parametri dei metadata del Wallet".
wallet_nonce
RACCOMANDATO. Stringa utilizzata dall'Istanza del Wallet per prevenire il replay delle risposte della Relying Party.
OBBLIGATORIO. Oggetto con identificatori di formato degli Attestati Elettronici. Vedi OpenID4VP Appendice B.
alg_values_supported
OPZIONALE. Array di suite crittografiche supportate. Vedi OpenID4VP Appendice B.
client_id_prefixes_supported
RACCOMANDATO. Un array non vuoto dei prefissi dell’identificatore del Client supportati dall’Istanza del Wallet. I valori validi includono openid_federation e x509_hash; se omesso, il valore predefinito è pre-registrato.
authorization_endpoint
URL dell'endpoint del server di autorizzazione, vedi OAUTH2. L'utilizzo di un link universale è preferibile per una sicurezza migliorata e supporto di fallback, URL schems personalizzati possono anche essere utilizzati se necessario.
response_types_supported
OPZIONALE. Array JSON di valori "response_type" di OAuth 2.0. Se presente DEVE essere impostato su vp_token. Il valore predefinito è vp_token.
response_modes_supported
OPZIONALE. Array JSON di valori "response_mode" di OAuth 2.0 come specificato in OAUTH-MULT-RESP-TYPE. Il valore supportato DEVE essere query.
request_object_signing_alg_values_supported
OPZIONALE. Vedi OpenID Connect Discovery.
Nota
Nell’IT Wallet, le Relying Party legacy che utilizzano un URI https come client_id seguono implicitamente il prefisso dell’identificatore del client previsto da OpenID Federation (openid_federation). La loro fiducia è stabilita e validata tramite la risoluzione della catena di fiducia, che è considerata equivalente a quella dei client fidati staticamente (pre-registered), come definito in [RFC 6749], per garantire la compatibilità con le versioni precedenti.
Nota
Anche se il campo response_modes_supported fa riferimento a JARM per garantire l’interoperabilità a livello JARM della Authorization Response, mantenendo un formato basato su JWT per i reindirizzamenti front-channel come form_post.jwt nel Flusso Same Device, la Relying Party adotta invece direct_post.jwt nel Flusso Cross Device, che si basa su una consegna back-channel tramite una richiesta HTTP POST alla Relying Party. L’effettivo utilizzo di direct_post.jwt è descritto di seguito in Risposta dell'Endpoint URI Request, dove la Relying Party imposta il response_mode per la transazione.
Nota
Il parametro wallet_nonce è RACCOMANDATO per le Istanze del Wallet che vogliono prevenire il replay delle loro richieste HTTP alle Relying Party da parte di avversari. Quando presente, la Relying Party DEVE Controllarlo.
Nota
Per l'authorization_endpoint l'uso di univarsal link è preferito rispetto a URL scheme personalizzati perché, quando configurati correttamente utilizzando Assetlinks JSON per Android e Apple App Site Association per iOS, forniscono una sicurezza migliorata riducendo il rischio di dirottamento degli URL.
Inoltre, gli univarsal link offrono meccanismi di fallback, consentendo al flusso di continuare senza problemi in un browser anche se l'Istanza del Wallet non è installata, garantendo un'esperienza Utente più fluida. Per garantire l'interoperabilità, il supporto degli URL scheme personalizzati è anche RACCOMANDATO secondo il profilo di interoperabilità OpenID4VC High Assurance Interoperability Profile (HAIP) OPENID4VC-HAIP, e in particolare utilizzando l'url personalizzato haip://.
La Relying Party emette il Request Object firmato utilizzando il tipo di contenuto impostato su application/oauth-authz-req+jwt. Per il contenuto dell'oggetto Request, vedere la Sezione Request Object.
Quando la Relying Party incontra errori durante l'emissione del Request Object dall'endpoint request_uri, DEVE restituire una Error Response con application/json come tipo di contenuto e DEVE includere i seguenti parametri:
error: Il codice di errore.
error_description: Testo in forma leggibile che fornisce ulteriori dettagli per chiarire la natura dell'errore incontrato.
La seguente tabella elenca gli HTTP Status Code e i relativi Error codes che DEVONO essere supportati per la Error Response:
Codice di Stato
Codice di Errore
Descrizione
400BadRequest
invalid_request
L'Oggetto di Richiesta non può essere recuperato a causa di una richiesta non valida o malformata all’endpoint request_uri. (RFC 6749#section-4.1.2.1)
500InternalServerError
server_error
La richiesta non può essere soddisfatta perché l'Endpoint URI Request ha incontrato un problema interno. (RFC 6749#section-4.1.2.1).
503ServiceUnavailable
temporarily_unavailable
La richiesta non può essere soddisfatta perché l'Endpoint URI Request è temporaneamente non disponibile (ad esempio, a causa di manutenzione o sovraccarico). (RFC 6749#section-4.1.2.1).
Di seguito è riportato un esempio di Error Response dall'endpoint request_uri:
HTTP/1.1500Internal Server ErrorContent-Type:application/json{"error":"server_error","error_description":"The Request Object cannot be retrieved due to an internal server error."}
Dopo aver ricevuto una Error Response, l'Istanza del Wallet DOVREBBE informare l'Utente della condizione di errore in modo appropriato (WP_089). L'Istanza del Wallet DOVREBBE registrare l'errore e PUÒ tentare di recuperare da determinati errori se fattibile (WP_089a). Ad esempio, se l'errore è server_error, l'Istanza del Wallet DOVREBBE chiedere all'Utente di reinserire o scansionare un nuovo codice QR, se possibile (WP_089b).
I parametri dell'header JWT sono descritti di seguito:
Nome
Descrizione
alg
Algoritmo utilizzato per firmare il JWT, secondo [RFC 7516#section-4.1.1]. DEVE essere uno degli algoritmi supportati nella Sezione Algoritmi Crittografici e NON DEVE essere impostato su none o su un identificatore di algoritmo simmetrico (MAC) (RPR-104).
typ
Media Type del JWT, come definito in [RFC 7519] e [RFC 9101]. DOVREBBE essere impostato sul valore oauth-authz-req+jwt (RPR-105).
kid
ID della chiave della chiave pubblica necessaria per verificare la firma JWT, come definito in [RFC 7517]. OBBLIGATORIO quando viene utilizzato trust_chain.
trust_chain
CONDIZIONALE. OBBLIGATORIO quando il prefisso client_id utilizzato nella richiesta è impostato con openid-federation. È una sequenza di Entity Statement che compongono la Trust Chain relativa alla Relying Party, come definito in OID-FED Sezione 4.3 Trust Chain Header Parameter.
x5c
CONDIZIONALE. OBBLIGATORIO quando client_id utilizza il prefisso x509_hash; altrimenti viene utilizzato kid con jwks. Contiene il certificato X.509 foglia della Relying Party (e opzionalmente i certificati intermedi), utilizzato per verificare la firma JWT con la chiave pubblica nel certificato della Relying Party come definito in RFC 7515. Il certificato della Relying Party in x5c DEVE attestare informazioni di identità della Relying Party sufficienti per vincolare gli endpoint di rete referenziati dal flusso di presentazione. In particolare, gli endpoint utilizzati nella Authorization Request e Authorization Response (ad esempio, response_uri, redirect_uri) DEVONO corrispondere alle informazioni di identità contenute nel certificato della Relying Party (ad esempio, un SAN di tipo URI per il matching completo dell'URI o un DNS Name SAN per il matching del nome host).
Nota
L'intestazione x5c NON DEVE includere il certificato radice, come richiesto da OPENID4VC-HAIP. La catena di certificati x5c DEVE validare a un certificato radice preconfigurato; vedere la Sezione X.509 PKI per informazioni di base sulla validazione della catena di certificati X.509.
I parametri del payload JWT sono descritti qui:
Nome
Descrizione
client_id
Identificatore univoco della Relying Party.
client_metadata
Un oggetto JSON contenente i valori dei metadata della Relying Party, che DOVREBBE includere i seguenti parametri:
vp_formats_supported. Utilizzato dall'Istanza del Wallet per determinare i formati di Verifiable Presentation supportati.
encrypted_response_enc_values_supported. Array JSON che elenca gli algoritmi JWE enc supportati per le Authorization Response cifrate in direct_post.jwt.
jwks. JSON Web Key Set utilizzato dall'Istanza del Wallet per cifrare la Authorization Response o per l'accordo delle chiavi. Le chiavi contenute in questo set sono specifiche della richiesta e identificate dal loro valore kid.
client_name e logo_uri. OPZIONALE. Utilizzati per la visualizzazione del consenso dell'utente e per mostrare l'identità della Relying Party nell'interfaccia dell'Istanza del Wallet.
response_mode
DEVE essere impostato su direct_post.jwt (RPR-106).
dcql_query
Oggetto che rappresenta una richiesta di presentazione di Credenziali, secondo il linguaggio di query DCQL definito nella Sezione 6 di OpenID4VP.
transaction_data
Un array opzionale non vuoto di oggetti JSON, ognuno dei quali descrive una transazione che la Relying Party richiede all’Utente di autorizzare. Ogni oggetto di transazione include:
type. Stringa che identifica il tipo di dati della transazione.
credential_ids. Array che fa riferimento a una o più Credenziali provenienti dalla dcql_query che possono autorizzare la transazione.
transaction_data_hashes_alg
Un array opzionale di stringhe, ciascuna delle quali rappresenta un identificatore di algoritmo di hash, corrispondente a un nome di algoritmo di hash elencato nel registro IANA. Uno di questi algoritmi DEVE essere utilizzato per calcolare gli hash nel parametro di risposta transaction_data_hashes. Se omesso, l’algoritmo di hash predefinito è sha-256.
Valore stringa utilizzato per mitigare gli attacchi di replay della Request URI Response, come definito nella Sezione 5.10 (Request URI Method) di OpenID4VP. DEVE essere presente se precedentemente fornito dall'Istanza del Wallet (RPR-94).
response_uri
L'URI di Risposta a cui l'Istanza del Wallet DEVE inviare la Authorization Response utilizzando una HTTP Request con il metodo POST (RPR-112).
nonce
Numero unico e casuale con sufficiente entropia, la cui lunghezza DEVE essere di almeno 32 cifre (RPR-110).
state
Identificatore univoco della Authorization Request. È RACCOMANDATO di includere questo parametro e il valore DOVREBBE essere opaco per l’Istanza del Wallet.
iss
L'entità che ha emesso il JWT. Sarà popolato con il client_id della Relying Party.
iat
Timestamp Unix, che rappresenta l'ora in cui il JWT è stato emesso.
exp
Timestamp Unix, che rappresenta l'ora di scadenza in cui o dopo la quale il JWT NON DEVE più essere valido (RPR-111).
request_uri_method
Stringa che determina il metodo HTTP da utilizzare con l'endpoint request_uri per fornire i metadata dell'Istanza del Wallet alla Relying Party. Il valore non fa distinzione tra maiuscole e minuscole e può essere impostato su: get o post. Il metodo GET, come definito in RFC 9101, prevede che l'Istanza del Wallet invii una richiesta GET per recuperare un Request Object. Il metodo POST prevede che l'Istanza del Wallet richieda la creazione di un nuovo Request Object inviando una richiesta HTTP POST, con i suoi metadata, al request_uri della Relying Party.
Avvertimento
Per motivi di sicurezza e per prevenire attacchi di tipo endpoint mix-up, il valore contenuto nel parametro response_uri DEVE essere uno di quelli attestati da una terza parte fidata, come quelli forniti nei metadata openid_credential_verifier all'interno del parametro response_uris, ottenuti dalla Trust Chain relativa alla Relying Party (WP_091a and RPR-112).
Nota
Il parametro transaction_data è destinato ai casi d’uso in cui l’Istanza del Wallet DEVE autorizzare una transazione specifica, come l’inizio di un pagamento o la firma digitale. In questi scenari ad alta sensibilità, i dati della transazione possono essere collegati crittograficamente alla Risposta di Autorizzazione tramite transaction_data_hashes all’interno del Key Binding JWT, garantendo integrità e non ripudio. Per ulteriori dettagli, consultare OpenID4VP, Sezione 8.4.
Nota
Il parametro state in una richiesta OAuth è opzionale, ma è altamente RACCOMANDATO. Viene utilizzato principalmente per prevenire attacchi Cross-Site Request Forgery (CSRF) includendo un valore unico e imprevedibile che la Relying Party può verificare al momento della ricezione della risposta. Inoltre, aiuta a mantenere lo stato tra Request e Response, come le informazioni di sessione o altri dati di cui la Relying Party ha bisogno dopo il processo di autorizzazione.
Nota
L'utilizzo del parametro client_metadata è condizionale. Se client_id utilizza il prefisso x509_hash, tutti i metadata della Relying Party, oltre alla sua chiave pubblica utilizzata per firmare il Request Object, DEVONO essere forniti in client_metadata. Tuttavia, se è presente e client_id utilizza il prefisso openid_federation, l'Istanza del Wallet DEVE ignorarlo e ottenere i metadata attraverso la Trust Chain OpenID Federation (RPR-113).
Nota
Richiesta dell'Attestazione del Wallet
La Relying Party che richiede un'Attestazione del Wallet DEVE farlo utilizzando una query DCQL standard, tuttavia NON DOVREBBE includere il parametro claims nella query. A seconda del formato dell'Attestazione del Wallet, la Relying Party DEVE richiedere il parametro vct_values nella query DCQL, il quale DEVE essere impostato al valore definito nella Struttura del Catalogo degli Attestati Elettronici (RPR-114).
Dopo aver ottenuto l'autorizzazione e il consenso dell'Utente per la presentazione degli Attestati Elettronici, l'Istanza del Wallet invia la Authorization Response all'endpoint response_uri della Relying Party utilizzando una richiesta HTTP con il metodo POST (WP_091), il contenuto DOVREBBE essere cifrato secondo OpenID4VP Sezione 8.3, utilizzando la chiave pubblica della Relying Party (WP_092).
Nota
Perché la risposta è cifrata?
La risposta inviata dall'Istanza del Wallet alla Relying Party è cifrata per impedire a un avversario di sfruttare possibili vulnerabilità per accedere alle informazioni trasmesse in chiaro all'interno della rete della Relying Party. Per esempio, ciò è possibile se l'ambiente di rete della Relying Party impiega un proxy per le operazioni di TLS Termination, il quale agisce come intermediario tra il client e il backend web server della Relying Party e gestisce tutte le operazioni relative a TLS. In questo caso specifico, il proxy decifra il contenuto della trasmissione, in seguito lo inoltra al backend web server della Relying Party. Questa operazione può avvenire in chiaro oppure negoziando una ulteriore sessione TLS con il web server della Relying Party (sempre raccomandato). Nel primo caso, trasmissione dei dati TLS in chiaro, qualsiasi avversario all'interno del segmento di rete fra proxy e web server backend che intercettasse i dati trasmessi, potrebbe ottenere informazioni sensibili; se però la risposta è cifrata, la fattispece descritta viene mitigata anche mandando i dati in chiaro.
Nota
Presentazione dell'Attestazione del Wallet
L'Istanza del Wallet DEVE includere l'Attestazione del Wallet se richiesta dalla Relying Party usando la query DCQL. Durante la presentazione, l'Istanza del Wallet NON DOVREBBE richiedere il consenso dell'utente alla divulgazione degli attributi dell'Attestazione del Wallet, i quali sono dati tecnici non trasparenti per l'utente.
Nella Authorization Response vengono utilizzati i seguenti parametri (WP_093):
Nome
Descrizione
vp_token
Ci DEVONO essere almeno due presentazioni firmate in questo Array (WP_093a):
L'Attestato Elettronico richiesto (uno o più, in formato SD-JWT VC)
la Wallet Attestation (in formato SD-JWT VC)
Il formato vp_token è un JSON Object le cui chiavi corrispondono agli id degli Attestati Elettronici richieste nel dcql_query utilizzato nella richiesta, e i valori a ciascun Attestato Elettronico presentato.
state
Identificatore univoco fornito dalla Relying Party all'interno della Authorization Request.
Nota
Sebbene OpenID4VP prenda in considerazione la bozza -10 della specifica SD-JWT VC, la specifica IT Wallet considera la bozza -11 (SD-JWT-VC) in linea con la versione identificata in OpenID4VCI.
SD-JWT definisce come un Holder può presentare una Attestato Elettronico a una Relying Party, dimostrando il legittimo possesso dell'Attestato Elettronico. Per fare ciò, l'Holder DEVE includere il KB-JWT nell'SD-JWT aggiungendo il KB-JWT alla termine della stringa contenente l'SD-JWT (WP_093b), come rappresentato nell'esempio seguente
Per convalidare la firma sul Key Binding JWT, la Relying Party DEVE utilizzare il materiale crittografico incluso nell'Issuer-Signed-JWT. La convalida della firma del Key Binding JWT (KB-JWT) DEVE utilizzare la chiave pubblica inclusa nell'SD-JWT contenuta nel parametro cnf contenuto nell'Issuer-Signed-JWT.
Quando viene presentato un SD-JWT, il suo KB-JWT DEVE contenere i seguenti parametri nell'intestazione JWT (WP_093c):
Claim
Descrizione
typ
OBBLIGATORIO. DEVE essere kb+jwt, che caratterizza esplicitamente il Key Binding JWT come raccomandato nella Sezione 3.11 di RFC 8725.
alg
OBBLIGATORIO. Algoritmo di Firma utilizzando uno di quelli specificati nella Sezione Algoritmi Crittografici.
Quando viene presentato un SD-JWT, la firma KB-JWT DEVE essere verificata dalla stessa chiave pubblica inclusa nell'SD-JWT all'interno del parametro cnf. Il KB-JWT DEVE contenere i seguenti parametri nel payload JWT:
Claim
Descrizione
iat
OBBLIGATORIO. Il valore di questa claim DEVE essere l'ora in cui è stato emesso il Key Binding JWT, utilizzando la sintassi definita in RFC 7519.
aud
OBBLIGATORIO. Il ricevitore previsto del Key Binding JWT. Il valore di questo parametro DEVE corrispondere all'identificatore di entità (client_id) univoco della Relying Party.
nonce
OBBLIGATORIO. Garantisce l'unicità della firma. Il valore di questa claim DEVE essere una stringa e deve corrispondere a quello fornito nel Request Object.
sd_hash
OBBLIGATORIO. Il digest codificato in base64url del JWT firmato dal Fornitore di Attestati Elettronici (SD-JWT) e le selective disclosures selezionate dall'Utente.
transaction_data_hashes
CONDIZIONALE. OBBLIGATORIO quando la richiesta include transaction_data. Array non vuoto di hash codificati in base64url. Ogni hash è calcolato sul valore esatto della stringa corrispondente all’elemento transaction_data.
transaction_data_hashes_alg
CONDIZIONALE. OBBLIGATORIO solo se la richiesta includeva transaction_data_hashes_alg. Stringa che indica l’algoritmo di hash effettivamente utilizzato per calcolare transaction_data_hashes; se tale parametro non è stato fornito, la funzione di hash DEVE essere sha-256.
Ci sono casi in cui l'Istanza del Wallet non può convalidare il Request Object o il Request Object risulta non valido. Questo errore si verifica se il Request Object viene recuperato con successo dall'url fornito nel parametro request_uri ma non supera i controlli di convalida. Ciò potrebbe essere dovuto a firme errate, claim non conformim o altri errori di convalida, come la revoca della trust per la specifica Relying Party che lo ha emesso.
Se l'Istanza del Wallet incontra tali errori durante la valutazione della Authorization Request, DEVE notificare alla Relying Party inviando una Error Response nella Autorization Response (WP_090).
L'Istanza del Wallet invia la Error Response nella Autorization Response all'endpoint response_uri della Relying Party utilizzando una richiesta HTTP POST (WP_090). Questa Error Response DEVE essere codificata nel corpo della richiesta utilizzando il formato definito dal tipo di contenuto application/x-www-form-urlencoded.
Di seguito è riportato un esempio non normativo di una Error Response nella Autorization Response.
L'attuale specifica OpenID4VP delinea varie risposte di errore che un'Istanza del Wallet può restituire alla Relying Party in caso di Authorization Request errata. Per migliorare la privacy, le Istanze del Wallet NON DOVREBBERO notificare alla Relying Party le richieste errate qualora un uso improprio delle risposte di errore potrebbe portare a raccogliere informazioni lesive della privacy dell'Utente (ad esempio, se l'Utente decide di non voler presentare l'Attestato Elettronico richiesto).
Nella seguente tabella sono elencati gli Error codes e le descrizioni che sono supportati per la Error Response nella Autorization Response:
Codice di Errore
Descrizione
invalid_request_uri
Il request_uri nella Authorization Request restituisce un errore, contiene dati non validi o è altrimenti malformato. RFC 9101
vp_formats_not_supported
L'Istanza del Wallet non supporta nessuno dei formati vp richiesti dalla Relying Party. OpenID4VP
invalid_request_uri_method
Il valore del parametro request_uri_method non è né get né post. OpenID4VP
invalid_request
La richiesta è malformata o incoerente (ad esempio utilizza il Response Type vp_token ma non include il parametro dcql_query), il prefisso dell'identificatore del Client non è supportato oppure i requisiti del prefisso non sono rispettati (ad esempio, client_id con il prefisso x509_hash senza il client_metadata richiesto). OpenID4VP
access_denied
Il Wallet non aveva l'Attestato Elettronico richiesto, l'Utente non ha dato il consenso o il Wallet non è riuscito ad autenticare l'Utente. OpenID4VP
invalid_client
I metadata della Relying Party sono stati risolti basandosi sull'Identificatore del Client (utilizzando il prefisso openid_federation o x509_hash), ma la Relying Party non può essere autorizzata a causa di errori nella verifica della trust oppure dal fatto che non è stata riconosciuta come entità valida della federazione. OID-FED e OpenID4VP
Il parametro client_metadata è presente, ma il Wallet riconosce l'identificativo del client e conosce i metadati ad esso associati. OpenID4VP
I metadati pre-registrati del Relying Party sono stati trovati in base all'identificativo del client, ma è presente anche il parametro client_metadata. OpenID4VP
invalid_transaction_data
Uno o più oggetti nella struttura transaction_data non sono validi. Ad esempio, tali oggetti contengono tipi sconosciuti o non supportati, campi malformati (ad esempio è un oggetto di tipo noto ma contiene campi sconosciuti o campi di tipo errato per il tipo di transaction data) o mancanti, valori non validi (ad esempio il campo credential_ids non corrisponde) oppure riferimenti a Credenziali non disponibili. OpenID4VP
Come definito nella Sezione 8.2. (Response mode "direct_post") della specifica OpenID4VP, se l'Endpoint di Risposta della Relaying Party ha elaborato con successo la Authorization Response o la Error Response fornita dall'Istanza del Wallet, DEVE rispondere con un codice di stato HTTP 200 con Content-Type di application/json e un JSON Object nel corpo della risposta.
Nel Flusso Same Device, la Relying Party DOVREBBE aggiungere il parametro redirect_uri all'JSON Object nel corpo della risposta. Dopo aver ricevuto il redirect_uri, l'Istanza del Wallet DEVE eseguire un reindirizzamento all'URL specificato dal redirect_uri.
Questo reindirizzamento consente alla Relying Party di riprendere senza problemi l'interazione con l'Utente sul dispositivo che ha avviato il flusso, dopo che l'Istanza del Wallet ha trasmesso la Authorization Response al response_uri designato.
La Relying Party DEVE includere un codice di risposta all'interno del redirect_uri. Il codice di risposta è un numero fresco, crittograficamente casuale utilizzato per garantire che solo il ricevitore del reindirizzamento possa recuperare ed elaborare la Authorization Response. Il numero potrebbe essere aggiunto come componente del path, come parametro o come frammento all'URL. È RACCOMANDATO utilizzare un valore casuale crittografico di 128 bit o più al momento della scrittura di questa specifica.
Anche se un avversario riesce a rubare il valore casuale utilizzato nella richiesta allo Status Endpoint, il suo user-agent verrebbe rifiutato a causa del cookie mancante nella richiesta.
Avvertimento
Per motivi di sicurezza e per prevenire attacchi di tipo endpoint mix-up, il valore contenuto nel parametro redirect_uri DEVE essere uno di quelli attestati da una terza parte fidata, come quelli forniti nei metadata openid_credential_verifier all'interno del parametro redirect_uris, ottenuti dalla Trust Chain relativa alla Relying Party (WP_094a).
12.2.1.6.1. Errori della Risposta della Relying Party¶
Se qualsiasi controllo di convalida, eseguito dalla Relying Party sulla Authorization Response dall'Istanza del Wallet, fallisce; l'endpoint URI di Risposta DEVE restituire una Error Response. La struttura di questa Error Response dovrebbe essere determinata dalla natura specifica dell'errore incontrato. La risposta DEVE utilizzare application/json come tipo di contenuto e DEVE includere i seguenti parametri:
error: Il codice di errore.
error_description: Testo in forma leggibile che fornisce ulteriori dettagli per chiarire la natura dell'errore incontrato.
La seguente tabella elenca gli Status Code HTTP e i relativi Error codes che DEVONO essere supportati per la Error Response:
Codice di Stato
Codice di Errore
Descrizione
400BadRequest
invalid_request
La risposta non può essere elaborata perché mancano parametri obbligatori, contiene parametri non validi o è non conforme agli standard.
400BadRequest
invalid_request
Gli Attestati Elettronici presentati sono non conformi agli standard, non valide o revocate.
400BadRequest
invalid_request
La presentazione degli Attestati Elettronici, contenuta nell'oggetto vp_token, non è conforme agli standard, non ha i parametri richiesti o è formattata in modo errato.
400BadRequest
invalid_request
L'"sd-jwt" restituito non è conforme agli standard, mancano parametri obbligatori o è formattato in modo errato.
403Forbidden
invalid_request
La firma del KB-JWT non è valida o non corrisponde alla chiave pubblica associata (JWK) referenziata nell'SD-JWT firmato dall'Emittente.
403Forbidden
invalid_request
Il valore del nonce fornito è errato o altrimenti non conforme agli standard.
403Forbidden
invalid_request
La firma della Wallet Attestation non è valida o la fiducia non può essere stabilita con il suo Emittente.
403Forbidden
invalid_request
La trust non può essere stabilita con il Fornitore di Attestati Elettronici.
500InternalServerError
server_error
La richiesta non può essere soddisfatta perché il Response Endpoint ha incontrato un problema interno.
503ServiceUnavailable
temporarily_unavailable
La richiesta non può essere soddisfatta perché il Response Endpoint è temporaneamente non disponibile (ad esempio, a causa di manutenzione o sovraccarico).
Di seguito ci sono due esempi di risposte HTTP che utilizzano application/json che includono sia i membri error che error_description:
HTTP/1.1403ForbiddenContent-Type:application/json{"error":"invalid_request","error_description":"Trust cannot be established with the issuer: https://issuer.example.com"}
HTTP/1.1400Bad RequestContent-Type:application/json{"error":"invalid_request","error_description":"The vp_token is malformed, missing required parameters or incorrectly formatted"}
Questa specifica introduce lo Status Endpoint della Relying Party per le implementazioni che scelgono di utilizzarlo. Questo Endpoint è una funzionalità di sicurezza interna dell'implementazione e non è richiesto per l'interoperabilità.
Sia he il flusso sia Same Device o Cross Device, l'user-agent deve controllare lo stato della sessione all'endpoint reso disponibile dalla Relying Party (endpoint di stato). Questo controllo PUÒ essere implementato sotto forma di codice JavaScript, all'interno della pagina che mostra il Codice QR o il tramite pulsante href che punta all'URL di richiesta. Il codice JavaScript fa sì che l'user-agent controlli lo Status Endpoint utilizzando una strategia di polling (in secondi) o una strategia push (ad esempio, WebSocket).
Poiché la pagina HTML e lo Status Endpoint sono implementati dalla Relying Party, i dettagli di implementazione di questa soluzione sono responsabilità della Relying Party, in quanto sono relativi alle API interne della Relying Party. Tuttavia, il testo seguente descrive un'implementazione di esempio.
La Relying Party lega la richiesta dello user-agent, con un cookie di sessione contrassegnato come Secure e HttpOnly, con la richiesta emessa. L'URL della richiesta DOVREBBE includere un parametro con un valore casuale. La risposta HTTP restituita da questo endpoint di stato PUÒ contenere gli Status Code HTTP elencati di seguito:
201 Created; quando il Request Object firmato è stato emesso dalla Relying Party che attende di essere scaricato dall'Istanza del Wallet all'endpoint request_uri.
202 Accepted; quando il Request Object firmato è stato ottenuto dall'Istanza del Wallet.
200 OK; quando l'Istanza del Wallet ha fornito la presentazione all'endpoint response_uri della Relying Party e l'autenticazione dell'Utente ha avuto successo. La Relying Party aggiorna il cookie di sessione consentendo allo user-agent di accedere alla risorsa protetta. Viene fornito un redirect_uri che trasporta lo user-agent alla pagina in cui l'Utente deve navigare.
Se invece qualsiasi controllo di convalida eseguito dalla Relying Party fallisce, la pagina del Codice QR DOVREBBE essere aggiornata con un messaggio di errore. Inoltre, lo Status Endpoint DEVE restituire una Error Response, la cui struttura dipende dalla natura dell'errore. La risposta DEVE utilizzare application/json come tipo di contenuto e DEVE includere i seguenti parametri:
error: Il codice di errore.
error_description: Testo in forma leggibile che fornisce ulteriori dettagli per chiarire la natura dell'errore incontrato.
La seguente tabella elenca gli Status Code HTTP e i relativi Error codes che DEVONO essere supportati per la Error Response:
Codice di Stato
Codice di Errore
Descrizione
401Unauthorized
authentication_failed
L'Istanza del Wallet o il suo Utente hanno rifiutato la richiesta, la richiesta è scaduta o altri errori hanno impedito l'autenticazione.
403Forbidden
invalid_session
L'id di sessione fornito nella richiesta non è valido.
Il valore redirect_uri DEVE essere utilizzato con un metodo HTTP GET dall'user-agent per reindirizzare l'Utente a un endpoint specifico della Relying Party al fine di completare il processo.
Quando l'user-agent viene reindirizzato all'URI di Reindirizzamento fornito dalla Relying Party, possono verificarsi diversi errori che impediscono il completamento con successo del processo. Questi errori sono critici in quanto influenzano direttamente l'esperienza dell'Utente ostacolando il flusso fluido di informazioni tra l'Istanza del Wallet e la Relying Party. La gestione di questi errori richiede una comunicazione chiara all'Utente all'interno della pagina web di navigazione restituita. La Relying Party DEVE implementare i meccanismi di gestione degli errori e di convalida per gli URI di Reindirizzamento definiti in questa specifica. Di seguito sono riportati potenziali errori relativi all'URI di Reindirizzamento, la Error Response DEVE utilizzare application/json come tipo di contenuto e DEVE includere i seguenti parametri:
error: Il codice di errore.
error_description: Testo in forma leggibile che fornisce ulteriori dettagli per chiarire la natura dell'errore incontrato.
La seguente tabella elenca gli Status Code HTTP e i relativi Error codes che DEVONO essere supportati per la Error Response:
Codice di Stato
Codice di Errore
Descrizione
403Forbidden
invalid_request
L'URI di Reindirizzamento fornito dalla Relying Party non corrisponde a nessuno degli URI collegati alla sessione dell'Utente. (RFC 6749#section-4.1.2.1)
403Forbidden
invalid_request
La sessione dell'Utente non è valida o è scaduta.
500InternalServerError
server_error
La richiesta non può essere soddisfatta a causa di un errore interno del server. (RFC 6749#section-4.1.2.1).
503ServiceUnavailable
temporarily_unavailable
La richiesta non può essere soddisfatta perché il servizio è temporaneamente non disponibile (ad esempio, a causa di manutenzione o sovraccarico). (RFC 6749#section-4.1.2.1).
