OpenID Connect

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, conforme alla specifica OpenID Connect ed è certificata OpenID. Anche la documentazione disponibile in Utilizzo di OAuth 2.0 per accedere alle API di Google si applica a questo servizio. Se vuoi 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".

Configurare OAuth 2.0

Prima che l'applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso degli utenti, devi configurare un progetto nella Google API Console per ottenere le credenziali OAuth 2.0, impostare un URI di reindirizzamento e, facoltativamente, personalizzare le informazioni di branding che gli utenti vedono nella schermata per il consenso dell'utente. Puoi anche utilizzare API Console per creare un account di servizio, abilitare la fatturazione, configurare i filtri ed eseguire altre attività. Per maggiori dettagli, consulta la Guida diGoogle API Console.

Ottenere le credenziali OAuth 2.0

Per autenticare gli utenti e ottenere l'accesso alle API di Google sono necessarie le credenziali OAuth 2.0, inclusi un ID client e un client secret.

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

  1. Go to the Credentials page.
  2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

Imposta un URI di reindirizzamento

L'URI di reindirizzamento che imposti in API Console determina dove Google invia le risposte alle tue richieste di autenticazione.

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

  1. Go to the Credentials page.
  2. In the OAuth 2.0 client IDs section of the page, click a credential.
  3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Personalizzare la schermata per il consenso dell'utente

Per i tuoi 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, gli potrebbe essere chiesto di concedere alla tua app l'accesso al suo indirizzo email e ai dati di base dell'account. Puoi richiedere l'accesso a queste informazioni utilizzando il parametro scope, che l'app include nella richiesta di autenticazione. Puoi utilizzare gli ambiti anche per richiedere l'accesso ad altre API di Google.

La schermata per il consenso dell'utente contiene anche informazioni di branding come il nome del prodotto, il logo e l'URL di una home page. Puoi controllare le informazioni di branding in API Console.

Per abilitare la schermata di consenso del tuo progetto:

  1. Aprire Consent Screen page in Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Compila il modulo e fai clic su Salva .

La seguente finestra di dialogo per il consenso mostra ciò che un utente vede quando è presente una combinazione di ambiti OAuth 2.0 e Google Drive nella richiesta. Questa finestra di dialogo generica è stata generata utilizzando Google OAuth 2.0 Playground, quindi non include le informazioni di branding che verrebbero impostate in API Console.

Screenshot della pagina del consenso

Accedi al servizio

Google e le terze parti forniscono librerie che puoi utilizzare per gestire molti dei dettagli di implementazione relativi all'autenticazione degli utenti e all'accesso alle API di Google. Alcuni esempi sono i servizi di identità Google e le librerie client di Google, disponibili per una vasta gamma 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 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 la condivisione di asserzioni di identità su internet.

Gli approcci più comunemente utilizzati 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 suo server back-end.

Questo documento descrive come eseguire il flusso del server per l'autenticazione dell'utente. Il flusso implicito è molto 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 i servizi di identità Google.

Flusso server

Assicurati di configurare la tua app in API Console per abilitarla all'uso di questi protocolli e all'autenticazione degli utenti. Quando un utente tenta di accedere con Google, devi:

  1. Creare un token di stato anti-falsificazione
  2. Inviare una richiesta di autenticazione a Google
  3. Confermare il token dello stato anti-falsificazione
  4. Exchange code per token di accesso e token ID
  5. Ottenere le informazioni sull'utente dal token ID
  6. Autenticare l'utente

1. Creare un token di stato anti-falsificazione

È necessario proteggere la sicurezza degli utenti impedendo 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, associa questo token di sessione univoco alla risposta di autenticazione restituita dal servizio di accesso OAuth di Google per verificare che la richiesta sia stata effettuata dall'utente e che non sia un utente malintenzionato malintenzionato. Questi token sono spesso indicati come token di falsificazione di richieste tra siti (CSRF).

Una buona scelta per un token di stato è una stringa di circa 30 caratteri creata utilizzando un generatore di numeri casuali di alta qualità. Un altro è un hash generato firmando alcune variabili di stato della sessione con una chiave mantenuta segreta nel backend.

Il codice seguente illustra 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

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);

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. Invia una richiesta di autenticazione a Google

