OAuth 2.0 per app mobile e desktop

il tuo

Questo documento spiega in che modo le applicazioni installate su dispositivi quali telefoni, tablet e computer utilizzano gli endpoint OAuth 2.0 di Google per autorizzare l'accesso all'API di dati di YouTube.

OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo privati i nomi utente, le password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione a caricare video sul canale YouTube di un utente.

Le app installate vengono distribuite ai singoli dispositivi e si presume che non possano conservare i segreti. Possono accedere alle API di Google mentre l'utente è presente nell'app o quando l'app è in esecuzione in background.

Questo flusso di autorizzazione è simile a quello utilizzato per le applicazioni server web. La differenza principale è che le app installate devono aprire il browser di sistema e fornire un URI di reindirizzamento locale per gestire le risposte del server di autorizzazione di Google.

Alternative

Per le app mobile, potresti preferire Accedi con Google su Android o iOS. Le librerie client di Accedi con Google gestiscono l'autenticazione e l'autorizzazione degli utenti e potrebbero essere più semplici da implementare rispetto al protocollo di livello inferiore descritto qui.

Per le app in esecuzione su dispositivi che non supportano un browser di sistema o con capacità di input limitate, ad esempio TV, console per videogiochi, fotocamere o stampanti, consulta OAuth 2.0 per TV e dispositivi o Accesso su TV e dispositivi di input con limitazioni.

Librerie ed esempi

Consigliamo le librerie e gli esempi riportati di seguito per aiutarti a implementare il flusso OAuth 2.0 descritto in questo documento:

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiama le API di Google deve abilitare queste API in API Console.

Per abilitare un'API per il tuo progetto:

  1. Open the API Library in Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Utilizza la pagina Raccolta per trovare e attivare l'API di dati di YouTube. Trova eventuali altre API che la tua applicazione utilizzerà e abilita anche quelle.

Crea credenziali di autorizzazione

Qualsiasi applicazione che utilizza OAuth 2.0 per accedere alle API di Google deve avere credenziali di autorizzazione che identificano l'applicazione nel server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il tuo progetto. Le applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per il progetto.

  1. Go to the Credentials page.
  2. Fai clic su Crea credenziali > ID client OAuth.
  3. Le sezioni seguenti descrivono i tipi di client e i metodi di reindirizzamento supportati dal server di autorizzazione di Google. Scegli il tipo di client consigliato per la tua applicazione, assegna un nome al client OAuth e imposta gli altri campi del modulo come appropriato.
Android
  1. Seleziona il tipo di applicazione Android.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella Credentials page del progetto per identificare il client.
  3. Inserisci il nome del pacchetto della tua app Android. Questo valore è definito nell' attributo package dell'elemento <manifest> nel file manifest dell'app.
  4. Inserisci l'impronta digitale del certificato di firma SHA-1 della distribuzione dell'app.
    • Se la tua app utilizza la firma dell'app di Google Play, copia l'impronta SHA-1 dalla pagina di firma dell'app di Play Console.
    • Se gestisci il tuo archivio chiavi e le chiavi di firma, utilizza l'utilità keytool inclusa in Java per stampare le informazioni dei certificati in un formato leggibile. Copia il valore SHA1 nella sezione Certificate fingerprints dell'output keytool. Per ulteriori informazioni, consulta Autenticazione del client nella documentazione delle API di Google per Android.
  5. (Facoltativo) Verifica la proprietà della tua applicazione per Android.
  6. Fai clic su Crea.
iOS
  1. Seleziona il tipo di applicazione iOS.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella Credentials page del progetto per identificare il client.
  3. Inserisci l'identificatore bundle per l'app. L'ID bundle è il valore della chiave CFBundleIdentifier nel file di risorse dell'elenco di risorse delle informazioni dell'app (info.plist). Il valore viene visualizzato più di frequente nel riquadro Generale o nel riquadro Firma e funzionalità dell'editor di progetto Xcode. L'ID pacchetto viene visualizzato anche nella sezione Informazioni generali della pagina Informazioni sull'app per l'app sul sito App Store Connect di Apple.
  4. (Facoltativo)

    Inserisci l'ID App Store della tua app se è stata pubblicata nell'App Store di Apple. L'ID store è una stringa numerica inclusa in ogni URL dell'App Store di Apple.

    1. Apri l'app Apple App Store sul tuo dispositivo iOS o iPadOS.
    2. Cerca la tua app.
    3. Seleziona il pulsante Condividi (simbolo quadrato e freccia su).
    4. Seleziona Copia link.
    5. Incolla il link in un editor di testo. L'ID App Store è la parte finale dell'URL.

      Esempio: https://apps.apple.com/app/google/id284815942

  5. (Facoltativo)

    Inserisci il tuo ID team. Per saperne di più, consulta la sezione su come trovare il tuo ID team nella documentazione relativa all'account sviluppatore Apple.

  6. Fai clic su Crea.
