8.3. Endpoint della Relying Party¶
La Relying Party DEVE esporre un Endpoint per verificare il trust conforme alla specifica OpenID Federation 1.0 Wallet Architecture, facilitando la distribuzione dell'identità e dei metadata della Relying Party. Inoltre, nel caso in cui il Relying Party supporti la presentazione di prossimità, DEVE esporre una serie di endpoint per gestire il ciclo di vita delle App di Verifica (ad esempio, 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.
8.3.1. 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.
8.3.2. Endpoint Nonce della Relying Party¶
Il Nonce Endpoint della Relying Party consente all'App di Verifica di richiedere un nonce crittografico dal Backend della 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.
8.3.3. Endpoint di Inizializzazione dell'Istanza di 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.
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.
8.3.4. 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 della Relying Party deve anche verificare l'integrità dell'App di Verifica.
8.3.4.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.
8.3.4.2. Risposta di Associazione Chiavi della Relying Party¶
In caso di richiesta riuscita, il Backend della 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.
8.3.5. 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.
8.3.5.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'Istanza di Relying Party, codificato nel formato |
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..."
}
8.3.5.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 |
|---|---|---|
|
|
La richiesta non è conforme allo standard, mancano parametri richiesti (ad esempio, |
|
|
La chiave pubblica nel CSR non corrisponde alla chiave pubblica associata alle Cryptographic Hardware Keys. |
|
|
La richiesta non può essere soddisfatta perché l'Endpoint ha riscontrato un problema interno. |
|
|
La richiesta non può essere soddisfatta perché l'Endpoint è temporaneamente non disponibile (ad esempio, a causa di manutenzione o sovraccarico). |
8.3.6. 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.
8.3.6.1. 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
8.3.6.2. 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 |
|---|---|---|
|
|
La richiesta è malformata, mancano parametri richiesti (ad esempio, parametri di intestazione o asserzione di integrità), o include parametri non validi e sconosciuti. |
|
|
La richiesta non può essere soddisfatta in quanto l'autenticazione da parte dell'Utente risulta fallita o non valida. |
|
|
La richiesta non può essere soddisfatta perché l'Endpoint di Cancellazione ha riscontrato un problema interno. (RFC 6749#section-4.1.2.1). |
|
|
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.