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 riportata 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, tagga le tue domande con "google-oauth".
Configurare 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 in Google API Console per ottenere le credenziali OAuth 2.0, impostare un URI di reindirizzamento e, facoltativamente, personalizzare le informazioni sul branding visualizzate dagli utenti nella schermata del consenso dell'utente. Puoi anche utilizzare API Console per creare un account di servizio, attivare la fatturazione, impostare i filtri ed eseguire altre attività. Per ulteriori dettagli, consulta la Google API ConsoleGuida.
Ottenere le credenziali OAuth 2.0
Per autenticare gli utenti e ottenere l'accesso alle API di Google, devi disporre delle credenziali OAuth 2.0, inclusi un ID client e un client secret.
Per visualizzare l'ID client e il segreto client per una determinata credenziale OAuth 2.0, fare clic sul testo seguente: Seleziona credenziale . Nella finestra che si apre, scegli il tuo progetto e le credenziali desiderate, quindi fai clic su Visualizza .
In alternativa, visualizzare l'ID client e il segreto client dalla pagina Credenziali in API Console :
- Go to the Credentials page.
- Fai clic sul nome della tua credenziale o sull'icona a forma di matita ( create ). L'ID cliente e il segreto sono nella parte superiore della pagina.
Impostare un URI di reindirizzamento
L'URI di reindirizzamento impostato in API Console determina dove Google invia le risposte alle tue richieste di autenticazione.
Per creare, visualizzare o modificare gli URI di reindirizzamento per una determinata credenziale OAuth 2.0, procedi come segue:
- Go to the Credentials page.
- Nella sezione ID client OAuth 2.0 della pagina, fare clic su una credenziale.
- Visualizza o modifica gli URI di reindirizzamento.
Se non è presente la sezione ID client OAuth 2.0 nella pagina Credenziali, il progetto non ha credenziali OAuth. Per crearne uno, fai clic su Crea credenziali .
Personalizzare la schermata del consenso dell'utente
Per gli utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata di consenso che descrive le informazioni che l'utente sta rilasciando e i termini applicabili. Ad esempio, quando
l'utente accede, potrebbe essere chiesto di concedere alla tua app l'accesso al suo indirizzo email e ai dati di base del suo account. Richiedi 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 Google.
La schermata per il consenso dell'utente presenta anche informazioni sul branding, come il nome del prodotto, il logo e un URL della home page. Sei tu a controllare le informazioni sul branding in API Console.
To enable your project's consent screen:
- Open the Consent Screen page in the Google API Console.
- If prompted, select a project, or create a new one.
- Fill out the form and click Save.
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 sul branding che verrebbero impostate in API Console.
Accedi al servizio
Google e terze parti forniscono librerie che puoi utilizzare per gestire molti dettagli di implementazione dell'autenticazione degli utenti e dell'accesso alle API di Google. Alcuni esempi sono i Servizi di identità Google e le librerie client Google, disponibili per una serie di piattaforme.
Se scegli di non utilizzare una libreria, segui le istruzioni riportate nella parte rimanente 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 e la convalida di un token ID. I token di identità sono una funzionalità standardizzata di OpenID Connect progettata per essere utilizzata per condividere asserti di identità su internet.
Gli approcci più comunemente utilizzati per autenticare un utente e ottenere un token ID sono chiamati flusso "server" e flusso "implicito". Il flusso del server consente al server 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é tramite il 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 lato client. Se devi implementare un flusso implicito, ti consigliamo vivamente di utilizzare Google Identity Services.
Flusso del server
Assicurati di configurare l'app in API Console per consentirle di utilizzare questi protocolli e autenticare i tuoi utenti. Quando un utente tenta di accedere con Google, devi:
- Creare un token di stato anti-falsificazione
- Inviare una richiesta di autenticazione a Google
- Verificare il token dello stato anti-falsificazione
- Scambiare
code
con token di accesso e token ID - Ottenere le informazioni utente dal token ID
- Autenticare l'utente
1. Crea un token di stato anti-falsificazione
Devi proteggere la sicurezza dei tuoi utenti impedendo gli attacchi di contraffazione delle richieste. Il primo passaggio consiste nel creare un token di sessione univoco che memorizza lo stato tra la tua app e il client dell'utente. Successivamente, abbini questo token di sessione univoco alla risposta di autenticazione restituita dal servizio di accesso OAuth di Google per verificare che la richiesta sia stata effettuata dall'utente e non da un malintenzionato. Questi token sono spesso indicati come token di contraffazione di richieste 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 dello stato della sessione con una chiave che viene mantenuta segreta nel back-end.
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 creare una richiesta GET
HTTPS 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 base dal documento Discovery
utilizzando il valore dei metadati authorization_endpoint
. La seguente discussione presuppone
che l'URI di base sia https://accounts.google.com/o/oauth2/v2/auth
.
Per una richiesta di base, specifica i seguenti parametri:
client_id
, che puoi ottenere da API Console Credentials page .response_type
, che in una richiesta di flusso del codice di autorizzazione di base dovrebbe esserecode
. (Scopri di più all'indirizzoresponse_type
.)scope
, che in una richiesta di base dovrebbe essereopenid email
. (scopri di più all'indirizzoscope
).redirect_uri
deve essere l'endpoint HTTP sul tuo server che riceverà la risposta da Google. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, che hai configurato in API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, la richiesta non andrà a buon fine e verrà visualizzato un erroreredirect_uri_mismatch
.state
deve includere il valore del token di sessione univoco anti-falsificazione, nonché eventuali altre informazioni necessarie per recuperare il contesto quando l'utente torna alla tua applicazione, ad esempio l'URL iniziale. (scopri di più all'indirizzostate
).nonce
è un valore casuale generato dalla tua app che attiva la protezione antiriproduzione se presente.login_hint
può essere l'indirizzo email dell'utente o la stringasub
, che equivale all'ID Google dell'utente. Se non fornisci unlogin_hint
e l'utente ha eseguito l'accesso, la schermata del consenso include una richiesta di approvazione per divulgare l'indirizzo email dell'utente alla tua app. (Scopri di più inlogin_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ù suhd
).
Di seguito è riportato un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per la leggibilità:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Gli utenti sono tenuti a 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 dello stato anti-falsificazione
La risposta viene inviata all'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 verificare che il state
ricevuto da Google corrisponda al
token di sessione che hai creato nel Passaggio 1. Questa verifica di andata e ritorno contribuisce a garantire 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 token di accesso e token ID
La risposta include un parametro code
, un codice di autorizzazione una tantum che il tuo
server può scambiare con un token di accesso e un token ID. Il server esegue questo scambio inviando
una richiesta HTTPS POST
. La richiesta POST
viene inviata all'endpoint del token,
che devi recuperare dal documento Discovery 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 che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0. |
client_secret |
Il client secret che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0. |
redirect_uri |
Un URI di reindirizzamento autorizzato per il client_id specificato in
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 avere il seguente aspetto:
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 |
La durata rimanente del token di accesso in secondi. |
id_token |
Un JWT contenente informazioni sull'identità dell'utente firmato digitalmente da Google. |
scope |
Gli ambiti di accesso concessi dal 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
|
5. Ottenere le informazioni utente dal token ID
Un token di identità è un JWT (JSON Web Token), ovvero un oggetto JSON con codifica base64 firmato in modo crittografico. Normalmente, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché comunichi direttamente con Google tramite un canale HTTPS senza intermediari e utilizzi il tuo segreto cliente per autenticarti su Google, puoi essere certo che il token ricevuto provenga effettivamente da Google ed è valido. Se il server passa l'ID token 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 la decodifica dei valori codificati in base64url e l'analisi del JSON al loro interno, probabilmente convaliderai comunque il token quando accedi ai claim 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, con formattazione per la leggibilità:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Gli ID token di Google possono contenere i seguenti campi (noti come claim):
Richiedi | 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 | Data e ora di scadenza a partire dalle quali il token ID non deve essere accettato. Rappresentato in tempo Unix (secondi interi). |
iat |
sempre | L'ora in cui è stato emesso il token ID. Rappresentato in tempo 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 viene mai modificato. Utilizza sub all'interno della tua applicazione
come chiave dell'identificatore univoco per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole. |
at_hash |
Hash del token di accesso. Fornisce la convalida del fatto che il token di accesso sia associato al
token di identità. Se il token ID viene emesso con un valore access_token nel flusso
del server, questa rivendicazione è sempre inclusa. Questo claim può essere utilizzato come meccanismo alternativo per difendersi dagli attacchi di contraffazione delle richieste cross-site, 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 se
la parte che richiede l'ID token non corrisponde al pubblico dell'ID token. Questo
può 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 rivendicazione potrebbe non essere univoco per questo account e potrebbe cambiare nel tempo, pertanto non devi utilizzare questo valore come identificatore principale da collegare al tuo record utente. Inoltre, non puoi fare affidamento sul dominio della rivendicazione email per identificare gli utenti delle organizzazioni Google Workspace o Cloud. Utilizza invece la rivendicazione email .hd |
|
email_verified |
Vero se l'indirizzo email dell'utente è stato verificato, falso in caso contrario. | |
family_name |
I cognomi dell'utente. Può essere fornito quando è presente una richiesta
name . |
|
given_name |
I nomi o i nomi propri dell'utente. Può essere fornito quando è presente una richiesta
name . |
|
hd |
Il dominio associato all'organizzazione Google Workspace o Cloud dell'utente. Fornito solo se l'utente appartiene a un'organizzazione Google Cloud. Devi selezionare questa rivendicazione quando limiti l'accesso a una risorsa solo ai membri di determinati domini. L' assenza di questa rivendicazione indica che l'account non appartiene a un dominio ospitato da Google. | |
locale |
Le impostazioni internazionali dell'utente, rappresentate da un
tag lingua BCP 47.
Può essere fornito quando è presente una richiesta name . |
|
name |
Il nome completo dell'utente, in un formato visualizzabile. Può essere fornito quando:
Quando sono presenti rivendicazioni |
|
nonce |
Il valore di nonce fornito dalla tua app nella richiesta di autenticazione.
Devi applicare la protezione contro gli attacchi di replay assicurandoti che venga presentata solo
una volta. |
|
picture |
L'URL dell'immagine del profilo dell'utente. Può essere fornito quando:
Quando sono presenti rivendicazioni |
|
profile |
L'URL della pagina del profilo dell'utente. Può essere fornito quando:
Quando sono presenti rivendicazioni |
6. Autentica l'utente
Dopo aver ottenuto le informazioni sull'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 utente, devi reindirizzarlo al flusso di registrazione del nuovo utente. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni che ricevi da Google o, almeno, di precompilare molti dei campi richiesti nel modulo di registrazione. Oltre alle informazioni contenute nel token ID, puoi ottenere altre informazioni sul profilo dell'utente nei nostri endpoint del profilo dell'utente.
Argomenti avanzati
Le sezioni seguenti descrivono l'API Google OAuth 2.0 in modo più dettagliato. Queste informazioni sono rivolte agli sviluppatori con requisiti avanzati relativi ad 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 per 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 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 di
openid email https://www.googleapis.com/auth/profile.agerange.read
. All'utente viene rivolto un messaggio appropriato nella schermata di consenso. 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 che ti sono stati concessi.
Token di aggiornamento
Nella richiesta di accesso all'API puoi richiedere che venga restituito un token di aggiornamento durante la
scambio code
. Un token di aggiornamento fornisce alla tua app accesso continuo alle API di Google quando l'utente non è presente nella tua applicazione. Per richiedere un
token di aggiornamento, imposta il
parametro access_type
su offline
nella
tua richiesta di autenticazione.
Considerazioni:
- Assicurati di memorizzare il token di aggiornamento in modo sicuro e permanente, perché puoi ottenerne uno 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 di cliente/utente e un altro per utente su tutti i clienti. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe incontrare questi limiti, nel qual caso i token di aggiornamento meno recenti non funzioneranno più.
Per maggiori informazioni, consulta Aggiornare un token di accesso (accesso offline).
Richiesta di un nuovo consenso
Puoi chiedere all'utente di autorizzare di nuovo 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 per gli ambiti di accesso, anche se tutti gli ambiti sono stati concessi in precedenza 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 tabella seguente fornisce descrizioni più complete dei parametri accettati dall'API di autenticazione OAuth 2.0 di Google.
Parametro | Obbligatorio | Descrizione |
---|---|---|
client_id |
(Obbligatorio) | La stringa dell'ID client che ottieni da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0. |
nonce |
(Obbligatorio) | Un valore casuale generato dalla tua app che attiva la protezione da replay. |
response_type |
(Obbligatorio) | Se il valore è code , viene avviato 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 nell'URI di reindirizzamento per recuperare i token dall'identificatore URI #fragment . |
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 (incluso lo schema HTTP o HTTPS, le lettere maiuscole e l'eventuale carattere finale "/"). |
scope |
(Obbligatorio) | Il parametro ambito deve iniziare con il valore Se il valore dell'ambito Se è presente il valore dell'ambito Oltre a questi ambiti specifici di OpenID, l'argomento ambito può includere anche altri valori di ambito. Tutti i valori di ambito devono essere separati da spazi. Ad esempio, se vuoi accedere su base file a Google Drive di un utente, il parametro di ambito potrebbe essere Per informazioni sugli ambiti disponibili, consulta Ambiti OAuth 2.0 per le API di Google o la documentazione dell'API di Google che vuoi utilizzare. |
state |
(Facoltativo, ma vivamente consigliato) | Una stringa opaca che viene passata nel protocollo, ovvero viene
restituita come parametro URI nel flusso di base e nell'identificatore URI
|
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 di 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 Google, ma non influiscono sul loro comportamento: page , popup , touch e wap . |
hd |
(Facoltativo) | Semplifica la procedura di accesso per gli account di proprietà di un'organizzazione Google Cloud. Se includi il dominio dell'organizzazione Google Cloud (ad esempio mycollege.edu), puoi indicare che l'interfaccia utente di selezione dell'account deve essere ottimizzata per gli account di quel dominio. Per eseguire l'ottimizzazione per gli account delle organizzazioni Google Cloud in generale anziché per un solo dominio dell'organizzazione Google Cloud, imposta un valore di un asterisco ( 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 del claim |
include_granted_scopes |
(Facoltativo) | Se a questo parametro viene fornito il valore true e la richiesta di autorizzazione viene concessa, l'autorizzazione includerà eventuali 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 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, viene eliminato il selettore di account e la casella email del modulo di accesso viene precompilata oppure viene selezionata la sessione corretta (se l'utente utilizza l'accesso con più account). In questo modo puoi 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 è equivalente all'ID Google dell'utente. |
prompt |
(Facoltativo) | Un elenco di valori di stringa separati da spazi che specifica se il server di autorizzazione
chiede all'utente di eseguire nuovamente l'autenticazione e di dare il consenso. I valori possibili sono:
Se non viene specificato alcun valore e l'utente non ha autorizzato in precedenza l'accesso, 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 server deve verificare come autentici tutti i token ID ricevuti dalle tue app client.
Di seguito sono riportate 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 il determinato utente che effettua la richiesta e per quale client è stato concesso il token ID.
I token di identità 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 di richiesta. Se memorizzi i token ID sul tuo server, devi anche archiviarli in modo sicuro.
Un aspetto che rende utili i token ID è che puoi trasmetterli ai 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 utilizzarlo come affermazione che l'utente si è autenticato, devi convalidarlo.
La convalida di un token ID richiede diversi passaggi:
- Verifica che il token ID sia firmato correttamente dall'emittente. I token emessi da Google sono firmati
utilizzando uno dei certificati trovati nell'URI specificato nel valore dei metadati
jwks_uri
del documento Discovery. - Verifica che il valore del claim
iss
nel token ID sia uguale ahttps://accounts.google.com
oaccounts.google.com
. - Verifica che il valore dell'affermazione
aud
nel token ID sia uguale all'ID cliente della tua app. - Verifica che l'ora di scadenza (affermazione
exp
) del token ID non sia passata. - Se hai specificato un valore del parametro hd nella richiesta, verifica che
il token di abilitazione contenga un claim
hd
che corrisponda 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 abbastanza semplici, quindi non li descriveremo nel dettaglio qui.
Il primo passaggio è più complesso e prevede il controllo della firma crittografica. Per scopi di debug, puoi utilizzare l'endpoint tokeninfo
di Google per fare un confronto con l'elaborazione locale implementata sul tuo server o dispositivo. Supponiamo che il valore del token di identità sia
XYZ123
. Poi 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 chiavi ed esegui la convalida localmente. Devi recuperare l'URI delle chiavi dal documento Discovery
utilizzando il valore dei metadati jwks_uri
. Le richieste all'endpoint di debug potrebbero essere
ridotte o comunque soggette a errori intermittenti.
Poiché Google modifica le sue chiavi pubbliche solo di rado, puoi memorizzarle nella cache utilizzando le direttive della cache della risposta HTTP e, nella maggior parte dei casi, eseguire la convalida locale molto più efficacemente 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, esistono librerie ben debuggate disponibili in una vasta gamma di lingue per farlo (vedi jwt.io).
Ottenere le informazioni del profilo dell'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:
Per essere conforme a OpenID, devi includere i valori di ambito
openid profile
nella richiesta di autenticazione.Se vuoi che l'indirizzo email dell'utente venga incluso, puoi specificare un valore di ambito aggiuntivo di
email
. Per specificare siaprofile
cheemail
, puoi includere il seguente parametro nell'URI della richiesta di autenticazione:scope=openid%20profile%20email
- Aggiungi il token di accesso all'intestazione di autorizzazione e invia una richiesta
GET
HTTPS all'endpoint userinfo, che devi recuperare dal documento Discovery utilizzando il valore dei metadatiuserinfo_endpoint
. La risposta userinfo include informazioni sull'utente, come descritto inOpenID Connect Standard Claims
e il valore del metadatoclaims_supported
del documento Discovery. Gli utenti o le loro organizzazioni possono scegliere di fornire o trattenere determinati campi, pertanto potresti non ricevere informazioni per ogni campo per i tuoi ambiti di accesso autorizzati.
Il documento di rilevamento
Il protocollo OpenID Connect richiede l'utilizzo di più endpoint per autenticare gli utenti e per richiedere 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 discovery", un documento JSON trovato 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, userinfo e chiavi pubbliche. Il documento Discovery per il servizio OpenID Connect di Google può essere recuperato da:
https://accounts.google.com/.well-known/openid-configuration
Per utilizzare i servizi OpenID Connect di Google, devi codificare l'URI del documento di scoperta
(https://accounts.google.com/.well-known/openid-configuration
) nell'applicazione.
L'applicazione recupera il documento, applica le regole di memorizzazione nella risposta e poi recupera gli URI endpoint in base alle necessità. Ad esempio, per autenticare un utente, il codice recupererebbe il valore del metadato authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
nell'esempio seguente) come URI base per le richieste di autenticazione inviate a Google.
Ecco un esempio di questo tipo di documento: i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fai riferimento a questo documento per il relativo significato). I valori sono puramente indicativi e potrebbero cambiare, anche se sono stati copiati da una versione recente del 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 riuscire a evitare un viaggio di andata e ritorno HTTP memorizzando nella cache i valori del documento Discovery. Le intestazioni di memorizzazione nella cache HTTP standard vengono utilizzate e devono essere rispettate.
Librerie client
Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 grazie all'integrazione con i framework più diffusi:
- 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 Google per PHP
- Libreria OAuth 2.0 per Google Web Toolkit
- Controllori OAuth 2.0 di Google Toolbox per Mac
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 interoperare con questo servizio (ad eccezione dell'oggetto della richiesta OpenID).