UWP
  1. Seleziona il tipo di applicazione Piattaforma Windows Universal.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella Credentials page del progetto per identificare il client.
  3. Inserisci l'ID Microsoft Store di 12 caratteri della tua app. Puoi trovare questo valore nel Centro partner di Microsoft nella pagina Identità app nella sezione Gestione app.
  4. Fai clic su Crea.

Per le app UWP, lo schema dell'URI personalizzato non può contenere più di 39 caratteri.

Schema URI personalizzato (Android, iOS, UWP)

Gli schemi URI personalizzati sono una forma di link diretti che utilizzano uno schema definito personalizzato per aprire la tua app.

Alternativa all'utilizzo degli schemi URI personalizzati su Android

Utilizza l'SDK Accedi con Google per Android che invia la risposta OAuth 2.0 direttamente alla tua app, eliminando la necessità di un URI di reindirizzamento.

Come eseguire la migrazione all'SDK Accedi con Google per Android

Se al momento utilizzi uno schema personalizzato per l'integrazione OAuth su Android, devi completare le azioni seguenti per eseguire la migrazione completa utilizzando l'SDK consigliato Accedi con Google per Android:

  1. Aggiorna il codice per utilizzare l'SDK Accedi con Google.
  2. Disattiva il supporto per lo schema personalizzato nella console API di Google.

Per eseguire la migrazione all'SDK Android Accedi con Google:

  1. Aggiorna il codice per utilizzare l'SDK Accedi con Google per Android:
    1. Esamina il codice per identificare dove stai inviando una richiesta al server OAuth 2.0 di Google. Se utilizzi uno schema personalizzato, la richiesta avrà il seguente aspetto:
        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        
      com.example.app:/oauth2redirect è l'URI di reindirizzamento dello schema personalizzato nell'esempio riportato sopra. Per ulteriori dettagli sul formato del valore dello schema dell'URI personalizzato, consulta la definizione del parametro redirect_uri.
    2. Prendi nota dei parametri di richiesta scope e client_id necessari per configurare l'SDK Accedi con Google.
    3. Segui le istruzioni per iniziare a integrare l'opzione Accedi con Google nella tua app Android per configurare l'SDK. Puoi saltare il passaggio Recupero dell'ID client OAuth 2.0 del tuo server di backend, così come puoi riutilizzare l'elemento client_id recuperato dal passaggio precedente.
    4. Segui le istruzioni per l' abilitazione dell'accesso all'API lato server. Ecco quali sono:
      1. Utilizza il metodo getServerAuthCode per recuperare un codice di autorizzazione per gli ambiti per i quali richiedi l'autorizzazione.
      2. Invia il codice di autenticazione al backend dell'app per scambiarlo con un token di accesso e aggiornamento.
      3. Utilizza il token di accesso recuperato per effettuare chiamate alle API di Google per conto dell'utente.
  2. Disabilita il supporto per lo schema personalizzato nella console API di Google:
    1. Vai all'elenco delle credenziali OAuth 2.0 e seleziona il tuo client Android.
    2. Vai alla sezione Impostazioni avanzate, deseleziona la casella di controllo Abilita schema URI personalizzato e fai clic su Salva per disabilitare il supporto dello schema URI personalizzato.
Abilitazione dello schema URI personalizzato in corso...
Se l'alternativa consigliata non funziona, puoi abilitare gli schemi URI personalizzati per il tuo client Android seguendo le istruzioni riportate di seguito:
  1. Vai all'elenco Credenziali OAuth 2.0 e seleziona il tuo client Android.
  2. Vai alla sezione Impostazioni avanzate, seleziona la casella di controllo Abilita schema URI personalizzato e fai clic su Salva per abilitare il supporto dello schema URI personalizzato.
