OpenID Connect

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 ed è certificata OpenID. La documentazione disponibile anche 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".

Nota: se vuoi fornire un pulsante "Accedi con Google" per il tuo sito web o la tua app, ti consigliamo di utilizzare i servizi di identità Google, la nostra libreria client di accesso basata sul protocollo OpenID Connect e che fornisce i token ID formattati OpenID Connect.

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 di Google 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.

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 :

1. Go to the Credentials page.
2. Fai clic sul nome della tua credenziale o sull'icona a forma di matita ( ). L'ID cliente e il segreto sono nella parte superiore della pagina.

Imposta un URI di reindirizzamento

L'URI di reindirizzamento che hai impostato in API Console determina dove Google invia 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 degli utenti

Per gli utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata per il consenso che descrive le informazioni rilasciate dall'utente e i termini che si applicano. Ad esempio, quando l'utente accede, potrebbe essere chiesto all'app di accedere al suo indirizzo email e alle informazioni di base del suo account. Puoi richiedere l'accesso a queste informazioni utilizzando il parametro scope, che la tua app include nella sua richiesta di autenticazione. Puoi inoltre utilizzare gli ambiti per richiedere l'accesso ad altre API di Google.

La schermata per il consenso degli utenti presenta anche informazioni di branding come il nome del prodotto, il logo e l'URL della home page. Puoi controllare le informazioni sul 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 vedrà un utente quando nella richiesta è presente una combinazione di ambiti OAuth 2.0 e Google Drive. Questa finestra di dialogo generica è stata generata utilizzando Google OAuth 2.0 Playground, quindi non include informazioni di branding che verrebbero impostate in API Console.

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 diverse piattaforme.

Nota: date le implicazioni relative alla sicurezza per ottenere un'implementazione corretta, ti consigliamo vivamente di usufruire di una libreria o un servizio precompilati. autenticare correttamente gli utenti è importante per la loro sicurezza e per la tua sicurezza; inoltre, l'utilizzo di codice ben debug scritto da altri è in genere una best practice. Per saperne di più, consulta Librerie client.

Se scegli di non utilizzare una libreria, segui le istruzioni nella parte restante di questo documento, che descrive i flussi di richiesta HTTP che sono alla base delle librerie disponibili.

Autenticazione dell'utente

Per autenticare l'utente è necessario ottenere un token ID e convalidarlo. I token ID sono una funzionalità standardizzata di OpenID Connect, progettata per essere utilizzata nella condivisione di asserzioni di identità su Internet.

Gli approcci più comunemente utilizzati per autenticare un utente e ottenere un token ID sono chiamati flusso "server" e flusso "implicit". Il flusso del server consente al server back-end di un'applicazione di verificare l'identità della persona tramite 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 invece che 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 lato client. Se devi implementare un flusso implicito, ti consigliamo vivamente di utilizzare i servizi di identità Google.

Flusso del server

Assicurati di configurare la tua app in API Console in modo da abilitare questi protocolli e autenticare gli utenti. Quando un utente tenta di accedere con Google, devi:

1. Creare un token di stato per la contraffazione
2. Inviare una richiesta di autenticazione a Google
3. Conferma il token di stato della contraffazione
4. Exchange code per token di accesso e token ID
5. Ottenere informazioni sull'utente dal token ID
6. Autenticare l'utente

1. Crea un token di stato per la contraffazione

Devi proteggere la sicurezza degli utenti evitando attacchi di falsificazione. Il primo passaggio consiste nel creare un token di sessione univoco che tenga uno stato tra la tua app e il client dell'utente. Successivamente, assumi questo token di sessione univoco con la 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 dannoso. Questi token sono spesso denominati token di richiesta di falsificazione 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 mantenuta segreta nel backend.

Il seguente codice dimostra che sono stati generati token di sessione unici.

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 creare una richiesta GET di 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 ottieni dall' API Console Credentials page.
• response_type, che in una richiesta di flusso di 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 dovrebbe essere l'endpoint HTTP sul 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 nel API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, la richiesta avrà esito negativo con un errore redirect_uri_mismatch.
• state dovrebbe includere il valore del token di sessione univoco anti-falso, 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 attiva la protezione della riproduzione, se presente.
• login_hint può corrispondere all'indirizzo email dell'utente o alla 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 rilasciare l'indirizzo email dell'utente nella tua app. Leggi ulteriori informazioni 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 Cloud. Scopri di più all'indirizzo hd.

Nota: sopra sono elencati solo i parametri di uso comune. Per un elenco completo, oltre a ulteriori dettagli su tutti i parametri, consulta la pagina relativa ai 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//oauth2.example.com/code&
 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 fornire il consenso se la tua app richiede nuove informazioni in merito o se richiede l'accesso all'account che non hanno precedentemente approvato.

