2. Richiesta e Risposta di Scambio di Token

2.1. Richiesta

Un client richiede un token di sicurezza effettuando una richiesta di token all'endpoint del token del server di autorizzazione utilizzando il meccanismo del tipo di concessione di estensione definito nella Sezione 4.5 della [RFC6749].

L'autenticazione del client al server di autorizzazione viene eseguita utilizzando i normali meccanismi forniti da OAuth 2.0. La Sezione 2.3.1 della [RFC6749] definisce l'autenticazione basata su password del client, tuttavia, l'autenticazione del client è estensibile e sono possibili altri meccanismi. Ad esempio, la [RFC7523] definisce l'autenticazione del client utilizzando JSON Web Token (JWT) bearer [JWT]. I metodi supportati di autenticazione del client e se consentire o meno client non autenticati o non identificati sono decisioni di distribuzione a discrezione del server di autorizzazione. Si noti che l'omissione dell'autenticazione del client consente a chiunque possieda un token compromesso di utilizzare tale token tramite un STS per ottenerne altri. Pertanto, l'autenticazione del client consente controlli di autorizzazione aggiuntivi da parte dell'STS su quali entità sono autorizzate a impersonare o ricevere deleghe da altre entità.

Il client effettua una richiesta di scambio di token all'endpoint del token con un tipo di concessione di estensione utilizzando il metodo HTTP "POST". I seguenti parametri sono inclusi nel corpo dell'entità della richiesta HTTP utilizzando il formato "application/x-www-form-urlencoded" con una codifica dei caratteri UTF-8 come descritto nell'Appendice B della [RFC6749].

grant_type OBBLIGATORIO (REQUIRED). Il valore urn:ietf:params:oauth:grant-type:token-exchange indica che è in corso uno scambio di token.

resource OPZIONALE (OPTIONAL). Un URI che indica il servizio o la risorsa di destinazione in cui il client intende utilizzare il token di sicurezza richiesto. Ciò consente al server di autorizzazione di applicare la politica appropriata per la destinazione, come determinare il tipo e il contenuto del token da emettere o se e come il token deve essere crittografato. In molti casi, un client non sarà a conoscenza dell'organizzazione logica dei sistemi con cui interagisce e conoscerà solo un URI del servizio in cui intende utilizzare il token. Il parametro resource consente al client di indicare al server di autorizzazione dove intende utilizzare il token emesso fornendo la posizione, tipicamente come URL https, nella richiesta di scambio di token nella stessa forma che verrà utilizzata per accedere a quella risorsa. Il server di autorizzazione avrà tipicamente la capacità di mappare un valore URI di risorsa in una politica appropriata. Il valore del parametro resource DEVE essere un URI assoluto, come specificato dalla Sezione 4.3 della [RFC3986], che PUÒ includere un componente di query e NON DEVE includere un componente di frammento. È possibile utilizzare più parametri resource per indicare che il token emesso è destinato a essere utilizzato presso le più risorse elencate. Vedere [OAUTH-RESOURCE] per ulteriori informazioni e utilizzi del parametro resource.

audience OPZIONALE (OPTIONAL). Il nome logico del servizio di destinazione in cui il client intende utilizzare il token di sicurezza richiesto. Ciò serve a uno scopo simile al parametro resource ma con il client che fornisce un nome logico per il servizio di destinazione. L'interpretazione del nome richiede che il valore sia qualcosa che sia il client che il server di autorizzazione comprendono. Un identificatore client OAuth, un identificatore entità SAML [OASIS.saml-core-2.0-os] e un identificatore emittente OpenID Connect [OpenID.Core] sono esempi di cose che potrebbero essere utilizzate come valori del parametro audience. Tuttavia, i valori audience utilizzati con un determinato server di autorizzazione devono essere univoci all'interno di quel server per garantire che vengano interpretati correttamente come il tipo di valore previsto. È possibile utilizzare più parametri audience per indicare che il token emesso è destinato a essere utilizzato presso le più audience elencate. I parametri audience e resource possono essere utilizzati insieme per indicare più servizi di destinazione con un mix di nomi logici e URI di risorse.