Alternativa all'utilizzo degli schemi URI personalizzati nelle app di Chrome

Utilizza l'API Chrome Identity che fornisce la risposta OAuth 2.0 direttamente nella tua app, eliminando la necessità di un URI di reindirizzamento.

Verificare la proprietà dell'app (Android, Chrome)

Puoi verificare la proprietà della tua applicazione per ridurre il rischio di furto d'identità.

Android

Per completare la procedura di verifica, puoi utilizzare il tuo account sviluppatore Google Play se ne hai uno e la tua app è registrata su Google Play Console. Per una verifica corretta, devono essere soddisfatti i seguenti requisiti:

  • Devi avere un'applicazione registrata in Google Play Console con lo stesso nome di pacchetto e la stessa impronta digitale del certificato di firma SHA-1 del client OAuth di Android per cui stai completando la verifica.
  • Devi disporre dell'autorizzazione di amministratore per l'app in Google Play Console. Scopri di più sulla gestione degli accessi in Google Play Console.

Nella sezione Verifica la proprietà dell'app del client Android, fai clic sul pulsante Verifica proprietà per completare la procedura di verifica.

Se la verifica ha esito positivo, verrà visualizzata una notifica che conferma il completamento della procedura. In caso contrario, verrà visualizzato un messaggio di errore.

Per correggere una verifica non riuscita, prova a procedere nel seguente modo:

  • Assicurati che l'app che stai verificando sia un'app registrata in Google Play Console.
  • Assicurati di avere l'autorizzazione di amministratore per l'app in Google Play Console.
Chrome

Per completare la procedura di verifica, devi utilizzare il tuo account sviluppatore del Chrome Web Store. Affinché la verifica vada a buon fine, devono essere soddisfatti i seguenti requisiti:

  • Devi avere un elemento registrato nella Dashboard per sviluppatori del Chrome Web Store con lo stesso ID elemento del client OAuth dell'estensione di Chrome per cui stai completando la verifica.
  • Devi essere un publisher dell'articolo del Chrome Web Store. Scopri di più sulla gestione degli accessi nella Dashboard per sviluppatori del Chrome Web Store.

Nella sezione Verifica proprietà dell'app del client dell'estensione di Chrome, fai clic sul pulsante Verifica proprietà per completare la procedura di verifica.

Nota: attendi qualche minuto prima di completare la procedura di verifica dopo aver concesso l'accesso al tuo account.

Se la verifica ha esito positivo, verrà visualizzata una notifica che conferma il completamento della procedura. In caso contrario, verrà visualizzato un messaggio di errore.

Per correggere una verifica non riuscita, prova a procedere nel seguente modo:

  • Assicurati che sia presente un elemento registrato nella Dashboard per sviluppatori del Chrome Web Store con lo stesso ID elemento del client OAuth dell'estensione di Chrome per cui stai completando la verifica.
  • Assicurati di essere un publisher dell'app, ovvero devi essere il singolo publisher dell'app o un membro del publisher del gruppo dell'app. Scopri di più sulla gestione degli accessi nella Dashboard per sviluppatori del Chrome Web Store.
  • Se hai appena aggiornato l'elenco di publisher del gruppo, verifica che l'elenco dei publisher del gruppo sia sincronizzato nella Dashboard per sviluppatori del Chrome Web Store. Scopri di più sulla sincronizzazione dell'elenco di abbonamenti dell'editore.

Indirizzo IP di loopback (macOS, Linux, desktop Windows)

Per ricevere il codice di autorizzazione utilizzando questo URL, l'applicazione deve essere in ascolto sul server web locale. Questo è possibile su molte piattaforme, ma non su tutte. Tuttavia, se la tua piattaforma lo supporta, questo è il meccanismo consigliato per ottenere il codice di autorizzazione.

Quando la tua app riceve la risposta di autorizzazione, per una migliore usabilità dovrebbe rispondere mostrando una pagina HTML che indica all'utente di chiudere il browser e tornare all'app.

