Le API OAuth 2.0 di Google possono essere utilizzate sia per l'autenticazione che per l'autorizzazione. Questo documento descrive la nostra implementazione OAuth 2.0 per l'autenticazione, che è conforme alla specifica OpenID Connect ed è OpenID Certified . La documentazione disponibile in Utilizzo di OAuth 2.0 per accedere alle API di Google si applica anche a questo servizio. Se desideri esplorare questo protocollo in modo interattivo, ti consigliamo Google OAuth 2.0 Playground . Per ricevere assistenza su Stack Overflow , tagga le tue domande con "google-oauth".
Configurazione di OAuth 2.0
Prima che la tua applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso utente, devi configurare un progetto in Google API Console per ottenere le credenziali OAuth 2.0, impostare un URI di reindirizzamento e (facoltativamente) personalizzare le informazioni di branding che i tuoi utenti vedono sull'utente- schermata di consenso. Puoi anche utilizzare API Console per creare un account di servizio, abilitare la fatturazione, impostare filtri e svolgere altre attività. Per ulteriori dettagli, vedere la Guida di Google API Console .
Ottieni le credenziali OAuth 2.0
Sono necessarie le credenziali OAuth 2.0, inclusi un ID client e un client secret, per autenticare gli utenti e ottenere l'accesso alle API di Google.
Per visualizzare l'ID client e il segreto client per una determinata credenziale OAuth 2.0, fare clic sul testo seguente: Seleziona credenziale . Nella finestra che si apre, scegli il tuo progetto e le credenziali desiderate, quindi fai clic su Visualizza .
In alternativa, visualizzare l'ID client e il segreto client dalla pagina Credenziali in API Console :
- Go to the Credentials page.
- Fai clic sul nome della tua credenziale o sull'icona a forma di matita ( create ). L'ID cliente e il segreto sono nella parte superiore della pagina.
Imposta un URI di reindirizzamento
L'URI di reindirizzamento che hai impostato in API Console determina dove Google invia le risposte alle tue richieste di autenticazione .
Per creare, visualizzare o modificare gli URI di reindirizzamento per una determinata credenziale OAuth 2.0, procedi come segue:
- Go to the Credentials page.
- Nella sezione ID client OAuth 2.0 della pagina, fare clic su una credenziale.
- Visualizza o modifica gli URI di reindirizzamento.
Se non è presente la sezione ID client OAuth 2.0 nella pagina Credenziali, il progetto non ha credenziali OAuth. Per crearne uno, fai clic su Crea credenziali .
Personalizza la schermata di consenso dell'utente
Per i tuoi utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata di consenso che descrive le informazioni che l'utente rilascia e i termini applicabili. Ad esempio, quando l'utente accede, potrebbe essere chiesto di concedere alla tua app l'accesso al proprio indirizzo e-mail e alle informazioni di base sull'account. Richiedi l'accesso a queste informazioni utilizzando il parametro scope , che la tua app include nella sua richiesta di autenticazione . Puoi anche utilizzare gli ambiti per richiedere l'accesso ad altre API di Google.
La schermata di consenso dell'utente presenta anche informazioni sul marchio come il nome del prodotto, il logo e l'URL della home page. Sei tu a controllare le informazioni sul marchio in API Console.
Per abilitare la schermata di consenso del tuo progetto:
- Aprire Consent Screen page in Google API Console .
- If prompted, select a project, or create a new one.
- Compila il modulo e fai clic su Salva .
La seguente finestra di dialogo per il consenso mostra cosa vedrebbe un utente quando nella richiesta è presente una combinazione di ambiti OAuth 2.0 e Google Drive. (Questa finestra di dialogo generica è stata generata utilizzando Google OAuth 2.0 Playground , quindi non include le informazioni sul marchio che verrebbero impostate in API Console.)
Accesso al servizio
Google e terze parti forniscono librerie che puoi utilizzare per occuparti di molti dei dettagli di implementazione dell'autenticazione degli utenti e dell'accesso alle API di Google. Gli esempi includono Google Sign-In e le librerie client di Google , disponibili per una varietà di piattaforme.
Se scegli di non utilizzare una libreria, segui le istruzioni nella parte restante di questo documento, che descrive i flussi di richieste HTTP che sono alla base delle librerie disponibili.
Autenticazione dell'utente
L'autenticazione dell'utente implica l'ottenimento di un token ID e la sua convalida. I token ID sono una funzionalità standardizzata di OpenID Connect progettata per essere utilizzata nella condivisione di asserzioni di identità su Internet.
Gli approcci più comunemente usati per autenticare un utente e ottenere un token ID sono chiamati flusso "server" e flusso "implicito". Il flusso del server consente al server back-end di un'applicazione di verificare l'identità della persona utilizzando un browser o un dispositivo mobile. Il flusso implicito viene utilizzato quando un'applicazione lato client (in genere un'app JavaScript in esecuzione nel browser) deve accedere alle API direttamente anziché tramite il server back-end.
Questo documento descrive come eseguire il flusso del server per autenticare l'utente. Il flusso implicito è notevolmente più complicato a causa dei rischi per la sicurezza nella gestione e nell'utilizzo dei token sul lato client. Se devi implementare un flusso implicito, ti consigliamo vivamente di utilizzare Google Sign-In .
Flusso del server
Assicurati di aver configurato la tua app in API Console per consentirle di utilizzare questi protocolli e autenticare i tuoi utenti. Quando un utente tenta di accedere con Google, è necessario:
- Crea un token di stato antifalsificazione
- Invia una richiesta di autenticazione a Google
- Conferma il token di stato antifalsificazione
-
codescambio per token di accesso e token ID - Ottieni le informazioni sull'utente dal token ID
- Autentica l'utente
1. Creare un token di stato antifalsificazione
Devi proteggere la sicurezza dei tuoi utenti prevenendo attacchi di falsificazione delle richieste. Il primo passaggio è creare un token di sessione univoco che mantiene lo stato tra la tua app e il client dell'utente. Successivamente, abbini questo token di sessione univoco alla risposta di autenticazione restituita dal servizio di accesso OAuth di Google per verificare che l'utente stia effettuando la richiesta e non un malintenzionato. Questi token sono spesso indicati come token CSRF (Cross-Site Request Forgery ).
Una buona scelta per un token di stato è una stringa di circa 30 caratteri costruita utilizzando un generatore di numeri casuali di alta qualità. Un altro è un hash generato firmando alcune delle variabili di stato della sessione con una chiave che viene tenuta segreta nel back-end.
Il codice seguente mostra la generazione di token di sessione univoci.
PHP
È necessario scaricare la libreria client delle API di Google affinché PHP possa utilizzare questo esempio.
// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
'CLIENT_ID' => CLIENT_ID,
'STATE' => $state,
'APPLICATION_NAME' => APPLICATION_NAME
));Giava
Devi scaricare la libreria client delle API di Google per Java per utilizzare questo esempio.
// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
.useDelimiter("\\A").next()
.replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
.replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
.replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
APPLICATION_NAME);Pitone
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python .
# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
render_template('index.html',
CLIENT_ID=CLIENT_ID,
STATE=state,
APPLICATION_NAME=APPLICATION_NAME))2. Invia una richiesta di autenticazione a Google
Il passaggio successivo consiste nel formare una richiesta HTTPS GET con i parametri URI appropriati. Notare l'uso di HTTPS piuttosto che di HTTP in tutte le fasi di questo processo; Le connessioni HTTP vengono rifiutate. Si dovrebbe recuperare l'URI di base del documento di individuazione utilizzando authorization_endpoint valore di metadati. La discussione seguente presuppone che l'URI di base sia https://accounts.google.com/o/oauth2/v2/auth .
Per una richiesta di base, specificare i seguenti parametri:
-
client_id, che ottieni da API Console Credentials page. -
response_type, che in una richiesta di flusso del codice di autorizzazione di base dovrebbe esserecode. (Maggiori informazioni suresponse_type.) -
scope, che in una richiesta di base dovrebbe essereopenid email. (Leggi di più ascope.) -
redirect_uridovrebbe essere l'endpoint HTTP sul tuo server che riceverà la risposta da Google. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, che hai configurato in API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, la richiesta non andrà a buon fine con un erroreredirect_uri_mismatch. -
statedovrebbe includere il valore del token di sessione univoco anti-contraffazione, nonché qualsiasi altra informazione necessaria per ripristinare il contesto quando l'utente torna all'applicazione, ad esempio l'URL iniziale. (Leggi di più allostate.) -
nonceè un valore casuale generato dalla tua app che abilita la protezione dal replay quando presente. -
login_hintpuò essere l'indirizzo email dell'utente o lasub, che è equivalente all'ID Google dell'utente. Se non fornisci unlogin_hinte l'utente è attualmente connesso, la schermata di consenso include una richiesta di approvazione per rilasciare l'indirizzo email dell'utente alla tua app. (Maggiori informazioni sulogin_hint.) - Utilizza il parametro
hdper ottimizzare il flusso OpenID Connect per gli utenti di un particolare dominio G Suite. (Maggiori informazioni suhd.)
Ecco un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per la leggibilità:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Gli utenti sono tenuti a dare il consenso se la tua app richiede nuove informazioni su di loro o se la tua app richiede l'accesso all'account che non hanno precedentemente approvato.
3. Conferma il token di stato antifalsificazione
La risposta viene inviata al redirect_uri specificato nella richiesta . Tutte le risposte vengono restituite nella stringa di query, come mostrato di seguito:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
Sul server, devi confermare che lo state ricevuto da Google corrisponda al token di sessione creato nel passaggio 1 . Questa verifica di andata e ritorno aiuta a garantire che l'utente, non uno script dannoso, stia effettuando la richiesta.
Il codice seguente mostra la conferma dei token di sessione creati nel passaggio 1:
PHP
È necessario scaricare la libreria client delle API di Google affinché PHP possa utilizzare questo esempio.
// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
return new Response('Invalid state parameter', 401);
}Giava
Devi scaricare la libreria client delle API di Google per Java per utilizzare questo esempio.
// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
request.session().attribute("state"))) {
response.status(401);
return GSON.toJson("Invalid state parameter.");
}Pitone
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python .
# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
response = make_response(json.dumps('Invalid state parameter.'), 401)
response.headers['Content-Type'] = 'application/json'
return response 4. Scambia il code per il token di accesso e il token ID
La risposta include un parametro di code , un codice di autorizzazione monouso che il server può scambiare per un token di accesso e un token ID. Il tuo server effettua questo scambio inviando una richiesta HTTPS POST . La richiesta POST viene inviata all'endpoint del token, che è necessario recuperare dal documento Discovery utilizzando il valore dei metadati token_endpoint . La discussione seguente presuppone che l'endpoint sia https://oauth2.googleapis.com/token . La richiesta deve includere i seguenti parametri nel corpo del POST :
| Campi | |
|---|---|
code | Il codice di autorizzazione restituito dalla richiesta iniziale . |
client_id | L'ID client ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0 . |
client_secret | Il client secret ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0 . |
redirect_uri | Un URI di reindirizzamento autorizzato per il client_id specificato specificato in API Console Credentials page, come descritto in Impostare un URI di reindirizzamento . |
grant_type | Questo campo deve contenere un valore di authorization_code , come definito nella specifica OAuth 2.0 . |
La richiesta effettiva potrebbe essere simile al seguente esempio:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Una risposta positiva a questa richiesta contiene i seguenti campi in un array JSON:
| Campi | |
|---|---|
access_token | Un token che può essere inviato a un'API di Google. |
expires_in | La durata rimanente del token di accesso in secondi. |
id_token | Un JWT che contiene informazioni sull'identità dell'utente con firma digitale da parte di Google. |
scope | Gli ambiti di accesso concessi da access_token espressi come un elenco di stringhe delimitate da spazi e con distinzione tra maiuscole e minuscole. |
token_type | Identifica il tipo di token restituito. In questo momento, questo campo ha sempre il valore Bearer . |
refresh_token | (opzionale) Questo campo è presente solo se il parametro |
5. Ottenere le informazioni sull'utente dal token ID
Un token ID è un JWT (JSON Web Token), ovvero un oggetto JSON con codifica Base64 firmato crittograficamente. Normalmente, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché stai comunicando direttamente con Google su un canale HTTPS senza intermediari e utilizzi il tuo client secret per autenticarti su Google, puoi essere certo che il token tu ricevere proviene davvero da Google ed è valido. Se il tuo server passa il token ID ad altri componenti della tua app, è estremamente importante che gli altri componenti convalidino il token prima di utilizzarlo.
Poiché la maggior parte delle librerie API combina la convalida con il lavoro di decodifica dei valori con codifica base64url e l'analisi del JSON all'interno, probabilmente finirai per convalidare il token comunque quando accedi alle attestazioni nel token ID.
Il payload di un token ID
Un token ID è un oggetto JSON contenente un set di coppie nome / valore. Ecco un esempio, formattato per la leggibilità:
{
"iss": "https://accounts.google.com",
"azp": "1234987819200.apps.googleusercontent.com",
"aud": "1234987819200.apps.googleusercontent.com",
"sub": "10769150350006150715113082367",
"at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
"hd": "example.com",
"email": "jsmith@example.com",
"email_verified": "true",
"iat": 1353601026,
"exp": 1353604926,
"nonce": "0394852-3190485-2490358"
}I token ID Google possono contenere i seguenti campi (noti come attestazioni ):
| Richiesta | Fornito | Descrizione |
|---|---|---|
aud | sempre | Il pubblico a cui è destinato questo token ID. Deve essere uno degli ID client OAuth 2.0 della tua applicazione. |
exp | sempre | Tempo di scadenza in cui o dopo il quale il token ID non deve essere accettato. Rappresentato in tempo Unix (interi secondi). |
iat | sempre | L'ora in cui è stato emesso il token ID. Rappresentato in tempo Unix (interi secondi). |
iss | sempre | L'identificativo dell'emittente per l'emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token ID Google. |
sub | sempre | Un identificatore per l'utente, univoco tra tutti gli account Google e mai riutilizzato. Un account Google può avere più indirizzi email in momenti diversi, ma il valore sub non viene mai modificato. Usa sub all'interno della tua applicazione come chiave di identificazione univoca per l'utente. Lunghezza massima di 255 caratteri ASCII con distinzione tra maiuscole e minuscole. |
at_hash | Hash del token di accesso. Fornisce la convalida che il token di accesso è legato al token di identità. Se il token ID viene emesso con un valore access_token nel flusso del server, questa access_token è sempre inclusa. Questa affermazione può essere utilizzata come meccanismo alternativo per la protezione da attacchi di falsificazione di richieste tra siti, ma se si seguono i passaggi 1 e 3 non è necessario verificare il token di accesso. | |
azp | Il client_id del presentatore autorizzato. Questa affermazione è necessaria solo quando la parte che richiede il token ID non è la stessa del pubblico del token ID. Questo potrebbe essere il caso di Google per le app ibride in cui un'applicazione Web e un'app Android hanno un client_id OAuth 2.0 client_id ma condividono lo stesso progetto API di Google. | |
email | L'indirizzo e-mail dell'utente. Questo valore potrebbe non essere univoco per questo utente e non è adatto per essere utilizzato come chiave primaria. Fornito solo se l'ambito includeva il valore dell'ambito email . | |
email_verified | Vero se l'indirizzo e-mail dell'utente è stato verificato; altrimenti falso. | |
family_name | Il / i cognome / i dell'utente / i. Potrebbe essere fornito quando è presente una rivendicazione di name . | |
given_name | Il nome o i nomi di battesimo dell'utente. Potrebbe essere fornito quando è presente una rivendicazione di name . | |
hd | Il dominio G Suite ospitato dell'utente. Fornito solo se l'utente appartiene a un dominio ospitato. | |
locale | Le impostazioni internazionali dell'utente, rappresentate da un tag della lingua BCP 47 . Potrebbe essere fornito quando è presente una rivendicazione di name . | |
name | Il nome completo dell'utente, in una forma visualizzabile. Potrebbe essere fornito quando:
Quando sono presenti attestazioni di | |
nonce | Il valore del nonce fornito dalla tua app nella richiesta di autenticazione. È necessario applicare la protezione contro gli attacchi di replay assicurandosi che venga presentato una sola volta. | |
picture | L'URL dell'immagine del profilo dell'utente. Potrebbe essere fornito quando:
Quando sono presenti rivendicazioni per | |
profile | L'URL della pagina del profilo dell'utente. Potrebbe essere fornito quando:
Quando sono presenti attestazioni del |
6. Autentica l'utente
Dopo aver ottenuto le informazioni sull'utente dal token ID, è necessario eseguire una query nel database degli utenti dell'app. Se l'utente esiste già nel database, è necessario avviare una sessione dell'applicazione per quell'utente se tutti i requisiti di accesso sono soddisfatti dalla risposta dell'API di Google.
Se l'utente non esiste nel database degli utenti, è necessario reindirizzare l'utente al flusso di registrazione del nuovo utente. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni che ricevi da Google, o per lo meno potresti essere in grado di precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni nel token ID, è possibile ottenere ulteriori informazioni sul profilo utente presso i nostri endpoint del profilo utente.
Argomenti avanzati
Le sezioni seguenti descrivono l'API Google OAuth 2.0 in modo più dettagliato. Queste informazioni sono destinate agli sviluppatori con requisiti avanzati in materia di autenticazione e autorizzazione.
Accesso ad altre API di Google
Uno dei vantaggi dell'utilizzo di OAuth 2.0 per l'autenticazione è che la tua applicazione può ottenere l'autorizzazione a utilizzare altre API di Google per conto dell'utente (come YouTube, Google Drive, Calendar o Contatti) mentre autentichi l'utente. A tale scopo, includi gli altri ambiti di cui hai bisogno nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere il gruppo di età dell'utente alla richiesta di autenticazione, passare un parametro di openid email https://www.googleapis.com/auth/profile.agerange.read . L'utente viene richiesto in modo appropriato nella schermata di consenso . Il token di accesso che ricevi da Google ti consente di accedere a tutte le API relative agli ambiti di accesso che hai richiesto e che ti sono stati concessi.
Aggiorna i gettoni
Nella tua richiesta di accesso API puoi richiedere la restituzione di un token di aggiornamento durante lo scambio di code . Un token di aggiornamento fornisce alla tua app l'accesso continuo alle API di Google mentre l'utente non è presente nella tua applicazione. Per richiedere un token di aggiornamento, aggiungi set il parametro access_type su offline nella richiesta di autenticazione .
Considerazioni:
- Assicurati di archiviare il token di aggiornamento in modo sicuro e permanente, perché puoi ottenere un token di aggiornamento solo la prima volta che esegui il flusso di scambio del codice.
- Esistono limiti al numero di token di aggiornamento emessi: un limite per combinazione client / utente e un altro per utente su tutti i client. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe rientrare in questi limiti, nel qual caso i token di aggiornamento meno recenti smettono di funzionare.
Per ulteriori informazioni, vedere Aggiornamento di un token di accesso (accesso offline) .
Richiesta di nuovo consenso
Puoi chiedere all'utente di autorizzare nuovamente la tua app impostando il parametro prompt per il consent nella richiesta di autenticazione . Quando prompt=consent è incluso, la schermata di consenso viene visualizzata ogni volta che la tua app richiede l'autorizzazione degli ambiti di accesso, anche se tutti gli ambiti erano stati precedentemente concessi al tuo progetto API di Google. Per questo motivo, includi prompt=consent solo quando necessario.
Per ulteriori informazioni sul parametro prompt , vedere prompt nella tabella dei parametri URI di autenticazione .
Parametri URI di autenticazione
La tabella seguente fornisce descrizioni più complete dei parametri accettati dall'API di autenticazione OAuth 2.0 di Google.
| Parametro | necessario | Descrizione |
|---|---|---|
client_id | (Necessario) | La stringa dell'ID client ottenuta da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0 . |
nonce | (Necessario) | Un valore casuale generato dalla tua app che abilita la protezione dal replay. |
response_type | (Necessario) | Se il valore è code , avvia un flusso di codice di autorizzazione di base , che richiede un POST all'endpoint del token per ottenere i token. Se il valore è token id_token o id_token token , avvia un flusso implicito , che richiede l'uso di JavaScript all'URI di reindirizzamento per recuperare i token dall'identificatore #fragment URI . |
redirect_uri | (Necessario) | Determina dove viene inviata la risposta. Il valore di questo parametro deve corrispondere esattamente a uno dei valori di reindirizzamento autorizzati impostati in API Console Credentials page (inclusi lo schema HTTP o HTTPS, le maiuscole e le minuscole e il carattere "/" finale, se presenti). |
scope | (Necessario) | Il parametro scope deve iniziare con il valore Se il valore dell'ambito del Se il valore dell'ambito Oltre a questi ambiti specifici di OpenID, l'argomento dell'ambito può includere anche altri valori di ambito. Tutti i valori di ambito devono essere separati da spazi. Ad esempio, se desideri l'accesso per file a Google Drive di un utente, il tuo parametro di ambito potrebbe essere l' Per informazioni sugli ambiti disponibili, consulta Ambiti OAuth 2.0 per le API di Google o la documentazione per l'API di Google che desideri utilizzare. |
state | (Facoltativo, ma fortemente consigliato) | Una stringa opaca di cui viene eseguito il round trip nel protocollo; vale a dire, viene restituito come parametro URI nel flusso Basic e Lo |
access_type | (Opzionale) | I valori consentiti sono offline e online . L'effetto è documentato in Accesso offline ; se viene richiesto un token di accesso, il client non riceve un token di aggiornamento a meno che offline venga specificato un valore offline . |
display | (Opzionale) | Un valore stringa ASCII per specificare come il server delle autorizzazioni visualizza le pagine dell'interfaccia utente di autenticazione e consenso. I seguenti valori sono specificati e accettati dai server di Google, ma non hanno alcun effetto sul suo comportamento: page , popup , touch e wap . |
hd | (Opzionale) | Il parametro Non fare affidamento su questa ottimizzazione dell'interfaccia utente per controllare chi può accedere alla tua app, poiché le richieste lato client possono essere modificate. Assicurarsi di convalidare che l' ID ritornato di token ha un |
include_granted_scopes | (Opzionale) | Se questo parametro viene fornito con il valore true e la richiesta di autorizzazione viene concessa, l'autorizzazione includerà tutte le autorizzazioni precedenti concesse a questa combinazione utente / applicazione per altri ambiti; vedere Autorizzazione incrementale .Tieni presente che non puoi eseguire l'autorizzazione incrementale con il flusso di app installate. |
login_hint | (Opzionale) | Quando la tua app sa quale utente sta tentando di autenticare, può fornire questo parametro come suggerimento al server di autenticazione. Il passaggio di questo suggerimento sopprime il selettore dell'account e precompila la casella di posta elettronica nel modulo di accesso o seleziona la sessione corretta (se l'utente utilizza l'accesso multiplo ), che può aiutarti a evitare problemi che si verificano se la tua app accede all'account utente sbagliato. Il valore può essere un indirizzo email o la sub , che è equivalente all'ID Google dell'utente. |
prompt | (Opzionale) | Un elenco delimitato da spazi di valori stringa che specifica se il server delle autorizzazioni richiede all'utente la riautenticazione e il consenso. I valori possibili sono:
Se non viene specificato alcun valore e l'utente non ha autorizzato l'accesso in precedenza, all'utente viene mostrata una schermata di consenso. |
Convalida di un token ID
Devi convalidare tutti i token ID sul tuo server a meno che tu non sappia che provengono direttamente da Google. Ad esempio, il tuo server deve verificare come autentico tutti i token ID che riceve dalle tue app client.
Le seguenti sono situazioni comuni in cui potresti inviare token ID al tuo server:
- Invio di token ID con richieste che devono essere autenticate. I token ID indicano l'utente specifico che effettua la richiesta e per quale client è stato concesso tale token ID.
I token ID sono sensibili e possono essere utilizzati in modo improprio se intercettati. Devi assicurarti che questi token siano gestiti in modo sicuro trasmettendoli solo su HTTPS e solo tramite dati POST o all'interno delle intestazioni di richiesta. Se archivi i token ID sul tuo server, devi anche archiviarli in modo sicuro.
Una cosa che rende utili i token ID è il fatto che puoi passarli a diversi componenti della tua app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione leggero che autentica l'app e l'utente. Ma prima di poter utilizzare le informazioni nel token ID o fare affidamento su di esso come un'asserzione che l'utente si è autenticato, è necessario convalidarlo.
La convalida di un token ID richiede diversi passaggi:
- Verifica che il token ID sia firmato correttamente dall'emittente. I token emessi da Google vengono firmati utilizzando uno dei certificati trovati nell'URI specificato nel valore dei metadati
jwks_uridel documento Discovery . - Verifica che il valore dell'attestazione
issnel token ID sia uguale ahttps://accounts.google.comoaccounts.google.com. - Verifica che il valore dell'attestazione
audnel token ID sia uguale all'ID client della tua app. - Verificare che l'ora di scadenza (
exppretesa) del token ID non ha superato. - Se hai specificato un valore per il parametro hd nella richiesta, verifica che il token ID abbia
hdche corrisponda a un dominio ospitato da G Suite accettato.
I passaggi da 2 a 5 comportano solo confronti di stringhe e date che sono abbastanza semplici, quindi non li dettagliamo qui.
Il primo passaggio è più complesso e prevede il controllo della firma crittografica. A scopo di debug , puoi utilizzare l'endpoint tokeninfo di Google per confrontare l'elaborazione locale implementata sul tuo server o dispositivo. Supponiamo che il valore del token ID sia XYZ123 . Quindi dovresti dereferenziare l'URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Se la firma del token è valida, la risposta sarebbe il payload JWT nel formato oggetto JSON decodificato.
L'endpoint tokeninfo è utile per il debug, ma per scopi di produzione, recupera le chiavi pubbliche di Google tokeninfo delle chiavi ed esegui la convalida in locale. È necessario recuperare l'URI delle chiavi dal documento Discovery utilizzando il valore dei metadati jwks_uri . Le richieste all'endpoint di debug possono essere limitate o altrimenti soggette a errori intermittenti.
Poiché Google modifica le sue chiavi pubbliche solo raramente, è possibile memorizzarle nella cache utilizzando le direttive cache della risposta HTTP e, nella stragrande maggioranza dei casi, eseguire la convalida locale in modo molto più efficiente rispetto all'utilizzo dell'endpoint tokeninfo . Questa convalida richiede il recupero e l'analisi dei certificati e l'esecuzione delle chiamate crittografiche appropriate per controllare la firma. Fortunatamente, ci sono librerie ben debuggate disponibili in un'ampia varietà di lingue per farlo (vedi jwt.io ).
Ottenimento delle informazioni sul profilo utente
Per ottenere ulteriori informazioni sul profilo dell'utente, è possibile utilizzare il token di accesso (che l'applicazione riceve durante il flusso di autenticazione ) e lo standard OpenID Connect :
Per essere conforme a OpenID, è necessario includere i valori dell'ambito del
openid profilenella richiesta di autenticazione .Se si desidera includere l'indirizzo di posta elettronica dell'utente, è possibile specificare un valore di ambito aggiuntivo
email. Per specificare sia ilprofileche l'email, puoi includere il seguente parametro nell'URI della tua richiesta di autenticazione:scope=openid%20profile%20email
- Aggiungi il tuo token di accesso all'intestazione dell'autorizzazione ed effettua una richiesta HTTPS
GETall'endpoint userinfo, che dovresti recuperare dal documento Discovery utilizzando il valore dei metadatiuserinfo_endpoint. La risposta userinfo include informazioni sull'utente, come descritto inOpenID Connect Standard Claimse il valore dei metadaticlaims_supporteddel documento Discovery. Gli utenti o le loro organizzazioni possono scegliere di fornire o trattenere determinati campi, quindi potresti non ottenere informazioni per ogni campo per i tuoi ambiti di accesso autorizzati.
Il documento Discovery
Il protocollo OpenID Connect richiede l'uso di più endpoint per autenticare gli utenti e per richiedere risorse, inclusi token, informazioni sugli utenti e chiavi pubbliche.
Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente l'uso di un "documento Discovery", un documento JSON trovato in una posizione ben nota contenente coppie chiave-valore che forniscono dettagli sulla configurazione del provider OpenID Connect, inclusi gli URI dell'autorizzazione , token, revoca, informazioni utente e endpoint a chiavi pubbliche. Il documento Discovery per il servizio OpenID Connect di Google può essere recuperato da:
https://accounts.google.com/.well-known/openid-configuration
Per utilizzare i servizi OpenID Connect di Google, è necessario codificare l'URI del documento di rilevamento ( https://accounts.google.com/.well-known/openid-configuration ) nella propria applicazione. L'applicazione recupera il documento, applica le regole di memorizzazione nella cache nella risposta, quindi recupera gli URI dell'endpoint da esso secondo necessità. Ad esempio, per autenticare un utente, il codice sarebbe recuperare authorization_endpoint valore di metadati ( https://accounts.google.com/o/oauth2/v2/auth nell'esempio qui sotto) come URI di base per le richieste di autenticazione che vengono inviati a Google.
Ecco un esempio di tale documento; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fare riferimento a quel documento per i loro significati). I valori sono puramente illustrativi e potrebbero cambiare, sebbene siano copiati da una versione recente dell'attuale documento di Google Discovery:
{
"issuer": "https://accounts.google.com",
"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
"device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
"token_endpoint": "https://oauth2.googleapis.com/token",
"userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
"revocation_endpoint": "https://oauth2.googleapis.com/revoke",
"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
"response_types_supported": [
"code",
"token",
"id_token",
"code token",
"code id_token",
"token id_token",
"code token id_token",
"none"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"scopes_supported": [
"openid",
"email",
"profile"
],
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic"
],
"claims_supported": [
"aud",
"email",
"email_verified",
"exp",
"family_name",
"given_name",
"iat",
"iss",
"locale",
"name",
"picture",
"sub"
],
"code_challenge_methods_supported": [
"plain",
"S256"
]
}Potrebbe essere possibile evitare un round trip HTTP memorizzando nella cache i valori dal documento Discovery. Le intestazioni di memorizzazione nella cache HTTP standard vengono utilizzate e devono essere rispettate.
Librerie client
Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 integrandosi con i framework più diffusi:
- Libreria client delle API di Google per Java
- Libreria client delle API di Google per Python
- Libreria client delle API di Google per .NET
- Libreria client delle API di Google per Ruby
- Libreria client delle API di Google per PHP
- Libreria OAuth 2.0 per Google Web Toolkit
- Google Toolbox per controller Mac OAuth 2.0
Conformità OpenID Connect
Il sistema di autenticazione OAuth 2.0 di Google supporta le funzionalità richieste dalla specifica OpenID Connect Core . Qualsiasi client progettato per funzionare con OpenID Connect dovrebbe interagire con questo servizio (ad eccezione dell'OpenID Request Object ).