scope OPZIONALE (OPTIONAL). Un elenco di stringhe delimitate da spazi, case-sensitive, come definito nella Sezione 3.3 della [RFC6749], che consentono al client di specificare l'ambito desiderato del token di sicurezza richiesto nel contesto del servizio o della risorsa in cui verrà utilizzato il token. I valori e la semantica associata dell'ambito sono specifici del servizio e dovrebbero essere descritti nella documentazione del servizio pertinente.

requested_token_type OPZIONALE (OPTIONAL). Un identificatore, come descritto nella Sezione 3, per il tipo di token di sicurezza richiesto. Se il tipo richiesto non è specificato, il tipo di token emesso è a discrezione del server di autorizzazione e può essere dettato dalla conoscenza dei requisiti del servizio o della risorsa indicata dal parametro resource o audience.

subject_token OBBLIGATORIO (REQUIRED). Un token di sicurezza che rappresenta l'identità della parte per conto della quale viene effettuata la richiesta. Tipicamente, il soggetto di questo token sarà il soggetto del token di sicurezza emesso in risposta alla richiesta.

subject_token_type OBBLIGATORIO (REQUIRED). Un identificatore, come descritto nella Sezione 3, che indica il tipo di token di sicurezza nel parametro subject_token.

actor_token OPZIONALE (OPTIONAL). Un token di sicurezza che rappresenta l'identità della parte agente. Tipicamente, questa sarà la parte autorizzata a utilizzare il token di sicurezza richiesto e ad agire per conto del soggetto.

actor_token_type Un identificatore, come descritto nella Sezione 3, che indica il tipo di token di sicurezza nel parametro actor_token. Questo è OBBLIGATORIO quando il parametro actor_token è presente nella richiesta ma NON DEVE essere incluso altrimenti.

Nell'elaborazione della richiesta, il server di autorizzazione DEVE eseguire le procedure di convalida appropriate per il tipo di token indicato e, se il token attore è presente, eseguire anche le procedure di convalida appropriate per il suo tipo di token indicato. I criteri di validità e i dettagli di qualsiasi token particolare esulano dall'ambito di questo documento e sono specifici del rispettivo tipo di token e del suo contenuto.

In assenza di un utilizzo una tantum o di altra semantica specifica per il tipo di token, l'atto di eseguire uno scambio di token non ha alcun impatto sulla validità del subject token o dell'actor token. Inoltre, lo scambio è un evento una tantum e non crea un forte legame tra i token di input e di output, in modo che (ad esempio) mentre il tempo di scadenza del token di output può essere influenzato da quello del token di input, non ci si aspetta che il rinnovo o l'estensione del token di input siano riflessi nelle proprietà del token di output. Potrebbe essere comunque appropriato o auspicabile propagare gli eventi di revoca del token. Tuttavia, farlo non è una proprietà generale del protocollo STS e sarebbe specifico per una particolare implementazione, tipo di token o distribuzione.

2.1.1. Relazione tra Resource, Audience e Scope

Quando richiede un token, il client può indicare i servizi di destinazione desiderati in cui intende utilizzare quel token tramite i parametri audience e resource nonché indicare l'ambito desiderato del token richiesto utilizzando il parametro scope. La semantica di tale richiesta è che il client chiede un token con l'ambito richiesto che sia utilizzabile in tutti i servizi di destinazione richiesti. Di fatto, i diritti di accesso richiesti del token sono il prodotto cartesiano di tutti gli ambiti in tutti i servizi di destinazione.

Un server di autorizzazione potrebbe non essere disposto o non essere in grado di soddisfare qualsiasi richiesta di token, ma la probabilità di una richiesta non soddisfatta è significativamente più alta quando vengono richiesti diritti di accesso molto ampi. Pertanto, in assenza di conoscenze specifiche sulla relazione dei sistemi in una distribuzione, i client dovrebbero esercitare discrezione nell'ampiezza dell'accesso richiesto, in particolare nel numero di servizi di destinazione. Un server di autorizzazione può utilizzare il codice di errore invalid_target, definito nella Sezione 2.2.2, per informare un client che ha richiesto l'accesso a troppi servizi di destinazione contemporaneamente.