Utilizzo consigliato App per macOS, Linux e Windows per desktop (ma non per piattaforma Universal Windows)
Valori del modulo Imposta il tipo di applicazione su App desktop.

Copia/incolla manuale

Identificare gli ambiti di accesso

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo anche agli utenti di controllare la quantità di accesso che concede all'applicazione. Pertanto, potrebbe sussistere una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

Prima di iniziare a implementare l'autorizzazione OAuth 2.0, ti consigliamo di identificare gli ambiti a cui la tua app avrà bisogno dell'autorizzazione per accedere.

La versione 3 dell'API di dati di YouTube utilizza i seguenti ambiti:

Mirini con ingrandimento
https://www.googleapis.com/auth/youtubeGestisci il tuo account YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorVisualizzare un elenco dei tuoi attuali membri attivi del canale, il loro livello corrente e quando sono diventati membri
https://www.googleapis.com/auth/youtube.force-sslVisualizzare, modificare ed eliminare definitivamente video, valutazioni, commenti e sottotitoli di YouTube
https://www.googleapis.com/auth/youtube.readonlyVisualizza il tuo account YouTube
https://www.googleapis.com/auth/youtube.uploadGestisci i tuoi video su YouTube
https://www.googleapis.com/auth/youtubepartnerVisualizzare e gestire le risorse e i relativi contenuti su YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditVisualizzare le informazioni private del tuo canale YouTube pertinenti durante la procedura di revisione con un partner di YouTube

Il documento Ambiti API OAuth 2.0 contiene un elenco completo di ambiti che potresti utilizzare per accedere alle API di Google.

Ottenere i token di accesso OAuth 2.0

I passaggi seguenti mostrano in che modo la tua applicazione interagisce con il server OAuth 2.0 di Google per ottenere il consenso di un utente a eseguire una richiesta API per suo conto. L'applicazione deve avere questo consenso prima di poter eseguire una richiesta API di Google che richiede l'autorizzazione dell'utente.

Passaggio 1: genera uno strumento di verifica del codice e una verifica

Google supporta il protocollo PKCE (Proof Key for Code Exchange) per rendere più sicuro il flusso dell'app installata. Per ogni richiesta di autorizzazione viene creato uno strumento di verifica del codice univoco e il suo valore trasformato, chiamato "code_challenge", viene inviato al server di autorizzazione per ottenere il codice di autorizzazione.

Crea lo strumento di verifica del codice

