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 di OAuth 2.0 per l'autenticazione, che è conforme alla specifica OpenID Connect e ha la certificazione OpenID. La documentazione disponibile in Utilizzare OAuth 2.0 per accedere alle API di Google si applica anche a questo servizio. Se vuoi esplorare questo protocollo in modo interattivo, ti consigliamo di utilizzare Google OAuth 2.0 Playground. Per ricevere assistenza su Stack Overflow, aggiungi il tag "google-oauth" alle tue domande.

Nota: per fornire un pulsante "Accedi con Google" per il tuo sito web, utilizza i Servizi di identità Google, la nostra libreria client di accesso basata sul protocollo OpenID Connect. Questa libreria fornisce token ID formattati OpenID Connect. Le app per Android devono utilizzare l'API Credential Manager per implementare il flusso di Accedi con Google.

Configurazione di OAuth 2.0

Prima che la tua applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso degli utenti, devi configurare un progetto nella console Google Cloud 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 la console Cloud per creare un service account, attivare la fatturazione, configurare i filtri e svolgere altre attività. Per maggiori dettagli, consulta la guida della console Google Cloud.

Ottieni le credenziali OAuth 2.0

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

Per visualizzare l'ID client e il client secret di una determinata credenziale OAuth 2.0, fai clic sul seguente testo: Seleziona credenziale. Nella finestra che si apre, scegli il progetto e la credenziale che ti interessa, quindi fai clic su Visualizza.

In alternativa, visualizza l'ID client e il client secret dalla pagina Clienti nella console Cloud:

1. Vai alla pagina Clienti.
2. Fai clic sul nome del cliente o sull'icona di modifica (). L'ID client e il secret si trovano nella parte superiore della pagina.

Imposta un URI di reindirizzamento

L'URI di reindirizzamento impostato nella console Cloud 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, segui questi passaggi:

1. Vai alla pagina Clienti.
2. Fai clic sul cliente.
3. Visualizza o modifica gli URI di reindirizzamento.

Se nella pagina Client non è presente alcun client, il tuo progetto non ha credenziali OAuth. Per crearne uno, fai clic su Crea client.

Personalizza la schermata per il consenso dell'utente

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

La schermata per il consenso dell'utente presenta anche informazioni sul brand, come il nome del prodotto, il logo e l'URL della home page. Puoi controllare le informazioni di branding nella console Cloud.

Per attivare la schermata per il consenso del progetto:

1. Apri la pagina Branding nella console Google Cloud.
2. Se richiesto, seleziona un progetto o creane uno nuovo.
3. Compila il modulo e fai clic su Salva.

La seguente finestra di dialogo per il consenso mostra ciò che un utente vedrebbe 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 le informazioni di branding che verrebbero impostate nella console Cloud.)

Figura 1. Screenshot della pagina del consenso

Accedi al servizio

Google e terze parti forniscono librerie che puoi utilizzare per gestire molti dei dettagli di implementazione dell'autenticazione degli utenti e dell'accesso alle API di Google. Gli esempi includono i Servizi di identità Google e le librerie client di Google, disponibili per una serie di piattaforme.

Nota: date le implicazioni di sicurezza per ottenere l'implementazione corretta, ti consigliamo vivamente di utilizzare una libreria o un servizio pre-scritti. L'autenticazione corretta degli utenti è importante per la loro e la tua sicurezza e l'utilizzo di codice ben sottoposto a debug scritto da altri è generalmente una best practice. Per saperne di più, consulta Librerie client.

Se scegli di non utilizzare una libreria, segui le istruzioni riportate nel resto di questo documento, che descrive i flussi di richieste HTTP alla base delle librerie disponibili.

Autenticazione dell'utente

L'autenticazione dell'utente prevede l'ottenimento di un token ID e la sua convalida. I token ID sono una funzionalità standardizzata di OpenID Connect progettata per l'utilizzo nella condivisione di asserzioni di identità su internet.

Gli approcci di uso comune per autenticare un utente e ottenere un token ID sono chiamati flusso "server" e flusso "implicito". Il flusso del server consente al server di backend di un'applicazione di verificare l'identità della persona che utilizza 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é utilizzare il proprio server di backend.

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 Servizi di identità Google.

Flusso del server

Assicurati di configurare la tua app nella console Cloud per consentirle di utilizzare questi protocolli e autenticare gli utenti. Quando un utente tenta di accedere con Google, devi:

1. Crea un token di stato anti-falsificazione
2. Invia una richiesta di autenticazione a Google
3. Conferma il token di stato anti-falsificazione
4. Scambia code con il token di accesso e il token ID
5. Ottieni le informazioni utente dal token ID
6. Autentica l'utente