3. Conferma token di stato relativo a falsificazione

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 valore state ricevuto da Google corrisponda al token di sessione creato nel passaggio 1. Questa verifica di andata e ritorno aiuta a garantire che l'utente, non uno script dannoso, stia effettuando la richiesta.

Il codice seguente 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. Scambia code con token di accesso e token ID

La risposta include un parametro code, un codice di autorizzazione una tantum che il 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 di POST:

Campi
code	Il codice di autorizzazione restituito dalla richiesta iniziale.
client_id	L'ID client ottenuto dalla API Console Credentials page, come descritto nella sezione Ottenere le credenziali OAuth 2.0.
client_secret	Il client secret che ottieni dal API Console Credentials page, come descritto nella sezione Ottenere le credenziali OAuth 2.0.
redirect_uri	Un URI di reindirizzamento autorizzato per il client_id specificato in Credentials page API Console, come descritto nella sezione 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 avere il seguente esempio:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Una risposta corretta a questa richiesta contiene i seguenti campi in un array JSON:

Campi
access_token	Un token che può essere inviato a un'API Google.
expires_in	Durata rimanente del token di accesso, in secondi.
id_token	Un JWT che contiene informazioni sull'identità dell'utente firmate da Google in formato digitale.
scope	Gli ambiti di accesso concessi da access_token espressi come elenco di stringhe delimitati da maiuscole e minuscole.
token_type	Identifica il tipo di token restituito. Al momento, questo campo contiene 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 l'articolo Aggiornare i token.

Nota: è previsto un limite per il numero di token per account utente Google; qualsiasi richiesta di autenticazione al di sopra di questo limite potrebbe invalidare tranquillamente un token di aggiornamento in sospeso. Per maggiori dettagli, consulta la pagina Scadenza del token.

5. Ottenere informazioni sull'utente dal token ID

Un token ID è un token web JSON (JSON Web Token), ovvero un oggetto JSON con codifica Base64 firmato crittograficamente. In genere, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché stai comunicando direttamente con Google tramite un canale HTTPS privo di intermediario e utilizzando il tuo client secret per autenticarti a Google, puoi avere la certezza che il token che ricevi proviene davvero da Google ed è valido. Se il server trasmette il token ID ad altri componenti della tua app, è estremamente importante che gli altri componenti convalidino il token prima di utilizzarlo.

Poiché la maggior parte delle librerie API combina la convalida con il lavoro di decodifica dei valori con codifica base64url e di analisi del JSON, probabilmente finirai comunque per convalidare 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"
}

I token ID Google possono contenere i seguenti campi (chiamati rivendicazioni):

Rivendicazione	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 e ora di scadenza a partire dal quale il token ID non deve essere accettato. Rappresentato in tempo Unix (numero intero).
iat	always	L'ora in cui è stato emesso il token ID. Rappresentato in tempo Unix (numero intero).
iss	always	L'identificatore dell'emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token dell'ID Google.
sub	always	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 con distinzione tra maiuscole e minuscole.
at_hash		Accedi all'hash del token. 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 rivendicazione è sempre inclusa. Questa rivendicazione può essere utilizzata come meccanismo alternativo per proteggersi dagli attacchi di falsificazione di più siti; tuttavia, 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 è uguale al pubblico del token ID. Questo potrebbe 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 questo utente e non è adatto per essere utilizzato come chiave primaria. Indicato solo se il tuo ambito includeva il valore dell'ambito email.
email_verified		True se l'indirizzo email dell'utente è stato verificato, altrimenti è false.
family_name		Il cognome o i cognomi dell'utente. Potrebbe essere fornito quando è presente una rivendicazione di name.
given_name		I nomi o i nomi specificati dell'utente. Potrebbe essere fornito quando è presente una rivendicazione di name.
hd		Il dominio associato all'organizzazione Google Cloud dell'utente. Indicato 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. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Se sono presenti rivendicazioni 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 riproduzione assicurandoti che venga presentata 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 Se sono presenti rivendicazioni picture, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.
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 Se sono presenti rivendicazioni profile, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.

6. Autenticare l'utente

Dopo aver ottenuto le informazioni utente dal token ID, devi eseguire query sul database utente 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 degli utenti, devi reindirizzarlo al flusso di registrazione del nuovo utente. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni ricevute da Google o almeno potresti essere in grado di precompilare molti dei campi obbligatori nel modulo di registrazione. Oltre alle informazioni nel token ID, puoi ottenere informazioni aggiuntive sul profilo utente sui nostri endpoint del profilo utente.

Argomenti avanzati

