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 e con la certificazione OpenID. Anche la documentazione si trova in Utilizzo di OAuth 2.0 per accedere alle API di Google per questo servizio. Se vuoi esplorare questo protocollo in modo interattivo, ti consigliamo di utilizzare Google OAuth 2.0 Playground. Per ricevere aiuto su Stack Overflow, tagga le tue domande con 'google-oauth'.

Nota: se vuoi fornire un pulsante "Accedi con Google" per il tuo sito web o la tua app, ti consigliamo di utilizzare Accedi con 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

Affinché la tua applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso dell'utente, devi configurare un progetto in Google API Console per ottenere le credenziali OAuth 2.0, impostare un URI di reindirizzamento e (facoltativamente) personalizzare le informazioni di branding visualizzate dagli utenti nella schermata di consenso dell'utente. Puoi anche utilizzare API Console per creare un account di servizio, abilitare la fatturazione, configurare i filtri e svolgere altre attività. Per ulteriori dettagli, consulta la Guida di Google API Console.

Ottenere le credenziali OAuth 2.0

Per autenticare gli utenti e ottenere l'accesso alle API di Google, devi disporre delle credenziali OAuth 2.0, inclusi un ID client e un client secret.

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 URI di reindirizzamento

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

Per creare, visualizzare o modificare gli URI di reindirizzamento per una determinata credenziale OAuth 2.0, procedi come segue:

1. Go to the Credentials page.
2. Nella sezione ID client OAuth 2.0 della pagina, fare clic su una credenziale.
3. Visualizza o modifica gli URI di reindirizzamento.

Se non è presente la sezione ID client OAuth 2.0 nella pagina Credenziali, il progetto non ha credenziali OAuth. Per crearne uno, fai clic su Crea credenziali .

Personalizza la schermata per il consenso degli utenti

Per gli utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata per il consenso che descrive le informazioni che l'utente sta rilasciando e i termini applicabili. Ad esempio, quando l'utente accede, potrebbe essere chiesto di fornire all'app l'accesso al suo indirizzo email e ai dati di base dell'account. Devi richiedere l'accesso a queste informazioni utilizzando il parametro scope, che la tua app include nella sua richiesta di autenticazione. Puoi anche utilizzare gli ambiti per richiedere l'accesso ad altre API di Google.

La schermata per il consenso degli utenti mostra anche le informazioni di branding, come il nome del prodotto, il logo e l'URL di una home page. Puoi gestire le informazioni sul branding nel API Console.

Per abilitare la schermata di consenso del tuo progetto:

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 visualizzerà quando nella richiesta è presente una combinazione di ambiti OAuth 2.0 e Google Drive. Questa finestra di dialogo generica è stata generata utilizzando Google OAuth 2.0 Playground, pertanto non include informazioni di branding che potrebbero essere impostate in API Console.

Accedi al servizio

Google e terze parti forniscono librerie che puoi utilizzare per gestire molti dei dettagli di implementazione relativi all'autenticazione degli utenti e alle modalità di accesso alle API di Google. Alcuni esempi sono Accedi con Google e le librerie client di Google, disponibili per diverse piattaforme.

Nota: date le implicazioni di sicurezza legate alla corretta implementazione dell'implementazione, ti consigliamo vivamente di usufruire di una libreria o di un servizio precompilato. Autenticare correttamente gli utenti è importante per loro e per la loro sicurezza. L'utilizzo di codice di cui è stato eseguito il debug scritto da altri utenti è in genere una best practice. Per scoprire 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 alla base delle librerie disponibili.

Autenticazione dell'utente

L'autenticazione dell'utente comporta l'ottenimento di un token ID e la sua convalida. I token ID sono una funzionalità standardizzata di OpenID Connect progettata per essere utilizzata per la dichiarazione delle asserzioni su Internet.

