OAuth 2.0 per app mobile e desktop

Nota: se non hai mai utilizzato OAuth 2.0, ti consigliamo di leggere Panoramica di OAuth 2.0 prima di iniziare. La Panoramica riassume i flussi OAuth 2.0 supportati da Google, che possono aiutarti a garantire che hai selezionato il flusso giusto per la tua applicazione.

Questo documento spiega come le applicazioni installate su dispositivi quali telefoni, tablet e utilizzano gli endpoint OAuth 2.0 di Google per autorizzare l'accesso l'API YouTube Data.

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

Le app installate vengono distribuite su singoli dispositivi e si presume che tali app non possono 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 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 risposte dal server di autorizzazione di Google.

Alternative

Per le app mobile, potresti preferire utilizzare Accedi con Google per Android o iOS. Accedi con Google librerie client gestiscono l'autenticazione e l'autorizzazione dell'utente e possono essere più semplici rispetto al protocollo di livello inferiore descritto qui.

Per le app in esecuzione su dispositivi che non supportano i browser di sistema o con input limitato come TV, console per videogiochi, fotocamere o stampanti, vedi OAuth 2.0 per TV e Dispositivi o Accedi su TV e dispositivi di input limitato.

Librerie ed esempi

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

• Libreria AppAuth per Android
• Libreria AppAuth per iOS
• OAuth per le app: Windows Esempi

Prerequisiti

Abilita le API per il progetto

Qualsiasi applicazione che chiama le API di Google deve abilitare tali API nel 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 YouTube Data. Trova altro che verranno utilizzate dalla tua applicazione e che abiliteranno.

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 nel server OAuth 2.0 di Google. I passaggi seguenti spiegano come e 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 utilizzati da Google di autorizzazione in base al server di autorizzazione. Scegli il tipo di client consigliato per applicazione, denominare il client OAuth e impostare gli altri campi del modulo come appropriato.

Android

1. Seleziona il tipo di applicazione per Android.
2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella Credentials page per identificare il cliente.
3. Inserisci il nome del pacchetto della tua app per Android. Questo valore è definito nel 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 firma dell'app di Google Play, copia l'algoritmo SHA-1 improntata nella pagina di firma dell'app di Play Console.
   • Se gestisci autonomamente il tuo archivio chiavi e le tue chiavi di firma, usa l'utilità keytool incluso con Java per stampare le informazioni del certificato in un formato leggibile. Copia il Valore SHA1 nella sezione Certificate fingerprints di keytool. Consulta Autenticazione del cliente nel Documentazione sulle API di Google per Android per saperne di più.
5. (Facoltativo) Verifica la proprietà del tuo dispositivo Android un'applicazione.
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 per identificare il cliente.
3. Inserisci l'identificatore pacchetto per la tua app. L'ID pacchetto è il valore dell'attributo CFBundleIdentifier nel file di risorse dell'elenco di proprietà delle informazioni dell'app (info.plist). Il valore è visualizzata più di frequente nel riquadro Generale o nella sezione Firma e Riquadro delle funzionalità Editor di progetto Xcode. L'ID pacchetto viene visualizzato anche nella sezione Informazioni generali di la pagina Informazioni sull'app su 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 negozio è una stringa numerica inclusa in ogni URL dell'App Store di Apple.

   1. Apri l'app 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. Consulta Individuare l'ID team nella documentazione dell'account sviluppatore Apple per ulteriori informazioni.

6. Fai clic su Crea.

UWP

1. Seleziona il tipo di applicazione Piattaforma Universal Windows.
2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nella Credentials page per identificare il cliente.
3. Inserisci l'ID Microsoft Store di 12 caratteri dell'app. Puoi trovare questo valore in Centro partner Microsoft il Identità dell'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 di URI personalizzati sono una forma di link diretti che utilizzano uno schema personalizzato per aprire la tua app.

