OAuth 2.0 per app desktop

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

Questo documento spiega in che modo le applicazioni desktop (come le applicazioni in esecuzione su Windows, macOS o Linux o gli strumenti dell'interfaccia a riga di comando (CLI)) utilizzano gli endpoint OAuth 2.0 di Google per autorizzare l'accesso alle API di Google.

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 degli utenti ad archiviare file nei loro Google Drive.

Le applicazioni desktop vengono installate localmente sulla macchina di un utente (ad esempio software desktop autonomo, strumenti CLI per sviluppatori, utilità di sincronizzazione in background o script). Poiché queste app vengono distribuite ai singoli dispositivi, si presume che non possano mantenere segreti (sono client pubblici). Possono accedere alle API di Google mentre l'utente interagisce attivamente con l'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 desktop devono aprire il browser di sistema e fornire un URI di reindirizzamento locale (ad esempio un indirizzo IP di loopback) per gestire le risposte dal server di autorizzazione di Google.

Librerie ed esempi

Ti consigliamo di utilizzare le librerie client delle API di Google per il tuo linguaggio di programmazione (ad es. Python, Java, Node.js, Go, .NET) quando implementi OAuth 2.0 per le applicazioni desktop. Le librerie client gestiscono l'autorizzazione degli utenti e la gestione dei token, semplificando l'implementazione e riducendo il rischio di errori rispetto all'utilizzo diretto degli endpoint HTTP/REST di livello inferiore.

Per le app mobile, consulta le guide all'autorizzazione per Android e iOS.

Per le app in esecuzione su dispositivi che non supportano un browser di sistema o che hanno funzionalità di immissione limitate, come TV, console per videogiochi, fotocamere o stampanti, consulta OAuth 2.0 per TV e dispositivi o Accedi su TV e dispositivi di immissione limitata.

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiama le API di Google deve abilitarle nella console API.

Per abilitare un'API per il tuo progetto:

1. Apri la libreria API nella console API di Google.
2. Se richiesto, seleziona un progetto o creane uno nuovo.
3. La libreria API elenca tutte le API disponibili, raggruppate per famiglia di prodotti e popolarità. Se l'API che vuoi attivare non è visibile nell'elenco, utilizza la ricerca per trovarla o fai clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
4. Seleziona l'API che vuoi abilitare, quindi fai clic sul pulsante Abilita.
5. Se richiesto, abilita la fatturazione.
6. Se richiesto, leggi e accetta i Termini di servizio dell'API.

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 la identificano per il server OAuth 2.0 di Google. I passaggi seguenti 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 quel progetto.

1. Vai alla pagina Clienti.
2. Fai clic su Crea client.
3. Seleziona il tipo di applicazione App desktop.
4. Nel campo Nome, inserisci un nome per il client OAuth. Questo nome viene visualizzato nella pagina Clienti del progetto per identificare il client.
5. Fai clic su Crea.

L'ID client e il client secret vengono generati e visualizzati nella console Google Cloud. Le app desktop sono client pubblici e non possono mantenere riservati i secret. Utilizza sempre PKCE (Proof Key for Code Exchange) quando richiedi i codici di autorizzazione.

Identifica 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 il livello 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 per cui la tua app avrà bisogno dell'autorizzazione di accesso.

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

Il documento 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 determinati dati utente, deve completare una procedura di verifica. Se durante il test della tua applicazione vedi la dicitura app non verificata sullo schermo, devi inviare una richiesta di verifica per rimuoverla. Scopri di più sulle app non verificate e trova le risposte alle domande frequenti sulla verifica app nel Centro assistenza.

Ottenere i token di accesso OAuth 2.0

I passaggi seguenti 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 verifica

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 un verificatore di codice univoco e il suo 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 impossibile indovinare il valore.

Crea la verifica con codice

Sono supportati due metodi per creare la verifica del codice.

Metodi di generazione della verifica del codice
S256 (consigliato)	La verifica del codice è l'hash SHA256 con codifica Base64URL (senza padding) del verificatore del codice. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain	La verifica del codice è lo stesso valore del codice di verifica generato sopra. code_challenge = code_verifier

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

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

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

Parametri
client_id	Obbligatorio L'ID client della tua applicazione. Puoi trovare questo valore 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 dovrai configurare le tue credenziali di autorizzazione tenendo presente un metodo di reindirizzamento specifico. 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 Cloud del tuo client. Se questo valore non corrisponde a un URI autorizzato, riceverai un errore redirect_uri_mismatch. La tabella mostra il valore del parametro redirect_uri appropriato per ogni 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 sotto il tuo controllo. Per essere valido, lo schema personalizzato deve contenere un punto. com.googleusercontent.apps.123 è la notazione DNS inversa dell'ID client. redirect_uri_path è un componente facoltativo del percorso, ad esempio /oauth2redirect. Tieni presente che il percorso deve iniziare con una singola barra, a differenza dei normali URL HTTP. Nota : gli schemi URI personalizzati non sono più supportati nelle app per Android e nelle app di Chrome. Scopri di più sulle alternative allo schema personalizzato. Indirizzo IP di loopback http://127.0.0.1:port o http://[::1]:port Esegui una query sulla tua piattaforma per l'indirizzo IP di loopback pertinente e avvia un listener HTTP su una porta disponibile casuale. Sostituisci port con il numero di porta effettivo su cui l'app è in ascolto. Tieni presente che il supporto per l'opzione di reindirizzamento dell'indirizzo IP di loopback nelle app mobile è DEPRECATO.
response_type	Obbligatorio Determina se l'endpoint Google OAuth 2.0 restituisce un codice di autorizzazione. Imposta il valore parametro su code per le applicazioni installate.
scope	Obbligatorio Un elenco di ambiti delimitati da spazi che identificano le risorse a cui l'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 il livello 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.
code_challenge	Consigliato Specifica un code_verifier codificato che verrà utilizzato come verifica lato server durante lo scambio del codice di autorizzazione. Per saperne di più, consulta Crea una verifica del codice.
code_challenge_method	Consigliato Specifica il metodo utilizzato per codificare un code_verifier che verrà utilizzato durante lo scambio del codice di autorizzazione. Questo parametro deve essere utilizzato con il parametro code_challenge. Il valore di code_challenge_method viene impostato per impostazione predefinita su 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 di stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione. Il server restituisce il valore esatto che invii come coppia name=value nell'identificatore di frammenti di URL (#) di redirect_uri dopo che l'utente acconsente o nega la richiesta di accesso della tua applicazione. Puoi utilizzare questo parametro per diversi scopi, ad esempio per indirizzare l'utente alla risorsa corretta nella tua applicazione, inviare nonce e mitigare gli attacchi di tipo richiesta cross-site forgery. Poiché il tuo redirect_uri può essere indovinato, l'utilizzo di un valore state può aumentare la certezza che una connessione in entrata sia il risultato di una richiesta di autenticazione. Se generi una stringa casuale o codifichi l'hash di un cookie o un altro valore che acquisisce lo stato del client, puoi convalidare la risposta per assicurarti ulteriormente che la richiesta e la risposta provengano dallo stesso browser, fornendo protezione contro attacchi come la richiesta cross-site forgery. Consulta la documentazione di OpenID Connect per un esempio di come creare e confermare un token state. Importante: il client OAuth deve impedire gli attacchi CSRF, come indicato nella specifica OAuth2 . Un modo per farlo è utilizzare il parametro state per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.
login_hint	Facoltativo Se la tua applicazione conosce l'utente che sta tentando di eseguire l'autenticazione, può utilizzare questo parametro per fornire un suggerimento al server di autenticazione di Google. Il server utilizza il suggerimento per semplificare il flusso di accesso precompilando il campo email nel modulo di accesso o selezionando la sessione di accesso multiplo appropriata. Imposta il valore del parametro su un indirizzo email o un identificatore sub, che equivale all'ID Google dell'utente.

Nota: l'autorizzazione incrementale con le app installate non è supportata perché il client non può mantenere riservato il client_secret.

URL di autorizzazione di esempio

Le schede di seguito mostrano URL di autorizzazione di esempio per le diverse opzioni di URI di reindirizzamento.

Gli URL sono identici, ad eccezione del 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 la leggibilità.

Schema URI personalizzato

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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 dell'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 riporta il nome della tua applicazione e i servizi API di Google per cui richiede l'autorizzazione di accesso 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 dalla tua applicazione o rifiutare la richiesta.

In questa fase, l'applicazione non deve fare nulla, ma deve attendere la risposta del server OAuth 2.0 di Google che indica se è stato concesso l'accesso. La risposta è spiegata nel passaggio successivo.

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. 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 policy dell'amministratore di Google Workspace. Per saperne di più su come un amministratore può limitare l'accesso a tutti gli ambiti o agli ambiti sensibili e con restrizioni fino a quando non viene concesso esplicitamente l'accesso al tuo ID client OAuth, consulta l'articolo del Centro assistenza per gli amministratori di Google Workspace Specifica 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 uno user agent incorporato non consentito dalle norme OAuth 2.0 di Google.

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 generico 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 dei link predefinito del sistema operativo, che include sia i gestori di link universali sia l'app del 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 Configurazione della 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 inutilizzati . I client eliminati possono essere ripristinati entro 30 giorni dall'eliminazione. Scopri di più .

invalid_grant

Se utilizzi un verificatore di codice e una verifica, il parametro code_callenge non è valido o è mancante. Assicurati che il parametro code_challenge sia impostato correttamente.

Durante l'aggiornamento di 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 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 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 client.

Il parametro redirect_uri potrebbe fare riferimento al flusso out-of-band (OOB) di OAuth, che è stato deprecato 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 una serie di 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 Android o sulle app di Chrome, scopri di più sulle alternative allo schema URI personalizzato.

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui l'applicazione riceve la risposta di autorizzazione dipende dallo schema 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 Clienti della console Cloud.
client_secret	Facoltativo Il client secret ottenuto dalla pagina Client della console Cloud.
code	Il codice di autorizzazione restituito dalla richiesta iniziale.
code_verifier	Il codice di verifica 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 della console Cloud 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 fuori dal dispositivo, ad esempio utilizzando TPM, Secure Enclave o altri keystore con crittografia hardware. Per utilizzare DPoP, l'applicazione deve generare un nuovo JWT di prova DPoP univoco per ogni richiesta all'endpoint del 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

Crea una prova DPoP

I passaggi seguenti mostrano come creare una prova DPoP utilizzando OpenSSL dalla riga di comando:

1. 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

2. Crea l'intestazione DPoP:

   L'intestazione deve includere le attestazioni typ, alg e jwk (chiave pubblica). I valori x e y sono le coordinate con codifica Base64Url della tua chiave pubblica EC. Codifica questo JSON in Base64Url:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. Crea il payload DPoP:

   Il payload deve includere jti (un identificatore univoco per la richiesta), htm (metodo HTTP, ad esempio POST), htu (URI HTTP, ad esempio https://oauth2.googleapis.com/token) e iat (ora di emissione). Se hai ricevuto un nonce dal server in un'intestazione DPoP-Nonce nella risposta a una richiesta precedente, devi includere il valore del nonce in un claim nonce. La dichiarazione nonce è facoltativa per gli scambi di codici di autorizzazione e viene utilizzata solo quando l'intestazione DPoP-Nonce è stata ricevuta in precedenza. Codifica questo JSON in Base64Url:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   Il valore jti dipende dal tipo di piattaforma di scambio:

   • Per gli scambi di codici di autorizzazione, jti deve essere l'hash SHA256 con codifica Base64Url del codice di autorizzazione: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • Per gli scambi di token di aggiornamento, jti deve essere un identificatore univoco per richiesta: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. 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 un formato concatenato R | S non elaborato (64 byte per P-256). Se utilizzi direttamente OpenSSL, devi convertire la firma predefinita con codifica ASN.1 DER 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 tramite DPoP, ma i token di accesso non saranno associati tramite DPoP. I token di accesso manterranno il 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 nella dichiarazione 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 non è presente quando prevista, 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'attestazione iat scaduta, un'attestazione jti riutilizzata 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 nella prova DPoP manca un claim nonce o il valore del nonce non è accettabile per il server (ad esempio, è 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 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 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à, ad esempio openid, profile o email. Il valore è un token JWT (JSON Web Token) che contiene informazioni sull'identità dell'utente firmate digitalmente.
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 finché 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 basato sul tempo.
scope	Gli ambiti di accesso concessi da access_token espressi come un elenco di stringhe sensibili alle maiuscole delimitate da spazi.
token_type	Il tipo di token restituito. Questo valore è sempre Bearer, anche quando viene utilizzato DPoP.

Importante: l'applicazione deve archiviare entrambi i token in una posizione sicura e di lunga durata, accessibile tra diverse chiamate dell'applicazione. Il token di aggiornamento consente alla tua applicazione di ottenere un nuovo token di accesso se quello che hai scade. Pertanto, se la tua applicazione perde il token di aggiornamento, l'utente dovrà ripetere il flusso di consenso OAuth 2.0 in modo che la tua applicazione possa ottenere un nuovo token di aggiornamento.

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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Nota: l'applicazione deve ignorare tutti i campi non riconosciuti inclusi nella risposta.

Nota: se la tua applicazione ha già un token di aggiornamento per l'utente e vuoi ottenere un nuovo token di aggiornamento associato a DPoP, l'utente deve revocare la concessione esistente o devi utilizzare il parametro prompt=consent nella richiesta di autorizzazione iniziale per assicurarti che venga emesso un nuovo token di aggiornamento.

Passaggio 6: controlla gli ambiti 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 correttamente le situazioni in cui alcune autorizzazioni vengono negate, in genere disattivando le funzionalità che si basano su questi ambiti negati.

Tuttavia, ci sono delle eccezioni. Le app Google Workspace Enterprise con delega di autorità a livello di dominio o le app contrassegnate come Attendibili ignorano la schermata per il consenso alle autorizzazioni granulari. Per queste app, gli utenti non vedranno la schermata per il consenso alle autorizzazioni granulari. La tua app riceverà invece tutti gli ambiti richiesti o nessuno.

Per informazioni più dettagliate, consulta Come gestire le autorizzazioni granulari.

Per verificare se l'utente ha concesso alla tua applicazione l'accesso a un determinato ambito, esamina il campo scope nella risposta del token di accesso. Gli ambiti di accesso concessi dal token di accesso espressi come elenco di stringhe sensibili alle maiuscole 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 nel calendario:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Chiama 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 Bearer dell'intestazione HTTP Authorization. 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 Drive Files).

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 drive.files (l'API Drive Files) utilizzando l'intestazione HTTP Authorization: Bearer potrebbe essere simile alla seguente. Tieni presente che devi specificare il tuo token di accesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Ecco una chiamata alla stessa API per l'utente autenticato che utilizza il parametro della stringa di query access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

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/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Aggiorna 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, l'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	Facoltativo Il client secret ottenuto dalla console API. (Il parametro client_secret non è applicabile alle richieste provenienti da client registrati come applicazioni Android, iOS o Chrome.)
grant_type	Come definito nella specifica OAuth 2.0, il valore di questo campo deve essere impostato su refresh_token.
refresh_token	Il token di aggiornamento restituito dallo scambio del codice di autorizzazione.

Sebbene l'utilizzo di DPoP sia facoltativo, è consigliato per una maggiore sicurezza. Per utilizzare DPoP con un token di aggiornamento, l'applicazione deve generare un nuovo JWT di prova DPoP univoco per ogni richiesta all'endpoint del 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 prova DPoP univoco per la richiesta. Consulta Crea una prova 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, token_type è Bearer. Una risposta positiva 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 nella rivendicazione 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 sulla gestione dei nonce, consulta 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 nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe raggiungere questi limiti e, in questo caso, i token di aggiornamento meno recenti smetteranno di funzionare.

Revoca dei token

In alcuni casi, un utente potrebbe voler revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le Impostazioni account. Per ulteriori informazioni, consulta la sezione Rimuovere l'accesso di un sito o di un'app del documento di assistenza Siti e app di terze parti con accesso al tuo account.

È anche possibile che un'applicazione revochi l'accesso concesso in modo programmatico. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse API richieste da un'app sono cambiate in modo significativo. In altre parole, parte del processo di rimozione può includere una richiesta API per garantire che le autorizzazioni 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. In caso di condizioni di errore, viene restituito un codice di stato HTTP 400 insieme a un codice di errore.

Punto chiave: la revoca rimuove tutti gli ambiti OAuth 2.0 precedentemente concessi a un progetto, invalidando tutti i token di accesso o i token di aggiornamento emessi per tutti i client registrati in quel progetto.

Nota: dopo una risposta di revoca riuscita, potrebbe essere necessario un po' di tempo prima che la revoca abbia pieno effetto.

Metodi di reindirizzamento alle app

Schema URI personalizzato

Gli schemi URI personalizzati sono una forma di deep linking che utilizza uno schema personalizzato per aprire la tua app.

Importante: gli schemi URI personalizzati non sono più supportati a causa del rischio di furto d'identità delle app.

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

Utilizza l'API Chrome Identity, che invia 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)

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

Per ricevere il codice di autorizzazione utilizzando questo URL, l'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 l'app riceve la risposta di autorizzazione, per una migliore usabilità deve rispondere visualizzando una pagina HTML che indica all'utente di chiudere il browser e tornare all'app.

Utilizzo consigliato	App desktop per macOS, Linux e Windows
Valori dei moduli	Imposta il tipo di applicazione su App desktop.

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

Copia/Incolla manuale (ritirato)

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

Proteggi le tue app

Verifica la proprietà dell'app per Chrome

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

Per completare la procedura di verifica, devi utilizzare il tuo account sviluppatore del Chrome Web Store. Per superare la verifica, 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 di Chrome per cui stai completando la verifica.
• Devi essere un publisher dell'elemento 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 la 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 va a buon fine, viene visualizzata una notifica per confermare l'esito positivo della procedura di verifica. In caso contrario, verrà visualizzato un messaggio di errore.

Per risolvere un problema di verifica, prova i seguenti 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 di 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 publisher del gruppo sia sincronizzato nella Dashboard per sviluppatori del Chrome Web Store. Scopri di più sulla sincronizzazione dell'elenco degli abbonati dell'editore.

Accesso in base al tempo

L'accesso basato sul tempo consente a un utente di concedere alla tua app l'accesso ai suoi dati per un periodo di tempo limitato per completare un'azione. L'accesso basato sul tempo è disponibile in alcuni prodotti Google durante il flusso di consenso e offre agli utenti la possibilità di concedere l'accesso per un periodo di tempo limitato. Un esempio è l' API Data Portability, che consente un trasferimento dei 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 maggiori dettagli, consulta questi casi. In questi casi, il campo refresh_token_expires_in restituito nella risposta dello scambio del codice di autorizzazione rappresenta il tempo rimanente prima della scadenza del token di aggiornamento.

Per approfondire

La best practice attuale dell'IETF OAuth 2.0 for App native stabilisce molte delle best practice documentate qui.

Implementa la Protezione su più account

Un ulteriore passaggio da eseguire per proteggere gli account degli utenti è l'implementazione della Protezione su più account utilizzando il servizio Protezione su più account di Google. Questo servizio ti consente di iscriverti alle notifiche di eventi di sicurezza che forniscono alla tua applicazione informazioni su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per passare all'azione 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 Proteggi gli account utente con la protezione su più account .