13.3. Endpoint della Relying Party¶

La Relying Party DEVE esporre una serie completa di endpoint per supportare l'ecosistema IT-Wallet completo, inclusi sia i flussi di presentazione remoti che di prossimità.

Nota

I test relativi agli endpoint della Relying Party sono definiti nella matrice di test per presentazione remota (test-plans-remote-presentation:Matrice di Test per la Presentazione di Credenziali Remota) e prossimità (test-plans-proximity-presentation:Matrice di Test per la Presentazione di Credenziali in Prossimità).

13.3.1. Endpoint per Flussi Remoti¶

13.3.2. Endpoint per Flussi Remoti della Relying Party¶

La Relying Party DEVE esporre una serie di endpoint per supportare i flussi di presentazione remoti come definiti in OpenID4VP 1.0. Questi endpoint abilitano la verifica sicura delle credenziali, l'instaurazione della fiducia e l'autenticazione dell'utente per modelli di interazione cross-device e same-device.

Nota

I test relativi agli endpoint per flussi remoti della Relying Party sono definiti nella matrice di test per presentazione remota (test-plans-remote-presentation:Matrice di Test per la Presentazione di Credenziali Remota).

13.3.3. Endpoint di Federazione¶

La Relying Party DEVE fornire la propria Entity Configuration attraverso l'endpoint /.well-known/openid-federation, secondo la Sezione Entity Configuration. Questo endpoint abilita l'instaurazione della fiducia e la scoperta delle capacità della Relying Party.

I dettagli tecnici sono forniti nella Sezione Entity Configuration Relying Party.

13.3.4. Endpoint per Flussi Remoti OpenID4VP¶

I seguenti endpoint sono richiesti per i flussi di presentazione remota OpenID4VP 1.0 come descritto in Flusso Remoto. Questi endpoint supportano sia i flussi Same Device che Cross Device:

13.3.4.1. Endpoint Request URI¶

L'Endpoint Request URI è dove la Relying Party fornisce il Request Object firmato all'Istanza del Wallet. Questo endpoint supporta sia i metodi GET che POST come definito nella specifica OpenID4VP 1.0.

Per i requisiti di implementazione dettagliati, vedere remote-flow:Endpoint URI Request e Richiesta all'Endpoint URI Request.

13.3.4.2. Endpoint Response URI¶

L'Endpoint Response URI riceve l'Authorization Response dall'Istanza del Wallet contenente la Verifiable Presentation. Questo endpoint elabora la presentazione e convalida le credenziali.

Per i requisiti di implementazione dettagliati, vedere Authorization Response e Risposta della Relying Party.

13.3.4.3. Endpoint Status (Opzionale)¶

L'Endpoint Status è un endpoint opzionale che consente all'user-agent di monitorare il progresso del flusso di presentazione. Questo endpoint è particolarmente utile per i flussi Same Device dove l'user-agent deve sapere quando l'Istanza del Wallet ha completato la presentazione.

Per i requisiti di implementazione dettagliati, vedere Status Endpoint e remote-flow:Errori Status Endpoint.

13.3.5. Endpoint di Gestione Dati Utente¶

Il seguente endpoint supporta la gestione dei dati utente e i requisiti di conformità alla privacy per i flussi remoti:

13.3.5.1. Endpoint di Cancellazione della Relying Party¶

L'Endpoint di Cancellazione, che è descritto in Metadati della Relying Party, consente alle Istanze di Wallet di richiedere la cancellazione degli attributi presentati alla Relying Party. La Relying Party DEVE richiedere l'autenticazione dell'Utente prima di procedere con la cancellazione degli attributi.

13.3.5.2. Richiesta di Cancellazione¶

La Richiesta di Cancellazione DEVE essere una richiesta GET all'Endpoint di Cancellazione. L'Istanza di Wallet DEVE anche supportare un meccanismo di callback che consenta allo User-Agent di notificare lo stato della richiesta all'Istanza di Wallet (e quindi all'Utente) una volta che viene restituita la Risposta di Cancellazione.

Di seguito è riportato un esempio non normativo di una Richiesta di Cancellazione in cui l'URL di callback viene passato come parametro di query.

GET /erasure-endpoint?callback_url=https://wallet-instance/erasure_response HTTP/1.1
Host: relying-party.example.org

13.3.5.3. Risposta di Cancellazione¶

Se la cancellazione di tutti gli attributi associati all'Utente è avvenuta con successo, la Risposta di Cancellazione DEVE restituire un Status Code HTTP 204.