Importante:gli schemi di URI personalizzati non sono più supportati nelle nuove app di Chrome e sono è disabilitata per impostazione predefinita sui nuovi client Android a causa del rischio di furto d'identità delle app.

Alternativa all'utilizzo di schemi URI personalizzati su Android

Utilizza la SDK Accedi con Google per Android che fornisce la risposta OAuth 2.0 direttamente nell'app, eliminando la necessità di una 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 completa le azioni riportate di seguito per eseguire la migrazione completa all'utilizzo della funzionalità Accedi con Google consigliata per SDK 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.

Nota: devi completare e implementare gli aggiornamenti del codice (tenendo conto del tempo di adozione). nella base utenti o sui dispositivi più vecchi) prima di disattivare il supporto degli schemi personalizzati nella la console API di Google per evitare che gli utenti ricevano Messaggio di errore invalid_request quando tentano di utilizzare la tua app.

Segui questi passaggi per eseguire la migrazione all'SDK Accedi con Google per Android:

1. Aggiorna il codice per utilizzare l'SDK di Accedi con Google per Android:
   1. Esamina il codice per identificare la tua posizione invio di una richiesta al server OAuth 2.0 di Google; se utilizzi uno schema personalizzato, la tua richiesta sarà simile a questa:

        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 nella dall'esempio riportato sopra. Consulta le Definizione del parametro redirect_uri per ulteriori dettagli sul formato del valore dello schema dell'URI personalizzato.
   2. Prendi nota dei parametri della richiesta scope e client_id che devi configurare l'SDK Accedi con Google.
      Nota: se utilizzi una raccolta di terze parti, consulta le relative sezioni. di configurazione del deployment per trovare queste informazioni.
   3. Segui le Inizia a integrare l'opzione Accedi con Google nella tua app per Android istruzioni per configurare l'SDK. Puoi saltare le Recupera l'ID client OAuth 2.0 del server di backend come riutilizzeresti il client_id recuperato dal passaggio precedente.
   4. Segui le Abilitare l'accesso all'API lato server istruzioni. Sono inclusi i seguenti passaggi:
      1. Utilizza il metodo getServerAuthCode per recuperare un codice di autorizzazione per il gli ambiti per i quali richiedi l'autorizzazione.
      2. Invia il codice di autorizzazione al backend dell'app per scambiarlo con un accesso e aggiorna di accesso.
      3. Utilizza il token di accesso recuperato per effettuare chiamate alle API di Google per conto dell'utente.
      Nota: se la tua applicazione non richiede l'accesso offline, segui queste istruzioni per richiedere l'accesso all'API lato client.
2. Disattiva il supporto per lo schema personalizzato nella console API di Google:
   1. Vai al tuo Credenziali OAuth 2.0 dall'elenco e seleziona il tuo client Android.
   2. Vai alla sezione Impostazioni avanzate e deseleziona la casella casella di controllo Abilita schema URI personalizzato e fai clic su Salva in disabilita il supporto dello schema dell'URI personalizzato.

Abilitazione dello schema URI personalizzato

Se l'alternativa consigliata non funziona nel tuo caso, puoi attivare gli schemi URI personalizzati per il tuo Per il client Android, segui le istruzioni riportate di seguito:

1. Vai al tuo Elenco di credenziali OAuth 2.0 e seleziona il tuo client Android.
2. Vai alla sezione Impostazioni avanzate, controlla casella di controllo Abilita schema URI personalizzato e fai clic su Salva per abilitarlo per lo schema URI personalizzato.

Alternativa all'utilizzo di schemi URI personalizzati nelle app di Chrome

Utilizza la API Chrome Identity che fornisce la risposta OAuth 2.0 direttamente nell'app, eliminando la necessità di una 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

Nota: la verifica della proprietà delle app per Android è attualmente disponibile solo per Google Play app.

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 Le seguenti Per una verifica con esito positivo, devono essere soddisfatti i seguenti requisiti:

• Devi avere un'applicazione registrata in Google Play Console con lo stesso nome del pacchetto e impronta digitale del certificato di firma SHA-1 come client OAuth per Android aver completato 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 sull'icona Verifica proprietà per completare la procedura di verifica.

Se la verifica ha esito positivo, verrà visualizzata una notifica per confermarne l'esito del processo di verifica. 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 disporre di un articolo registrato in Dashboard per sviluppatori del Chrome Web Store con lo stesso ID elemento del client OAuth dell'estensione di Chrome che stai completando verifica per.
• 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 su sul pulsante Verifica proprietà per completare la procedura di verifica.

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

Se la verifica ha esito positivo, verrà visualizzata una notifica per confermarne l'esito del processo di verifica. 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 il lo stesso ID elemento del client OAuth estensione di Chrome per cui stai completando la verifica.
• Assicurati di essere un publisher dell'app, ad esempio 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 l'appartenenza dei publisher del gruppo viene sincronizzato nella Dashboard per sviluppatori del Chrome Web Store. Scopri di più sulla sincronizzazione dell'elenco di membri dei publisher.

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

Importante: l'opzione di reindirizzamento dell'indirizzo IP di loopback è OBSOLETO per i tipi di client OAuth per Android, app Chrome e iOS. Esamina l'IP di loopback alla migrazione per istruzioni su come eseguire la migrazione a un'alternativa supportata.

Per ricevere il codice di autorizzazione utilizzando questo URL, la tua applicazione deve essere in ascolto sul server web locale. Ciò è possibile su molte piattaforme, ma non su tutte. Tuttavia, se la tua piattaforma 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 entro visualizzazione di 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.

Nota: consulta le Definizione del parametro redirect_uri per ulteriori informazioni sull'indirizzo IP di loopback. È anche possibile utilizzare localhost al posto dell'IP di loopback, ma questa configurazione potrebbe causare problemi con firewall client. La maggior parte dei firewall, ma non tutti, consente la comunicazione loopback.

Copia/incolla manuale

Importante: l'opzione di copia/incolla manuale, nota anche come il metodo di reindirizzamento out-of-band (OOB), è non è più supportato. Consulta la guida alla migrazione OOB per istruzioni su come eseguire la migrazione a un'alternativa sicura.

Identifica gli ambiti di accesso

Gli ambiti consentono all'applicazione di richiedere solo l'accesso alle risorse di cui ha bisogno, permettendo agli utenti di controllare la quantità di accesso che concedono alla tua applicazione. Pertanto, potrebbe essere una relazione inversa tra il numero di ambiti richiesti e la probabilità l'ottenimento del 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à avere l'autorizzazione ad accedere.

Nota: l'autorizzazione incrementale non è supportata per le app installate o .

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 sugli ambiti API OAuth 2.0 contiene un elenco completo degli ambiti che potresti utilizzare per accedere alle API di Google.

