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 YouTube Data.
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 su singoli dispositivi e si presume che queste app non possano mantenere secret. 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 dal server di autorizzazione di Google.
Alternative
Per le app mobile, è preferibile utilizzare Accedi con Google per Android o iOS. Le librerie client di Accedi con Google gestiscono l'autenticazione e l'autorizzazione utente 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 funzionalità di input limitate, come TV, console per videogiochi, videocamere o stampanti, consulta OAuth 2.0 per TV e dispositivi o Accesso su TV e dispositivi a input limitato.
Librerie ed esempi
Consigliamo le librerie e gli esempi seguenti per aiutarti a implementare il flusso OAuth 2.0 descritto in questo documento:
- Libreria AppAuth per Android
- Libreria AppAuth per iOS
- OAuth per le app: esempi di Windows
Prerequisiti
Abilita le API per il progetto
Qualsiasi applicazione che chiama le API di Google deve abilitare queste API in API Console.
Per abilitare un'API per il tuo progetto:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- Utilizza la pagina Raccolta per trovare e attivare l'API YouTube Data. Trova e abilita anche le altre API utilizzate dalla tua applicazione.
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 sul 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 abilitate per il progetto.
- Go to the Credentials page.
- Fai clic su Crea credenziali > ID client OAuth.
- 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
- Seleziona il tipo di applicazione per Android.
- Inserisci un nome per il client OAuth. Questo nome viene visualizzato in Credentials page del progetto per identificare il client.
- Inserisci il nome del pacchetto della tua app per Android. Questo valore è definito nell'
attributo
package
dell'elemento<manifest>
nel file manifest dell'app. - 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 tue chiavi di firma, utilizza l'utilità keytool inclusa in Java per stampare le informazioni del certificato in un formato leggibile. Copia il
valore
SHA1
nella sezioneCertificate fingerprints
dell'output keytool. Per ulteriori informazioni, vedi Autenticazione del client nella documentazione delle API di Google per Android.
- (Facoltativo) Verifica la proprietà della tua applicazione Android.
- Fai clic su Crea.
iOS
- Seleziona il tipo di applicazione iOS.
- Inserisci un nome per il client OAuth. Questo nome viene visualizzato in Credentials page del progetto per identificare il client.
- Inserisci l'identificatore pacchetto per l'app. L'ID pacchetto è il valore della chiave CFBundleIdentifier nel file di risorse dell'elenco delle proprietà di informazioni dell'app (info.plist). Il valore viene visualizzato più di frequente nel riquadro General (Generale) o nel riquadro Signing & Capabilities (Firma e funzionalità) dell'editor del 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.
- (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.
- Apri l'app Apple App Store sul tuo dispositivo iOS o iPadOS.
- Cerca la tua app.
- Seleziona il pulsante Condividi (simbolo quadrato e freccia su).
- Seleziona Copia link.
- 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
- (Facoltativo)
Inserisci il tuo ID team. Per maggiori informazioni, consulta Individuare l'ID team nella documentazione dell'account sviluppatore Apple.
- Fai clic su Crea.
UWP
- Seleziona il tipo di applicazione Piattaforma Universal Windows.
- Inserisci un nome per il client OAuth. Questo nome viene visualizzato in Credentials page del progetto per identificare il client.
- Inserisci l'ID Microsoft Store di 12 caratteri dell'app. Puoi trovare questo valore nel Centro partner Microsoft nella pagina Identità app nella sezione Gestione app.
- 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 di URI personalizzati sono una forma di link diretti che utilizzano uno schema personalizzato per aprire la tua app.
Alternativa all'utilizzo di schemi URI personalizzati su AndroidUtilizza l'SDK Accedi con Google per Android, che fornisce 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 all'utilizzo dell'SDK Accedi con Google per Android consigliato:
- Aggiorna il codice per utilizzare l'SDK Accedi con Google.
- Disattiva il supporto per lo schema personalizzato nella console API di Google.
Segui questi passaggi per eseguire la migrazione all'SDK Accedi con Google per Android:
-
Aggiorna il codice per utilizzare l'SDK di Accedi con Google per Android:
-
Esamina il codice per identificare dove stai
inviando una richiesta al server OAuth 2.0 di Google. Se utilizzi uno schema personalizzato, la richiesta sarà simile a quella riportata di seguito:
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 precedente. Consulta la definizione del parametroredirect_uri
per ulteriori dettagli sul formato del valore dello schema dell'URI personalizzato. -
Prendi nota dei parametri della richiesta
scope
eclient_id
necessari per configurare l'SDK Accedi con Google. -
Segui le istruzioni
Inizia a integrare l'opzione Accedi con Google nell'app per Android
per configurare l'SDK. Puoi saltare il passaggio Recuperare l'ID client OAuth 2.0 del server di backend perché riutilizzeresti il
client_id
recuperato nel passaggio precedente. -
Segui le istruzioni per
abilitare l'accesso all'API lato server. Sono inclusi i seguenti passaggi:
-
Utilizza il metodo
getServerAuthCode
per recuperare un codice di autorizzazione per gli ambiti per cui richiedi l'autorizzazione. - Invia il codice di autorizzazione al backend dell'app per scambiarlo con un token di accesso e aggiornamento.
- Utilizza il token di accesso recuperato per effettuare chiamate alle API di Google per conto dell'utente.
-
Utilizza il metodo
-
Esamina il codice per identificare dove stai
inviando una richiesta al server OAuth 2.0 di Google. Se utilizzi uno schema personalizzato, la richiesta sarà simile a quella riportata di seguito:
-
Disabilita il supporto per lo schema personalizzato nella console API di Google:
- Vai all'elenco Credenziali OAuth 2.0 e seleziona il tuo client Android.
- Vai alla sezione Impostazioni avanzate, deseleziona la casella di controllo Abilita schema URI personalizzato e fai clic su Salva per disattivare il supporto dello schema URI personalizzato.
Abilitazione dello schema URI personalizzato
Se l'alternativa consigliata non funziona, puoi attivare gli schemi URI personalizzati per il tuo client Android seguendo le istruzioni riportate di seguito:- Vai all'elenco Credenziali OAuth 2.0 e seleziona il tuo client Android.
- Vai alla sezione Impostazioni avanzate, seleziona la casella di controllo Abilita schema URI personalizzato e fai clic su Salva per attivare il supporto dello schema URI personalizzato.
Utilizza l'API Chrome Identity, che fornisce la risposta OAuth 2.0 direttamente alla 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 usare il tuo account sviluppatore Google Play se ne hai uno e la tua app è registrata su Google Play Console. Affinché la verifica vada a buon fine, 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 del certificato di firma SHA-1 del client OAuth per Android per cui stai completando la verifica.
- Devi avere l'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 per confermare l'esito positivo 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 la proprietà dell'app del client dell'estensione di Chrome, fai clic sul pulsante Verifica proprietà per completare la procedura di verifica.
Nota:attendi alcuni minuti 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 per confermare l'esito positivo 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 nella Dashboard per sviluppatori del Chrome Web Store sia presente un elemento registrato con lo stesso ID elemento del client OAuth dell'estensione di Chrome per il quale 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 dei publisher del gruppo, verifica che quest'ultimo sia sincronizzato nella Dashboard per sviluppatori del Chrome Web Store. Scopri di più sulla sincronizzazione dell'elenco dei membri del publisher.
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. Ciò è 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 l'app riceve la risposta di autorizzazione, per una migliore usabilità deve rispondere mostrando una pagina HTML che indica all'utente di chiudere il browser e tornare all'app.
Utilizzo consigliato | App macOS, Linux e Windows Desktop (ma non Universal Windows Platform) |
Valori modulo | Imposta il tipo di applicazione su App desktop. |
Copia/incolla manuale
Identifica gli ambiti di accesso
Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare il livello di accesso che concedono all'applicazione. Pertanto, potrebbe esistere una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso degli utenti.
Prima di iniziare a implementare l'autorizzazione OAuth 2.0, ti consigliamo di identificare gli ambiti a cui la tua app dovrà disporre dell'autorizzazione per accedere.
La YouTube Data API v3 utilizza i seguenti ambiti:
Mirini con ingrandimento | |
---|---|
https://www.googleapis.com/auth/youtube | Gestisci il tuo account YouTube |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | Visualizzare 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-ssl | Visualizzare, modificare ed eliminare definitivamente video, valutazioni, commenti e sottotitoli di YouTube |
https://www.googleapis.com/auth/youtube.readonly | Visualizza il tuo account YouTube |
https://www.googleapis.com/auth/youtube.upload | Gestisci i tuoi video su YouTube |
https://www.googleapis.com/auth/youtubepartner | Visualizzare e gestire le risorse e i relativi contenuti su YouTube |
https://www.googleapis.com/auth/youtubepartner-channel-audit | Visualizzare 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 degli 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. La tua 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 e verifica del codice
Google supporta il protocollo Proof Key for Code Exchange (PKCE) per rendere più sicuro il flusso delle app installate. Per ogni richiesta di autorizzazione viene creato uno strumento di verifica univoco del codice 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
Un code_verifier
è una stringa casuale con elevata 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 deve avere un'entropia sufficiente per rendere impossibile indovinare il valore.
Crea la verifica del codice
Sono supportati due metodi di creazione della verifica del codice.
Metodi di generazione delle sfide del codice | |
---|---|
S256 (consigliato) | La verifica del codice è l'hash SHA256 codificato Base64URL (senza spaziatura interna) dello strumento di verifica del codice.
|
normale | La verifica del codice corrisponde al valore dello strumento di verifica del codice generato in precedenza.
|
Passaggio 2: invia una richiesta al server OAuth 2.0 di Google
Per ottenere l'autorizzazione degli utenti, invia una richiesta al server di autorizzazione di Google all'indirizzo
https://accounts.google.com/o/oauth2/v2/auth
. Questo endpoint gestisce la ricerca di 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 dell'applicazione. Puoi trovare questo valore nella sezione API Console Credentials page. |
||||||||||||||||
redirect_uri |
Obbligatorio
Determina il modo in 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 in considerazione un determinato 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, riceverai un errore La tabella seguente mostra il valore del parametro
|
||||||||||||||||
response_type |
Obbligatorio
Determina se l'endpoint Google OAuth 2.0 restituisce un codice di autorizzazione. Imposta il valore del parametro su |
||||||||||||||||
scope |
Obbligatorio
Un elenco di ambiti delimitato da spazi che identificano le risorse a cui l'applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di consenso che Google mostra all'utente. Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare il livello di accesso che concedono all'applicazione. Pertanto, esiste una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso degli utenti. La YouTube Data API v3 utilizza i seguenti ambiti:
Il documento Ambiti API OAuth 2.0 fornisce un elenco completo degli ambiti che potresti utilizzare per accedere alle API di Google. |
||||||||||||||||
code_challenge |
Consigliato
Specifica un valore |
||||||||||||||||
code_challenge_method |
Consigliato
Specifica il metodo utilizzato per codificare un elemento |
||||||||||||||||
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 Puoi utilizzare questo parametro per diversi scopi, ad esempio indirizzare l'utente alla risorsa corretta nell'applicazione, inviare nonce e ridurre la falsificazione delle richieste tra siti. Poiché |
||||||||||||||||
login_hint |
Facoltativo
Se la tua 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 con accesso multiplo appropriata. Imposta il valore del parametro su un indirizzo email o un identificatore |
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 consente l'accesso per visualizzare l'account YouTube dell'utente.Gli URL sono identici, ad eccezione del valore del parametro redirect_uri
. Gli URL
contengono anche i parametri response_type
e client_id
obbligatori, nonché il
parametro facoltativo state
. Ogni URL contiene interruzioni di riga e spazi per una migliore 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 richiede il consenso all'utente
In questo passaggio, l'utente deciderà se concedere alla tua applicazione l'accesso richiesto. In questa fase, Google mostra una finestra di consenso che mostra il nome della tua applicazione e dei servizi API di Google per i quali richiede l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente e un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire alla concessione dell'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 all'endpoint di autorizzazione OAuth 2.0 di Google potrebbero visualizzare 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 soluzioni suggerite.
admin_policy_enforced
L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dei criteri dell'amministratore di Google Workspace. Consulta l'articolo del Centro assistenza per amministratori di Google Workspace Specificare quali app di terze parti e interne possono accedere ai dati 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 finché l'accesso non viene concesso esplicitamente all'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 quando aprono le richieste di autorizzazione in
android.webkit.WebView
.
Gli sviluppatori devono invece 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 devono consentire l'apertura dei link generali nel gestore di link predefinito del sistema operativo, che include sia i gestori Link per app Android sia l'app browser predefinita. È supportata anche la raccolta Schede personalizzate Android.
iOS
Gli sviluppatori iOS e macOS potrebbero riscontrare questo errore quando aprono le richieste di autorizzazione in
WKWebView
.
Gli sviluppatori devono invece utilizzare 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 devono consentire l'apertura dei link generali nel gestore di link predefinito del sistema operativo, che include sia i gestori Universal Links sia l'app browser predefinita. È supportata anche la libreria SFSafariViewController
.
org_internal
L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una specifica organizzazione Google Cloud. Per maggiori informazioni su questa opzione di configurazione, consulta la sezione Tipo di utente nell'articolo del Centro assistenza Configurare la schermata per il consenso OAuth.
invalid_grant
Se utilizzi uno strumento di verifica e verifica del codice, il parametro code_callenge
non è valido o non è presente. Assicurati che il parametro code_challenge
sia impostato correttamente.
Quando aggiorni un token di accesso, il token potrebbe essere scaduto o non essere più valido. Autentica di nuovo l'utente e richiedi il consenso dell'utente per ottenere nuovi token. Se continui a visualizzare questo errore, assicurati che l'applicazione sia stata configurata correttamente e di utilizzare 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
trasmesso 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
potrebbe fare riferimento al flusso OAuth out-of-band (OOB) che è stato
deprecato e non è più supportato. Consulta la
guida alla migrazione per aggiornare la tua
integrazione.
invalid_request
Si è verificato un problema nella richiesta che hai inviato. Ciò potrebbe essere dovuto a una serie di motivi:
- La richiesta non è formattata correttamente
- Nella richiesta mancano dei 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 dell'URI personalizzato non è supportato nelle app di Chrome o lo schema dell'URI personalizzato non è abilitato per il tuo client Android, significa che stai utilizzando uno schema di URI personalizzato che non è supportato nelle app di Chrome ed è 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 utilizzato. 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 all'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 che contiene un token di accesso di breve durata e un token di aggiornamento.
La risposta contiene i seguenti campi:
Campi | |
---|---|
access_token |
Il token che l'applicazione invia 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 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à con firma digitale
dell'utente. |
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 come elenco di stringhe delimitate da spazi e sensibili alle maiuscole. |
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 utilizzarlo 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. Per farlo, 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, quando chiami l'API YouTube Data).
Tieni presente che la YouTube Data API supporta gli account di servizio solo per i proprietari di contenuti YouTube che possiedono e gestiscono più canali YouTube, come le case discografiche e gli studi cinematografici.
Puoi provare tutte le API di Google e visualizzarne gli ambiti nel OAuth 2.0 Playground.
Esempi GET HTTP
Una chiamata all'endpoint
youtube.channels
(l'API YouTube Data) utilizzando l'intestazione HTTP Authorization: Bearer
potrebbe essere simile alla seguente. Tieni presente che devi specificare un tuo token di accesso:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Ecco 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
curl
esempi
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
Oppure, 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
Aggiornamento di un token di accesso
I token di accesso scadono periodicamente e diventano credenziali non valide per una richiesta API correlata. Se hai richiesto l'accesso offline agli ambiti associati al token, puoi aggiornare un token di accesso senza richiedere l'autorizzazione all'utente (anche quando l'utente non è presente).
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.
(Il client_secret non si applica alle richieste provenienti da client registrati come
applicazioni per 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 del codice 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 dei limiti al numero di token di aggiornamento che verranno emessi: un limite per ogni combinazione client/utente e un altro per utente per 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 imbattersi in questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.
Revoca di un token
In alcuni casi un utente potrebbe decidere di revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le Impostazioni account. Per ulteriori informazioni, consulta la sezione relativa alla rimozione dell'accesso di siti o app del documento di assistenza per siti e app di terze parti con accesso al tuo account.
È anche possibile che un'applicazione revoca in modo programmatico l'accesso concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione o rimuove un'applicazione oppure 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 precedentemente concesse all'applicazione vengano rimosse.
Per revocare un token in modo programmatico, l'applicazione invia 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
Il protocollo OAuth 2.0 per app native delle best practice correnti dell'IETF definisce molte delle best practice qui documentate.