Le sezioni seguenti descrivono in maggiore dettaglio 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 utilizzare OAuth 2.0 per l'autenticazione è che la tua applicazione può ottenere l'autorizzazione per utilizzare altre API di Google per conto dell'utente (come YouTube, Google Drive, Calendar o Contatti) contemporaneamente all'autenticazione dell'utente. Per farlo, includi gli altri ambiti di cui hai bisogno nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere l'età dell'utente alla richiesta di autenticazione, passa un parametro dell'ambito di openid email https://www.googleapis.com/auth/profile.agerange.read. L'utente viene richiesto in modo appropriato nella schermata di consenso. Il token di accesso che ricevi da Google ti consente di accedere a tutte le API correlate agli ambiti di accesso che hai richiesto e che ti sono stati concessi.

Nota: se l'applicazione richiede molti ambiti, la schermata per il consenso conterrà molte righe di testo. Maggiore è l'ambito delle richieste dell'applicazione, minore è la probabilità che l'utente acconsenta, pertanto l'applicazione deve chiedere solo gli ambiti di cui ha bisogno.

Aggiorna token

Nella richiesta di accesso all'API, puoi richiedere che venga restituito un token di aggiornamento durante lo scambio di code. Un token di aggiornamento fornisce alla tua app l'accesso continuo alle API di Google mentre l'utente non è presente 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, 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, questi potrebbero essere soggetti a tali limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.

Per ulteriori informazioni, consulta la pagina Aggiornare un token di accesso (accesso offline).

Richiesta di nuovo consenso