Se invece la procedura di cancellazione degli attributi fallisce per qualsiasi circostanza, la Relying Party DEVE restituire una risposta di errore 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 riscontrato.

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
`400 Bad Request`	`bad_request`	La richiesta è malformata, mancano parametri richiesti (ad esempio, parametri di intestazione o asserzione di integrità), o include parametri non validi e sconosciuti.
`401 Unauthorized`	`unauthorized`	La richiesta non può essere soddisfatta in quanto l'autenticazione da parte dell'Utente risulta fallita o non valida.
`500 Internal Server Error`	`server_error`	La richiesta non può essere soddisfatta perché l'Endpoint di Cancellazione ha riscontrato un problema interno. (RFC 6749#section-4.1.2.1).
`503 Service Unavailable`	`temporarily_unavailable`	La richiesta non può essere soddisfatta perché l'Endpoint di Cancellazione è 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 di Cancellazione:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
 "error": "server_error",
 "error_description": "The request cannot be fulfilled due to an internal server error."
}

Alla ricezione di una Error Response, l'Istanza di Wallet che ha effettuato la Richiesta di Cancellazione DEVE informare l'Utente della condizione di errore in modo appropriato.

13.3.6. Considerazioni di Sicurezza¶

Tutti gli endpoint della Relying Party DEVONO implementare appropriate misure di sicurezza:

Solo HTTPS: Tutti gli endpoint DEVONO essere accessibili solo tramite HTTPS
Protezione Endpoint Mix-up: Gli URL degli endpoint DEVONO essere attestati da terze parti fidate attraverso la Trust Chain
Validazione Input: Tutti gli endpoint DEVONO convalidare i parametri di input e rifiutare richieste malformate
Rate Limiting: Gli endpoint DOVREBBERO implementare rate limiting per prevenire abusi
Audit Logging: Tutte le interazioni degli endpoint DOVREBBERO essere registrate per il monitoraggio della sicurezza

Per i requisiti di sicurezza dettagliati, vedere remote-flow:Considerazioni di Sicurezza e i casi di test pertinenti in test-plans-remote-presentation:Matrice di Test per la Presentazione di Credenziali Remota.

13.3.7. Note di Implementazione¶

I dettagli di implementazione specifici per la maggior parte degli endpoint sono lasciati alla discrezione della Relying Party
Gli endpoint DEVONO essere conformi alla specifica OpenID4VP 1.0 per i flussi remoti
Gli endpoint per flussi di prossimità DEVONO supportare la gestione del ciclo di vita delle App di Verifica
Tutti gli endpoint DEVONO essere scopribili attraverso l'Entity Configuration della Relying Party
Le risposte di errore DEVONO seguire i codici di stato HTTP standard e includere appropriate descrizioni degli errori

Per una guida di implementazione completa, fare riferimento alle sezioni degli endpoint individuali e alle matrici di test per i requisiti di validazione.

13.3.8. Endpoint del Backend del Provider di Relying Party¶

13.3.9. Endpoint del Backend del Provider di Relying Party¶

La Relying Party DEVE esporre una serie di endpoint per gestire il ciclo di vita delle App di Verifica che utilizzano un servizio di backend remoto fornito dal loro Backend del Provider di Relying Party. Questi endpoint supportano i flussi di presentazione in prossimità fornendo generazione di nonce, registrazione delle chiavi hardware, convalida dell'integrità e rilascio del Certificato di Accesso. I dettagli specifici della loro implementazione sono lasciati alla discrezione della Relying Party.

Nota

I test relativi agli endpoint della Relying Party sono definiti nella matrice di test per presentazione remota (test-plans-remote-presentation:Matrice di Test per la Presentazione di Credenziali Remota) e prossimità (test-plans-proximity-presentation:Matrice di Test per la Presentazione di Credenziali in Prossimità).

13.3.10. Endpoint di Federazione della Relying Party¶

La Relying Party DEVE fornire la propria Entity Configuration attraverso l'Endpoint /.well-known/openid-federation, secondo la Sezione Entity Configuration. I dettagli tecnici sono forniti nella Sezione Entity Configuration Relying Party.

13.3.11. Endpoint Nonce della Relying Party¶

Il Nonce Endpoint della Relying Party consente all'App di Verifica di richiedere un nonce crittografico dal Backend del Provider di Relying Party. Il nonce, un codice monouso e casuale, serve per garantire l'unicità e prevenire replay attacks.

Ulteriori dettagli sulla Richiesta e Risposta Nonce sono forniti rispettivamente nelle Sezioni Richiesta di Nonce dell'Applicazione Mobile e Richiesta di Nonce dell'Applicazione Mobile.

13.3.12. Endpoint di Inizializzazione dell'App di Verifica della Relying Party¶

L'Endpoint di Inizializzazione dell'App di Verifica consente l'inizializzazione delle App di Verifica, consistente nella registrazione di una coppia di Cryptographic Hardware Keys a lunga durata, memorizzate in modo sicuro (Matrice di Test per il Verificatore di Credenziali in Prossimità).

Ulteriori dettagli sulla Richiesta e Risposta di Inizializzazione dell'App di Verifica sono forniti rispettivamente nelle Sezioni Richiesta di Inizializzazione dell'Istanza dell'Applicazione Mobile e Risposta di Inizializzazione dell'Istanza dell'Applicazione Mobile.

