Le API OAuth 2.0 di Google possono essere utilizzate sia per l'autenticazione sia per l'autorizzazione. Questo documento descrive la nostra implementazione di OAuth 2.0 per l'autenticazione, che è conforme alla specifica OpenID Connect e con la certificazione OpenID. Anche la documentazione si trova in Utilizzo di OAuth 2.0 per accedere alle API di Google per questo servizio. Se vuoi esplorare questo protocollo in modo interattivo, ti consigliamo di utilizzare Google OAuth 2.0 Playground. Per ricevere aiuto su Stack Overflow, tagga le tue domande con 'google-oauth'.
Configurare OAuth 2.0
Affinché la tua applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso dell'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 visualizzate dagli utenti nella schermata di consenso dell'utente. Puoi anche utilizzare API Console per creare un account di servizio, abilitare la fatturazione, configurare i filtri e svolgere altre attività. Per ulteriori dettagli, consulta la Guida di Google API Console.
Ottenere le credenziali OAuth 2.0
Per autenticare gli utenti e ottenere l'accesso alle API di Google, devi disporre delle credenziali OAuth 2.0, inclusi un ID client e un client secret.
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 URI di reindirizzamento
L'URI di reindirizzamento che imposti 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 per il consenso degli utenti
Per gli utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata per il consenso che
descrive le informazioni che l'utente sta rilasciando e i termini applicabili. Ad esempio, quando
l'utente accede, potrebbe essere chiesto di fornire all'app l'accesso al suo indirizzo email
e ai dati di base dell'account. Devi richiedere 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 per il consenso degli utenti mostra anche le informazioni di branding, come il nome del prodotto, il logo e l'URL di una home page. Puoi gestire le informazioni sul branding nel 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 ciò che un utente visualizzerà 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, pertanto non include informazioni di branding che potrebbero essere impostate in API Console.