Se la tua applicazione pubblica utilizza ambiti che consentono l'accesso a alcuni dati utente, è necessario completare una procedura di verifica. Se vedi il messaggio non verificato visualizzata sullo schermo quando testi la tua applicazione, devi inviare una richiesta di verifica per rimuoverlo. Scopri di più su app non verificate e ricevere risposte a domande frequenti sulla verifica delle app nel Centro assistenza.

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 Consenso prima che possa 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 la chiave di prova per lo scambio del codice. (PKCE) per rendere più sicuro il flusso delle app installate. Viene creato uno strumento di verifica del codice univoco di autorizzazione e il suo valore trasformato, denominato "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 il token caratteri [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 sfida del codice è l'hash SHA256 codificato Base64URL (senza spaziatura interna) del codice strumento di verifica. 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 di sessioni attive, autentica l'utente e ottiene il consenso dell'utente. L'endpoint è accessibile solo tramite SSL rifiuta le connessioni HTTP (non SSL).

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

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. Esistono diverse opzioni di reindirizzamento disponibili per le app installate. Dopo aver configurato credenziali di autorizzazione con un particolare metodo di reindirizzamento a mente. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per OAuth 2.0 che hai configurato nel client API Console Credentials page. Se questo valore non corrisponde a URI autorizzato, riceverai un errore redirect_uri_mismatch. La tabella seguente mostra il valore del parametro redirect_uri appropriato per ciascun metodo: redirect_uri valori 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 in controllo. Per essere valido, lo schema personalizzato deve contenere un punto. com.googleusercontent.apps.123 è la notazione DNS inversa del l'ID client. redirect_uri_path è un componente del percorso facoltativo, ad esempio /oauth2redirect. Tieni presente che il percorso deve iniziare con una singola , che è diverso dai normali URL HTTP. Nota : gli schemi URI personalizzati non sono più supportati nelle app di Chrome e sono disattivate per impostazione predefinita su Android. Scopri di più sulle alternative agli schemi personalizzati per le app di Android e Chrome. Indirizzo IP di loopback http://127.0.0.1:port o http://[::1]:port Esegui una query sulla tua piattaforma per trovare l'indirizzo IP di loopback pertinente e avvia una richiesta HTTP su una porta casuale disponibile. Sostituisci port con il valore effettivo numero di porta su cui la tua app rimane in ascolto. Tieni presente che il supporto dell'opzione di reindirizzamento dell'indirizzo IP di loopback sui dispositivi mobili Google Cloud è . OBSOLETO.
response_type	Obbligatorio Determina se l'endpoint Google OAuth 2.0 restituisce un codice di autorizzazione. Imposta il valore del parametro su code per le applicazioni installate.
scope	Obbligatorio R delimitato da spazi l'elenco degli ambiti che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di consenso che Google mostra al utente. Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno consentendo agli utenti di controllare il livello di accesso che concedono al tuo un'applicazione. Esiste quindi 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: 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 fornisce un elenco completo degli ambiti che potresti utilizzare per accedere alle API di Google.
code_challenge	Consigliato Specifica un valore code_verifier codificato che verrà utilizzato come lato server verifica durante lo scambio del codice di autorizzazione. Consulta crea codice per saperne di più.
code_challenge_method	Consigliato Specifica il metodo utilizzato per codificare un elemento code_verifier che verrà utilizzato durante lo scambio del codice di autorizzazione. Questo parametro deve essere utilizzato con code_challenge descritto sopra. Il valore dell'attributo code_challenge_method il valore predefinito è plain se non presente nella richiesta che include un code_challenge. Gli unici valori supportati per questo parametro sono S256 o plain.
state	Consigliato Specifica qualsiasi valore stringa che l'applicazione utilizza per mantenere lo stato tra e la risposta del server di autorizzazione. Il server restituisce il valore esatto che invii come coppia name=value nel Identificatore di frammento di URL (#) del redirect_uri dopo che l'utente ha dato il consenso o nega l'utilizzo dell'applicazione richiesta di accesso. Puoi utilizzare questo parametro per diversi scopi, ad esempio per indirizzare l'utente alla sezione risorsa corretta nella tua applicazione, invio di nonce e mitigazione delle richieste tra siti contraffazione. Poiché redirect_uri può essere intuito, utilizzando un state può aumentare la tua garanzia che una connessione in entrata sia il risultato di un 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 assicura inoltre che la richiesta e la risposta provengano dallo stesso browser che fornisce protezione contro attacchi richiesta tra siti falsificazione. Consulta le OpenID Connect documentazione per un esempio di come creare e confermare un token state. Importante: il client OAuth deve impedire la comunicazione CSRF come indicato nel Specifica OAuth2 . Un modo per raggiungere questo obiettivo è utilizzare il parametro state per mantenere lo stato desiderato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.
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 semplificare il flusso di accesso precompilando il campo dell'email nel modulo di accesso o e selezionare la sessione con accesso multiplo appropriata. Imposta il valore del parametro su un indirizzo email o un identificatore sub, che equivalente all'ID Google dell'utente.

