2. Token Revocation (Revoca del token)

Le implementazioni DEVONO (MUST) supportare la revoca dei token di aggiornamento e DOVREBBERO (SHOULD) supportare la revoca dei token di accesso (vedere Nota di implementazione).

Il client richiede la revoca di un particolare token effettuando una richiesta HTTP POST all'URL dell'endpoint di revoca del token. Questo URL DEVE (MUST) essere conforme alle regole fornite in [RFC6749], Sezione 3.1. I client DEVONO (MUST) verificare che l'URL sia un URL HTTPS.

I mezzi per ottenere la posizione dell'endpoint di revoca esulano dallo scopo di questa specifica. Ad esempio, lo sviluppatore del client può consultare la documentazione del server oppure può essere utilizzata l'individuazione automatica. Poiché questo endpoint gestisce credenziali di sicurezza, la posizione dell'endpoint deve essere ottenuta da una fonte attendibile.

Poiché le richieste all'endpoint di revoca del token comportano la trasmissione di credenziali in testo normale nella richiesta HTTP, gli URL per gli endpoint di revoca del token DEVONO (MUST) essere URL HTTPS. Il server di autorizzazione DEVE (MUST) utilizzare Transport Layer Security (TLS) [RFC5246] in una versione conforme a [RFC6749], Sezione 1.6. Le implementazioni POSSONO (MAY) anche supportare meccanismi di sicurezza del livello di trasporto aggiuntivi che soddisfano i loro requisiti di sicurezza.

Se l'host dell'endpoint di revoca del token può essere raggiunto anche tramite HTTP, il server DOVREBBE (SHOULD) offrire anche un servizio di revoca all'URI HTTP corrispondente, ma NON DEVE (MUST NOT) pubblicare questo URI come endpoint di revoca del token. Ciò garantisce che i token inviati accidentalmente tramite HTTP verranno revocati.

2.1. Revocation Request (Richiesta di revoca)

Il client costruisce la richiesta includendo i seguenti parametri utilizzando il formato "application/x-www-form-urlencoded" nel corpo dell'entità della richiesta HTTP:

token : REQUIRED (RICHIESTO). Il token che il client desidera revocare.

token_type_hint : OPTIONAL (OPZIONALE). Un suggerimento sul tipo di token inviato per la revoca. I client POSSONO (MAY) passare questo parametro per aiutare il server di autorizzazione a ottimizzare la ricerca del token. Se il server non è in grado di individuare il token utilizzando il suggerimento fornito, DEVE (MUST) estendere la ricerca a tutti i tipi di token supportati. Un server di autorizzazione PUÒ (MAY) ignorare questo parametro, in particolare se è in grado di rilevare automaticamente il tipo di token. Questa specifica definisce due valori di questo tipo:

access_token: Un token di accesso come definito in [RFC6749], Sezione 1.4
refresh_token: Un token di aggiornamento come definito in [RFC6749], Sezione 1.5

Implementazioni, profili ed estensioni specifici di questa specifica POSSONO (MAY) definire altri valori per questo parametro utilizzando il registro definito nella Sezione 4.1.2.

Il client include anche le proprie credenziali di autenticazione come descritto nella Sezione 2.3 di [RFC6749].

Ad esempio, un client può richiedere la revoca di un token di aggiornamento con la seguente richiesta:

POST /revoke HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

Il server di autorizzazione convalida prima le credenziali del client (nel caso di un client riservato) e quindi verifica se il token è stato rilasciato al client che effettua la richiesta di revoca. Se questa convalida fallisce, la richiesta viene rifiutata e il client viene informato dell'errore dal server di autorizzazione come descritto di seguito.

Nel passaggio successivo, il server di autorizzazione invalida il token. L'invalidazione avviene immediatamente e il token non può più essere utilizzato dopo la revoca. In pratica, potrebbe esserci un ritardo di propagazione, ad esempio, in cui alcuni server sono a conoscenza dell'invalidazione mentre altri no. Le implementazioni dovrebbero ridurre al minimo tale finestra e i client non devono tentare di utilizzare il token dopo aver ricevuto una risposta HTTP 200 dal server.

A seconda della politica di revoca del server di autorizzazione, la revoca di un particolare token può causare la revoca dei token correlati e della concessione di autorizzazione sottostante. Se il token particolare è un token di aggiornamento e il server di autorizzazione supporta la revoca dei token di accesso, il server di autorizzazione DOVREBBE (SHOULD) invalidare anche tutti i token di accesso basati sulla stessa concessione di autorizzazione (vedere Nota di implementazione). Se il token passato alla richiesta è un token di accesso, il server PUÒ (MAY) revocare anche il rispettivo token di aggiornamento.

Nota: un client conforme a [RFC6749] deve essere preparato a gestire un'invalidazione imprevista del token in qualsiasi momento. Indipendentemente dal meccanismo di revoca specificato in questo documento, i proprietari delle risorse possono revocare le concessioni di autorizzazione o il server di autorizzazione può invalidare i token al fine di mitigare le minacce alla sicurezza. Pertanto, avere diverse politiche del server rispetto alla revoca a cascata dei token non dovrebbe porre problemi di interoperabilità.

2.2. Revocation Response (Risposta di revoca)

Il server di autorizzazione risponde con codice di stato HTTP 200 se il token è stato revocato con successo o se il client ha inviato un token non valido.

Nota: i token non validi non causano una risposta di errore poiché il client non può gestire tale errore in modo ragionevole. Inoltre, lo scopo della richiesta di revoca, invalidare il token particolare, è già stato raggiunto.

Il contenuto del corpo della risposta viene ignorato dal client poiché tutte le informazioni necessarie vengono trasmesse nel codice di risposta.

Un valore di suggerimento del tipo di token non valido viene ignorato dal server di autorizzazione e non influenza la risposta di revoca.

2.2.1. Error Response (Risposta di errore)

La presentazione dell'errore è conforme alla definizione nella Sezione 5.2 di [RFC6749]. Il seguente codice di errore aggiuntivo è definito per l'endpoint di revoca del token:

unsupported_token_type : Il server di autorizzazione non supporta la revoca del tipo di token presentato. Cioè, il client ha tentato di revocare un token di accesso su un server che non supporta questa funzionalità.

Se il server risponde con codice di stato HTTP 503, il client deve presumere che il token esista ancora e può riprovare dopo un ritardo ragionevole. Il server può includere un'intestazione "Retry-After" nella risposta per indicare per quanto tempo si prevede che il servizio non sarà disponibile per il client richiedente.

2.3. Cross-Origin Support (Supporto Cross-Origin)

L'endpoint di revoca PUÒ (MAY) supportare Cross-Origin Resource Sharing (CORS) [W3C.WD-cors-20120403] se è destinato all'uso in combinazione con applicazioni basate su user-agent.

Inoltre, per l'interoperabilità con user-agent legacy, PUÒ (MAY) anche offrire JSONP (Remote JSON - JSONP) [jsonp] consentendo richieste GET con un parametro aggiuntivo:

callback : OPTIONAL (OPZIONALE). Il nome qualificato di una funzione JavaScript.

Ad esempio, un client può richiedere la revoca di un token di accesso con la seguente richiesta (le interruzioni di riga sono solo a scopo di visualizzazione):

https://example.com/revoke?token=agabcdefddddafdd&
callback=package.myCallback

Risposta riuscita:

package.myCallback();

Risposta di errore:

package.myCallback({"error":"unsupported_token_type"});

I client dovrebbero essere consapevoli del fatto che quando si affidano a JSONP, un endpoint di revoca dannoso potrebbe tentare di iniettare codice dannoso nel client.