2.2. Risposta

Il server di autorizzazione risponde a una richiesta di scambio di token con una normale risposta OAuth 2.0 dall'endpoint del token, come specificato nella Sezione 5 della [RFC6749]. Ulteriori dettagli e spiegazioni sono forniti nelle sottosezioni seguenti.

2.2.1. Risposta Riuscita

Se la richiesta è valida e soddisfa tutte le politiche e gli altri criteri del server di autorizzazione, viene costruita una risposta token riuscita aggiungendo i seguenti parametri al corpo dell'entità della risposta HTTP utilizzando il tipo di supporto "application/json", come specificato da [RFC8259], e un codice di stato HTTP 200. I parametri vengono serializzati in una struttura JSON (JavaScript Object Notation) aggiungendo ciascun parametro al livello superiore. I nomi dei parametri e i valori stringa sono inclusi come stringhe JSON. I valori numerici sono inclusi come numeri JSON. L'ordine dei parametri non ha importanza e può variare.

access_token OBBLIGATORIO (REQUIRED). Il token di sicurezza emesso dal server di autorizzazione in risposta alla richiesta di scambio di token. Il parametro access_token dalla Sezione 5.1 della [RFC6749] viene utilizzato qui per trasportare il token richiesto, il che consente a questo protocollo di scambio di token di utilizzare i costrutti di richiesta e risposta OAuth 2.0 esistenti definiti per l'endpoint del token. L'identificatore access_token è utilizzato per ragioni storiche e il token emesso non deve essere necessariamente un token di accesso OAuth.

issued_token_type OBBLIGATORIO (REQUIRED). Un identificatore, come descritto nella Sezione 3, per la rappresentazione del token di sicurezza emesso.

token_type OBBLIGATORIO (REQUIRED). Un valore che non fa distinzione tra maiuscole e minuscole che specifica il metodo di utilizzo del token di accesso emesso, come specificato nella Sezione 7.1 della [RFC6749]. Fornisce al client informazioni su come utilizzare il token di accesso per accedere alle risorse protette. Ad esempio, un valore di "Bearer", come specificato in [RFC6750], indica che il token di sicurezza emesso è un token bearer e il client può semplicemente presentarlo così com'è senza alcuna prova aggiuntiva di ammissibilità oltre al contenuto del token stesso. Si noti che il significato di questo parametro è diverso dal significato del parametro issued_token_type, che dichiara la rappresentazione del token di sicurezza emesso; il termine "tipo di token" è più tipicamente utilizzato per indicare la rappresentazione strutturale o sintattica del token di sicurezza, come in tutti i parametri *_token_type in questa specifica. Se il token emesso non è un token di accesso o utilizzabile come token di accesso, allora il valore token_type "N_A" viene utilizzato per indicare che un identificatore OAuth 2.0 token_type non è applicabile in quel contesto.

expires_in RACCOMANDATO (RECOMMENDED). La durata di validità, in secondi, del token emesso dal server di autorizzazione. Spesso, il client non avrà l'inclinazione o la capacità di ispezionare il contenuto del token e questo parametro fornisce un'indicazione coerente e indipendente dal tipo di token di quanto tempo ci si può aspettare che il token sia valido. Ad esempio, il valore 1800 indica che il token scadrà tra trenta minuti dal momento in cui è stata generata la risposta.

scope OPZIONALE se l'ambito del token di sicurezza emesso è identico all'ambito richiesto dal client; altrimenti, è OBBLIGATORIO.

refresh_token OPZIONALE (OPTIONAL). Un refresh token non verrà tipicamente emesso quando lo scambio è di una credenziale temporanea (il subject_token) per una credenziale temporanea diversa (il token emesso) per l'uso in qualche altro contesto. Un refresh token può essere emesso nei casi in cui il client dello scambio di token ha bisogno della capacità di accedere a una risorsa anche quando la credenziale originale non è più valida (ad esempio, scenari utente non presente o offline in cui non c'è più alcun utente che intrattiene una sessione attiva con il client). I profili o le distribuzioni di questa specifica dovrebbero documentare chiaramente le condizioni in cui un client dovrebbe aspettarsi un refresh token in risposta alle richieste del tipo di concessione urn:ietf:params:oauth:grant-type:token-exchange.