Accedi al servizio
Google e terze parti forniscono librerie che puoi utilizzare per gestire molti dei dettagli di implementazione relativi all'autenticazione degli utenti e alle modalità di accesso alle API di Google. Alcuni esempi sono Accedi con Google e le librerie client di Google, disponibili per diverse piattaforme.
Se scegli di non utilizzare una libreria, segui le istruzioni nella parte restante di questo documento, che descrive i flussi di richiesta HTTP alla base delle librerie disponibili.
Autenticazione dell'utente
L'autenticazione dell'utente comporta l'ottenimento di un token ID e la sua convalida. I token ID sono una funzionalità standardizzata di OpenID Connect progettata per essere utilizzata per la dichiarazione delle asserzioni su Internet.
Gli approcci più utilizzati per l'autenticazione di un utente e per ottenere un token ID sono chiamati flusso "server" e "implicit". 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 direttamente alle API anziché tramite il suo server di backend.
Questo documento descrive come eseguire il flusso del server per autenticare l'utente. Il flusso implicito è significativamente 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 Accedi con Google.
Flusso server
Assicurati di configurare la tua app in API Console per consentirla di utilizzare questi protocolli e di autenticare i tuoi utenti. Quando un utente prova ad accedere con Google, devi:
- Creare un token di stato anti-falso
- Inviare una richiesta di autenticazione a Google
- Conferma il token di stato di contraffazione
- Exchange
code
per il token di accesso e il token ID - Ottenere le informazioni utente dal token ID
- Autentica l'utente
1. Crea un token di stato anti-falso
Devi proteggere la sicurezza dei tuoi utenti da attacchi di richiesta di falsificazione. Il primo passaggio consiste nel creare un token di sessione univoco che contenga lo stato tra l'app e il client dell'utente. Successivamente, potrai associare 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 sia un utente malintenzionato dannoso. Questi token sono spesso indicati come token di richiesta di falsificazione tra siti (CSRF).
Un'ottima scelta per un token di stato è una stringa di circa 30 caratteri, generata 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 mantenuta segreta sul tuo backend.
Il seguente codice dimostra la generazione di token di sessione univoci.
PHP
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.
// 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 ));
Java
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.
// 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);
Python
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. Inviare una richiesta di autenticazione a Google
Il passaggio successivo consiste nel generare una richiesta HTTPS GET
con i parametri URI appropriati.
Nota l'utilizzo di HTTPS anziché HTTP in tutte le fasi di questo processo; le connessioni HTTP vengono
rifiutate. Devi recuperare l'URI di base dal documento di rilevamento
utilizzando il valore dei metadati authorization_endpoint
. La seguente discussione presuppone che l'URI di base sia https://accounts.google.com/o/oauth2/v2/auth
.
Per una richiesta di base, specifica i seguenti parametri:
client_id
, che puoi ottenere dal API Console Credentials page .response_type
, che in una richiesta di flusso di codice di autorizzazione di base dovrebbe esserecode
. Scopri di più all'indirizzoresponse_type
.scope
: in una richiesta di base dovrebbe essereopenid email
. Scopri di più all'indirizzoscope
.redirect_uri
deve essere l'endpoint HTTP del 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, 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
.state
deve includere il valore del token di sessione univoco anti-falso, nonché eventuali altre informazioni necessarie per recuperare il contesto quando l'utente torna all'applicazione, ad esempio l'URL iniziale. Scopri di più all'indirizzostate
.nonce
è un valore casuale generato dalla tua app che consente la protezione della riproduzione quando è presente.login_hint
può essere l'indirizzo email dell'utente o la stringasub
, che equivale all'ID Google dell'utente. Se non fornisci unlogin_hint
e l'utente ha eseguito l'accesso, la schermata di consenso include una richiesta di approvazione per rilasciare l'indirizzo email dell'utente nella tua app. Scopri di più all'indirizzologin_hint
.- Utilizza il parametro
hd
per ottimizzare il flusso OpenID Connect per gli utenti di un particolare dominio associato a un'organizzazione Google Cloud. Scopri di più all'indirizzohd
.
Ecco un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per una migliore 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
È necessario dare il proprio consenso agli utenti se la tua app richiede nuove informazioni in merito o se richiede l'accesso all'account da parte delle tue app non approvate in precedenza.
3. Conferma token di stato anti-falso
La risposta viene inviata all'elemento 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 il state
ricevuto da Google corrisponda al
token di sessione che hai 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 seguente codice dimostra la conferma dei token di sessione che hai creato nel passaggio 1:
PHP
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.
// 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); }
Java
Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.
// 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."); }
Python
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. Scambio di code
per il token di accesso e il token ID
La risposta include un parametro code
, un codice di autorizzazione monouso che il tuo server può scambiare con 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 devi recuperare dal documento di rilevamento utilizzando il
valore dei metadati token_endpoint
. La seguente discussione presuppone che l'endpoint sia https://oauth2.googleapis.com/token
. La richiesta deve includere i seguenti parametri nel
corpo POST
:
Campi | |
---|---|
code |
Il codice di autorizzazione che viene 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 secret client che ottieni 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 nel file
API Console
Credentials page, come descritto in
Impostare un URI di reindirizzamento. |
grant_type |
Questo campo deve contenere un valore authorization_code ,
come definito nella specifica OAuth 2.0. |
La richiesta effettiva potrebbe essere simile all'esempio seguente:
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 corretta 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 che è stato digitalmente firmato da Google. |
scope |
Gli ambiti di accesso concessi da access_token espressi come elenco di
stringhe sensibili alle maiuscole. |
token_type |
Identifica il tipo di token restituito. Al momento, questo campo ha sempre il valore
Bearer .
|
refresh_token |
(facoltativo)
Questo campo è presente solo se il parametro
|
5. Ottieni le informazioni dell'utente dal token ID
Un token ID è un token web JSON, ovvero un oggetto JSON con codifica Base64 firmato con crittografia. Normalmente, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché stai comunicando direttamente con Google tramite un canale HTTPS senza intermediari e utilizzando il client secret per autenticarti su Google, puoi avere la certezza che il token che ricevi proviene effettivamente da Google ed è valido. Se il server trasmette il token ID ad altri componenti dell'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 codice JSON al suo interno, è probabile che la convalida del token avvenga comunque, quando accedi alle richieste nel token ID.
Il payload di un token ID
Un token ID è un oggetto JSON contenente un insieme 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 (chiamati rivendicazioni):
Claim | fornito | Description |
---|---|---|
aud |
sempre | Il pubblico a cui è destinato questo token ID. Deve essere uno degli ID client OAuth 2.0 dell'applicazione. |
exp |
sempre | La data di scadenza il giorno dopo la quale il token ID non deve essere accettato. Rappresentato in tempo Unix (numeri interi). |
iat |
sempre | La data di emissione del token ID. Rappresentato in tempo Unix (numeri interi). |
iss |
sempre | L'identificatore dell'emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token ID Google. |
sub |
sempre | Un identificatore dell'utente, univoco per 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. Utilizza sub nella tua applicazione come chiave di identificazione univoca per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole. |
at_hash |
Hash del token di accesso. Offre la convalida che il token di accesso è associato al token di identità. Se il token ID viene emesso con un valore access_token nel flusso
del server, questa rivendicazione è sempre inclusa. Questa dichiarazione può essere utilizzata come meccanismo alternativo per
proteggersi dagli attacchi di falsificazione di richieste tra siti, ma se segui il
Passaggio 1 e il Passaggio 3,
non è necessario verificare il token di accesso. |
|
azp |
Il client_id del presentatore autorizzato. Questa rivendicazione è necessaria solo quando
la parte che richiede il token ID non corrisponde al pubblico del token ID. Questo può valere per Google per le app ibride in cui un'applicazione web e un'app Android hanno un OAuth 2.0 client_id diverso, ma condividono lo stesso progetto API di Google. |
|
email |
L'indirizzo email dell'utente. Questo valore potrebbe non essere univoco per l'utente e non è idoneo
per essere utilizzato come chiave primaria. Fornito solo se il tuo ambito includeva il valore dell'ambito email . |
|
email_verified |
True se l'indirizzo email dell'utente è stato verificato; in caso contrario è falso. | |
family_name |
I cognomi dell'utente o i cognomi. Potrebbe essere fornito quando è presente una rivendicazione di name . |
|
given_name |
I nomi o i nomi degli utenti. Potrebbe essere fornito quando è presente una rivendicazione di name . |
|
hd |
Il dominio associato all'organizzazione Google Cloud dell'utente. Fornito solo se l'utente appartiene a un'organizzazione Google Cloud. | |
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 un formato visibile. Può essere fornito quando:
Quando sono presenti rivendicazioni di |
|
nonce |
Il valore di nonce fornito dalla tua app nella richiesta di autenticazione.
Devi imporre la protezione contro gli attacchi di replica assicurandoti che venga presentata una sola volta. |
|
picture |
L'URL dell'immagine del profilo dell'utente. Può essere fornito quando:
Quando sono presenti rivendicazioni di |
|
profile |
L'URL della pagina del profilo dell'utente. Può essere fornito quando:
Quando sono presenti rivendicazioni di |
6. Autentica l'utente
Dopo aver ottenuto le informazioni utente dal token ID, devi eseguire una query sul database utente della tua app. Se l'utente esiste già nel tuo database, devi 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 tuo database utenti, devi reindirizzarlo al flusso di registrazione dei nuovi utenti. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni ricevute da Google, o almeno puoi precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni nel token ID, puoi ottenere ulteriori informazioni sul profilo utente nei nostri endpoint del profilo utente.
Argomenti avanzati
Le seguenti sezioni descrivono in modo più dettagliato l'API Google OAuth 2.0. Queste informazioni sono rivolte agli sviluppatori con requisiti avanzati di autenticazione e autorizzazione.
Accesso ad altre API di Google
Uno dei vantaggi di OAuth 2.0 per l'autenticazione è che l'applicazione può ottenere l'autorizzazione per l'utilizzo di altre API di Google per conto dell'utente (ad esempio YouTube, Google Drive, Calendar o Contatti), contemporaneamente all'autenticazione dell'utente. A tale scopo, includi gli altri ambiti di cui hai bisogno nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere la fascia d'età dell'utente alla richiesta di autenticazione, passa un
parametro di ambito a
openid email https://www.googleapis.com/auth/profile.agerange.read
. alla schermata per il consenso viene richiesta l'autorizzazione dell'utente. 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 a cui ti è stato concesso.
Token di aggiornamento
Nella tua richiesta di accesso all'API, puoi richiedere la restituzione di un token di aggiornamento durante lo
scambio di code
. Un token di aggiornamento fornisce alla tua app accesso continuo alle API di Google anche quando l'utente non è presente nella tua applicazione. Per richiedere un
token di aggiornamento, aggiungi il parametro
access_type
a 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 in tutti i client. Se la tua applicazione richiede troppi token di aggiornamento, potrebbero verificarsi questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.
Per ulteriori informazioni, consulta Aggiornare un token di accesso (accesso offline).
Richiesta di nuovo consenso
Puoi chiedere all'utente di autorizzare di nuovo la tua app impostando il parametro prompt
su consent
nella richiesta di autenticazione. Se prompt=consent
è
inclusa, la schermata per il consenso viene visualizzata ogni volta che la tua app richiede l'autorizzazione
agli ambiti di accesso, anche se tutti gli ambiti sono stati precedentemente concessi al progetto delle API di Google. Per questo motivo, includi prompt=consent
solo quando necessario.
Per saperne di più sul parametro prompt
, consulta prompt
nella tabella Parametri URI di autenticazione.
Parametri di URI di autenticazione
La tabella seguente fornisce descrizioni più complete dei parametri accettati dall'API di autenticazione OAuth 2.0 di Google.
Parametro | Obbligatorio | Description |
---|---|---|
client_id |
(Obbligatorio) | La stringa dell'ID client ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0. |
nonce |
(Obbligatorio) | Un valore casuale generato dalla tua app che consente la protezione dalla riproduzione. |
response_type |
(Obbligatorio) | Se il valore è code , viene avviato un flusso di codice di autorizzazione di base, che richiede un POST all'endpoint per ottenere i token. Se il valore è
token id_token o id_token token , viene avviato un
flusso implicito,
che richiede l'utilizzo di JavaScript nell'URI di reindirizzamento per recuperare i token dall'identificatore #fragment URI. |
redirect_uri |
(Obbligatorio) | 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 (compresi lo schema HTTP o HTTPS, quello specificato nella parte finale e '/', se presente). |
scope |
(Obbligatorio) | Il parametro dell'ambito deve iniziare con il valore Se è presente il valore dell'ambito Se è presente il valore dell'ambito Oltre a questi ambiti specifici per 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 vuoi consentire l'accesso per file a Google Drive di un utente, il parametro di ambito potrebbe essere Per informazioni sugli ambiti disponibili, consulta gli ambiti OAuth 2.0 per le API di Google o la documentazione dell'API Google che vuoi utilizzare. |
state |
(Facoltativo, ma vivamente consigliato) | Una stringa opaca che viene roundtrip nel protocollo, vale a dire che viene restituita come parametro URI nel flusso di base e nell'identificatore
|
access_type |
(facoltativo) | 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 non venga specificato un valore offline . |
display |
(facoltativo) | Un valore stringa ASCII per specificare la modalità di visualizzazione delle pagine dell'interfaccia utente per l'autenticazione e il consenso. I seguenti valori sono specificati e accettati dai server di Google, ma non hanno alcun effetto sul loro comportamento: page , popup , touch e wap . |
hd |
(facoltativo) | Semplifica la procedura di accesso per gli account di proprietà di un'organizzazione Google Cloud. Se
includi il dominio dell'organizzazione Google Cloud (ad esempio mycollege.edu),
puoi indicare che l'UI di selezione degli account deve essere ottimizzata per gli account
di quel dominio. Per ottimizzare in generale gli account dell'organizzazione Google Cloud anziché un solo dominio dell'organizzazione Google Cloud, imposta il valore di un asterisco ( Non fare affidamento su questa ottimizzazione dell'interfaccia utente per controllare chi può accedere alla tua app, poiché è possibile modificare le richieste lato client. Assicurati di convalidare che
il token ID restituito ha un valore di rivendicazione
|
include_granted_scopes |
(facoltativo) | Se a questo parametro viene fornito 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; consulta la sezione
Autorizzazione incrementale.
Tieni presente che non puoi eseguire un'autorizzazione incrementale con il flusso delle app installate. |
login_hint |
(facoltativo) | 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 elimina il selettore account
e precompila il riquadro dell'email nel modulo di accesso, oppure seleziona la
sessione adeguata (se l'utente utilizza
l'accesso simultaneo),
in modo da evitare problemi che si verificano se l'app registra l'account utente sbagliato.
Il valore può essere un indirizzo email o la stringa sub , equivalente all'ID Google dell'utente. |
prompt |
(facoltativo) | Un elenco di valori stringa separati da spazi che specificano se il server di autorizzazione richiede l'autenticazione e il consenso all'utente. I valori possibili sono:
Se non viene specificato alcun valore e l'utente non ha autorizzato l'accesso in precedenza, viene visualizzata una schermata per il 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 autentici i token ID che riceve dalle app client.
Di seguito sono riportate le situazioni comuni in cui potresti inviare i token ID al tuo server:
- Invio di token ID con richieste da autenticare. I token ID indicano all'utente specifico che ha effettuato la richiesta e per quale client è stato concesso il token ID.
I token ID sono sensibili e possono essere utilizzati in modo improprio se intercettati. Devi assicurarti che questi token vengano gestiti in modo sicuro trasmettendoli solo tramite HTTPS e solo tramite dati POST o all'interno delle intestazioni delle richieste. Se memorizzi i token ID sul tuo server, devi archiviarli anche in modo sicuro.
Una cosa che rende utili i token ID è il fatto che puoi trasmetterli intorno 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. Tuttavia, prima di poter utilizzare le informazioni nel token ID o farne affidamento come asserzione che l'utente ha autenticato, devi convalidarle.
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 che si trovano all'URI specificato nel valore dei metadati
jwks_uri
del documento di rilevamento. - Verifica che il valore della rivendicazione
iss
nel token ID sia uguale ahttps://accounts.google.com
oaccounts.google.com
. - Verifica che il valore della rivendicazione
aud
nel token ID sia uguale all'ID client della tua app. - Verifica che la data di scadenza (
exp
rivendicazione) del token ID non sia passata. - Se hai specificato un valore hdparameter nella richiesta, verifica che
il token ID abbia una rivendicazione
hd
che corrisponde a un dominio accettato associato a un'organizzazione Google Cloud.
I passaggi da 2 a 5 prevedono il confronto di stringhe e date, che sono piuttosto semplici, quindi non li dettagliamo qui.
Il primo passaggio è più complesso e prevede il controllo della firma crittografica. Ai fini di debug, puoi utilizzare l'endpoint tokeninfo
di Google per confrontarlo con l'elaborazione locale implementata sul tuo server o dispositivo. Supponiamo che il valore del token ID sia XYZ123
. Devi quindi dereferenziare l'URI
https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Se la firma del token è valida, la risposta sarà il payload JWT nel suo formato oggetto JSON decodificato.
L'endpoint tokeninfo
è utile per il debug, ma a fini di produzione recupera le chiavi pubbliche di Google dall'endpoint ed esegui la convalida in locale. Devi recuperare l'URI delle chiavi dal documento di rilevamento utilizzando il valore dei metadati jwks_uri
. Le richieste all'endpoint di debug possono essere
ridotte o altrimenti soggette a errori intermittenti.
Poiché Google modifica le chiavi pubbliche solo raramente, puoi memorizzarle nella cache utilizzando le istruzioni cache della risposta HTTP e, nella grande maggioranza dei casi, esegui 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 di chiamate crittografiche appropriate per controllare la firma. Fortunatamente sono disponibili librerie ben sottoposte a debug in una vasta gamma di linguaggi, per questo scopo (vedi jwt.io).
Ottenere informazioni del profilo utente
Per ottenere ulteriori informazioni sul profilo dell'utente, puoi utilizzare il token di accesso (che l'applicazione riceve durante il flusso di autenticazione) e lo standard OpenID Connect:
Per essere compatibile con OpenID, devi includere i valori dell'ambito
openid profile
nella tua richiesta di autenticazione.Se vuoi includere l'indirizzo email dell'utente, puoi specificare un valore aggiuntivo dell'ambito di
email
. Per specificare siaprofile
siaemail
, 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
GET
richiesta HTTPS all'endpoint userinfo, che dovresti recuperare dal documento di Discovery utilizzando il valore dei metadatiuserinfo_endpoint
. La risposta dell'utente include informazioni sull'utente, come descritto inOpenID Connect Standard Claims
e nel valore dei metadaticlaims_supported
del documento di rilevamento. Gli utenti o le loro organizzazioni possono scegliere di fornire o trattenere determinati campi, quindi potresti non ricevere informazioni su tutti i campi relativi agli ambiti di accesso autorizzati.
Il documento di rilevamento
Il protocollo OpenID Connect richiede l'utilizzo di più endpoint per l'autenticazione degli utenti e per la richiesta di risorse tra cui token, informazioni utente e chiavi pubbliche.
Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente l'utilizzo di un documento &Discovery: un documento JSON che si trova in una posizione nota contenente coppie chiave-valore che forniscono dettagli sulla configurazione del provider OpenID Connect, inclusi gli URI di endpoint di autorizzazione, token, revoca, userinfo e chiave pubblica. Il documento di rilevamento 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, devi impostare come hardcoded l'URI del documento di rilevamento (https://accounts.google.com/.well-known/openid-configuration
) nella tua applicazione.
L'applicazione recupera il documento, applica le regole di memorizzazione nella cache nella risposta e recupera gli URI degli endpoint
in base alle esigenze. Ad esempio, per autenticare un utente, il tuo codice recupera il
valore dei metadati authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
nell'esempio sotto)
come URI di base per le richieste di autenticazione inviate a Google.
Ecco un esempio di tale documento; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fai riferimento a tale documento per conoscere i loro significati). I valori sono puramente illustrativi e potrebbero cambiare, anche se sono copiati da una versione recente dell'effettivo 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" ] }
Potresti evitare un roundtrip HTTP memorizzando nella cache i valori contenuti nel documento di rilevamento. Vengono utilizzate intestazioni di memorizzazione nella cache HTTP standard, che devono essere rispettate.
Librerie client
Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 mediante l'integrazione 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
- Strumenti Google per controller Mac OAuth 2.0
Conformità di OpenID Connect
Il sistema di autenticazione OAuth 2.0 di Google supporta le funzionalità richieste della specifica OpenID Connect Core. Qualsiasi client progettato per funzionare con OpenID Connect deve interagire con questo servizio (tranne che con OpenID Request Object).