Questo documento spiega come le applicazioni installate su dispositivi come smartphone, tablet e computer utilizzano gli endpoint OAuth 2.0 di Google per autorizzare l'accesso all'API YouTube Analytics o all'API di reporting di YouTube.
OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo privati i propri nomi utente, le password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione a recuperare i dati di YouTube Analytics di un canale.
Le app installate vengono distribuite ai singoli dispositivi e si presume che queste app non possano mantenere 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.
Librerie ed esempi
Per le app per iOS, ti consigliamo di utilizzare l'ultima versione dell' SDK Accedi con Google per iOS. L'SDK gestisce l'autorizzazione utente ed è più semplice da implementare rispetto al protocollo di livello inferiore descritto in questa guida.
Per le app in esecuzione su dispositivi che non supportano un browser di sistema o che hanno funzionalità di input limitate, come TV, console per videogiochi, videocamere o stampanti, vedi OAuth 2.0 per TV e dispositivi o Accesso su TV e dispositivi con input limitato.
Prerequisiti
Abilitare le API per il progetto
Qualsiasi applicazione che chiama le API di Google deve abilitarle nella console API.
Per abilitare un'API per il tuo progetto:
- Apri la libreria API nella console API di Google.
- Se richiesto, seleziona un progetto o creane uno nuovo.
- Utilizza la pagina Libreria per trovare e abilitare l'API YouTube Analytics e l'API di reporting di YouTube. Molte applicazioni che recuperano i dati di YouTube Analytics interagiscono anche con l'API YouTube Data. Trova altre API che la tua applicazione utilizzerà e abilita anche queste.
Crea le credenziali di autorizzazione
Qualsiasi applicazione che utilizza OAuth 2.0 per accedere alle API di Google deve disporre di credenziali di autorizzazione che identificano l'applicazione sul server OAuth 2.0 di Google. I seguenti passaggi spiegano come creare le credenziali per il tuo progetto. Le tue applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per il progetto.
- Vai alla pagina Clienti.
- Fai clic su Crea client.
- Le sezioni seguenti descrivono i tipi di client 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 in modo appropriato.
iOS
- Seleziona il tipo di applicazione iOS.
- Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella pagina Clienti del progetto per identificare il cliente.
- Inserisci l'identificatore pacchetto per la tua app. L'ID pacchetto è il valore della chiave
CFBundleIdentifier
nel file di risorse dell'elenco delle proprietà delle informazioni dell'app (info.plist). Il valore
viene visualizzato più comunemente 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 app per l'app sul
sito App Store Connect di Apple.
Verifica di utilizzare l'ID pacchetto corretto per la tua app, in quanto non potrai modificarlo se utilizzi la funzionalità App Check.
- (Facoltativo)
Inserisci l'ID App Store della tua app se è 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 (quadrato e simbolo della freccia verso l'alto).
- Seleziona Copia link.
- Incolla il link in un editor di testo. L'ID App Store è l'ultima parte dell'URL.
Esempio:
https://apps.apple.com/app/google/id284815942
- (Facoltativo)
Inserisci l'ID team. Per saperne di più, consulta Trovare l'ID team nella documentazione dell'account sviluppatore Apple.
Nota:il campo ID team è obbligatorio se stai abilitando App Check per il tuo client. - (Facoltativo)
Attiva App Check per la tua app per iOS. Quando attivi App Check, il servizio App Attest di Apple viene utilizzato per verificare che le richieste OAuth 2.0 provenienti dal tuo client OAuth siano autentiche e provengano dalla tua app. In questo modo si riduce il rischio di rappresentazione dell'app. Scopri di più su come attivare App Check per la tua app per iOS.
- Fai clic su Crea.
UWP
- Seleziona il tipo di applicazione Universal Windows Platform.
- Inserisci un nome per il client OAuth. Questo nome viene visualizzato nel del progetto per identificare il cliente.
- Inserisci l'ID Microsoft Store di 12 caratteri della tua app. Puoi trovare questo valore in Microsoft Partner Center nella pagina Identità app della sezione Gestione app.
- Fai clic su Crea.
Per le app UWP, l'URI di reindirizzamento viene creato utilizzando l'identificatore di sicurezza del pacchetto (SID) univoco dell'applicazione. Puoi trovare il Package SID della tua app nel
file Package.appxmanifest all'interno del progetto Visual Studio.
Quando crei l'ID client nella console Google Cloud, devi specificare l'URI di reindirizzamento nel seguente formato, utilizzando il valore in minuscolo del SID pacchetto:
ms-app://YOUR_APP_PACKAGE_SID
Per le app UWP, lo schema URI personalizzato non può superare i 39 caratteri, come specificato nella documentazione di Microsoft.
Identificare gli ambiti di accesso
Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, consentendo al contempo agli utenti di controllare la quantità di accesso che concedono alla tua applicazione. Pertanto, potrebbe esserci 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 dovrà accedere.
L'API YouTube Analytics utilizza i seguenti ambiti:
| Ambito | Descrizione |
|---|---|
https://www. |
Gestisci il tuo account YouTube |
https://www. |
Visualizza il tuo account YouTube |
https://www. |
Visualizzare e gestire le risorse e i relativi contenuti su YouTube |
https://www. |
Visualizzare i rapporti di YouTube Analytics relativi al valore monetario e non monetario per i contenuti di YouTube |
https://www. |
Visualizzare i rapporti Analytics su YouTube per i contenuti di YouTube |
L'API di reporting di YouTube utilizza i seguenti ambiti:
| Ambito | Descrizione |
|---|---|
https://www. |
Visualizzare i rapporti di YouTube Analytics relativi al valore monetario e non monetario per i contenuti di YouTube |
https://www. |
Visualizzare i rapporti Analytics su YouTube per i contenuti di YouTube |
Il documento Ambiti API OAuth 2.0 contiene un elenco completo di ambiti che puoi utilizzare per accedere alle API di Google.
Ottenere token di accesso OAuth 2.0
I seguenti passaggi mostrano come l'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 un verificatore di codice e una sfida
Google supporta il protocollo Proof Key for Code Exchange (PKCE) per rendere più sicuro il flusso dell'app installata. Per ogni richiesta di autorizzazione viene creato un verificatore di codice univoco e il relativo valore trasformato, chiamato "code_challenge", viene inviato al server di autorizzazione per ottenere il codice di autorizzazione.
Crea il verificatore del codice
Un 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.
Il verificatore del codice deve avere un'entropia sufficiente per rendere impraticabile l'ipotesi del valore.
Creare la verifica con codice
Sono supportati due metodi per creare la sfida di codifica.
| Metodi di generazione delle sfide di codifica | |
|---|---|
| S256 (consigliato) | La sfida del codice è l'hash SHA256 del verificatore del codice con codifica Base64URL (senza padding).
|
| plain | La sfida del codice è lo stesso valore del verificatore del codice generato sopra.
|
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 per la tua applicazione. Puoi trovare questo valore nella pagina Client della console Cloud. |
||||||||||||||||||
redirect_uri |
Obbligatorio
Determina il modo in cui il server di autorizzazione di Google invia una risposta alla tua app. Esistono diverse opzioni di reindirizzamento disponibili per le app installate e avrai configurato le credenziali di autorizzazione con un particolare metodo di reindirizzamento in mente. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, che hai configurato nella pagina Client della console Google Cloud del client. Se questo valore non corrisponde a un URI autorizzato, riceverai un errore La tabella mostra il valore parametro
|
||||||||||||||||||
response_type |
Obbligatorio
Determina se l'endpoint Google OAuth 2.0 restituisce un codice di autorizzazione. Imposta il valore parametro su |
||||||||||||||||||
scope |
Obbligatorio
Un elenco delimitato da spazi di ambiti che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori informano 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, consentendo al contempo agli utenti di controllare la quantità di accesso che concedono alla tua applicazione. Pertanto, esiste una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente. L'API YouTube Analytics utilizza i seguenti ambiti:
L'API di reporting di YouTube utilizza i seguenti ambiti:
Il documento Ambiti API OAuth 2.0 fornisce un elenco completo degli ambiti che puoi utilizzare per accedere alle API di Google. |
||||||||||||||||||
code_challenge |
Consigliati
Specifica un |
||||||||||||||||||
code_challenge_method |
Consigliati
Specifica il metodo utilizzato per codificare un |
||||||||||||||||||
state |
Consigliati
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 per indirizzare l'utente alla risorsa corretta nella tua applicazione, inviare nonce e mitigare la falsificazione delle richieste cross-site. Poiché il tuo |
||||||||||||||||||
login_hint |
Optional
Se la tua applicazione sa quale utente sta tentando di autenticarsi, può utilizzare questo parametro per fornire un suggerimento al server di autenticazione Google. Il server utilizza il suggerimento per semplificare il flusso di accesso compilando automaticamente il campo email nel modulo di accesso o selezionando la sessione di accesso multiplo appropriata. Imposta il valore parametro su un indirizzo email o un identificatore |
||||||||||||||||||
URL di autorizzazione di esempio
Le schede seguenti mostrano URL di autorizzazione di esempio per le diverse opzioni di URI di reindirizzamento.
Ogni URL richiede l'accesso a un ambito che consente di recuperare i report di YouTube Analytics dell'utente.Gli URL sono identici, tranne 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%2Fyt-analytics.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%2Fyt-analytics.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 il consenso all'utente
In questo passaggio, l'utente decide se concedere alla tua applicazione l'accesso richiesto. In questa fase, Google mostra una finestra di consenso che indica il nome dell'applicazione e i servizi dell'API di Google a cui sta richiedendo l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente, nonché un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire a concedere l'accesso a uno o più ambiti richiesti dall'applicazione o rifiutare la richiesta.
In questa fase, l'applicazione non deve fare nulla, in quanto attende la risposta dal server OAuth 2.0 di Google che indica se è stato concesso l'accesso. Questa risposta è spiegata nel passaggio successivo.
Errori
Le richieste all'endpoint di autorizzazione OAuth 2.0 di Google potrebbero mostrare messaggi di errore rivolti agli utenti anziché i flussi di autenticazione e autorizzazione previsti. I codici di errore comuni e le soluzioni suggerite sono:
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 ulteriori informazioni su come un amministratore può limitare l'accesso a tutti gli ambiti o agli ambiti sensibili e con limitazioni finché l'accesso non viene concesso esplicitamente all'ID client OAuth, consulta l'articolo del Centro assistenza Google Workspace Admin Specificare quali app di terze parti e interne possono accedere ai dati di Google Workspace.
disallowed_useragent
L'endpoint di autorizzazione viene visualizzato all'interno di un user agent incorporato non consentito dai criteri OAuth 2.0 di Google.
Gli sviluppatori iOS e macOS potrebbero riscontrare questo errore quando aprono 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
un user agent incorporato e un utente passa 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 di link universali sia 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 un' organizzazione Google Cloud specifica. Per saperne di più su questa opzione di configurazione, consulta la sezione Tipo di utente nell'articolo del Centro assistenza Configurare la schermata per il consenso OAuth.
deleted_client
Il client OAuth utilizzato per effettuare la richiesta è stato eliminato. L'eliminazione può avvenire manualmente o automaticamente nel caso di client non utilizzati . I clienti eliminati possono essere ripristinati entro 30 giorni dall'eliminazione. Scopri di più .
invalid_grant
Se utilizzi un
verificatore di codice e
una sfida, il parametro code_callenge non è valido o è mancante. Assicurati che il parametro
code_challenge sia impostato correttamente.
Quando aggiorni un token di accesso, il token potrebbe essere scaduto o essere stato invalidato. Autentica di nuovo l'utente e chiedi il consenso dell'utente per ottenere nuovi token. Se continui a visualizzare questo errore, assicurati che la tua applicazione sia 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
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 nella
pagina Client della
console Google Cloud.
Il valore redirect_uri passato potrebbe non essere valido per il tipo di cliente.
Il parametro redirect_uri potrebbe fare riferimento al flusso OAuth out-of-band (OOB) che è stato
ritirato e non è più supportato. Consulta la
guida alla migrazione per aggiornare l'integrazione.
invalid_request
Si è verificato un problema con la richiesta che hai effettuato. Ciò potrebbe essere dovuto a diversi motivi:
- La richiesta non è stata formattata correttamente
- Nella richiesta mancavano i parametri obbligatori
- La richiesta utilizza un metodo di autorizzazione non supportato da Google. Verifica che l'integrazione OAuth utilizzi un metodo di integrazione consigliato
- È stato utilizzato uno schema personalizzato non supportato per l'URI di reindirizzamento. Se viene visualizzato il messaggio di errore Lo schema URI personalizzato non è supportato su app per Android o Chrome, scopri di più sulle alternative allo schema URI personalizzato.
Passaggio 4: gestisci la risposta del server OAuth 2.0
Il modo in cui la tua 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 con 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 dalla pagina Client della console Cloud. |
client_secret |
Optional
Il client secret ottenuto dalla pagina Client della console Google Cloud. |
code |
Il codice di autorizzazione restituito dalla richiesta iniziale. |
code_verifier |
Il verificatore 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 nella
pagina Client di
Cloud Console per il client_id specificato. |
Sebbene l'utilizzo di DPoP sia facoltativo, è consigliato per una maggiore sicurezza. La sicurezza di DPoP si basa sulla limitazione della chiave privata a un singolo dispositivo. Ti consigliamo di archiviarla in modo che non possa essere copiata dal dispositivo, ad esempio utilizzando TPM, Secure Enclave o altri archivio chiavi supportati dalla crittografia hardware. Per utilizzare DPoP, la tua applicazione deve generare un JWT di prova DPoP nuovo e univoco per ogni richiesta all'endpoint token e aggiungerlo come intestazione della richiesta HTTP.
| Intestazione | Obbligatorio | Descrizione |
|---|---|---|
DPoP |
Facoltativo | Una prova DPoP è un JWT che dimostra il possesso di una chiave privata. Si tratta di un'intestazione, non di un parametro. Se forniti, i token restituiti sono associati a questa chiave. Per ogni richiesta deve essere generata una nuova prova univoca, che deve includere le attestazioni htm (metodo HTTP) e htu (URI HTTP) corrispondenti alla richiesta. |
Il seguente snippet mostra una richiesta di esempio:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Costruire una prova DPoP
I seguenti passaggi mostrano come creare una prova DPoP utilizzando OpenSSL dalla riga di comando:
- Genera una coppia di chiavi EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Crea l'intestazione DPoP:
L'intestazione deve includere le rivendicazioni
typ,algejwk(chiave pubblica). I valorixeysono le coordinate con codifica Base64Url della tua chiave pubblica EC. Codifica in Base64Url questo JSON:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Crea il payload DPoP:
Il payload deve includere
jti(un identificatore univoco per la richiesta),htm(metodo HTTP, ad es.POST),htu(URI HTTP, ad es.https://oauth2.googleapis.com/token) eiat(ora di emissione). Se hai ricevuto un nonce dal server in un'intestazioneDPoP-Noncenella risposta a una richiesta precedente, devi includere questo valore nonce in un'attestazionenonce. L'attestazione nonce è facoltativa per gli scambi di codici di autorizzazione e viene utilizzata solo quando l'intestazione DPoP-Nonce è stata ricevuta in precedenza. Codifica Base64Url questo JSON:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }Il valore di
jtidipende dal tipo di scambio:- Per gli scambi di codici di autorizzazione,
jtideve essere l'hash SHA256 con codifica Base64Url del codice di autorizzazione:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Per gli scambi di token di aggiornamento,
jtideve essere un identificatore univoco per richiesta:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- Per gli scambi di codici di autorizzazione,
- Firma la bozza:
Concatena l'intestazione e il payload codificati con un punto (
.), quindi firma il risultato con la tua chiave privata utilizzando ES256. Tieni presente che JWS richiede che la firma sia in formatoR | Sconcatenato non elaborato (64 byte per P-256). Se utilizzi OpenSSL direttamente, devi convertire la firma codificata ASN.1 DER predefinita in questo formato non elaborato.
Uno scambio riuscito è indicato da una risposta 200 OK
contenente i token. Se durante lo scambio viene utilizzata una prova DPoP valida, il token di aggiornamento restituito da Google sarà associato alla tua chiave, ma i token di accesso non saranno associati a DPoP. I token di accesso manterranno il valore token_type di
Bearer anziché DPoP.
Inoltre, Google restituisce un'intestazione HTTP DPoP-Nonce nella risposta.
Il client deve memorizzare nella cache questo nonce e includerlo nell'attestazione nonce della prova DPoP
nelle richieste successive (ad esempio quando scambia un token di aggiornamento con un nuovo token di accesso o quando
chiama API protette da DPoP). Utilizzando questo nonce emesso in anticipo, puoi evitare un errore di round trip aggiuntivo (use_dpop_nonce) nella richiesta successiva.
Le prove DPoP devono essere incluse per le richieste di scambio di token effettuate con token di aggiornamento associati a DPoP.
Uno scambio non riuscito si verifica se l'intestazione DPoP
è mancante quando previsto, non valida o se la prova utilizza una chiave diversa da quella
associata al token. In questi casi, il server restituisce un errore
400 Bad Request.
Se la prova DPoP presenta attestazioni htm o htu non corrispondenti, un iat scaduto, un jti riutilizzato o una firma non valida, Google restituisce un codice di errore invalid_dpop_proof.
Se è richiesto un nonce DPoP, ad esempio durante uno scambio di token di aggiornamento, e la prova DPoP non include un'attestazione nonce o il valore nonce non è accettabile per il server (ad es. è scaduto, è già stato utilizzato o non è corretto), Google restituisce un codice di errore use_dpop_nonce insieme a un'intestazione HTTP DPoP-Nonce contenente un nuovo nonce che puoi utilizzare in una richiesta successiva.
Altri errori potrebbero restituire invalid_grant.
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 che la tua 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 di identità,
come openid, profile o email. Il valore è un
token JWT (JSON Web Token) che contiene informazioni sull'identità firmate digitalmente 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 o il token di aggiornamento non scade. Se è stato utilizzato DPoP, il token di aggiornamento è associato alla chiave privata utilizzata per firmare la prova DPoP. Tieni presente che i token di aggiornamento vengono sempre restituiti per le applicazioni installate. |
refresh_token_expires_in |
La durata rimanente del token di aggiornamento in secondi. Questo valore viene impostato solo quando l'utente concede l'accesso temporaneo. |
scope |
Gli ambiti di accesso concessi da access_token espressi come elenco di
stringhe sensibili alle maiuscole e minuscole delimitate da spazi. |
token_type |
Il tipo di token restituito. Questo valore è sempre Bearer, anche quando viene utilizzato DPoP. |
Il seguente snippet mostra un esempio di intestazioni e corpo della risposta corretta quando viene utilizzato DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Passaggio 6: controlla quali ambiti sono stati concessi dagli utenti
Quando richiedi più autorizzazioni (ambiti), gli utenti potrebbero non concedere alla tua app l'accesso a tutte. La tua app deve verificare quali ambiti sono stati effettivamente concessi e gestire le situazioni in cui alcune autorizzazioni vengono negate, in genere disattivando le funzionalità che si basano su questi ambiti negati.
Tuttavia, esistono delle eccezioni. Le app Google Workspace Enterprise con delega a livello di dominio, o le app contrassegnate come attendibili, aggirano la schermata di consenso per le autorizzazioni granulari. Per queste app, gli utenti non vedranno la schermata di consenso per le autorizzazioni granulari. Al contrario, la tua app riceverà tutti gli ambiti richiesti o nessuno.
Per informazioni più dettagliate, vedi Come gestire le autorizzazioni granulari.
Per verificare se l'utente ha concesso alla tua applicazione l'accesso a un ambito specifico,
esamina il campo scope nella risposta del token di accesso. Gli ambiti di accesso concessi da
access_token espressi come elenco di stringhe sensibili alle maiuscole e minuscole delimitate da spazi.
Ad esempio, la seguente risposta di esempio del token di accesso indica che l'utente ha concesso alla tua applicazione l'accesso alle autorizzazioni di sola lettura per l'attività di Drive e gli eventi di Calendar:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Chiamare le API di Google
Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API 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 di intestazione HTTP Authorization Bearer. Se possibile,
è preferibile l'intestazione HTTP, perché 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 Analytics).
Tieni presente che l'API YouTube Analytics non supporta il flusso dell'account di servizio. L'API YouTube Reporting supporta gli account di servizio solo per i proprietari di contenuti YouTube che possiedono e gestiscono più canali YouTube, come case discografiche e studi cinematografici.
Puoi provare tutte le API di Google e visualizzare i relativi ambiti in OAuth 2.0 Playground.
Esempi di HTTP GET
Una chiamata all'endpoint
reports.query (l'API YouTube Analytics) utilizzando l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare il tuo token di accesso:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views 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/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
curl esempi
Puoi testare questi comandi con l'applicazione a riga di comando curl. Di seguito è riportato un esempio che utilizza l'opzione dell'intestazione HTTP (preferita):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
In alternativa, puoi utilizzare l'opzione del parametro stringa di query:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
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 l'autorizzazione all'utente (anche quando l'utente non è presente) se hai richiesto l'accesso offline agli ambiti associati al token.
Per aggiornare un token di accesso, la tua applicazione invia una richiesta HTTPS POST
al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che
include i seguenti parametri nel corpo della richiesta:
| Nome | Valore |
|---|---|
client_id |
L'ID client ottenuto dalla console API. |
client_secret |
Optional
Il client secret ottenuto dalla console API.
(Il |
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. |
Sebbene l'utilizzo di DPoP sia facoltativo, è consigliato per una maggiore sicurezza. Per utilizzare DPoP con un token di aggiornamento, la tua applicazione deve generare un nuovo JWT di prova DPoP univoco per ogni richiesta all'endpoint token. Questa prova deve essere firmata con la stessa chiave privata utilizzata durante lo scambio iniziale del codice di autorizzazione. La tua applicazione aggiunge la prova come intestazione della richiesta HTTP.
| Intestazione | Obbligatorio | Descrizione |
|---|---|---|
DPoP |
Facoltativo | Una prova DPoP è un JWT che dimostra il possesso di una chiave privata. Si tratta di un'intestazione, non di un parametro. Se forniti, i token restituiti sono associati a questa chiave. Per ogni richiesta deve essere generata una nuova prova univoca, che deve includere le attestazioni htm (metodo HTTP) e htu (URI HTTP) corrispondenti alla richiesta. |
Il seguente snippet mostra una richiesta di esempio:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Per utilizzare DPoP con un token di aggiornamento, devi generare un nuovo JWT di verifica DPoP univoco per la richiesta. Consulta Creare una verifica DPoP per istruzioni passo passo sulla generazione della coppia di chiavi e sulla creazione del JWT.
Uno scambio riuscito è indicato da una risposta 200 OK
contenente un nuovo token di accesso. Quando viene utilizzato DPoP, il
token_type è Bearer. Una risposta riuscita conferma
che la prova DPoP per il token di aggiornamento è stata accettata. Google potrebbe anche restituire una nuova
intestazione HTTP DPoP-Nonce nella risposta; se restituita, il client deve memorizzare nella cache questo
nonce e includerlo nell'attestazione nonce della prova DPoP nelle richieste successive.
Uno scambio non riuscito si verifica se l'intestazione DPoP è mancante, non valida o utilizza una chiave errata. Per informazioni dettagliate su codici di errore DPoP specifici e gestione dei nonce, vedi Scambio non riuscito.
Il seguente snippet mostra un esempio di intestazioni e corpo della risposta corretta quando viene utilizzato DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Tieni presente che esistono 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. Devi salvare i token di aggiornamento in un archivio a lungo termine e continuare a utilizzarli finché rimangono validi. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe raggiungere questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno di funzionare.
Revoca del token
In alcuni casi, un utente potrebbe voler revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le impostazioni dell'account. Per saperne di più, consulta la sezione Rimuovere l'accesso di un sito o di un'app del documento di assistenza App e siti di terze parti con accesso al tuo account.
È anche possibile che un'applicazione revochi programmaticamente l'accesso che le è stato 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 della procedura 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, la tua 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, anche quest'ultimo verrà revocato.
Se la revoca viene elaborata correttamente, il codice di stato HTTP della risposta è
200. In caso di errore, viene restituito un codice di stato HTTP 400 insieme
a un codice di errore.
Metodi di reindirizzamento delle app
Schema URI personalizzato
Gli schemi URI personalizzati sono una forma di link diretto che utilizza uno schema definito in modo personalizzato per aprire la tua app.
Alternativa all'utilizzo di schemi URI personalizzati nelle app Chrome
Utilizza l'API Chrome Identity, che fornisce la risposta OAuth 2.0 direttamente alla tua app, eliminando la necessità di un URI di reindirizzamento.
Indirizzo IP di loopback (macOS, Linux, Windows desktop)
Per ricevere il codice di autorizzazione utilizzando questo URL, la tua applicazione deve essere in ascolto sul server web locale. Questa operazione è 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à deve rispondere visualizzando una pagina HTML che invita l'utente a chiudere il browser e tornare alla tua app.
| Utilizzo consigliato | App desktop per macOS, Linux e Windows (ma non Universal Windows Platform) |
| Valori del modulo | Imposta il tipo di applicazione su App per desktop. |
Copia/incolla manuale (ritirato)
Proteggere le tue app
Verificare la proprietà dell'app per Chrome
Puoi verificare la proprietà della tua applicazione per ridurre il rischio di rappresentazione dell'app.
Per completare la procedura di verifica, devi utilizzare il tuo account sviluppatore del Chrome Web Store. Per una verifica riuscita, devono essere soddisfatti i seguenti requisiti:
- Devi avere un elemento registrato nella Dashboard per sviluppatori del Chrome Web Store con lo stesso ID articolo del client OAuth dell'estensione Chrome per cui stai completando la verifica.
- Devi essere un publisher dell'elemento del Chrome Web Store. Scopri di più sulla gestione dell'accesso nella Dashboard per sviluppatori del Chrome Web Store.
Nella sezione Verifica proprietà app del client dell'estensione 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, viene visualizzata una notifica che conferma il successo della procedura di verifica. In caso contrario, verrà visualizzato un prompt di errore.
Per risolvere un problema di verifica non riuscita, prova a svolgere questi passaggi:
- Assicurati che nella Dashboard per sviluppatori del Chrome Web Store sia presente un elemento registrato con lo stesso ID articolo del client OAuth dell'estensione di Chrome per cui stai completando la verifica.
- Assicurati di essere un publisher dell'app, ovvero devi essere il publisher individuale 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 l'elenco dei membri del gruppo di publisher sia sincronizzato nella Dashboard per sviluppatori del Chrome Web Store. Scopri di più sulla sincronizzazione dell'elenco degli abbonati del publisher.
Controllo app (solo iOS)
La funzionalità App Check aiuta a proteggere le tue applicazioni iOS da un utilizzo non autorizzato utilizzando il servizio App Attest di Apple per verificare che le richieste effettuate agli endpoint Google OAuth 2.0 provengano dalle tue applicazioni autentiche. Ciò contribuisce a ridurre il rischio di rappresentazione di app.
Abilitare App Check per il client iOS
Per abilitare correttamente App Check per il client iOS, devono essere soddisfatti i seguenti requisiti:- Devi specificare un ID team per il tuo client iOS.
- Non devi utilizzare un carattere jolly nell'ID pacchetto, in quanto può essere risolto in più di un'app. Ciò significa che l'ID pacchetto non deve includere il simbolo asterisco (*).
Dopo aver attivato App Check, inizierai a visualizzare le metriche relative alle richieste OAuth dal tuo client nell'area di modifica del client OAuth. Le richieste provenienti da origini non verificate non verranno bloccate finché non applichi App Check. Le informazioni nella pagina di monitoraggio delle metriche possono aiutarti a determinare quando iniziare l'applicazione.
Quando abiliti App Check per la tua app per iOS, potresti visualizzare errori correlati alla funzionalità App Check. Per risolvere questi errori, prova a procedere nel seguente modo:
- Verifica che l'ID pacchetto e l'ID team specificati siano validi.
- Verifica di non utilizzare un carattere jolly per l'ID pacchetto.
Applicare App Check per il client iOS
L'attivazione di App Check per la tua app non blocca automaticamente le richieste non riconosciute. Per applicare questa protezione, vai all'area di modifica del client iOS. Qui vedrai le metriche di App Check a destra della pagina nella sezione Google Identity per iOS. Le metriche includono le seguenti informazioni:- Numero di richieste verificate: richieste con un token App Check valido. Dopo aver abilitato l'applicazione di App Check, solo le richieste di questa categoria andranno a buon fine.
- Numero di richieste non verificate: probabili richieste client obsolete: richieste senza un token App Check; queste richieste potrebbero provenire da una versione precedente della tua app che non include un'implementazione di App Check.
- Numero di richieste non verificate: richieste di origini sconosciute: richieste senza un token App Check che non sembrano provenire dalla tua app.
- Numero di richieste non verificate: richieste non valide: richieste con un token App Check non valido, probabilmente provenienti da un client non autentico che cerca di passare per la tua app o da ambienti emulati.
Per applicare App Check, fai clic sul pulsante ENFORCE e conferma la tua scelta. Una volta attiva l'applicazione, tutte le richieste non verificate del client verranno rifiutate.
Nota: dopo aver attivato l'applicazione, possono essere necessari fino a 15 minuti prima che le modifiche diventino effettive.
Annulla l'applicazione di App Check per il tuo client iOS
L'annullamento dell'applicazione di App Check per la tua app interromperà l'applicazione e consentirà tutte le richieste dal tuo client agli endpoint OAuth 2.0 di Google, incluse le richieste non verificate.
Per disattivare App Check per il client iOS, vai all'area di modifica del client iOS e fai clic sul pulsante DISATTIVA e conferma la tua scelta.
Nota: dopo aver disattivato App Check, l'applicazione delle modifiche può richiedere fino a 15 minuti.
Disabilita App Check per il client iOS
Se disabiliti App Check per la tua app, tutto il monitoraggio di App Check e l'applicazione verranno interrotti. Valuta la possibilità di non applicare App Check per continuare a monitorare le metriche per il tuo client.
Per disattivare App Check per il client iOS, vai all'area di modifica del client iOS e disattiva il pulsante di attivazione/disattivazione Proteggi il tuo client OAuth da comportamenti illeciti con Firebase App Check.
Nota: dopo aver disattivato App Check, l'applicazione delle modifiche può richiedere fino a 15 minuti.
Accesso a tempo
L'accesso temporaneo consente a un utente di concedere alla tua app l'accesso ai propri dati per un periodo di tempo limitato per completare un'azione. L'accesso temporaneo è disponibile in alcuni prodotti Google durante il flusso di consenso, offrendo agli utenti la possibilità di concedere l'accesso per un periodo di tempo limitato. Un esempio è l' API Data Portability, che consente un trasferimento di dati una tantum.
Quando un utente concede alla tua applicazione l'accesso basato sul tempo, il token di aggiornamento scade dopo la durata specificata. Tieni presente che i token di aggiornamento potrebbero essere invalidati prima in circostanze specifiche. Per ulteriori dettagli, consulta questi casi. Il campo refresh_token_expires_in restituito nella risposta di scambio del codice di autorizzazione rappresenta il tempo rimanente prima della scadenza del token di aggiornamento in questi casi.
Per approfondire
La best practice attuale dell'IETF OAuth 2.0 per app native stabilisce molte delle best practice documentate qui.
Implementare la Protezione su più account
Un ulteriore passaggio da intraprendere per proteggere gli account dei tuoi utenti è l'implementazione della Protezione su più account utilizzando il servizio di Protezione su più account di Google. Questo servizio ti consente di iscriverti alle notifiche degli eventi di sicurezza che forniscono alla tua applicazione informazioni su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per intraprendere azioni a seconda di come decidi di rispondere agli eventi.
Ecco alcuni esempi dei tipi di eventi inviati alla tua app dal servizio di Protezione su più account di Google:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Per ulteriori informazioni su come implementare la protezione su più account e per l'elenco completo degli eventi disponibili, consulta la pagina Proteggere gli account utente con la protezione su più account .