Una code_verifier è una stringa casuale crittografica ad alta entropia che utilizza i caratteri non riservati [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", con una lunghezza minima di 43 caratteri e una lunghezza massima di 128 caratteri.

Lo strumento di verifica del codice dovrebbe avere un'entropia sufficiente a rendere impossibile indovinare il valore.

Crea la verifica del codice

Sono supportati due metodi per creare la verifica del codice.

Metodi di generazione di sfide di codice
S256 (opzione consigliata) La verifica del codice è l'hash SHA256 codificato in Base64URL (senza spaziatura interna) dello strumento di verifica del codice.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
normale La verifica del codice corrisponde al valore dello strumento di verifica del codice generato in precedenza.
code_challenge = code_verifier

Passaggio 2: invia una richiesta al server OAuth 2.0 di Google

Per ottenere l'autorizzazione dell'utente, invia una richiesta al server di autorizzazione di Google all'indirizzo https://accounts.google.com/o/oauth2/v2/auth. Questo endpoint gestisce la ricerca delle sessioni attive, autentica l'utente e ottiene il consenso dell'utente. L'endpoint è accessibile solo tramite SSL e rifiuta le connessioni HTTP (non SSL).

Il server di autorizzazione supporta i seguenti parametri della stringa di query per le applicazioni installate:

Parametri
client_id Obbligatorio

L'ID client della tua applicazione. Puoi trovare questo valore in API Console Credentials page.

redirect_uri Obbligatorio

Determina la modalità con cui il server di autorizzazione di Google invia una risposta alla tua app. Sono disponibili diverse opzioni di reindirizzamento per le app installate e avrai configurato le credenziali di autorizzazione tenendo conto di un particolare metodo di reindirizzamento.

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 pagedel client. Se questo valore non corrisponde a un URI autorizzato, verrà visualizzato un errore redirect_uri_mismatch.

La tabella seguente mostra il valore del parametro redirect_uri appropriato per ciascun metodo:

redirect_uri valore
Schema URI personalizzato com.example.app:redirect_uri_path

o

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app è la notazione DNS inversa di un dominio che è sotto il tuo controllo. Per essere valido, lo schema personalizzato deve contenere un punto.
  • com.googleusercontent.apps.123 è la notazione DNS inversa dell'ID client.
  • redirect_uri_path è un componente facoltativo del percorso, come /oauth2redirect. Tieni presente che il percorso deve iniziare con una singola barra, diversa dai normali URL HTTP.
Indirizzo IP di loopback http://127.0.0.1:port oppure http://[::1]:port

Esegui una query sulla tua piattaforma per trovare l'indirizzo IP di loopback pertinente e avvia un listener HTTP su una porta disponibile casuale. Sostituisci port con il numero di porta effettivo su cui la tua app è in ascolto.

Tieni presente che il supporto dell'opzione di reindirizzamento dell'indirizzo IP di loopback sulle app mobile è OBSOLETO.

response_type Obbligatorio

Determina se l'endpoint OAuth 2.0 di Google restituisce un codice di autorizzazione.

Imposta il valore del parametro su code per le applicazioni installate.

scope Obbligatorio

Un elenco di ambiti delimitato da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori indicano la schermata per il consenso che Google mostra all'utente.

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare la quantità di accesso che concede alla tua applicazione. Esiste quindi una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

La versione 3 dell'API di dati di YouTube utilizza i seguenti ambiti:

Mirini con ingrandimento
https://www.googleapis.com/auth/youtubeGestisci il tuo account YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorVisualizzare un elenco dei tuoi attuali membri attivi del canale, il loro livello corrente e quando sono diventati membri
https://www.googleapis.com/auth/youtube.force-sslVisualizzare, modificare ed eliminare definitivamente video, valutazioni, commenti e sottotitoli di YouTube
https://www.googleapis.com/auth/youtube.readonlyVisualizza il tuo account YouTube
https://www.googleapis.com/auth/youtube.uploadGestisci i tuoi video su YouTube
https://www.googleapis.com/auth/youtubepartnerVisualizzare e gestire le risorse e i relativi contenuti su YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditVisualizzare le informazioni private del tuo canale YouTube pertinenti durante la procedura di revisione con un partner di YouTube

Il documento Ambiti API OAuth 2.0 fornisce un elenco completo degli ambiti che puoi utilizzare per accedere alle API di Google.

code_challenge Consigliato

Specifica un code_verifier codificato che verrà utilizzato come verifica lato server durante lo scambio del codice di autorizzazione. Consulta la sezione relativa alla creazione di un codice sopra per maggiori informazioni.

code_challenge_method Consigliato

Specifica il metodo utilizzato per codificare un elemento code_verifier che verrà usato durante lo scambio del codice di autorizzazione. Questo parametro deve essere utilizzato con il parametro code_challenge descritto sopra. Il valore predefinito di code_challenge_method è plain se non è presente nella richiesta che include un valore code_challenge. Gli unici valori supportati per questo parametro sono S256 o plain.

state Consigliato

Specifica qualsiasi valore stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione. Il server restituisce il valore esatto che invii come coppia name=value nell'identificatore di frammento di URL (#) di redirect_uri dopo che l'utente ha acconsentito o negato la richiesta di accesso dell'applicazione.

Puoi utilizzare questo parametro per diversi scopi, ad esempio per indirizzare l'utente alla risorsa corretta nell'applicazione, inviare nonce e mitigare la falsificazione delle richieste tra siti. Poiché il redirect_uri può essere intuito, l'utilizzo di un valore state può aumentare la certezza che una connessione in entrata sia il risultato di una richiesta di autenticazione. Se generi una stringa casuale o codifichi l'hash di un cookie o un altro valore che acquisisce lo stato del client, puoi convalidare la risposta per assicurarti inoltre che la richiesta e la risposta abbiano avuto origine dallo stesso browser, fornendo protezione da attacchi come la falsificazione delle richieste tra siti. Consulta la documentazione di OpenID Connect per un esempio di come creare e confermare un token state.

login_hint Facoltativo

Se l'applicazione sa quale utente sta tentando di eseguire l'autenticazione, può utilizzare questo parametro per fornire un suggerimento al server di autenticazione di Google. Il server utilizza il suggerimento per semplificare il flusso di accesso precompilando il campo email nel modulo di accesso o selezionando la sessione di accesso multiplo appropriata.

Imposta il valore del parametro su un indirizzo email o un identificatore sub, che equivale all'ID Google dell'utente.

Esempi di URL di autorizzazione

Le schede riportate di seguito mostrano esempi di URL di autorizzazione per le diverse opzioni dell'URI di reindirizzamento.

Ogni URL richiede l'accesso a un ambito che permette di visualizzare l'account YouTube dell'utente.

Gli URL sono identici, tranne che per il valore del parametro redirect_uri. Gli URL contengono anche i parametri obbligatori response_type e client_id, nonché il parametro facoltativo state. Ogni URL contiene interruzioni di riga e spazi per una maggiore leggibilità.

Schema URI personalizzato

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

Indirizzo IP di loopback

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Passaggio 3: Google chiede all'utente il consenso

In questo passaggio, l'utente decide se concedere alla tua applicazione l'accesso richiesto. In questa fase, Google mostra una finestra per il consenso che mostra il nome della tua applicazione e i servizi API di Google per cui richiede l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente, oltre a un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire a concedere l'accesso a uno o più ambiti richiesti dalla tua applicazione o rifiutare la richiesta.

L'applicazione non deve fare nulla in questa fase perché attende la risposta dal server OAuth 2.0 di Google che indica se è stato concesso un accesso. Questa risposta è spiegata nel passaggio seguente.

Errori

Le richieste agli endpoint di autorizzazione OAuth 2.0 di Google potrebbero mostrare messaggi di errore rivolti agli utenti anziché i flussi di autenticazione e autorizzazione previsti. Di seguito sono elencati i codici di errore comuni e le risoluzioni suggerite.

admin_policy_enforced

L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa delle norme dell'amministratore di Google Workspace. Per saperne di più su come un amministratore può limitare l'accesso a tutti gli ambiti o agli ambiti sensibili e con restrizioni, consulta l'articolo del Centro assistenza per amministratori di Google Workspace Stabilire quali app di terze parti e interne possono accedere ai dati di Google Workspace per maggiori informazioni su come un amministratore può limitare l'accesso a tutti gli ambiti o a quelli sensibili e con restrizioni finché l'accesso non viene concesso esplicitamente al tuo ID client OAuth.

disallowed_useragent

L'endpoint di autorizzazione viene visualizzato all'interno di uno user agent incorporato non consentito dai criteri OAuth 2.0 di Google.

Android

Gli sviluppatori Android potrebbero visualizzare questo messaggio di errore durante l'apertura delle richieste di autorizzazione in android.webkit.WebView. Gli sviluppatori dovrebbero usare librerie Android come Accedi con Google per Android o AppAuth per Android di OpenID Foundation.

Gli sviluppatori web potrebbero riscontrare questo errore quando un'app per Android apre un link web generale in uno user agent incorporato e un utente accede all'endpoint di autorizzazione OAuth 2.0 di Google dal tuo sito. Gli sviluppatori dovrebbero consentire l'apertura dei link generali nel gestore dei link predefinito del sistema operativo, che include i gestori Link per app Android o l'app browser predefinita. Anche la libreria Schede personalizzate Android è un'opzione supportata.

iOS

Gli sviluppatori iOS e macOS potrebbero riscontrare questo errore durante l'apertura delle richieste di autorizzazione in WKWebView. Gli sviluppatori dovrebbero usare invece librerie iOS come Accedi con Google per iOS o AppAuth per iOS di OpenID Foundation.

Gli sviluppatori web potrebbero riscontrare questo errore quando un'app per iOS o macOS apre un link web generale in uno user agent incorporato e un utente accede all'endpoint di autorizzazione OAuth 2.0 di Google dal tuo sito. Gli sviluppatori dovrebbero consentire l'apertura dei link generali nel gestore dei link predefinito del sistema operativo, che include i gestori Link universali o l'app browser predefinita. Anche la libreria SFSafariViewController è un'opzione supportata.

org_internal

L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una organizzazione Google Cloud specifica. Per ulteriori informazioni su questa opzione di configurazione, consulta la sezione Tipo di utente nell'articolo del Centro assistenza sulla schermata per il consenso OAuth.

invalid_grant

Se utilizzi una verifica del codice e una verifica, il parametro code_callenge non è valido o non è presente. Assicurati che il parametro code_challenge sia impostato correttamente.

Durante l'aggiornamento di un token di accesso, questo potrebbe essere scaduto o essere stato invalidato. Autentica di nuovo l'utente e chiedi il suo consenso per ottenere nuovi token. Se continui a visualizzare questo errore, assicurati che l'applicazione sia stata configurata correttamente e che tu stia utilizzando i token e i parametri corretti nella richiesta. In caso contrario, l'account utente potrebbe essere stato eliminato o disattivato.

redirect_uri_mismatch

Il valore redirect_uri passato nella richiesta di autorizzazione non corrisponde a un URI di reindirizzamento autorizzato per l'ID client OAuth. Esamina gli URI di reindirizzamento autorizzati in Google API Console Credentials page.

Il valore redirect_uri trasmesso potrebbe non essere valido per il tipo di client.

Il parametro redirect_uri può fare riferimento al flusso OAuth fuori banda (OOB) che è stato deprecato e non è più supportato. Per aggiornare l'integrazione, consulta la guida alla migrazione.

invalid_request

Si è verificato un problema con la richiesta che hai effettuato. Ciò potrebbe essere dovuto a una serie di motivi:

  • La richiesta non è stata formattata correttamente
  • Nella richiesta mancano parametri obbligatori
  • La richiesta utilizza un metodo di autorizzazione non supportato da Google. Verifica che l'integrazione OAuth utilizzi un metodo di integrazione consigliato
  • Per l'URI di reindirizzamento viene utilizzato uno schema personalizzato. Se viene visualizzato il messaggio di errore Lo schema URI personalizzato non è supportato nelle app di Chrome o Lo schema URI personalizzato non è abilitato per il client Android, significa che stai utilizzando uno schema URI personalizzato non supportato nelle app di Chrome e disattivato per impostazione predefinita su Android. Scopri di più sulle alternative agli schemi URI personalizzati

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui l'applicazione riceve la risposta di autorizzazione dipende dallo schema dell'URI di reindirizzamento che utilizza. Indipendentemente dallo schema, la risposta conterrà un codice di autorizzazione (code) o un errore (error). Ad esempio, error=access_denied indica che l'utente ha rifiutato la richiesta.

Se l'utente concede l'accesso alla tua applicazione, puoi scambiare il codice di autorizzazione con un token di accesso e un token di aggiornamento, come descritto nel passaggio successivo.

Passaggio 5: scambia il codice di autorizzazione per i token di aggiornamento e di accesso

Per scambiare un codice di autorizzazione con un token di accesso, chiama l'endpoint https://oauth2.googleapis.com/token e imposta i seguenti parametri:

Campi
client_id L'ID client ottenuto da API Console Credentials page.
client_secret Il client secret ottenuto da API Console Credentials page.
code Il codice di autorizzazione restituito dalla richiesta iniziale.
code_verifier Lo strumento di verifica del codice che hai creato nel Passaggio 1.
grant_type Come definito nella specifica OAuth 2.0, il valore di questo campo deve essere impostato su authorization_code.
redirect_uri Uno degli URI di reindirizzamento elencati per il tuo progetto in API Console Credentials page per il client_id specificato.

Lo snippet seguente mostra una richiesta di 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=http://127.0.0.1:9004&
grant_type=authorization_code

Google risponde a questa richiesta restituendo un oggetto JSON contenente un token di accesso di breve durata e un token di aggiornamento.

La risposta contiene i seguenti campi:

Campi
access_token Il token inviato dall'applicazione per autorizzare una richiesta API di Google.
expires_in La durata rimanente del token di accesso, in secondi.
id_token Nota: questa proprietà viene restituita solo se la tua richiesta includeva un ambito dell'identità, ad esempio openid, profile o email. Il valore è un token JWT (JSON Web Token) che contiene informazioni sull'identità dell'utente con firma digitale.
refresh_token Un token che puoi utilizzare per ottenere un nuovo token di accesso. I token di aggiornamento sono validi finché l'utente non revoca l'accesso. Tieni presente che i token di aggiornamento vengono sempre restituiti per le applicazioni installate.
scope Gli ambiti di accesso concessi da access_token espressi sotto forma di elenco di stringhe sensibili alle maiuscole e delimitate da spazi.
token_type Il tipo di token restituito. Al momento, il valore di questo campo è sempre impostato su Bearer.

Lo snippet seguente mostra una risposta di esempio:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Chiamata alle API di Google

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzare il token per effettuare chiamate a un'API di Google per conto di un determinato account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. A questo scopo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile utilizzare l'intestazione HTTP, in quanto le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi, puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, durante la chiamata all'API di dati di YouTube).

Tieni presente che l'API di dati di YouTube supporta gli account di servizio solo per i proprietari di contenuti di YouTube che possiedono e gestiscono più canali YouTube, come case discografiche e studi cinematografici.

Puoi provare tutte le API di Google e visualizzarne gli ambiti in OAuth 2.0 Playground.

Esempi di HTTP GET

Una chiamata all'endpoint youtube.channels (l'API di dati di YouTube) che utilizza l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare il tuo token di accesso:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Di seguito è riportata una chiamata alla stessa API per l'utente autenticato utilizzando il parametro della stringa di query access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Esempi di curl