1. Crea un token di stato anti-forgery

Devi proteggere la sicurezza dei tuoi utenti impedendo gli attacchi di falsificazione delle richieste. Il primo passaggio consiste nel creare un token di sessione univoco che mantiene lo stato tra la tua app e il client dell'utente. In seguito, 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 utente malintenzionato. Questi token vengono spesso definiti token di richiesta cross-site (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 delle variabili di stato della sessione con una chiave che viene mantenuta segreta nel backend.

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

Il passaggio successivo consiste nel formare una richiesta HTTPS GET con i parametri URI appropriati. Tieni presente l'utilizzo di HTTPS anziché HTTP in tutti i passaggi di questa procedura; le connessioni HTTP vengono rifiutate. Devi recuperare l'URI di base dal documento di rilevamento utilizzando il valore dei metadati authorization_endpoint. La discussione seguente 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 ottieni dalla pagina Client della console Cloud.
• response_type, che in una richiesta di flusso del codice di autorizzazione di base deve essere code. (Scopri di più all'indirizzo response_type.)
• scope, che in una richiesta di base deve 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 nella pagina Credenziali della console Cloud. 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 anti-contraffazione, nonché qualsiasi altra informazione necessaria per recuperare il contesto quando l'utente torna alla tua applicazione, ad esempio l'URL di partenza. (Scopri di più all'indirizzo state.)
• nonce è un valore casuale generato dalla tua app che attiva la protezione da replay, 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 per il consenso include una richiesta di approvazione per il rilascio dell'indirizzo email dell'utente alla 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ù su hd).
Nota: questi sono alcuni dei parametri di uso comune. Per un elenco completo e ulteriori dettagli su tutti i parametri, consulta Parametri URI di autenticazione.

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//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Gli utenti devono dare il consenso se la tua app richiede nuove informazioni su di loro o se richiede l'accesso all'account che non hanno approvato in precedenza.

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:

https://developers.google.com/oauthplayground?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

In base alla RFC 6749, i client DEVONO ignorare i parametri di risposta non riconosciuti. 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 verificare che la richiesta venga effettuata dall'utente e non da uno script dannoso.

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

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. Scambia code con il token di accesso e il 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 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 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 dalla pagina Client della console Cloud, come descritto in Ottieni le credenziali OAuth 2.0.
client_secret	Il client secret che ottieni dalla pagina Client della console Cloud, come descritto in Ottieni le credenziali OAuth 2.0.
redirect_uri	Un URI di reindirizzamento autorizzato per il client_id specificato nella pagina Client della console Cloud, come descritto in Imposta 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 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//developers.google.com/oauthplayground&
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 firmate digitalmente da Google.
scope	Gli ambiti di accesso concessi da access_token espressi come un elenco di stringhe sensibili alle maiuscole delimitate da spazi.
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 access_type è stato impostato su offline nella richiesta di autenticazione. Per maggiori dettagli, vedi Token di aggiornamento.

Nota: esiste un limite al numero di token per account utente Google e qualsiasi richiesta di autenticazione che superi questo limite potrebbe invalidare silenziosamente un token di aggiornamento in sospeso. Per maggiori dettagli, consulta Scadenza dei token.

5. Ottieni le informazioni utente dal token ID

Un token ID è un JWT (JSON Web Token), ovvero un oggetto JSON con codifica Base64 con firma crittografica. In genere, è 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 su Google, puoi avere la certezza che il token che ricevi provenga effettivamente da Google e sia valido. Se il tuo server passa il token ID ad altri componenti della tua app, è estremamente importante che questi 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 comunque il token quando accedi alle rivendicazioni 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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Avviso: quando implementi il tuo sistema di gestione degli account, non devi utilizzare il campo email nel token ID come identificatore univoco per un utente. Utilizza sempre il campo sub, poiché è univoco per un Account Google, anche se l'utente modifica il proprio indirizzo email.

I token ID Google possono contenere i seguenti campi (noti come claim):

Rivendica	Fornito da Google	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	La data e l'ora di scadenza dopo le quali il token ID non deve essere accettato. Rappresentato in tempo Unix epoch (secondi interi).
iat	sempre	L'ora di emissione del token ID. Rappresentato nell'epoca di Unix (secondi 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 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 cambia mai. Utilizza sub all'interno della tua applicazione come chiave dell'identificatore univoco per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole.
amr		Un array JSON di stringhe che identificano i metodi di autenticazione utilizzati per accedere a un Account Google. Se presente, include uno o più di questi possibili valori [IANA.AMR]: hwk è stata utilizzata una chiave hardware mfa L'autenticazione a più fattori è stata completata pwd è stata utilizzata una password sms è stato utilizzato un SMS per la verifica È stata utilizzata una chiave software come una passkey (swk) tel è stata utilizzata una telefonata per la verifica Presente solo quando l'attestazione amr è inclusa nella richiesta di autenticazione e abilitata nelle impostazioni.
auth_time		L'ora in cui è avvenuta l'autenticazione dell'utente, un numero JSON che rappresenta il numero di secondi trascorsi dall'epoca di Unix (1° gennaio 1970, 00:00:00 UTC). Fornito quando la rivendicazione auth_time è inclusa nella richiesta di autenticazione e abilitata nelle impostazioni.
at_hash		Hash del token di accesso. Fornisce 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 attestazione è sempre inclusa. Questa attestazione può essere utilizzata come meccanismo alternativo per proteggersi dagli attacchi di tipo cross-site request forgery, 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 potrebbe essere il caso di Google per le app ibride in cui un'applicazione web e un'app per Android hanno un client_id OAuth 2.0 diverso, ma condividono lo stesso progetto API di Google.
email		L'indirizzo email dell'utente. Fornito solo se hai incluso l'ambito email nella richiesta. Il valore di questa attestazione potrebbe non essere univoco per questo account e potrebbe cambiare nel tempo, pertanto non devi utilizzarlo come identificatore principale per il collegamento al tuo record utente. Inoltre, non puoi fare affidamento sul dominio della rivendicazione email per identificare gli utenti delle organizzazioni Google Workspace o Cloud; utilizza invece la rivendicazione hd. Avviso: non utilizzare il campo email come identificatore univoco per un utente. Utilizza sempre il campo sub.
email_verified		True se l'indirizzo email dell'utente è stato verificato; in caso contrario, false.
family_name		Il cognome o i cognomi dell'utente. Potrebbe essere fornito quando è presente una rivendicazione name.
given_name		Il nome o i nomi dell'utente. Potrebbe essere fornito quando è presente una rivendicazione name.
hd		Il dominio associato all'organizzazione Google Workspace o Google Cloud dell'utente. Fornito solo se l'utente appartiene a un'organizzazione Google Cloud. Devi controllare questa richiesta quando limiti l'accesso a una risorsa solo ai membri di determinati domini. L'assenza di questa attestazione indica che l'account non appartiene a un dominio ospitato da Google.
locale		Le impostazioni internazionali dell'utente, rappresentate da un tag di lingua BCP 47. Potrebbe essere fornito quando è presente una rivendicazione name.
name		Il nome completo dell'utente, in un formato visualizzabile. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti attestazioni name, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantita la presenza di questa attestazione.
nonce		Il valore di nonce fornito dalla tua app nella richiesta di autenticazione. Devi proteggerti dagli attacchi di replay presentando questo valore una sola volta.
picture		L'URL dell'immagine del profilo dell'utente. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni picture, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantita la presenza di questa attestazione.
profile		L'URL della pagina del profilo dell'utente. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni profile, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantita la presenza di questa attestazione.

6. Autentica l'utente

Dopo aver ottenuto le informazioni dell'utente dal token ID, devi eseguire una query sul database degli utenti 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 per i nuovi utenti. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni che ricevi da Google o, almeno, di precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni contenute nel token ID, puoi ottenere ulteriori informazioni sul profilo utente nei nostri endpoint del profilo utente.

Argomenti avanzati

Le sezioni seguenti descrivono l'API Google OAuth 2.0 in maggiore dettaglio. Queste informazioni sono rivolte 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 (ad esempio YouTube, Google Drive, Calendar o Contatti) contemporaneamente all'autenticazione dell'utente. Per farlo, includi gli altri ambiti necessari 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 openid email https://www.googleapis.com/auth/profile.agerange.read. All'utente viene chiesto di fornire il consenso in modo appropriato nella schermata per il consenso. Il token di accesso che ricevi da Google consentirà alla tua applicazione di accedere a tutte le API relative agli ambiti di accesso richiesti e concessi.

Nota: se la tua applicazione richiede molti ambiti, la schermata per il consenso contiene molte righe di testo. Più ambiti richiede la tua applicazione, meno è probabile che l'utente acconsenta, quindi la tua applicazione deve richiedere solo gli ambiti di cui ha bisogno.

Token di aggiornamento

Nella 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 l'accesso continuo alle API di Google quando l'utente non è presente nella tua applicazione. Per richiedere un token di aggiornamento, aggiungi il parametro access_type impostandolo su offline nella tua richiesta di autenticazione.

Considerazioni:

• Assicurati di archiviare il token di aggiornamento in modo sicuro e permanente, perché puoi ottenerlo 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, potrebbe raggiungere questi limiti, nel qual caso i token di aggiornamento meno recenti smettono di funzionare.

Per saperne di più, consulta Aggiornamento di un token di accesso (accesso offline).

Richiesta di un nuovo consenso

Puoi chiedere all'utente di autorizzare nuovamente la tua app impostando il parametro prompt su consent nella richiesta di autenticazione. Quando è incluso prompt=consent, la schermata per il consenso viene visualizzata ogni volta che l'app richiede l'autorizzazione degli ambiti di accesso, anche se tutti gli ambiti sono stati precedentemente concessi al progetto API di Google. Per questo motivo, includi prompt=consent solo se necessario.

Per saperne di più sul parametro prompt, consulta prompt nella tabella Parametri URI di autenticazione.

Parametri 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 dalla pagina Client della console Cloud, come descritto in Ottieni le credenziali OAuth 2.0.
nonce	(Obbligatorio)	Un valore casuale generato dalla tua app che attiva la protezione dai replay.
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 nell'URI di reindirizzamento per recuperare i token dall'identificatore #fragment dell'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 nella pagina Client della console Cloud (inclusi lo schema HTTP o HTTPS, le maiuscole e le minuscole e il carattere "/" finale, se presente).
scope	(Obbligatorio)	Il parametro scope 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 di OpenID, l'argomento scope può includere anche altri valori di ambito. Tutti i valori degli ambiti devono essere separati da spazi. Ad esempio, se vuoi l'accesso per file a 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 relativa all'API di Google che vuoi utilizzare.
state	(Facoltativo, ma vivamente consigliato)	Una stringa opaca che viene restituita nel protocollo, ovvero come parametro URI nel flusso di base e nell'identificatore URI #fragment nel flusso implicito. state può essere utile per correlare richieste e risposte. Poiché il tuo redirect_uri può essere indovinato, 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 uno stato del client (ad esempio un cookie) in questa variabile state, puoi convalidare la risposta per verificare che la richiesta e la risposta provengano dallo stesso browser. In questo modo, viene fornita protezione contro attacchi come la falsificazione di richiesta cross-site.
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 di offline.
claims	(Facoltativo)	Il parametro claims viene utilizzato per specificare uno o più campi facoltativi da includere nei tipi di risposta dell'endpoint userinfo o del token ID della richiesta di autenticazione. Il valore è un oggetto JSON contenente il tipo di risposta e le rivendicazioni richieste. Le seguenti richieste di rivendicazione sono accettate dai server di Google: Richieste di rivendicazione amr Richiedi il metodo utilizzato per l'ultima autenticazione dell'utente. Per restituire amr come campo nella risposta del token ID, includi il parametro di richiesta claims: claims={"id_token":{"amr":{"essential":true}}} Deve essere attivato nelle impostazioni. auth_time Richiedi l'ora dell'ultima autenticazione dell'utente. Per restituire auth_time come campo nella risposta del token ID, includi il parametro di richiesta claims: claims={"id_token":{"auth_time":{"essential":true}}} Deve essere attivato nelle impostazioni.
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 comportamento del flusso del protocollo: 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 la UI di selezione dell'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 un valore con un asterisco (*): hd=*. 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. Assicurati di convalidare che il token ID restituito abbia un valore della rivendicazione hd corrispondente a quello previsto (ad es. mycolledge.edu). A differenza del parametro della richiesta, la rivendicazione hd del token ID è contenuta in un token di sicurezza di Google, pertanto il valore può essere considerato attendibile.
include_granted_scopes	(Facoltativo)	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 di utente/applicazione per altri ambiti; consulta Autorizzazione incrementale. Tieni presente che non puoi eseguire l'autorizzazione incrementale con il flusso dell'app installata.
login_hint	(Facoltativo)	Quando l'app sa quale utente sta tentando di autenticare, può fornire questo parametro come suggerimento al server di autenticazione. Se passi questo suggerimento, il selettore dell'account viene soppresso e il campo dell'indirizzo email nel modulo di accesso viene precompilato oppure viene selezionata la sessione corretta (se l'utente utilizza l'accesso simultaneo), il che può aiutarti a evitare i problemi che si verificano se la tua app accede all'account utente sbagliato. Il valore può essere un indirizzo email o la stringa sub, che equivale all'ID Google dell'utente.
prompt	(Facoltativo)	Un elenco di valori di stringa delimitati da spazi che specifica se il server di autorizzazione richiede all'utente di eseguire nuovamente l'autenticazione e di fornire il consenso. I valori possibili sono: none Il server di autorizzazione non visualizza schermate di autenticazione o di consenso dell'utente; restituirà un errore se l'utente non è già 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 chiede 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. In questo modo, un utente che ha più account sul server di autorizzazione può selezionare tra i vari account quelli per cui potrebbe avere sessioni correnti. Se non viene specificato alcun valore e l'utente non ha autorizzato l'accesso in precedenza, viene visualizzata una schermata per il consenso.
hl	(Facoltativo)	Un tag di lingua BCP 47 utilizzato per specificare la lingua di visualizzazione per le schermate di accesso, di selezione dell'account e per la schermata per il consenso. Se questo parametro non viene fornito, la lingua predefinita è quella dell'Account Google o delle impostazioni del browser dell'utente. Ad esempio, per richiedere la UI in inglese britannico, imposta il parametro su en-GB.

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 l'autenticità di tutti i token ID che riceve dalle tue 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 specifico che effettua la richiesta e il client per cui è 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 utilizzando solo dati POST o all'interno delle intestazioni delle richieste. Se memorizzi i token ID sul tuo server, devi farlo in modo sicuro.

Un aspetto che rende utili i token ID è il fatto che puoi passarli tra i diversi componenti della tua app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione leggero per autenticare l'app e l'utente. Tuttavia, prima di poter utilizzare le informazioni nel token ID o fare affidamento su di esse come conferma 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 vengono firmati utilizzando uno dei certificati presenti nell'URI specificato nel valore dei metadati jwks_uri del documento di rilevamento.
2. Verifica che il valore della dichiarazione iss nel token ID sia uguale a https://accounts.google.com o accounts.google.com.
3. Verifica che il valore della dichiarazione aud nel token ID sia uguale all'ID client della tua app.
4. Verifica che la data di scadenza (claim exp) del token ID non sia trascorsa.
5. Se nella richiesta hai specificato un valore per il parametro hd, verifica che il token ID abbia un claim hd corrispondente 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 descriveremo in dettaglio qui.

Il primo passaggio è più complesso e prevede il controllo della firma crittografica. Per il 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. Quindi, devi dereferenziare l'URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Se la firma del token è valida, la risposta sarà il payload JWT nella forma di oggetto JSON decodificato.

L'endpoint tokeninfo è utile per il debug, ma per scopi di produzione, recupera le chiavi pubbliche di Google dall'endpoint keys ed esegui la convalida localmente. 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 soggette a errori intermittenti.

Poiché Google modifica le sue chiavi pubbliche solo di rado, puoi memorizzarle nella cache utilizzando le istruzioni di memorizzazione nella 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, nonché l'esecuzione delle chiamate crittografiche appropriate per controllare la firma. Fortunatamente, per farlo sono disponibili librerie ben sottoposte a debug in un'ampia varietà di linguaggi (vedi jwt.io).

Ottenere informazioni sul profilo utente

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

1. Per essere conforme a OpenID, devi includere i valori di ambito openid profile nella richiesta di autenticazione.

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

   scope=openid%20profile%20email

2. Aggiungi il token di accesso all'intestazione dell'autorizzazione ed effettua una richiesta HTTPS GET all'endpoint userinfo, che devi recuperare dal documento di discovery utilizzando il valore dei metadati userinfo_endpoint. La risposta userinfo 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 meno determinati campi, pertanto potresti non ricevere informazioni per ogni campo per gli 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 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 degli endpoint di autorizzazione, token, revoca, informazioni utente e 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 impostare l'URI del documento Discovery (https://accounts.google.com/.well-known/openid-configuration) come hardcoded nella tua applicazione. La tua applicazione recupera il documento, applica le regole di memorizzazione nella cache nella risposta, quindi recupera gli URI degli endpoint in base alle necessità. Ad esempio, per autenticare un utente, il codice recupera 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 questo documento; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (consulta il documento per i relativi significati). I valori sono puramente illustrativi e potrebbero cambiare, anche se sono 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"
  ]
}

Potresti evitare un round trip HTTP memorizzando nella cache i valori del documento di rilevamento. Vengono utilizzate le intestazioni di memorizzazione nella cache HTTP standard, che devono essere rispettate.

Librerie client

Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 grazie all'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
• Google Toolbox for Mac OAuth 2.0 Controllers

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 dovrebbe interagire con questo servizio (ad eccezione dell'oggetto richiesta OpenID).