Il passaggio successivo consiste nel creare una richiesta GET HTTPS con i parametri URI appropriati. Tieni presente l'utilizzo di HTTPS anziché di HTTP in tutti i passaggi della procedura; 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 da API Console Credentials page .
  • response_type, che in una richiesta di flusso del codice di autorizzazione di base dovrebbe essere code. (Scopri di più all'indirizzo response_type.)
  • scope, che in una richiesta di base dovrebbe essere openid email. (Scopri di più all'indirizzo scope.)
  • redirect_uri deve 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 e verrà visualizzato un errore redirect_uri_mismatch.
  • state deve includere il valore del token di sessione univoco contro la falsificazione, nonché eventuali altre informazioni necessarie per recuperare il contesto quando l'utente torna alla tua applicazione, ad esempio l'URL iniziale. (Scopri di più all'indirizzo state.)
  • nonce è un valore casuale generato dalla tua app che consente la protezione dalla riproduzione, se presente.
  • login_hint può essere l'indirizzo email dell'utente o la stringa sub, che equivale all'ID Google dell'utente. Se non fornisci un login_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'indirizzo login_hint.
  • Utilizza il parametro hd per ottimizzare il flusso OpenID Connect per gli utenti di un determinato dominio associato a un'organizzazione Google Workspace o Cloud (scopri di più all'indirizzo hd).

Ecco un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per una maggiore 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 devono dare il consenso se la tua app richiede nuove informazioni al riguardo o se la tua app richiede l'accesso all'account che non hanno approvato in precedenza.

3. Conferma il token di stato anti-falsificazione

La risposta viene inviata all'entità redirect_uri che hai 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 creato nel Passaggio 1. Questa verifica di round trip contribuisce ad assicurare che la richiesta sia l'utente, non uno script dannoso.

Il codice seguente mostra la conferma dei token di sessione creati 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

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.");
}

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. Scambia code per token di accesso e token ID

La risposta include un parametro code, un codice di autorizzazione una tantum che il tuo server può scambiare con un token di accesso e un token ID. Il tuo server effettua questo scambio inviando una richiesta POST HTTPS. La richiesta POST viene inviata all'endpoint del token, che devi recuperare dal documento di rilevamento 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 POST:

Campi
code Il codice di autorizzazione restituito dalla richiesta iniziale.
client_id L'ID client che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
client_secret Il client secret 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 specificato in API Console Credentials page, come descritto in Impostare un URI di reindirizzamento.
grant_type Questo campo deve contenere il valore authorization_code, come definito nella specifica OAuth 2.0.

La richiesta effettiva potrebbe avere l'aspetto 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 contenente informazioni sull'identità dell'utente, firmato digitalmente da Google.
scope Gli ambiti di accesso concessi da access_token espressi come elenco di stringhe sensibili alle maiuscole e delimitate da spazi.
token_type Identifica il tipo di token restituito. Al momento, questo campo presenta sempre il valore Bearer.
refresh_token (facoltativo)

Questo campo è presente solo se il parametro access_type è stato impostato su offline nella richiesta di autenticazione. Per maggiori dettagli, consulta Token di aggiornamento.

5. Ottenere le informazioni sull'utente dal token ID

Un token ID è un JWT (JSON Web Token), ovvero un oggetto JSON firmato crittograficamente con codifica Base64. Normalmente, è fondamentale convalidare un token ID prima di utilizzarlo, ma, poiché comunichi direttamente con Google tramite un canale HTTPS senza intermediari e utilizzi il tuo client secret per autenticarti con Google, puoi avere la certezza che il token che ricevi provenga davvero da Google e sia valido. Se il server passa 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 di analisi del JSON al suo interno, probabilmente finirai comunque per convalidare il token quando accedi alle attestazioni 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 (noti come rivendicazioni):

Claim fornito Descrizione
aud always Il pubblico a cui è destinato questo token ID. Deve essere uno degli ID client OAuth 2.0 della tua applicazione.
exp always Data di scadenza entro la quale il token ID non deve essere accettato. Rappresentato in tempo Unix (secondi interi).
iat always L'ora in cui è stato emesso il token ID. Rappresentato in tempo Unix (secondi interi).
iss always L'identificatore emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token ID Google.
sub always 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. Utilizza sub all'interno dell'applicazione come chiave di identificatore univoco per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole.
at_hash Hash del token di accesso. Fornisce la convalida che il token di accesso sia associato al token di identità. Se il token ID viene emesso con un valore access_token nel flusso del server, questa richiesta è sempre inclusa. Questa attestazione può essere utilizzata come meccanismo alternativo per proteggerti da 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 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 potrebbe verificarsi in Google per le app ibride, dove un'applicazione web e un'app Android hanno un valore OAuth 2.0 client_id diverso ma condividono lo stesso progetto delle API di Google.
email L'indirizzo email dell'utente. Fornito solo se hai incluso l'ambito email nella richiesta. Il valore di questa rivendicazione potrebbe non essere univoco per questo account e potrebbe cambiare nel tempo, pertanto non devi utilizzare questo valore come identificatore principale da collegare al tuo record utente. Inoltre, non è possibile fare affidamento sul dominio della dichiarazione email per identificare gli utenti delle organizzazioni Google Workspace o Cloud; utilizza invece la rivendicazione hd.
email_verified True se l'indirizzo email dell'utente è stato verificato; in caso contrario è falso.
family_name I cognomi o i cognomi dell'utente. Potrebbe essere fornito quando è presente una rivendicazione name.
given_name I nomi o i nomi dell'utente. Potrebbe essere fornito quando è presente una rivendicazione name.
hd Il dominio associato all'organizzazione Google Workspace o Cloud dell'utente. Fornito solo se l'utente appartiene a un'organizzazione Google Cloud. Devi selezionare questa rivendicazione quando limiti l'accesso a una risorsa solo ai membri di determinati domini. L'assenza di questa rivendicazione indica che l'account non appartiene a un dominio ospitato da Google.
locale Le impostazioni internazionali dell'utente, rappresentate da un tag lingua BCP 47. Potrebbe essere fornito quando è presente una dichiarazione name.
name Il nome completo dell'utente, in formato visualizzabile. L'autorizzazione può essere fornita nei seguenti casi:
  • L'ambito della richiesta includeva la stringa "profile"
  • Il token ID viene restituito dall'aggiornamento dei token

Quando sono presenti rivendicazioni di name, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.

nonce Il valore del valore nonce fornito dalla tua app nella richiesta di autenticazione. Dovresti applicare la protezione contro gli attacchi di replay assicurandoti che vengano presentate una sola volta.
picture L'URL dell'immagine del profilo dell'utente. L'autorizzazione può essere fornita nei seguenti casi:
  • L'ambito della richiesta includeva la stringa "profile"
  • Il token ID viene restituito dall'aggiornamento dei token

Quando sono presenti rivendicazioni di picture, puoi utilizzarle per aggiornare i record degli utenti della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.

profile L'URL della pagina del profilo dell'utente. L'autorizzazione può essere fornita nei seguenti casi:
  • L'ambito della richiesta includeva la stringa "profile"
  • Il token ID viene restituito dall'aggiornamento dei token

Quando sono presenti rivendicazioni di profile, puoi utilizzarle per aggiornare i record degli utenti della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.

6. Autenticare l'utente

Dopo aver ottenuto le informazioni sugli utenti dal token ID, devi eseguire una query nel database degli utenti dell'app. Se l'utente esiste già nel 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 database utenti, devi reindirizzarlo 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 almeno potresti essere in grado di precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni nel token ID, puoi ricevere informazioni aggiuntive del profilo utente negli endpoint del nostro 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 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 (ad esempio YouTube, Google Drive, Calendar o Contatti) contemporaneamente all'autenticazione dell'utente. Per farlo, includi gli altri ambiti che ti servono nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere l'età dell'utente alla richiesta di autenticazione, passa un parametro di ambito openid email https://www.googleapis.com/auth/profile.agerange.read. L'utente viene richiesto appropriatamente nella schermata di consenso. Il token di accesso che ricevi da Google ti consente di accedere a tutte le API correlate agli ambiti di accesso che hai richiesto e che ti sono stati concessi.

Token di aggiornamento

Nella richiesta di accesso all'API, puoi richiedere la restituzione di un token di aggiornamento durante lo scambio code. Un token di aggiornamento fornisce alla tua app accesso continuo alle API di Google quando l'utente non è presente nell'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, poiché puoi ottenerlo solo la prima volta che esegui il flusso di scambio del codice.
  • Sono previsti dei 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, potrebbe raggiungere questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.

Per maggiori informazioni, consulta Aggiornare un token di accesso (accesso offline).

Puoi chiedere all'utente di autorizzare nuovamente l'app impostando il parametro prompt su consent nella richiesta di autenticazione. Se prompt=consent è incluso, la schermata di consenso viene visualizzata ogni volta che l'app richiede l'autorizzazione per gli ambiti di accesso, anche se tutti gli ambiti erano stati precedentemente concessi al tuo 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 dell'URI di autenticazione

La seguente tabella fornisce descrizioni più complete dei parametri accettati dall'API di autenticazione OAuth 2.0 di Google.

Parametro Obbligatorio Descrizione
client_id (obbligatorio) La stringa dell'ID client che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
nonce (obbligatorio) Un valore casuale generato dalla tua app che attiva la protezione dalle repliche.
response_type (obbligatorio) Se il valore è code, avvia un flusso del 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'utilizzo di JavaScript all'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 che hai impostato in API Console Credentials page (incluso lo schema HTTP o HTTPS, l'uso di maiuscole/minuscole ed eventuali caratteri "/" finali).
scope (obbligatorio)

Il parametro di ambito deve iniziare con il valore openid e poi includere il valore profile, il valore email o entrambi.

Se è presente il valore dell'ambito profile, il token ID potrebbe (ma non è garantito) includere le rivendicazioni profile predefinite dell'utente.

Se è presente il valore dell'ambito email, il token ID include le rivendicazioni email e email_verified.

Oltre a questi ambiti specifici per OpenID, l'argomento dell'ambito può includere anche altri valori dell'ambito. Tutti i valori dell'ambito devono essere separati da spazi. Ad esempio, se vuoi l'accesso per file al Google Drive di un utente, il parametro di ambito potrebbe essere openid profile email https://www.googleapis.com/auth/drive.file.

Per informazioni sugli ambiti disponibili, consulta Ambiti OAuth 2.0 per le API di Google o la documentazione dell'API di Google che vuoi utilizzare.

state (Facoltativo, ma vivamente consigliato)

Una stringa opaca che viene eseguita di andata e ritorno nel protocollo; vale a dire, viene restituita come parametro URI nel flusso Basic e nell'identificatore #fragment URI nel flusso implicito.

state può essere utile per mettere in correlazione richieste e risposte. Poiché il valore redirect_uri può essere intuito, l'utilizzo di un valore state può aumentare la certezza che una connessione in entrata sia il risultato di una richiesta di autenticazione avviata dalla tua app. Se generi una stringa casuale o codifichi l'hash di un determinato stato client (ad esempio un cookie) in questa variabile state, puoi convalidare la risposta per assicurarti inoltre che la richiesta e la risposta abbiano avuto origine nello stesso browser. Ciò fornisce protezione da attacchi come la falsificazione di richieste tra siti.

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 di stringa ASCII per specificare in che modo il server di autorizzazione 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 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'interfaccia utente per la selezione degli account deve essere ottimizzata per gli account in quel dominio. Per eseguire l'ottimizzazione in base agli account dell'organizzazione Google Cloud in generale anziché a un solo dominio dell'organizzazione Google Cloud, imposta il valore di un asterisco (*): hd=*.

Non fare affidamento su questa ottimizzazione dell'interfaccia utente per controllare chi può accedere alla tua app, perché le richieste lato client possono essere modificate. Assicurati di validate che il token ID restituito abbia un valore di rivendicazione hd corrispondente a quello previsto (ad es. mycolledge.edu). A differenza del parametro di richiesta, la rivendicazione del token ID hd è contenuta in un token di sicurezza di Google, pertanto il valore è attendibile.

include_granted_scopes (Facoltativo) Se a questo parametro viene fornito il valore true e la richiesta di autorizzazione viene approvata, l'autorizzazione includerà tutte le autorizzazioni precedenti concesse a questa combinazione utente/applicazione per altri ambiti; consulta Autorizzazione incrementale.

Tieni presente che non puoi eseguire l'autorizzazione incrementale con il flusso App installata.

login_hint (Facoltativo) Quando l'app sa quale utente sta tentando di eseguire l'autenticazione, può fornire questo parametro come suggerimento al server di autenticazione. Se passi questo suggerimento, il selettore account viene eliminato e precompilato la casella email del modulo di accesso oppure viene selezionata la sessione corretta (se l'utente utilizza l'accesso simultaneo), il che può aiutarti a evitare problemi che si verificano se la tua app accede all'account utente errato. Il valore può essere un indirizzo email o la stringa sub, che equivale all'ID Google dell'utente.
prompt (Facoltativo) Un elenco di valori stringa delimitato da spazi che specifica se il server di autorizzazione richiede all'utente una nuova autenticazione e il consenso. I valori possibili sono:
  • none

    Il server di autorizzazione non mostra alcuna schermata di autenticazione o di consenso degli utenti; restituirà un errore se l'utente non è già stato autenticato e non ha preconfigurato il consenso per gli ambiti richiesti. Puoi utilizzare none per verificare l'autenticazione e/o il consenso esistenti.

  • consent

    Il server di autorizzazione richiede all'utente il consenso prima di restituire le informazioni al client.

  • select_account

    Il server di autorizzazione chiede all'utente di selezionare un account utente. Ciò consente a un utente che dispone di più account sul server di autorizzazione di selezionare tra i vari account per cui potrebbe avere sessioni in corso.

Se non viene specificato alcun valore e l'utente non ha precedentemente autorizzato l'accesso, all'utente 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 abbia la certezza che provengono direttamente da Google. Ad esempio, il server deve verificare l'autenticità di tutti i token ID che riceve dalle app client.

Di seguito sono riportate le situazioni più 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 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 vengono 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 anche archiviarli in modo sicuro.

Una cosa che rende utili i token ID è il fatto che puoi trasferirli tra diversi componenti dell'app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione leggero per l'autenticazione dell'app e dell'utente. Tuttavia, prima di poter utilizzare le informazioni nel token ID o considerarle come un'asserzione dell'autenticazione dell'utente, devi convalidarle.

La convalida di un token ID richiede diversi passaggi:

  1. Verifica che il token ID sia firmato correttamente dall'emittente. I token emessi da Google sono firmati utilizzando uno dei certificati presenti all'URI specificato nel valore dei metadati jwks_uri del documento di rilevamento.
  2. Verifica che il valore dell'attestazione iss nel token ID sia uguale a https://accounts.google.com o accounts.google.com.
  3. Verifica che il valore dell'attestazione aud nel token ID corrisponda all'ID client della tua app.
  4. Verifica che la scadenza (exp rivendicazione) del token ID non sia trascorsa.
  5. Se hai specificato un valore del parametro hd 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 solo confronti di stringhe e date che sono piuttosto semplici, quindi non li analizzeremo 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 il confronto 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 di oggetto JSON decodificato.

L'endpoint tokeninfo è utile per il debug, ma per scopi di produzione, recupera le chiavi pubbliche di Google dall'endpoint delle chiavi 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 potrebbero essere limitate o essere comunque soggette a errori intermittenti.

Poiché Google modifica le sue chiavi pubbliche solo raramente, puoi memorizzarle nella cache utilizzando le istruzioni di cache della risposta HTTP e, nella maggior parte 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, nonché l'esecuzione delle chiamate crittografiche appropriate per verificare la firma. Fortunatamente, a questo scopo, sono disponibili librerie con un buon debug in un'ampia varietà di linguaggi (vedi jwt.io).

Recupero delle informazioni del profilo utente

Per ottenere informazioni aggiuntive del profilo dell'utente, puoi utilizzare il token di accesso (che l'applicazione riceve durante il flusso di autenticazione) e lo standard OpenID Connect:

  1. Per garantire la conformità a OpenID, devi includere i valori dell'ambito openid profile nella richiesta di autenticazione.

    Se vuoi che l'indirizzo email dell'utente sia incluso, puoi specificare un valore di ambito aggiuntivo pari a email. Per specificare sia profile sia email, puoi includere il seguente parametro nell'URI della richiesta di autenticazione:

    scope=openid%20profile%20email
  2. Aggiungi il token di accesso all'intestazione di autorizzazione ed effettua una richiesta GET HTTPS all'endpoint userinfo, che devi recuperare dal documento di rilevamento utilizzando il valore dei metadati userinfo_endpoint. La risposta info utente include informazioni sull'utente, come descritto in OpenID Connect Standard Claims e il valore dei metadati claims_supported del documento di rilevamento. Gli utenti o le loro organizzazioni possono scegliere di fornire o trattenere determinati campi, pertanto potresti non ricevere informazioni per ogni campo relativo agli ambiti di accesso autorizzati.

Il documento Rilevamento

Il protocollo OpenID Connect richiede l'utilizzo di più endpoint per l'autenticazione degli utenti e per la richiesta di risorse, inclusi token, informazioni utente e chiavi pubbliche.

Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente l'utilizzo di un "documento di rilevamento", 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 dell'autorizzazione, del token, della revoca, delle informazioni utente e degli endpoint delle chiavi pubbliche. 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 codificare in forma rigida l'URI del documento di rilevamento (https://accounts.google.com/.well-known/openid-configuration) nell'applicazione. L'applicazione recupera il documento, applica regole di memorizzazione nella cache nella risposta, quindi recupera gli URI dell'endpoint da questo in base alle esigenze. Ad esempio, per autenticare un utente, il codice recupererà il valore dei metadati authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth nell'esempio seguente) come URI di base per le richieste di autenticazione inviate a Google.

Ecco un esempio di documento di questo tipo; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fai riferimento al documento per conoscere il loro significato). I valori sono puramente illustrativi e potrebbero cambiare, anche se sono stati copiati da una versione recente del documento Google Discovery effettivo:

{
  "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"
  ]
}

Puoi evitare un round trip HTTP memorizzando nella cache i valori dal documento di rilevamento. Vengono utilizzate intestazioni di memorizzazione nella cache HTTP standard e devono essere rispettate.

Librerie client

Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 grazie all'integrazione con i framework più diffusi:

Conformità a 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 (ad eccezione dell'oggetto di richiesta OpenID).