Documenti correlati
OAuth 2.0 è standardizzato come RFC 6749. Un documento dettagliato è disponibile all'indirizzo https://oauth.net/2. L'autenticazione di base HTTP è definita nella sezione 2 del documento RFC 2617.
Panoramica
Di solito, per fornire alle applicazioni di terze parti l'accesso a risorse con limitazioni come i dettagli del piano dati e del portafoglio, l'utente finale (proprietario della risorsa) deve condividere le proprie credenziali con la terza parte. Ciò crea diversi problemi e limitazioni, come l'archiviazione delle credenziali, l'autenticazione con password, l'ampio accesso alle risorse dell'utente finale e la divulgazione della password e così via. OAuth 2.0 risolve questi problemi introducendo un livello di autorizzazione e quindi proteggendo e limitando l'accesso alle risorse protette dell'utente finale.
Anziché utilizzare le credenziali dell'utente finale per accedere a risorse protette come i dettagli del piano dati, il GTAF ottiene un token di accesso. I token di accesso vengono emessi a GTAF per conto delle credenziali di GTAF. Il GTAF utilizza poi il token di accesso per accedere ai dettagli del piano dati ospitati dal DPA.
La seguente figura mostra il flusso di informazioni di alto livello:
Figura 1. Abstract OAuth Flow.
Token di accesso
I token di accesso sono le credenziali utilizzate da GTAF per accedere ai dettagli del piano dati dal DPA dell'operatore. Un token di accesso è una stringa che rappresenta un'autorizzazione rilasciata al GTAF. La stringa è in genere opaca per GTAF. I token rappresentano ambiti e durate di accesso specifici, concessi dall'utente finale all'operatore e applicati dal DPA e dal server OAuth dell'operatore.
Il token di accesso fornisce un livello di astrazione, sostituendo diverse strutture di autorizzazione (ad es. nome utente e password) con un singolo token compreso dal DPA. Questa astrazione consente di emettere token di accesso più restrittivi rispetto alla concessione di autorizzazione utilizzata per ottenerli, nonché di eliminare la necessità per il DPA di comprendere un'ampia gamma di metodi di autenticazione.
I token di accesso possono avere formati, strutture e metodi di utilizzo diversi (ad es. proprietà crittografiche) in base ai requisiti di sicurezza dell'operatore. GTAF supporta solo i token di accesso di tipo bearer definiti in [RFC6750].
Autenticazione client
Il GTAF funziona come un "client confidenziale" ed è in grado di mantenere le password al sicuro. Al momento, GTAF supporta solo l'autenticazione di base HTTP per l'autenticazione con il DPA. L'identificatore client viene codificato utilizzando l'algoritmo di codifica "application/x-www-form-urlencoded" e il valore codificato viene utilizzato come nome utente; la password viene codificata utilizzando lo stesso algoritmo e utilizzata come password.
I client confidenziali come GTAF, a cui vengono rilasciate credenziali client, eseguono l'autenticazione con il server OAuth dell'operatore durante l'invio di richieste all'endpoint token. L'autenticazione client viene utilizzata per: \
- Recupero da un client compromesso disattivando il client o modificandone le credenziali, impedendo così a un malintenzionato di utilizzare in modo illecito i token di aggiornamento rubati. La modifica di un singolo insieme di credenziali client è molto più rapida della revoca di un intero insieme di token di aggiornamento.
- Implementare le best practice per la gestione dell'autenticazione, che richiedono la rotazione periodica delle credenziali.
GTAF utilizza il parametro di richiesta "client_id" per identificarsi quando invia richieste all'endpoint token.
Particolarmente importante è la possibilità di ruotare le credenziali client. Il server OAuth deve essere in grado di supportare due coppie di credenziali simultanee durante la rotazione e deve avere la possibilità di disattivare le credenziali. In una rotazione delle credenziali tipica:
- L'operatore crea nuove credenziali sul server OAuth e le invia al proprio Technical Account Manager in modo sicuro.
- Google testa la nuova credenziale e modifica la configurazione di GTAF per utilizzare la nuova credenziale.
- Google comunica all'operatore che le vecchie credenziali potrebbero essere disattivate.
- L'operatore disattiva le credenziali e invia una notifica a Google
- Google verifica che le vecchie credenziali non siano più operative
Il server OAuth deve essere in grado di supportare la procedura di rotazione descritta sopra.
Endpoint token
L'endpoint token viene utilizzato da GTAF per ottenere un token di accesso presentando la sua concessione di autorizzazione o il token di aggiornamento. L'endpoint token viene utilizzato con ogni autorizzazione, ad eccezione del tipo di autorizzazione implicita (poiché viene emesso direttamente un token di accesso).
Di seguito sono riportati alcuni punti da considerare durante la configurazione di un endpoint token:
- La posizione dell'endpoint del token deve essere fornita nella documentazione del servizio.
- L'URI dell'endpoint può includere un componente di query formattato "application/x-www-form-urlencoded" che deve essere conservato quando vengono aggiunti parametri di query aggiuntivi. L'URI dell'endpoint non deve includere un componente frammento.
- Poiché le richieste all'endpoint token comportano la trasmissione di credenziali in testo non crittografato (nella richiesta e nella risposta HTTP), il server OAuth dell'operatore deve utilizzare TLS per l'invio di richieste all'endpoint token.
- GTAF utilizza il metodo HTTP "POST" quando effettua la richiesta di token di accesso.
- I parametri inviati senza un valore devono essere considerati omessi dalla richiesta. Il server OAuth deve ignorare i parametri di richiesta non riconosciuti. I parametri di richiesta e risposta non devono essere inclusi più di una volta.
- GTAF supporta solo i token di accesso di tipo bearer.
Ambito del token di accesso
Gli endpoint di autorizzazione e token consentono al client di specificare l'ambito della richiesta di accesso utilizzando il parametro di richiesta "scope". A sua volta, il server di autorizzazione utilizza il parametro di risposta "scope" per informare il client dell'ambito del token di accesso emesso.
Il valore del parametro scope è espresso come elenco di stringhe sensibili alle maiuscole separate da spazi. Le stringhe sono definite dal server di autorizzazione. Se il valore contiene più stringhe delimitate da spazi, il loro ordine non ha importanza e ogni stringa aggiunge un intervallo di accesso aggiuntivo all'ambito richiesto.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
GTAF non richiede l'implementazione dell'ambito, ma supporta questa funzionalità. Per ulteriori informazioni, consulta la sezione 3.3 di RFC 6749.
Emissione di un token di accesso
Se la richiesta di token di accesso inviata da GTAF è valida e autorizzata, il server OAuth emette un token di accesso e un token di aggiornamento facoltativo. Se la richiesta non riesce l'autenticazione client o non è valida, il server OAuth restituisce una risposta di errore come descritto nella sezione seguente.
Risposta riuscita
Quando GTAF invia una richiesta, il server OAuth rilascia un token di accesso e un token di aggiornamento facoltativo e crea la risposta aggiungendo i seguenti parametri al corpo dell'entità della risposta HTTP con un codice di stato 200 (OK):
- access_token: OBBLIGATORIO. Il token di accesso emesso dal server OAuth. GTAF prevede che l'endpoint token restituisca un token di tipo bearer.
- expires_in: OBBLIGATORIO. La durata del token di accesso in secondi. Ad esempio, il valore "3600" indica che il token di accesso scadrà un'ora dopo la generazione della risposta. Se omesso, il server OAuth deve fornire il tempo di scadenza con altri mezzi o documentare il valore predefinito.
- token_type: OBBLIGATORIO. Il tipo di token emesso. Per ulteriori informazioni sui diversi tipi di token, consulta la sezione 7.1 di RFC 6749. Il valore non fa distinzione tra maiuscole e minuscole. Al momento della stesura di questo documento, GTAF supporta solo i token di autenticazione.
- refresh_token: FACOLTATIVO. Il token di aggiornamento, che può essere utilizzato per ottenere nuovi token di accesso utilizzando la stessa concessione di autorizzazione.
- scope: FACOLTATIVO, se implementato e identico all'ambito richiesto dal GTAF; altrimenti, obbligatorio.
I parametri sono inclusi nel corpo dell'entità della risposta HTTP utilizzando "application/json". I parametri vengono serializzati in una struttura JavaScript Object Notation (JSON) aggiungendo ogni parametro al livello più alto della struttura. I nomi dei parametri e i valori delle stringhe sono inclusi come stringhe JSON. I valori numerici sono inclusi come numeri JSON. L'ordine dei parametri non è importante e può variare.
Il server di autorizzazione DEVE includere il campo di intestazione della risposta HTTP "Cache-Control"
con un valore "no-store" in qualsiasi risposta contenente token, credenziali
o altre informazioni sensibili, nonché il campo di intestazione della risposta "Pragma"
con un valore "no-cache".
Ad esempio:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Di seguito sono riportati alcuni punti importanti da considerare:
- GTAF ignora i nomi dei valori non riconosciuti nella risposta.
- Le dimensioni dei token e di altri valori ricevuti dal server OAuth non sono definite.
- Il GTAF deve evitare di fare ipotesi sulle dimensioni dei valori. Il server OAuth deve documentare la dimensione di qualsiasi valore emesso.
Risposta di errore
Se una richiesta di autorizzazione non va a buon fine per qualsiasi motivo, ad esempio URI di reindirizzamento mancante, non valido o non corrispondente oppure se l'identificatore client è mancante o non valido, il server OAuth deve rispondere con un codice di stato HTTP 400 (Richiesta non valida), a meno che non sia specificato diversamente, e deve includere almeno uno dei parametri elencati nella sezione Risposta e codici di errore.
Concessione dell'autorizzazione in GTAF
Una concessione di autorizzazione è una credenziale che rappresenta l'autorizzazione dell'utente finale (per accedere alle sue risorse protette, come le informazioni sul saldo dei dati) utilizzata dal GTAF per ottenere un token di accesso.
GTAF utilizza il tipo di concessione client_credentials. Nel tipo di concessione client_credentials, GTAF richiede un token utilizzando una richiesta HTTP POST e l'autenticazione di base HTTP. Tutte le richieste vengono inviate tramite TLS (ad es. HTTPS) e GTAF non può integrarsi con un server OAuth senza un certificato TLS valido. GTAF è in grado di passare un ambito del token configurabile e passerà un ambito vuoto se non ne è configurato uno.
GTAF prevede che venga restituito un token di accesso insieme a un valore "expires_in" (tempo di permanenza). Il valore expires_in deve essere di almeno 900 secondi e non deve superare qualche ora. La richiesta di un nuovo token non deve causare la scadenza anticipata dei token esistenti.
Per maggiori dettagli sui vari tipi di concessione, consulta la sezione 1.3 della RFC 6749.
Esempio di richiesta e risposta
Supponiamo che GTAF abbia la seguente configurazione per un server OAuth:
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Nota:il client secret per un DPA reale deve essere molto più sicuro di quello mostrato nell'esempio.
Per produrre la stringa di autorizzazione, l'ID client, ':' e la password vengono concatenati e codificati in base64. Questa operazione può essere replicata in un'interfaccia a riga di comando nel seguente modo:
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
GTAF effettua quindi una richiesta POST HTTPS al server OAuth utilizzando queste credenziali, il tipo di concessione client_credentials e l'ambito configurato. Per l'esempio, la richiesta di GTAF è simile a quella generata da:
$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'
Le intestazioni utilizzate da GTAF non corrisponderanno a quelle inviate da curl, anche se l'intestazione di autorizzazione sarà identica.
GTAF prevede una risposta nel formato:
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
Di seguito è riportato un esempio di risposta valida:
{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}
Nota:la risposta deve essere un JSON valido.
Risposta e codici di errore
Se una richiesta di autorizzazione da GTAF non va a buon fine per uno dei motivi indicati nella sezione Risposta di errore, il server OAuth deve rispondere con un codice di stato HTTP 400 (Richiesta errata), salvo diversa indicazione, e includere uno dei seguenti parametri nella risposta:
Ad esempio: \
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
GTAF prevede che il server OAuth supporti le seguenti risposte di errore:
| Codice di errore | Risposta | Motivo |
| HTTP 400 | invalid_request | La richiesta non include un parametro obbligatorio, include un valore parametro non supportato (diverso dal tipo di concessione), ripete un parametro, include più credenziali, utilizza più di un meccanismo per l'autenticazione con GTAF o presenta un formato non valido. |
| HTTP 401 | invalid_client | L'autenticazione client non è riuscita (ad es. client sconosciuto, nessuna autenticazione client inclusa o metodo di autenticazione non supportato). Il server OAuth potrebbe restituire un codice di stato HTTP 401 (Autorizzazione assente) per indicare quali schemi di autenticazione HTTP sono supportati. Se il client ha tentato di autenticarsi tramite il campo dell'intestazione della richiesta "Authorization", il server OAuth deve rispondere con un codice di stato HTTP 401 (non autorizzato) e includere il campo dell'intestazione della risposta "WWW-Authenticate" corrispondente allo schema di autenticazione utilizzato dal client. |
| HTTP 500 | Errore del server OAuth |
Per i dettagli di altre risposte che possono essere utilizzate per il debug, consulta la sezione 5.2 della RFC 6749.