2.2.2. Risposta di Errore

Se la richiesta stessa non è valida o se subject_token o actor_token non sono validi per qualsiasi motivo o sono inaccettabili in base alla politica, il server di autorizzazione DEVE costruire una risposta di errore, come specificato nella Sezione 5.2 della [RFC6749]. Il valore del parametro error DEVE essere il codice di errore invalid_request.

Se il server di autorizzazione non è disposto o non è in grado di emettere un token per qualsiasi servizio di destinazione indicato dai parametri resource o audience, il codice di errore invalid_target DOVREBBE essere utilizzato nella risposta di errore.

Il server di autorizzazione PUÒ includere informazioni aggiuntive riguardanti i motivi dell'errore utilizzando error_description come discusso nella Sezione 5.2 della [RFC6749].

Possono essere utilizzati anche altri codici di errore, a seconda dei casi.

2.3. Esempio di Scambio di Token

Il seguente esempio dimostra un ipotetico scambio di token in cui un server di risorse OAuth assume il ruolo del client durante lo scambio. Scambia un token di accesso, che ha ricevuto in una richiesta di risorsa protetta, con un nuovo token che utilizzerà per chiamare un servizio backend (interruzioni di riga e rientri extra negli esempi sono solo a scopo di visualizzazione).

La Figura 1 mostra il server di risorse che riceve una richiesta di risorsa protetta contenente un token di accesso OAuth nell'intestazione Authorization, come specificato nella Sezione 2.1 della [RFC6750].

GET /resource HTTP/1.1
Host: frontend.example.com
Authorization: Bearer accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC

Figura 1: Richiesta di Risorsa Protetta

Nella Figura 2, il server di risorse assume il ruolo di client per lo scambio di token e il token di accesso dalla richiesta nella Figura 1 viene inviato al server di autorizzazione utilizzando una richiesta come specificato nella Sezione 2.1. Il valore del parametro subject_token trasporta il token di accesso e il valore del parametro subject_token_type indica che si tratta di un token di accesso OAuth 2.0. Il server di risorse, agendo nel ruolo del client, utilizza il suo identificatore e segreto per autenticarsi al server di autorizzazione utilizzando lo schema di autenticazione HTTP Basic. Il parametro resource indica la posizione del servizio backend, <https://backend.example.com/api>, dove verrà utilizzato il token emesso.

POST /as/token.oauth2 HTTP/1.1
Host: as.example.com
Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fbackend.example.com%2Fapi
&subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
&subject_token_type=
 urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

Figura 2: Richiesta di Scambio di Token

Il server di autorizzazione convalida le credenziali del client e il subject_token presentato nella richiesta di scambio di token. Dal parametro resource, il server di autorizzazione è in grado di determinare la politica appropriata da applicare alla richiesta ed emette un token adatto all'uso su <https://backend.example.com>. Il parametro access_token della risposta mostrata nella Figura 3 contiene il nuovo token, che è di per sé un token di accesso OAuth bearer valido per un minuto. Il token risulta essere un JWT; tuttavia, la sua struttura e formato sono opachi per il client, quindi issued_token_type indica solo che si tratta di un token di accesso.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
 "access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo
   dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV
   4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn
   N1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rx
   f59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCM
   y5-kdXjwhw",
 "issued_token_type":
     "urn:ietf:params:oauth:token-type:access_token",
 "token_type":"Bearer",
 "expires_in":60
}

Figura 3: Risposta di Scambio di Token

Il server di risorse può quindi utilizzare il token di accesso appena acquisito per effettuare una richiesta al server backend come illustrato nella Figura 4.

GET /api HTTP/1.1
Host: backend.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQ
   iOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2
   FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1M
   zMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQe
   dw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIW
   vmDCMy5-kdXjwhw

Figura 4: Richiesta di Risorsa Protetta Backend

Ulteriori esempi possono essere trovati nell'Appendice A.