Gli approcci più utilizzati per l'autenticazione di un utente e per ottenere un token ID sono chiamati flusso "server" e "implicit". Il flusso del server consente al server back-end di un'applicazione di verificare l'identità della persona utilizzando un browser o un dispositivo mobile. Il flusso implicito viene utilizzato quando un'applicazione lato client (in genere un'app JavaScript in esecuzione nel browser) deve accedere direttamente alle API anziché tramite il suo server di backend.

Questo documento descrive come eseguire il flusso del server per autenticare l'utente. Il flusso implicito è significativamente più complicato a causa dei rischi per la sicurezza nella gestione e nell'utilizzo dei token sul lato client. Se devi implementare un flusso implicito, ti consigliamo vivamente di utilizzare Accedi con Google.

Flusso server

Assicurati di configurare la tua app in API Console per consentirla di utilizzare questi protocolli e di autenticare i tuoi utenti. Quando un utente prova ad accedere con Google, devi:

1. Creare un token di stato anti-falso
2. Inviare una richiesta di autenticazione a Google
3. Conferma il token di stato di contraffazione
4. Exchange code per il token di accesso e il token ID
5. Ottenere le informazioni utente dal token ID
6. Autentica l'utente

1. Crea un token di stato anti-falso

Devi proteggere la sicurezza dei tuoi utenti da attacchi di richiesta di falsificazione. Il primo passaggio consiste nel creare un token di sessione univoco che contenga lo stato tra l'app e il client dell'utente. Successivamente, potrai associare questo token di sessione univoco alla risposta di autenticazione restituita dal servizio di accesso OAuth di Google per verificare che l'utente stia effettuando la richiesta e non sia un utente malintenzionato dannoso. Questi token sono spesso indicati come token di richiesta di falsificazione tra siti (CSRF).

Un'ottima scelta per un token di stato è una stringa di circa 30 caratteri, generata utilizzando un generatore di numeri casuali di alta qualità. Un altro è un hash generato firmando alcune delle variabili di stato della sessione con una chiave mantenuta segreta sul tuo backend.

Il seguente codice dimostra la generazione di token di sessione univoci.

PHP

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Inviare una richiesta di autenticazione a Google

Il passaggio successivo consiste nel generare una richiesta HTTPS GET con i parametri URI appropriati. Nota l'utilizzo di HTTPS anziché HTTP in tutte le fasi di questo processo; le connessioni HTTP vengono rifiutate. Devi recuperare l'URI di base dal documento di rilevamento utilizzando il valore dei metadati authorization_endpoint. La seguente discussione presuppone che l'URI di base sia https://accounts.google.com/o/oauth2/v2/auth.

Per una richiesta di base, specifica i seguenti parametri:

• client_id, che puoi ottenere dal API Console Credentials page .
• response_type, che in una richiesta di flusso di codice di autorizzazione di base dovrebbe essere code. Scopri di più all'indirizzo response_type.
• scope: in una richiesta di base dovrebbe essere openid email. Scopri di più all'indirizzo scope.
• redirect_uri deve essere l'endpoint HTTP del tuo server che riceverà la risposta da Google. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, configurato in API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, la richiesta non andrà a buon fine con un errore redirect_uri_mismatch.
• state deve includere il valore del token di sessione univoco anti-falso, nonché eventuali altre informazioni necessarie per recuperare il contesto quando l'utente torna all'applicazione, ad esempio l'URL iniziale. Scopri di più all'indirizzo state.
• nonce è un valore casuale generato dalla tua app che consente la protezione della riproduzione quando è presente.
• login_hint può essere l'indirizzo email dell'utente o la 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 particolare dominio associato a un'organizzazione Google Cloud. Scopri di più all'indirizzo hd.

Nota: solo i parametri più utilizzati sono elencati sopra. Per un elenco completo e per ulteriori dettagli su tutti i parametri, consulta la sezione Parametri dell'URI di autenticazione.

Ecco un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per una migliore leggibilità:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

È necessario dare il proprio consenso agli utenti se la tua app richiede nuove informazioni in merito o se richiede l'accesso all'account da parte delle tue app non approvate in precedenza.

3. Conferma token di stato anti-falso

La risposta viene inviata all'elemento redirect_uri specificato nella richiesta. Tutte le risposte vengono restituite nella stringa di query, come mostrato di seguito:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Sul server, devi confermare che il state ricevuto da Google corrisponda al token di sessione che hai creato nel Passaggio 1. Questa verifica di andata e ritorno aiuta a garantire che l'utente, non uno script dannoso, stia effettuando la richiesta.

Il seguente codice dimostra la conferma dei token di sessione che hai creato nel passaggio 1:

PHP

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Scambio di code per il token di accesso e il token ID

La risposta include un parametro code, un codice di autorizzazione monouso che il tuo server può scambiare con un token di accesso e un token ID. Il tuo server effettua questo scambio inviando una richiesta HTTPS POST. La richiesta POST viene inviata all'endpoint del token, che devi recuperare dal documento di rilevamento utilizzando il valore dei metadati token_endpoint. La seguente discussione presuppone che l'endpoint sia https://oauth2.googleapis.com/token. La richiesta deve includere i seguenti parametri nel corpo POST:

Campi
code	Il codice di autorizzazione che viene restituito dalla richiesta iniziale.
client_id	L'ID client ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
client_secret	Il secret client che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
redirect_uri	Un URI di reindirizzamento autorizzato per il client_id specificato nel file API Console Credentials page, come descritto in Impostare un URI di reindirizzamento.
grant_type	Questo campo deve contenere un valore authorization_code, come definito nella specifica OAuth 2.0.

La richiesta effettiva potrebbe essere simile all'esempio seguente:

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

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

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

Campi
access_token	Un token che può essere inviato a un'API di Google.
expires_in	La durata rimanente del token di accesso in secondi.
id_token	Un JWT che contiene informazioni sull'identità dell'utente che è stato digitalmente firmato da Google.
scope	Gli ambiti di accesso concessi da access_token espressi come elenco di stringhe sensibili alle maiuscole.
token_type	Identifica il tipo di token restituito. Al momento, questo campo ha sempre il valore Bearer.
refresh_token	(facoltativo) Questo campo è presente solo se il parametro access_type è stato impostato su offline nella richiesta di autenticazione. Per maggiori dettagli, vedi Aggiornare i token.

Nota: esiste un limite al numero di token per account utente Google e qualsiasi richiesta di autenticazione al di sopra di questo limite potrebbe invalidare in modo discreto un token di aggiornamento in sospeso. Per maggiori dettagli, consulta la pagina Scadenza token.

5. Ottieni le informazioni dell'utente dal token ID

Un token ID è un token web JSON, ovvero un oggetto JSON con codifica Base64 firmato con crittografia. Normalmente, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché stai comunicando direttamente con Google tramite un canale HTTPS senza intermediari e utilizzando il client secret per autenticarti su Google, puoi avere la certezza che il token che ricevi proviene effettivamente da Google ed è valido. Se il server trasmette il token ID ad altri componenti dell'app, è estremamente importante che gli altri componenti convalidino il token prima di utilizzarlo.

Poiché la maggior parte delle librerie API combina la convalida con il lavoro di decodifica dei valori con codifica base64url e l'analisi del codice JSON al suo interno, è probabile che la convalida del token avvenga comunque, quando accedi alle richieste nel token ID.

Il payload di un token ID

Un token ID è un oggetto JSON contenente un insieme di coppie nome/valore. Ecco un esempio, formattato per la leggibilità:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

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

Claim	fornito	Description
aud	sempre	Il pubblico a cui è destinato questo token ID. Deve essere uno degli ID client OAuth 2.0 dell'applicazione.
exp	sempre	La data di scadenza il giorno dopo la quale il token ID non deve essere accettato. Rappresentato in tempo Unix (numeri interi).
iat	sempre	La data di emissione del token ID. Rappresentato in tempo Unix (numeri interi).
iss	sempre	L'identificatore dell'emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token ID Google.
sub	sempre	Un identificatore dell'utente, univoco per tutti gli Account Google e mai riutilizzato. Un Account Google può avere più indirizzi email in momenti diversi, ma il valore sub non viene mai modificato. Utilizza sub nella tua applicazione come chiave di identificazione univoca per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole.
at_hash		Hash del token di accesso. Offre la convalida che il token di accesso è associato al token di identità. Se il token ID viene emesso con un valore access_token nel flusso del server, questa rivendicazione è sempre inclusa. Questa dichiarazione può essere utilizzata come meccanismo alternativo per proteggersi dagli attacchi di falsificazione di richieste tra siti, ma se segui il Passaggio 1 e il Passaggio 3, non è necessario verificare il token di accesso.
azp		Il client_id del presentatore autorizzato. Questa rivendicazione è necessaria solo quando la parte che richiede il token ID non corrisponde al pubblico del token ID. Questo può valere per Google per le app ibride in cui un'applicazione web e un'app Android hanno un OAuth 2.0 client_id diverso, ma condividono lo stesso progetto API di Google.
email		L'indirizzo email dell'utente. Questo valore potrebbe non essere univoco per l'utente e non è idoneo per essere utilizzato come chiave primaria. Fornito solo se il tuo ambito includeva il valore dell'ambito email.
email_verified		True se l'indirizzo email dell'utente è stato verificato; in caso contrario è falso.
family_name		I cognomi dell'utente o i cognomi. Potrebbe essere fornito quando è presente una rivendicazione di name.
given_name		I nomi o i nomi degli utenti. Potrebbe essere fornito quando è presente una rivendicazione di name.
hd		Il dominio associato all'organizzazione Google Cloud dell'utente. Fornito solo se l'utente appartiene a un'organizzazione Google Cloud.
locale		Le impostazioni internazionali dell'utente, rappresentate da un tag della lingua BCP 47. Potrebbe essere fornito quando è presente una rivendicazione di name.
name		Il nome completo dell'utente, in un formato visibile. Può essere fornito quando: L'ambito della richiesta includeva la stringa "profilo" Il token ID viene restituito da un aggiornamento del 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 di nonce fornito dalla tua app nella richiesta di autenticazione. Devi imporre la protezione contro gli attacchi di replica assicurandoti che venga presentata una sola volta.
picture		L'URL dell'immagine del profilo dell'utente. Può essere fornito quando: L'ambito della richiesta includeva la stringa "profilo" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni di 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. Può essere fornito quando: L'ambito della richiesta includeva la stringa "profilo" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni di profile, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che non è mai garantito che questa rivendicazione sia presente.

6. Autentica l'utente

Dopo aver ottenuto le informazioni utente dal token ID, devi eseguire una query sul database utente della tua app. Se l'utente esiste già nel tuo database, devi avviare una sessione dell'applicazione per quell'utente se tutti i requisiti di accesso sono soddisfatti dalla risposta dell'API di Google.

Se l'utente non esiste nel tuo database utenti, devi reindirizzarlo al flusso di registrazione dei nuovi utenti. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni ricevute da Google, o almeno puoi precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni nel token ID, puoi ottenere ulteriori informazioni sul profilo utente nei nostri endpoint del profilo utente.

Argomenti avanzati

Le seguenti sezioni descrivono in modo più dettagliato l'API Google OAuth 2.0. Queste informazioni sono rivolte agli sviluppatori con requisiti avanzati di autenticazione e autorizzazione.

Accesso ad altre API di Google

Uno dei vantaggi di OAuth 2.0 per l'autenticazione è che l'applicazione può ottenere l'autorizzazione per l'utilizzo di altre API di Google per conto dell'utente (ad esempio YouTube, Google Drive, Calendar o Contatti), contemporaneamente all'autenticazione dell'utente. A tale scopo, includi gli altri ambiti di cui hai bisogno nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere la fascia d'età dell'utente alla richiesta di autenticazione, passa un parametro di ambito a openid email https://www.googleapis.com/auth/profile.agerange.read. alla schermata per il consenso viene richiesta l'autorizzazione dell'utente. Il token di accesso che ricevi da Google ti consente di accedere a tutte le API relative agli ambiti di accesso che hai richiesto e a cui ti è stato concesso.

Nota: se la tua applicazione richiede molti ambiti, la schermata di consenso contiene molte righe di testo. Quanto più elevato è l'ambito richiesto dall'applicazione, tanto minore è la probabilità che l'utente fornisca il consenso, quindi l'applicazione dovrebbe chiedere solo gli ambiti di cui ha bisogno.

Token di aggiornamento

Nella tua richiesta di accesso all'API, puoi richiedere la restituzione di un token di aggiornamento durante lo scambio di code. Un token di aggiornamento fornisce alla tua app accesso continuo alle API di Google anche quando l'utente non è presente nella tua applicazione. Per richiedere un token di aggiornamento, aggiungi il parametro access_type a offline nella richiesta di autenticazione.

Considerazioni:

• Assicurati di archiviare il token di aggiornamento in modo sicuro e permanente, perché puoi ottenere un token di aggiornamento solo la prima volta che esegui il flusso di scambio del codice.
• Esistono limiti al numero di token di aggiornamento emessi: un limite per combinazione client/utente e un altro per utente in tutti i client. Se la tua applicazione richiede troppi token di aggiornamento, potrebbero verificarsi questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.

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

Richiesta di nuovo consenso

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

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

Parametri di URI di autenticazione

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

Parametro	Obbligatorio	Description
client_id	(Obbligatorio)	La stringa dell'ID client ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
nonce	(Obbligatorio)	Un valore casuale generato dalla tua app che consente la protezione dalla riproduzione.
response_type	(Obbligatorio)	Se il valore è code, viene avviato un flusso di codice di autorizzazione di base, che richiede un POST all'endpoint per ottenere i token. Se il valore è token id_token o id_token token, viene avviato un flusso implicito, che richiede l'utilizzo di JavaScript nell'URI di reindirizzamento per recuperare i token dall'identificatore #fragment URI.
redirect_uri	(Obbligatorio)	Determina dove viene inviata la risposta. Il valore di questo parametro deve corrispondere esattamente a uno dei valori di reindirizzamento autorizzati impostati in API Console Credentials page (compresi lo schema HTTP o HTTPS, quello specificato nella parte finale e '/', se presente).
scope	(Obbligatorio)	Il parametro dell'ambito deve iniziare con il valore openid e poi includere il valore profile, il valore email o entrambi. Se è presente il valore dell'ambito profile, il token ID potrebbe includere (ma non è garantito) 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 di ambito. Tutti i valori di ambito devono essere separati da spazi. Ad esempio, se vuoi consentire l'accesso per file a Google Drive di un utente, il parametro di ambito potrebbe essere openid profile email https://www.googleapis.com/auth/drive.file. Per informazioni sugli ambiti disponibili, consulta gli ambiti OAuth 2.0 per le API di Google o la documentazione dell'API Google che vuoi utilizzare.
state	(Facoltativo, ma vivamente consigliato)	Una stringa opaca che viene roundtrip nel protocollo, vale a dire che viene restituita come parametro URI nel flusso di base e nell'identificatore #fragmentURI del flusso implicito. state può essere utile per correlare richieste e risposte. Poiché redirect_uri può essere indovinato, 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 crei una stringa casuale o codifica l'hash di uno stato client (ad esempio un cookie) in questa variabile state, puoi convalidare la risposta per garantire inoltre che la richiesta e la risposta abbiano origine nello stesso browser. In questo modo proteggi gli attacchi, ad esempio 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 stringa ASCII per specificare la modalità di visualizzazione delle pagine dell'interfaccia utente per l'autenticazione e il consenso. I seguenti valori sono specificati e accettati dai server di Google, ma non hanno alcun effetto sul loro comportamento: page, popup, touch e wap.
hd	(facoltativo)	Semplifica la procedura di accesso per gli account di proprietà di un'organizzazione Google Cloud. Se includi il dominio dell'organizzazione Google Cloud (ad esempio mycollege.edu), puoi indicare che l'UI di selezione degli account deve essere ottimizzata per gli account di quel dominio. Per ottimizzare in generale gli account dell'organizzazione Google Cloud anziché un solo dominio dell'organizzazione Google Cloud, imposta il valore di un asterisco (*): 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 corrispondente a quello previsto (ad es. mycolledge.edu). A differenza del parametro di richiesta, la richiesta di token ID hd contiene un token di sicurezza di Google, quindi il valore è attendibile.
include_granted_scopes	(facoltativo)	Se a questo parametro viene fornito il valore true e la richiesta di autorizzazione viene concessa, l'autorizzazione includerà tutte le autorizzazioni precedenti concesse a questa combinazione utente/applicazione per altri ambiti; consulta la sezione Autorizzazione incrementale. Tieni presente che non puoi eseguire un'autorizzazione incrementale con il flusso delle app installate.
login_hint	(facoltativo)	Quando la tua app sa quale utente sta tentando di autenticare, può fornire questo parametro come suggerimento al server di autenticazione. Il passaggio di questo suggerimento elimina il selettore account e precompila il riquadro dell'email nel modulo di accesso, oppure seleziona la sessione adeguata (se l'utente utilizza l'accesso simultaneo), in modo da evitare problemi che si verificano se l'app registra l'account utente sbagliato. Il valore può essere un indirizzo email o la stringa sub, equivalente all'ID Google dell'utente.
prompt	(facoltativo)	Un elenco di valori stringa separati da spazi che specificano se il server di autorizzazione richiede l'autenticazione e il consenso all'utente. I valori possibili sono: none Il server di autorizzazione non mostra schermate di consenso o di autenticazione e restituisce 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 richiede il consenso 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ò scegliere tra i diversi account per cui può eseguire sessioni attuali. Se non viene specificato alcun valore e l'utente non ha autorizzato l'accesso in precedenza, viene visualizzata una schermata per il consenso.

Convalida di un token ID

Devi convalidare tutti i token ID sul tuo server, a meno che tu non sappia che provengono direttamente da Google. Ad esempio, il tuo server deve verificare come autentici i token ID che riceve dalle app client.

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

• Invio di token ID con richieste da autenticare. I token ID indicano all'utente specifico che ha effettuato la richiesta e per quale client è stato concesso il token ID.

I token ID sono sensibili e possono essere utilizzati in modo improprio se intercettati. Devi assicurarti che questi token vengano gestiti in modo sicuro trasmettendoli solo tramite HTTPS e solo tramite dati POST o all'interno delle intestazioni delle richieste. Se memorizzi i token ID sul tuo server, devi archiviarli anche in modo sicuro.

Una cosa che rende utili i token ID è il fatto che puoi trasmetterli intorno a diversi componenti della tua app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione leggero che autentica l'app e l'utente. Tuttavia, prima di poter utilizzare le informazioni nel token ID o farne affidamento come asserzione che l'utente ha autenticato, devi convalidarle.

La convalida di un token ID richiede diversi passaggi:

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 passata.
5. Se hai specificato un valore hdparameter nella richiesta, verifica che il token ID abbia una rivendicazione hd che corrisponde a un dominio accettato associato a un'organizzazione Google Cloud.

I passaggi da 2 a 5 prevedono il confronto di stringhe e date, che sono piuttosto semplici, quindi non li dettagliamo qui.

Il primo passaggio è più complesso e prevede il controllo della firma crittografica. Ai fini di debug, puoi utilizzare l'endpoint tokeninfo di Google per confrontarlo con l'elaborazione locale implementata sul tuo server o dispositivo. Supponiamo che il valore del token ID sia XYZ123. Devi quindi dereferenziare l'URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Se la firma del token è valida, la risposta sarà il payload JWT nel suo formato oggetto JSON decodificato.

L'endpoint tokeninfo è utile per il debug, ma a fini di produzione recupera le chiavi pubbliche di Google dall'endpoint ed esegui la convalida in locale. Devi recuperare l'URI delle chiavi dal documento di rilevamento utilizzando il valore dei metadati jwks_uri. Le richieste all'endpoint di debug possono essere ridotte o altrimenti soggette a errori intermittenti.

Poiché Google modifica le chiavi pubbliche solo raramente, puoi memorizzarle nella cache utilizzando le istruzioni cache della risposta HTTP e, nella grande maggioranza dei casi, esegui la convalida locale in modo molto più efficiente rispetto all'utilizzo dell'endpoint tokeninfo. Questa convalida richiede il recupero e l'analisi dei certificati e l'esecuzione di chiamate crittografiche appropriate per controllare la firma. Fortunatamente sono disponibili librerie ben sottoposte a debug in una vasta gamma di linguaggi, per questo scopo (vedi jwt.io).

Ottenere informazioni del profilo utente

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

1. Per essere compatibile con OpenID, devi includere i valori dell'ambito openid profile nella tua richiesta di autenticazione.

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

   scope=openid%20profile%20email

2. Aggiungi il tuo token di accesso all'intestazione dell'autorizzazione ed effettua una GETrichiesta HTTPS all'endpoint userinfo, che dovresti recuperare dal documento di Discovery utilizzando il valore dei metadati userinfo_endpoint. La risposta dell'utente include informazioni sull'utente, come descritto in OpenID Connect Standard Claims e nel valore dei metadati claims_supported del documento di rilevamento. Gli utenti o le loro organizzazioni possono scegliere di fornire o trattenere determinati campi, quindi potresti non ricevere informazioni su tutti i campi relativi agli ambiti di accesso autorizzati.

Il documento di rilevamento

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

Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente l'utilizzo di un documento &Discovery: un documento JSON che si trova in una posizione nota contenente coppie chiave-valore che forniscono dettagli sulla configurazione del provider OpenID Connect, inclusi gli URI di endpoint di autorizzazione, token, revoca, userinfo e chiave pubblica. Il documento di rilevamento per il servizio OpenID Connect di Google può essere recuperato da:

https://accounts.google.com/.well-known/openid-configuration

Per utilizzare i servizi OpenID Connect di Google, devi impostare come hardcoded l'URI del documento di rilevamento (https://accounts.google.com/.well-known/openid-configuration) nella tua applicazione. L'applicazione recupera il documento, applica le regole di memorizzazione nella cache nella risposta e recupera gli URI degli endpoint in base alle esigenze. Ad esempio, per autenticare un utente, il tuo codice recupera il valore dei metadati authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth nell'esempio sotto) come URI di base per le richieste di autenticazione inviate a Google.

Ecco un esempio di tale documento; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fai riferimento a tale documento per conoscere i loro significati). I valori sono puramente illustrativi e potrebbero cambiare, anche se sono copiati da una versione recente dell'effettivo documento di Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Potresti evitare un roundtrip HTTP memorizzando nella cache i valori contenuti nel documento di rilevamento. Vengono utilizzate intestazioni di memorizzazione nella cache HTTP standard, che devono essere rispettate.

Librerie client

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

• Libreria client delle API di Google per Java
• Libreria client delle API di Google per Python
• Libreria client delle API di Google per .NET
• Libreria client delle API di Google per Ruby
• Libreria client delle API di Google per PHP
• Libreria OAuth 2.0 per Google Web Toolkit
• Strumenti Google per controller Mac OAuth 2.0

Conformità di OpenID Connect

Il sistema di autenticazione OAuth 2.0 di Google supporta le funzionalità richieste della specifica OpenID Connect Core. Qualsiasi client progettato per funzionare con OpenID Connect deve interagire con questo servizio (tranne che con OpenID Request Object).