API per l'API del piano dati

OAuth 2.0 è standardizzato come RFC 6749. Un documento dettagliato è disponibile all'indirizzo https://oauth.net/2. L'autenticazione di base HTTP viene definita nella sezione 2 di RFC 2617.

Panoramica

In genere, per fornire alle applicazioni di terze parti l'accesso alle risorse limitate, come i piani dati e i dettagli del portafoglio, l'utente finale (proprietario della risorsa) deve condividere le proprie credenziali con la terza parte. Ciò crea diversi problemi e limitazioni come archiviazione delle credenziali, autenticazione delle password, ampio accesso alle risorse dell'utente finale, fuga di password e così via. OAuth2.0 risolve questi problemi introducendo un livello di autorizzazione e quindi garantendo e limitando l'accesso alle risorse protette dell'utente finale.

Anziché utilizzare le credenziali dell'utente finale per accedere alle 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. GTAF utilizza quindi il token di accesso per accedere ai dettagli del piano dati ospitati dall'ETD.

La figura seguente fornisce un flusso di informazioni generale:

Figura 1. Flusso OAuth astratto.

Token di accesso

I token di accesso sono le credenziali utilizzate da GTAF per accedere ai dettagli del piano dati dall'ETD dell'operatore. Un token di accesso è una stringa che rappresenta un'autorizzazione rilasciata alla GTAF. In genere la stringa è opaca alla GTAF. I token rappresentano ambiti e durate di accesso specifici, concessi dall'utente finale all'operatore e applicati dal server OAuth dell'ETD e dell'operatore.

Il token di accesso fornisce un livello di astrazione, sostituendo i diversi costrutti di autorizzazione (ad es. nome utente e password) con un singolo token capito dall'ETD. Questa astrazione consente di emettere token di accesso più restrittivi della concessione di autorizzazione utilizzata per ottenerli, nonché di rimuovere la necessità dell'ETD di comprendere un'ampia gamma di metodi di autenticazione.

I token di accesso possono avere diversi formati, strutture e metodi di utilizzo (ad esempio proprietà crittografiche) in base ai requisiti di sicurezza dell'operatore. GTAF supporta solo token di accesso di tipo Bearer definiti in [RFC6750].

Autenticazione client

GTAF funziona come un "client riservato" ed è in grado di tenere al sicuro le password. Attualmente GTAF supporta solo l'autenticazione HTTP di base per eseguire l'autenticazione con l'ETD. L'identificatore del client viene codificato mediante 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 riservati come GTAF, a cui vengono rilasciate le credenziali client, si autenticano con il server OAuth dell'operatore quando effettuano richieste all'endpoint del token. L'autenticazione client viene utilizzata per: \

  • Ripristino da un client compromesso disattivando il client o modificando le credenziali, impedendo così a un utente malintenzionato di utilizzare in modo illecito i token di aggiornamento rubati. La modifica di un singolo set di credenziali client è significativamente più veloce rispetto alla revoca di un intero set di token di aggiornamento.
  • Implementare le best practice di gestione dell'autenticazione, che richiedono una rotazione periodica delle credenziali.

GTAF utilizza un parametro di richiesta "&client_id" per identificarsi quando invia richieste all'endpoint del token.

Di particolare importanza è la capacità di ruotare le credenziali del client. Il server OAuth deve essere in grado di supportare due coppie di credenziali simultanee durante la rotazione e deve essere in grado di disabilitare le credenziali. In una tipico rotazione delle credenziali:

  1. L'operatore crea le nuove credenziali sul server OAuth e le consegna al proprio Technical Account Manager in modo sicuro.
  2. Google verifica le nuove credenziali e modifica la configurazione GTAF in modo da utilizzare le nuove credenziali.
  3. Google comunica all'operatore che le vecchie credenziali potrebbero essere disattivate.
  4. L'operatore disattiva le credenziali e invia una notifica a Google
  5. Google verifica che le vecchie credenziali non siano più operative

Il server OAuth deve essere in grado di supportare il processo di rotazione precedente.

Endpoint token

L'endpoint del token viene utilizzato dal GTAF per ottenere un token di accesso presentandone il token di autorizzazione o aggiornamento. L'endpoint del token viene utilizzato con ogni concessione di autorizzazione, fatta eccezione per il tipo di concessione implicita, dato che 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 della query "application/x-www-form-urlencoded" che deve essere conservato quando aggiungi parametri di query aggiuntivi. L'URI dell'endpoint non deve includere un componente frammento.
  • Poiché le richieste all'endpoint del token generano la trasmissione di credenziali in testo chiaro (nella richiesta e nella risposta HTTP), il server OAuth del corriere deve utilizzare TLS per l'invio delle richieste all'endpoint del token.
  • GTAF utilizza il metodo HTTP "POST" quando effettua la richiesta di un token di accesso.
  • I parametri inviati senza un valore devono essere considerati come omessi dalla richiesta. Il server OAuth deve ignorare i parametri della richiesta non riconosciuti. I parametri della richiesta e della risposta non devono essere inclusi più di una volta.
  • GTAF supporta solo token di accesso di tipo connessione.

