2. Introspection Endpoint (Endpoint di introspezione)
L'endpoint di introspezione è un endpoint OAuth 2.0 che accetta un parametro che rappresenta un token OAuth 2.0 e restituisce un documento JSON [RFC7159] che rappresenta le meta-informazioni relative al token, incluso se questo token è attualmente attivo. La definizione di token attivo dipende dal server di autorizzazione, ma è comunemente un token che è stato emesso da questo server di autorizzazione, non è scaduto, non è stato revocato ed è valido per l'uso presso la risorsa protetta che effettua la chiamata di introspezione.
L'endpoint di introspezione DEVE essere protetto da un meccanismo di sicurezza del livello di trasporto come descritto nella Sezione 4. I mezzi con cui la risorsa protetta scopre la posizione dell'endpoint di introspezione non rientrano nell'ambito di questa specifica.
2.1. Introspection Request (Richiesta di introspezione)
La risorsa protetta chiama l'endpoint di introspezione utilizzando una richiesta HTTP POST [RFC7231] con parametri inviati come dati "application/x-www-form-urlencoded" come definito in [W3C.REC-html5-20141028]. La risorsa protetta invia un parametro che rappresenta il token insieme a parametri opzionali che rappresentano un contesto aggiuntivo noto alla risorsa protetta per aiutare il server di autorizzazione nella sua risposta.
token : RICHIESTO (REQUIRED). Il valore stringa del token. Per i token di accesso, questo è il valore "access_token" restituito dall'endpoint del token definito in OAuth 2.0 [RFC6749], Sezione 5.1. Per i token di aggiornamento, questo è il valore "refresh_token" restituito dall'endpoint del token come definito in OAuth 2.0 [RFC6749], Sezione 5.1. Altri tipi di token non rientrano nell'ambito di questa specifica.
token_type_hint : OPZIONALE (OPTIONAL). Un suggerimento sul tipo di token inviato per l'introspezione. La risorsa protetta PUÒ (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 sua 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. I valori per questo campo sono definiti nel registro "OAuth Token Type Hints" definito in OAuth Token Revocation [RFC7009].
L'endpoint di introspezione PUÒ (MAY) accettare altri parametri OPZIONALI per fornire ulteriore contesto alla query. Ad esempio, un server di autorizzazione potrebbe desiderare di conoscere l'indirizzo IP del client che accede alla risorsa protetta per determinare se è probabile che il client corretto stia presentando il token. La definizione di questo o di altri parametri non rientra nell'ambito di questa specifica, e deve essere definita dalla documentazione del servizio o da estensioni a questa specifica. Se il server di autorizzazione non è in grado di determinare lo stato del token senza ulteriori informazioni, DOVREBBE (SHOULD) restituire una risposta di introspezione che indichi che il token non è attivo come descritto nella Sezione 2.2.
Per prevenire attacchi di scansione dei token, l'endpoint DEVE (MUST) richiedere anche una qualche forma di autorizzazione per accedere a questo endpoint, come l'autenticazione del client come descritto in OAuth 2.0 [RFC6749] o un token di accesso OAuth 2.0 separato come il token bearer descritto in OAuth 2.0 Bearer Token Usage [RFC6750]. I metodi di gestione e convalida di queste credenziali di autenticazione non rientrano nell'ambito di questa specifica.
Ad esempio, di seguito viene mostrata una risorsa protetta che chiama l'endpoint di introspezione del token per interrogare un token bearer OAuth 2.0. La risorsa protetta utilizza un token bearer OAuth 2.0 separato per autorizzare questa chiamata.
Quella che segue è una richiesta di esempio non normativa:
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA
In questo esempio, la risorsa protetta utilizza un identificatore client e un segreto client per autenticarsi all'endpoint di introspezione. La risorsa protetta invia anche un suggerimento sul tipo di token indicando che sta richiedendo informazioni su un token di accesso.
Quella che segue è una richiesta di esempio non normativa:
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
2.2. Introspection Response (Risposta di introspezione)
Il server risponde con un oggetto JSON [RFC7159] in formato "application/json" con i seguenti membri di primo livello.
active : RICHIESTO (REQUIRED). Indicatore booleano se il token presentato è attualmente attivo o meno. Le specifiche dello stato "active" di un token varieranno a seconda dell'implementazione del server di autorizzazione e delle informazioni che conserva sui suoi token, ma un valore "true" restituito per la proprietà "active" indicherà generalmente che un dato token è stato emesso da questo server di autorizzazione, non è stato revocato dal proprietario della risorsa ed è all'interno della sua data finestra temporale di validità (ad esempio, dopo l'orario di emissione e prima dell'orario di scadenza). Vedere la Sezione 4 per informazioni sull'implementazione di tali controlli.
scope : OPZIONALE (OPTIONAL). Una stringa JSON contenente un elenco separato da spazi di scope associati a questo token, nel formato descritto nella Sezione 3.3 di OAuth 2.0 [RFC6749].
client_id : OPZIONALE (OPTIONAL). Identificatore client per il client OAuth 2.0 che ha richiesto questo token.
username : OPZIONALE (OPTIONAL). Identificatore leggibile dall'uomo per il proprietario della risorsa che ha autorizzato questo token.
token_type : OPZIONALE (OPTIONAL). Tipo del token come definito nella Sezione 5.1 di OAuth 2.0 [RFC6749].
exp : OPZIONALE (OPTIONAL). Timestamp intero, misurato in numero di secondi dal 1 gennaio 1970 UTC, che indica quando questo token scadrà, come definito in JWT [RFC7519].
iat : OPZIONALE (OPTIONAL). Timestamp intero, misurato in numero di secondi dal 1 gennaio 1970 UTC, che indica quando questo token è stato originariamente emesso, come definito in JWT [RFC7519].
nbf : OPZIONALE (OPTIONAL). Timestamp intero, misurato in numero di secondi dal 1 gennaio 1970 UTC, che indica quando questo token non deve essere utilizzato prima di tale data, come definito in JWT [RFC7519].
sub : OPZIONALE (OPTIONAL). Oggetto (Subject) del token, come definito in JWT [RFC7519]. Di solito un identificatore leggibile dalla macchina del proprietario della risorsa che ha autorizzato questo token.
aud : OPZIONALE (OPTIONAL). Identificatore di stringa specifico del servizio o elenco di identificatori di stringa che rappresentano il pubblico previsto (Audience) per questo token, come definito in JWT [RFC7519].
iss : OPZIONALE (OPTIONAL). Stringa che rappresenta l'emittente (Issuer) di questo token, come definito in JWT [RFC7519].
jti : OPZIONALE (OPTIONAL). Identificatore di stringa per il token, come definito in JWT [RFC7519].
Implementazioni specifiche POSSONO (MAY) estendere questa struttura con i propri nomi di risposta specifici del servizio come membri di primo livello di questo oggetto JSON. I nomi di risposta destinati ad essere utilizzati tra domini DEVONO (MUST) essere registrati nel registro "OAuth Token Introspection Response" definito nella Sezione 3.1.
Il server di autorizzazione PUÒ (MAY) rispondere in modo diverso a diverse risorse protette che effettuano la stessa richiesta. Ad esempio, un server di autorizzazione PUÒ (MAY) limitare quali scope di un dato token vengono restituiti per ciascuna risorsa protetta per impedire a una risorsa protetta di apprendere più sulla rete più ampia di quanto sia necessario per il suo funzionamento.
La risposta PUÒ (MAY) essere memorizzata nella cache dalla risorsa protetta per migliorare le prestazioni e ridurre il carico sull'endpoint di introspezione, ma a costo della vivacità (liveness) delle informazioni utilizzate dalla risorsa protetta per prendere decisioni di autorizzazione. Vedere la Sezione 4 per ulteriori informazioni sul compromesso quando la risposta viene memorizzata nella cache.
Ad esempio, la seguente risposta contiene una serie di informazioni su un token attivo:
Quella che segue è una risposta di esempio non normativa:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"username": "jdoe",
"scope": "read write dolphin",
"sub": "Z5O3upPC88QrAjx00dis",
"aud": "https://protected.example.net/resource",
"iss": "https://server.example.com/",
"exp": 1419356238,
"iat": 1419350238,
"extension_field": "twenty-seven"
}
Se la chiamata di introspezione è correttamente autorizzata ma il token non è attivo, non esiste su questo server o la risorsa protetta non è autorizzata a introspezionare questo particolare token, allora il server di autorizzazione DEVE (MUST) restituire una risposta di introspezione con il campo "active" impostato su "false". Notare che per evitare di rivelare troppo dello stato del server di autorizzazione a una terza parte, il server di autorizzazione NON DOVREBBE (SHOULD NOT) includere ulteriori informazioni su un token inattivo, compreso il motivo per cui il token è inattivo.
Quella che segue è una risposta di esempio non normativa per un token che è stato revocato o è altrimenti non valido:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": false
}
2.3. Error Response (Risposta di errore)
Se la risorsa protetta utilizza credenziali client OAuth 2.0 per autenticarsi all'endpoint di introspezione e le sue credenziali non sono valide, il server di autorizzazione risponde con un HTTP 401 (Unauthorized) come descritto nella Sezione 5.2 di OAuth 2.0 [RFC6749].
Se la risorsa protetta utilizza un token bearer OAuth 2.0 per autorizzare la sua chiamata all'endpoint di introspezione e il token utilizzato per l'autorizzazione non contiene privilegi sufficienti o è altrimenti non valido per questa richiesta, il server di autorizzazione risponde con un codice HTTP 401 come descritto nella Sezione 3 di OAuth 2.0 Bearer Token Usage [RFC6750].
Notare che una query correttamente formata e autorizzata per un token inattivo o altrimenti non valido (o un token di cui la risorsa protetta non è autorizzata a sapere) non è considerata una risposta di errore da questa specifica. In questi casi, il server di autorizzazione DEVE (MUST) invece rispondere con una risposta di introspezione con il campo "active" impostato su "false" come descritto nella Sezione 2.2.