Nota: l'autorizzazione incrementale con le app installate non è supportata a causa che il cliente non può mantenere la client_secret riservata.

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 Account YouTube.

Gli URL sono identici, ad eccezione del valore del parametro redirect_uri. Gli URL contengono anche i parametri response_type e client_id obbligatori come parametro facoltativo state. Ogni URL contiene interruzioni di riga e spazi per la 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 questo momento di Google, Google mostra una finestra per il consenso che mostra il nome della tua applicazione e l'API di Google ai servizi a cui chiede l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente e un riepilogo degli ambiti di accesso da concedere. La l'utente può quindi concedere l'accesso a uno o più ambiti richiesti dalla tua applicazione oppure rifiutare la richiesta.

La tua richiesta non deve fare nulla in questa fase perché attende la risposta da Server OAuth 2.0 di Google che indica se è stato concesso un accesso. Questa risposta è spiegata in al 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. Codici di errore comuni e suggerimenti le risoluzioni sono elencate di seguito.

admin_policy_enforced

L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dei criteri di amministratore di Google Workspace. Consulta l'articolo del Centro assistenza per amministratori di Google Workspace Controllare quali terze parti e quali le app interne accedono ai dati di Google Workspace per ulteriori informazioni su come un amministratore può limitare l'accesso a tutti gli ambiti o a tutti gli ambiti ambiti 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 Norme relative a OAuth 2.0.

Android

Gli sviluppatori Android potrebbero visualizzare questo messaggio di errore quando aprono le richieste di autorizzazione in android.webkit.WebView Gli sviluppatori dovrebbero invece usare librerie Android come Accedi con Google per Android o OpenID Foundation AppAuth per Android.

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

iOS

Gli sviluppatori iOS e macOS potrebbero riscontrare questo errore quando aprono le richieste di autorizzazione in WKWebView Gli sviluppatori dovrebbero invece usare le librerie iOS come Accedi con Google per iOS o OpenID Foundation AppAuth per iOS.

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 da nel tuo sito. Gli sviluppatori devono consentire l'apertura dei link generali nel gestore di link predefinito del sistema operativo, che include Link universali oppure l'app browser predefinita. La 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 specifico Organizzazione Google Cloud. Per ulteriori informazioni su questa opzione di configurazione, consulta Tipo di utente nell'articolo del Centro assistenza Configurare la schermata per il consenso OAuth.

invalid_grant

Se utilizzi un strumento di verifica del codice challenge, il parametro code_callenge non è valido o è mancante. Assicurati che Il parametro code_challenge è impostato correttamente.

Quando aggiorni un token di accesso, il token potrebbe essere scaduto o invalidato. Autentica di nuovo l'utente e richiedi il consenso dell'utente per ottenere nuovi token. Se continui di visualizzare questo errore, accertati che l'applicazione sia stata configurata correttamente e di avere utilizzando i token e i parametri corretti nella richiesta. In caso contrario, l'account utente potrebbe avere eliminati o disattivati.

redirect_uri_mismatch

Il valore redirect_uri trasmesso nella richiesta di autorizzazione non corrisponde a un URI di reindirizzamento per l'ID client OAuth. Esamina gli URI di reindirizzamento autorizzati 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 ha è stata deprecata e non è più supportata. Consulta le guida alla migrazione per aggiornare e 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 il tuo OAuth l'integrazione utilizza 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 dello schema dell'URI personalizzato non sia abilitato per il tuo client Android, significa che stai utilizzando un URI personalizzato che non è supportato dalle app di Chrome ed è disattivato per impostazione predefinita Android. Scopri di più sullo schema dell'URI personalizzato alternative

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui l'applicazione riceve la risposta di autorizzazione dipende 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 alla tua applicazione, puoi scambiare il codice di autorizzazione con un di accesso e un token di aggiornamento, come descritto nel passaggio successivo.