13.3.13. Endpoint di Associazione Chiavi della Relying Party¶

Il Key Binding Endpoint della Relying Party consente alle App di Verifica di associare la coppia di chiavi appena creata, che sarà associata a un Certificato di Accesso, all'App di Verifica, basandosi su una dimostrazione di possesso delle Cryptographic Hardware Keys generate durante la fase di Inizializzazione dell'Istanza dell'Applicazione Mobile. Prima di completare il processo, il Backend del Provider di Relying Party deve anche verificare l'integrità dell'App di Verifica.

13.3.13.1. Richiesta di Associazione Chiavi della Relying Party¶

Ulteriori dettagli sulla Richiesta di Key Binding della Relying Party sono forniti nella sezione Richiesta di Associazione Chiave dell'Applicazione Mobile.

L'header typ del JWT di Richiesta di Integrità assume il valore rp-kb+jwt.

13.3.13.2. Risposta di Associazione Chiavi della Relying Party¶

In caso di richiesta riuscita, il Backend del Provider di Relying Party fornisce una HTTP Response con Status Code 204 No Content.

Di seguito è riportato un esempio non normativo di una Risposta alla Richiesta di Associazione Chiavi.

HTTP/1.1 204 No content

Se si verificano errori durante il processo, viene restituita una Error Response. Ulteriori dettagli sulla Error Response sono forniti nella sezione Risposta di Errore di Associazione Chiave dell'Applicazione Mobile.

13.3.14. Endpoint del Certificato di Accesso della Relying Party¶

L'Endpoint del Certificato di Accesso della Relying Party consente alle App di Verifica di ottenere un Certificato di Accesso.

13.3.14.1. Richiesta del Certificato di Accesso della Relying Party¶

La Richiesta del Certificato di Accesso utilizza il metodo HTTP POST con Content-Type impostato su application/json.

La richiesta include il seguente parametro nel body:

Parametro	Descrizione	Riferimento
csr	Il CSR generato dall'App di Verifica, codificato nel formato `base64url` come definito in RFC 2511.

Di seguito è riportato un esempio non normativo di una Richiesta di Certificato di Accesso.

POST /access-certificate HTTP/1.1
Host: relying-party.example.org
Content-Type: application/json

{
  "csr": "MIIBvzCCAa..."
}

13.3.14.2. Risposta del Certificato di Accesso della Relying Party¶

In caso di richiesta riuscita, l'Access Certificate Endpoint della Relying Party fornisce un HTTP Response con Status Code 200 OK e il Certificato di Accesso. La Risposta dell'Access Certificate Endpoint, che utilizza application/json come Content-Type, include i seguenti parametri nel body:

Parametro	Descrizione	Riferimento
access_certificate	Il Certificato di Accesso generato dal CSR.	Questa specifica.

Di seguito è riportato un esempio non normativo di Risposta dall'Access Certificate Endpoint.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_certificate": "hajdnhaghSDGns..."
}

Se si verificano errori, l'Access Certificate Endpoint della Relying Party restituisce una Error Response. La risposta utilizza application/json come tipo di contenuto e include i seguenti parametri:

error. Il codice di errore.

error_description. Testo in forma leggibile che fornisce ulteriori dettagli per chiarire la natura dell'errore riscontrato.

Di seguito è riportato un esempio non normativo di una Error Response dell'Access Certificate Endpoint.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": "invalid_request",
    "error_description": "The public key in the CSR is different from the one associated with the Cryptographic Hardware Keys."
}

La seguente tabella elenca gli HTTP Status Code e i relativi codici di errore che DEVONO essere supportati per l'Error Response, se non diversamente specificato:

Codice di Stato HTTP	Codice di Errore	Descrizione
`400 Bad Request`	`bad_request`	La richiesta non è conforme allo standard, mancano parametri richiesti (ad esempio, `integrity_assertion`), oppure sono includi parametri non validi e sconosciuti.
`403 Forbidden`	`invalid_request`	La chiave pubblica nel CSR non corrisponde alla chiave pubblica associata alle Cryptographic Hardware Keys.
`500 Internal Server Error`	`server_error`	La richiesta non può essere soddisfatta perché l'Endpoint ha riscontrato un problema interno.
`503 Service Unavailable`	`temporarily_unavailable`	La richiesta non può essere soddisfatta perché l'Endpoint è temporaneamente non disponibile (ad esempio, a causa di manutenzione o sovraccarico).

13.3.15. Endpoint di Cancellazione della Relying Party¶

L'Endpoint di Cancellazione consente alle Istanze di Wallet di richiedere la cancellazione degli attributi presentati alla Relying Party, supportando i diritti di privacy dell'utente e la conformità normativa.

Per i requisiti di implementazione dettagliati, vedere Endpoint di Cancellazione della Relying Party.