Puoi testare questi comandi con l'applicazione a riga di comando curl. Ecco un esempio che utilizza l'opzione dell'intestazione HTTP (preferita):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

In alternativa, l'opzione del parametro della stringa di query:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Aggiornare un token di accesso

I token di accesso scadono periodicamente e diventano credenziali non valide per una richiesta API correlata. Puoi aggiornare un token di accesso senza chiedere all'utente l'autorizzazione (anche quando l'utente non è presente) se hai richiesto l'accesso offline agli ambiti associati al token.

Per aggiornare un token di accesso, l'applicazione invia una richiesta POST HTTPS al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che include i seguenti parametri:

Campi
client_id L'ID client ottenuto da API Console.
client_secret Il client secret ottenuto da API Console. (client_secret non è applicabile alle richieste dei client registrati come applicazioni Android, iOS o Chrome).
grant_type Come definito nella specifica OAuth 2.0, il valore di questo campo deve essere impostato su refresh_token.
refresh_token Il token di aggiornamento restituito dallo scambio di codici di autorizzazione.

Lo snippet seguente mostra una richiesta di esempio:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Se l'utente non ha revocato l'accesso concesso all'applicazione, il server token restituisce un oggetto JSON contenente un nuovo token di accesso. Lo snippet seguente mostra una risposta di esempio:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Tieni presente che sono previsti limiti al numero di token di aggiornamento che verranno emessi: un limite per combinazione client/utente e un altro per utente in tutti i client. Dovresti salvare i token di aggiornamento nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se l'applicazione richiede troppi token di aggiornamento, potrebbe raggiungere questi limiti, nel qual caso i token di aggiornamento precedenti smetteranno di funzionare.

Revoca di un token

In alcuni casi un utente può voler revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le Impostazioni account. Per maggiori informazioni, consulta la sezione dedicata alla rimozione dell'accesso a siti o app del documento di assistenza su siti e app di terze parti con accesso al tuo account.

È anche possibile che un'applicazione revochi in modo programmatico l'accesso concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse API richieste da un'app sono cambiate in modo significativo. In altre parole, parte del processo di rimozione può includere una richiesta API per garantire che le autorizzazioni concesse in precedenza all'applicazione vengano rimosse.

Per revocare un token in modo programmatico, l'applicazione effettua una richiesta a https://oauth2.googleapis.com/revoke e include il token come parametro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Il token può essere un token di accesso o un token di aggiornamento. Se il token è un token di accesso e ha un token di aggiornamento corrispondente, verrà revocato anche il token di aggiornamento.

Se la revoca viene elaborata correttamente, il codice di stato HTTP della risposta è 200. Per le condizioni di errore, viene restituito un codice di stato HTTP 400 insieme a un codice di errore.

Per approfondire

La best practice attuale di IETF OAuth 2.0 per le app native stabilisce molte delle best practice qui documentate.