Passaggio 5: sostituisci il codice di autorizzazione per aggiornare e accedere token

Per scambiare un codice di autorizzazione con un token di accesso, chiama il metodo 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 creato Passaggio 1:
grant_type	Come definito nelle norme OAuth 2.0 specifica, il valore di questo campo deve essere impostato su authorization_code.
redirect_uri	Uno degli URI di reindirizzamento elencati per il tuo progetto nella API Console Credentials page per il dato client_id.

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 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 identità, come openid, profile o email. Il valore è un token JWT (JSON Web Token) che contiene informazioni sull'identità con firma digitale relative al utente.
refresh_token	Un token che puoi utilizzare per ottenere un nuovo token di accesso. I token di aggiornamento sono validi fino a quando l'utente 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 delimitate da spazi, con distinzione tra maiuscole e minuscole.
token_type	Il tipo di token restituito. Al momento, il valore di questo campo è sempre impostato su Bearer.

Importante: l'applicazione deve archiviare entrambi i token in un ambiente una posizione di lunga durata accessibile tra diverse chiamate della tua applicazione. La il token di aggiornamento consente all'applicazione di ottenere un nuovo token di accesso se quello che possiedi scade. Di conseguenza, se l'applicazione perde il token di aggiornamento, l'utente dovrà ripetere Flusso di consenso OAuth 2.0 in modo che l'applicazione possa ottenere un nuovo token di aggiornamento.

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"
}

Nota. La tua applicazione dovrebbe ignorare gli eventuali campi non riconosciuti inclusi nella la risposta.

Chiamata alle API di Google

Una volta che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un API per conto di un utente 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 mediante l'inclusione di una 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, casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, la chiamata all'API YouTube Data).

Tieni presente che la YouTube Data API supporta gli account di servizio solo per YouTube proprietari dei contenuti che possiedono e gestiscono più canali YouTube, come la registrazione case discografiche e studi cinematografici.

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

Esempi GET HTTP

Una chiamata al youtube.channels (l'API di dati di YouTube) utilizzando il protocollo Authorization: Bearer potrebbe avere il seguente aspetto. 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 access_token parametro della stringa di query:

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. Tu può aggiornare un token di accesso senza richiedere 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, l'applicazione invia un POST HTTPS al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che ha 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 è applicabile alle richieste di clienti registrati come per Android, iOS o Chrome.
grant_type	Come definite nel 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 che contiene un nuovo token di accesso. Lo snippet seguente mostra un esempio risposta:

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

Tieni presente che esistono limiti al numero di token di aggiornamento che verranno emessi. un limite per cliente/utente e un'altra per utente in tutti i client. Salva i token di aggiornamento nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe capitare che si verifichino questi limiti, nel qual caso i token di aggiornamento meno recenti. smetterà 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 Impostazioni account. Consulta le Rimuovi sezione "Accesso a siti o app" della sezione Siti e app con accesso al tuo account documento di supporto per ulteriori informazioni.

È 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, rimuove un 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 concessi all'applicazione vengono rimossi.

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 presenta un corrispondente, verrà revocato anche il token di aggiornamento.

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

Nota: se una risposta alla revoca è andata a buon fine, potrebbero essere necessarie alcune prima che la revoca abbia effetto.

Per approfondire

Best Current Practice di IETF: OAuth 2.0 per App native definisce molte delle best practice qui documentate.

Implementare la Protezione su più account

Un ulteriore passaggio da seguire per proteggere i tuoi utenti che stanno implementando più account Protezione con l'utilizzo del servizio di protezione su più account di Google. Questo servizio ti consente iscriviti alle notifiche di eventi di sicurezza che forniscono informazioni alla tua applicazione su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per intervenire in base al come decidi di rispondere agli eventi.

Ecco alcuni esempi di 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

Consulta le Proteggere gli account utente con la pagina Protezione su più account . per ulteriori informazioni su come implementare la Protezione su più account e per l'elenco completo degli eventi disponibili.