Puoi chiedere all'utente di autorizzare nuovamente la tua app impostando il parametro prompt su consent nella tua richiesta di autenticazione. Se prompt=consent è inclusa, la schermata per il consenso viene visualizzata ogni volta che la tua app richiede l'autorizzazione degli ambiti di accesso, anche se tutti gli ambiti sono stati concessi in precedenza al tuo progetto 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 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 proprietà API Consoledi Credentials page, come descritto nella sezione Ottenere le credenziali OAuth 2.0.
nonce	(Obbligatorio)	Un valore casuale generato dalla tua app che attiva la protezione della riproduzione.
response_type	(Obbligatorio)	Se il valore è code, avvia un flusso di codice di autorizzazione di base, che richiede un POST all'endpoint del token per ottenere i token. Se il valore è token id_token o id_token token, viene avviato un flusso implicito, che richiede l'utilizzo di JavaScript con l'URI di reindirizzamento per recuperare i token dall'identificatore #fragment #fragment.
redirect_uri	(Obbligatorio)	Determina dove inviare la risposta. Il valore di questo parametro deve corrispondere esattamente a uno dei valori di reindirizzamento autorizzati che hai impostato in API ConsoleCredentials page (inclusi lo schema HTTP o HTTPS e l'eventuale carattere '/' finale).
scope	(Obbligatorio)	Il parametro dell'ambito deve iniziare con il valore openid e quindi includere il valore profile, il valore email o entrambi. Se è presente il valore dell'ambito profile, il token ID potrebbe (ma non è garantito) che includa le rivendicazioni profile dell'utente predefinite. 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 degli ambiti devono essere separati da spazi. Ad esempio, se vuoi l'accesso per file a Google Drive di un utente, il tuo parametro di ambito potrebbe essere openid profile email https://www.googleapis.com/auth/drive.file. Per informazioni sugli ambiti disponibili, consulta la pagina relativa agli ambiti OAuth 2.0 per le API di Google o la documentazione per l'API di Google che vuoi utilizzare.
state	(opzione consigliata, ma vivamente consigliata)	Una stringa opaca per cui è necessario eseguire un round trip nel protocollo, ovvero viene restituito 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é è possibile indovinare l'elemento redirect_uri, l'utilizzo di un valore state può aumentare la garanzia che una connessione in entrata sia il risultato di una richiesta di autenticazione avviata dalla tua app. Se generi una stringa casuale o codifica l'hash di qualche stato del client (ad es. un cookie) in questa variabile state, puoi convalidare la risposta per garantire che la richiesta e la risposta abbiano origine nello stesso browser. Questo 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 di offline.
display	(Facoltativo)	Un valore stringa ASCII per specificare in che modo il server di autorizzazione mostra le pagine dell'interfaccia utente di autenticazione e consenso. I seguenti valori sono specificati e accettati dai server di Google, ma non influiscono sul suo comportamento: page, popup, touch e wap.
hd	(Facoltativo)	Semplifica il processo di accesso per gli account di proprietà di un'organizzazione Google Cloud. Se includi il dominio Google Cloud dell'organizzazione (ad esempio, mycollege.edu), puoi indicare che l'UI di selezione dell'account deve essere ottimizzata per gli account in quel dominio. Per ottimizzare gli account dell'organizzazione Google Cloud in generale, anziché applicare un unico dominio dell'organizzazione Google Cloud, imposta il valore dell'asterisco (*): hd=*. 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 hd che corrisponda a quanto 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, quindi 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 utente/applicazione per altri ambiti; consulta la sezione Autorizzazione incrementale. Tieni presente che non puoi eseguire l'autorizzazione incrementale con il flusso delle app installate.
login_hint	(Facoltativo)	Quando la tua app sa quale utente sta cercando di autenticare, può fornire questo parametro come suggerimento al server di autenticazione. Il passaggio di questo suggerimento sopprime il selettore di account e precompila la casella email nel modulo di accesso oppure seleziona la sessione appropriata (se l'utente sta utilizzando l'accesso simultaneo), che può aiutarti a evitare problemi che si verificano se la tua app accede all'account utente sbagliato. Il valore può essere un indirizzo email o la stringa sub, che è equivalente 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 la riautenticazione e il consenso. I valori possibili sono: none Il server di autorizzazione non mostra alcuna schermata di autenticazione o di consenso dell'utente; verrà restituito un errore se l'utente non è già autenticato e non ha un consenso preconfigurato per gli ambiti richiesti. Puoi utilizzare none per controllare l'autenticazione e/o il consenso esistenti. consent Il server di autorizzazione richiede l'autorizzazione dell'utente prima di restituire informazioni al client. select_account Il server di autorizzazione richiede all'utente di selezionare un account utente. In questo modo, un utente che ha più account sul server di autorizzazione può selezionare uno degli account per i quali potrebbe avere sessioni correnti. Se non viene specificato alcun valore e l'utente non ha autorizzato l'accesso in precedenza, l'utente visualizza 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 come autentici i token ID che riceve dalle app client.

Di seguito sono riportate alcune situazioni comuni in cui potresti inviare token ID al tuo server:

• Invio di token ID con richieste che devono essere autenticate. I token ID indicano all'utente specifico che effettua la richiesta e al quale è stato concesso il token ID.

I token ID sono sensibili e possono essere usati 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 intestazioni di richiesta. 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 possono essere trasferiti su diversi componenti della tua app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione semplice che autentica l'app e l'utente. Tuttavia, prima di poter utilizzare le informazioni nel token ID o di fare affidamento su di esso come una dichiarazione che l'utente ha autenticato, devi convalidarlo.

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 che si trovano all'URI specificato nel valore dei metadati jwks_uri del documento di rilevamento.
2. Verifica che il valore della rivendicazione iss nel token ID sia uguale a https://accounts.google.com o accounts.google.com.
3. Verifica che il valore della rivendicazione aud nel token ID sia uguale all'ID client della tua app.
4. Verifica che la data di scadenza (exp rivendicazione) del token ID non sia trascorsa.
5. Se hai specificato un valore parametro hd nella richiesta, verifica che il token ID abbia una rivendicazione hd che corrisponda a un dominio accettato associato a un'organizzazione Google Cloud.

I passaggi da 2 a 5 riguardano solo il confronto tra stringhe e date che sono abbastanza chiari, quindi non li dettagliamo qui.

Il primo passaggio è più complesso e comporta il controllo della firma crittografica. Ai fini del debug, puoi utilizzare l'endpoint tokeninfo di Google per eseguire un confronto con l'elaborazione locale implementata sul tuo server o sul tuo dispositivo. Supponiamo che il valore del token ID sia XYZ123. Quindi devi fare riferimento all'URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Se la firma del token è valida, la risposta sarà il payload JWT nel modulo dell'oggetto JSON decodificato.

L'endpoint tokeninfo è utile per il debug, ma ai fini della 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 comunque 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 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 e l'esecuzione delle chiamate crittografiche appropriate per controllare la firma. Fortunatamente sono disponibili librerie ben sottoposte a debug in un'ampia gamma di lingue per questo scopo (vedi jwt.io).

Ottenere informazioni del profilo dell'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:

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

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

   scope=openid%20profile%20email

2. Aggiungi il token di accesso all'intestazione di autorizzazione ed effettua una richiesta HTTPS GET all'endpoint userinfo, che dovresti recuperare dal documento di rilevamento 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 potrebbero scegliere di fornire o trattenere determinati campi, quindi potresti non ricevere informazioni relative a tutti i campi per gli ambiti di accesso autorizzati.

Il documento Discovery

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 sugli utenti e chiavi pubbliche.

Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente l'utilizzo di un "documento di rilevamento", un documento JSON trovato in una posizione nota contenente coppie chiave-valore che forniscono dettagli sulla configurazione del provider OpenID Connect, inclusi gli URI di autorizzazione, token, revoca, info utente e endpoint di 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 configurare 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 di endpoint da te eventualmente necessari. 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 riportato di seguito) 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 (fai riferimento al documento ai fini della definizione dei documenti). I valori sono a scopo puramente illustrativo e potrebbero variare, anche se vengono copiati da una versione recente dell'effettivo documento 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 essere in grado di evitare un round trip HTTP memorizzando i valori nella cache 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 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
• Google Toolbox per i controller OAuth 2.0 di Mac

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