Ambito token di accesso

Gli endpoint di autorizzazione e di 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 comunicare al client l'ambito del token di accesso emesso.

Il valore del parametro dell'ambito è espresso come elenco di stringhe con distinzione tra maiuscole e minuscole. Le stringhe sono definite dal server di autorizzazione. Se il valore contiene più stringhe delimitati da spazi, il loro ordine non è importante e ogni stringa aggiunge un ulteriore intervallo di accesso 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 del 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 a eseguire l'autenticazione del 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 emette un token di accesso e un token di aggiornamento facoltativo e costruisce 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 del token restituisca un token di connessione.
  • 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 dal momento in cui è stata generata la risposta. Se il criterio viene omesso, il server OAuth deve fornire la data di scadenza tramite altri mezzi o documentare il valore predefinito.
  • token_type: OBBLIGATORIO. Il tipo del token emesso. Per ulteriori informazioni sui diversi tipi di token, consulta la Sezione 7.1 della RFC 6749. Il valore non fa distinzione tra maiuscole e minuscole. GTAF supporta solo token di connessione al momento della stesura di questo articolo.
  • update_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 JSON (JavaScript Object Nottion) aggiungendo ogni parametro al livello più alto. 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 "Intestazione della risposta" HTTP-Control" con un valore di "no-store" in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, nonché il campo "Pragma" intestazione della risposta con un valore di "quo-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 aspetti importanti da considerare:

  • GTAF ignora i nomi di valori non riconosciuti nella risposta.
  • Le dimensioni dei token e altri valori ricevuti dal server OAuth non vengono definiti.
  • La GTAF dovrebbe evitare di fare ipotesi sulle dimensioni dei valori. Il server OAuth deve documentare le dimensioni dell'eventuale valore che emette.

Risposta di errore

Se una richiesta di autorizzazione non va a buon fine per qualsiasi motivo, come URI mancante, non valido o di reindirizzamento non corrispondente oppure se l'identificatore del client manca o non è valido, il server OAuth deve rispondere con un codice di stato HTTP 400 (Richiesta non valida) (se non diversamente specificato) e deve includere almeno uno dei parametri elencati nella sezione Error Response e codici.

Concessione di autorizzazione in GTAF

Una concessione di autorizzazione è una credenziale che rappresenta l'autorizzazione dell'utente finale (per accedere alle risorse protette, come le informazioni sul saldo 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 HTTP di base. Tutte le richieste vengono inviate tramite TLS (ad es. HTTPS) e GTAF non possono integrarsi con un server OAuth senza un certificato TLS valido. GTAF è in grado di passare un ambito di token configurabile e supererà un ambito vuoto se non è configurato.

GTAF prevede che venga restituito un token di accesso insieme a un "expires_in" valore (time to live). Il valore expire_in deve essere di almeno 900 secondi e non deve superare alcune ore. La richiesta di un nuovo token non deve causare la scadenza dei token esistenti.

Per ulteriori dettagli sui vari tipi di concessioni, consulta la sezione 1.3 di 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 di un DPA reale deve essere molto più sicuro di quello mostrato nell'esempio.

Per produrre la stringa di autorizzazione, l'ID client e ':' e la password sono concatenati e codificati in base64. Può essere replicato in un'interfaccia a riga di comando come segue:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

GTAF invia quindi una richiesta POST HTTPS al server OAuth utilizzando queste credenziali, il tipo di concessione client_credentials e l'ambito configurato. Ad esempio, la richiesta di GTAF sembra simile alla richiesta 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 modulo:

{
"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 in formato JSON valido.

Risposta di errore e codici

Se una richiesta di autorizzazione da parte di GTAF non riesce a causa di uno dei motivi indicati nella sezione Risposta di errore, il server OAuth deve rispondere con un codice di stato HTTP 400 (Richiesta non valida) (se non diversamente specificato) e includere uno dei seguenti parametri con la 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 richiesta_non_valida La richiesta non contiene un parametro obbligatorio, include un valore di parametro non supportato (diverso da un tipo di autorizzazione), ripete un parametro, include più credenziali, utilizza più di un meccanismo di autenticazione con GTAF o non è in altro modo valido.
HTTP 401 client_non valido Autenticazione del client non riuscita (ad es. client sconosciuto, nessuna autenticazione client inclusa o metodo di autenticazione non supportato). Il server OAuth può restituire un codice di stato HTTP 401 (Non autorizzato) per indicare quali schemi di autenticazione HTTP sono supportati. Se il client ha tentato di eseguire l'autenticazione tramite il campo di intestazione della richiesta "Autorizzazione", il server OAuth deve rispondere con un codice di stato HTTP 401 (Non autorizzato) e includere il campo di intestazione della risposta "WWW-Authenticate" corrispondente allo schema di autenticazione utilizzato dal client.
HTTP 500 Errore del server OAuth

Per informazioni dettagliate su altre risposte che possono essere utilizzate per il debug, consulta la sezione 5.2 di RFC 6749.