Guida all'implementazione di OAuth 2.1

Questa guida illustra come autorizzare in modo sicuro la piattaforma App connesse ad accedere ai tuoi servizi. Per le integrazioni MCP delle app connesse, consigliamo vivamente di utilizzare OAuth 2.1, lo standard di settore per l'autorizzazione delegata, con Proof Key for Code Exchange (PKCE) per garantire la massima sicurezza dei dati utente e l'affidabilità nei flussi "agentici". La piattaforma App connesse supporta il grant type del codice di autorizzazione con i parametri PKCE (Proof Key for Code Exchange).

PKCE è obbligatorio per tutti gli OAuth 2.1 e facoltativo per OAuth 2.0.

Per abilitare il rilevamento automatico e semplificare il processo di onboarding, il tuo server di autorizzazione deve supportare l'estensione dei metadati del server di autorizzazione, nota anche come OAuth Discovery.

Suggerimento: per evitare un'esperienza utente frustrante e la necessità di ricollegare gli account, il dettaglio più importante è gestire la durata del token di aggiornamento utilizzando il collegamento persistente.

In che modo Gemini MCP recupera il JSON di configurazione

La console Gemini MCP tenta di recuperare il JSON di configurazione dai seguenti URL, nell'ordine mostrato in questa sezione.

Attenzione: la console Gemini MCP utilizza il primo URL che restituisce una risposta, incluso un errore. Assicurati che l'endpoint preferito sia raggiungibile e restituisca HTTP 200.

Se l'URL del server di autorizzazione si trova al livello più alto del tuo dominio (ad esempio, https://auth.example.com), Gemini aggiunge directory standard "well-known" al tuo dominio e cerca il server nel seguente ordine:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

Se l'URL del tuo server di autorizzazione si trova all'interno di una sottodirectory o di un percorso specifico del tuo dominio, ad esempio https://auth.example.com/realms/master, Gemini aggiunge gli stessi percorsi "well-known" direttamente a quella sottodirectory, nel seguente ordine.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (supporto dei percorsi nidificati)

Funzionalità JSON richieste

La risposta dei metadati deve includere i seguenti campi. L'integrazione non va a buon fine se mancano i campi obbligatori o se non vengono trovati tipi validi.

authorization_endpoint

Deve essere un URL di stringa valido.

token_endpoint

Deve essere un URL di stringa valido.

response_types_supported

Deve contenere la stringa code.

registration_endpoint

Per il momento, Play Console si basa su Dynamic Client.

Registration (RFC 7591). Devi fornire un endpoint di registrazione nei metadati o inserire l'ID client/il secret direttamente nell'interfaccia utente di Play Console.

Se il tuo server di autorizzazione non supporta la Dynamic Client Registration (DCR), devi implementare e compilare manualmente i campi ID client e Client secret all'interno della UI di Play Console per completare l'integrazione.

Se la tua implementazione supporta Proof Key for Code Exchange (PKCE) o sessioni permanenti, devi includere i campi delle funzionalità pertinenti (come Challenge Methods e Grant Types) nel JSON di discovery. In questo modo, viene garantita la compatibilità con gli standard di sicurezza e connettività di Gemini. Se supporti l'ambito, devi includere il campo scopes_supported.

Configurazione di esempio

Di seguito è riportata una risposta JSON valida che soddisfa i requisiti del nostro cliente.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

Per i casi in cui includi PKCE, il seguente snippet mostra un esempio di ciò che potrebbe essere incluso nel blocco JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

Per i casi in cui includi il campo scopes_supported, il seguente snippet mostra un esempio di ciò che potrebbe essere incluso nel blocco JSON.

"scopes_supported": ["mcp", "cart.order"],

Flusso del codice di autorizzazione (versione semplificata)

I passaggi seguenti descrivono il flusso del codice di autorizzazione standard. Questa sequenza illustra esattamente in che modo la piattaforma di app connesse ottiene in modo sicuro i token di accesso necessari dal tuo server per agire per conto di un utente.

1. Richiesta di autorizzazione: la piattaforma Google determina che deve chiamare la tua funzione, ma l'utente non è ancora autorizzato. Il chatbot avvia il flusso reindirizzando il browser dell'utente (o visualizzando un link) al tuo endpoint di autorizzazione.

   Questa richiesta include il tuo ID client (o generato automaticamente con DCR), l'URI di reindirizzamento di Gemini e i parametri PKCE critici (code_challenge e code_challenge_method).

   Inserisci nella lista consentita i seguenti URL per la configurazione di OAuth:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. Consenso dell'utente: il tuo server di autorizzazione convalida la richiesta, autentica l'utente (accesso) e chiede all'utente di concedere l'autorizzazione alla piattaforma Google per accedere ai suoi dati o al suo servizio.

3. Concessione del codice: dopo che l'utente ha dato il consenso, il tuo server reindirizza il browser dell'utente all'URI di reindirizzamento di Gemini, aggiungendo un codice di autorizzazione temporaneo all'URL.

4. Scambio di token: il backend di Gemini invia una richiesta POST al tuo endpoint token, scambiando il codice di autorizzazione con un token di accesso.

   Nota: questa richiesta deve includere il parametro PKCE (code_verifier) per dimostrare che si tratta dello stesso client che ha avviato il flusso.

5. Accesso concesso: l'endpoint del token verifica il codice e i parametri PKCE, genera un token di accesso e, facoltativamente, un token di aggiornamento, quindi li restituisce a Gemini.

   Suggerimento: anche se i token di aggiornamento sono facoltativi, ti consigliamo vivamente di configurare il tuo server di autorizzazione in modo che li emetta. I token di aggiornamento consentono alla piattaforma di app connesse di mantenere l'accesso senza dover autenticare nuovamente l'utente.

Requisiti chiave di PKCE

PKCE aggiunge un livello di sicurezza per impedire l'intercettazione non autorizzata dei codici di autorizzazione.

Attenzione: il rispetto di questi requisiti PKCE è fondamentale per la corretta gestione dei token di accesso e dei token di aggiornamento, il che contribuisce a proteggere i dati degli utenti e a mantenere l'integrità dell'ecosistema.

• code_verifier: una stringa casuale crittografica generata da Gemini all'inizio del flusso. Queste informazioni rimangono private.
• code_challenge: una trasformazione di code_verifier, in genere l'hashing SHA256. Questo viene inviato pubblicamente, come descritto nel passaggio 1 del flusso del codice di autorizzazione.
• Convalida: l'endpoint token (descritto nel passaggio 4 del flusso del codice di autorizzazione) deve convalidare che il code_verifier ricevuto, una volta trasformato, corrisponda al code_challenge originale.

Debug…

Informazioni dettagliate sugli errori di collegamento sono disponibili in Esplora log. Per attivare e visualizzare gli errori, segui le istruzioni riportate in Monitora gli errori di collegamento degli account nel progetto della console Google.

Requisiti di configurazione del collegamento dell'Account Google

Leggi le seguenti indicazioni sull'API per informazioni sulla configurazione del collegamento dell'Account Google.

• Collegamento dell'Account Google con OAuth
• API Your Account Linking
• API per il collegamento dell'Account Google

Per registrare correttamente l'integrazione OAuth, devi configurare dettagli specifici sul tuo server di autorizzazione. Assicurati di aver preparato i seguenti endpoint, credenziali e asset.

Campo di configurazione	Descrizione	Responsabilità dello sviluppatore
ID client e secret	Le credenziali univoche generate dal tuo server di autorizzazione specificamente per la piattaforma di app collegate. Il client secret è la credenziale di sicurezza (password) associata all'ID client. Nota: se l'ID client è stato emesso dallo sviluppatore, deve essere fornito da quest'ultimo. Se l'ID client è stato emesso da Google, lo sviluppatore potrebbe dover registrare o verificare un secret.	Utilizza l'ID fornito dalla piattaforma in tutte le richieste di autorizzazione.
Endpoint di autorizzazione	L'URL a cui reindirizzare gli utenti per l'autenticazione e la concessione del consenso	Ospita l'endpoint, ad esempio https://yourdomain.com/oauth/authorize
Token Endpoint (Endpoint token)	L'endpoint di backend per scambiare i codici di autorizzazione con i token di accesso/aggiornamento e per aggiornare i token scaduti.	Ospita questo endpoint, ad esempio https://yourdomain.com/oauth/token
Endpoint di revoca Facoltativo	L'URL per notificare al tuo sistema di invalidare un token quando un utente si disconnette. Quando un utente scollega o disconnette la tua integrazione dalla piattaforma App collegate, invieremo una richiesta POST all'endpoint /revoke contenente il token di accesso o di aggiornamento. Per saperne di più, consulta Scollegamento degli account.	Ospita l'endpoint, ad esempio https://yourdomain.com/oauth/revoke Il tuo server deve gestire questa richiesta invalidando definitivamente il token fornito. In questo modo, tutti i tentativi successivi della Connected Apps Platform di utilizzare il token non andranno a buon fine, mantenendo la sicurezza dei dati dell'utente dopo la disconnessione.
URI di reindirizzamento	L'URL di callback specifico fornito dalla piattaforma a cui il server di autorizzazione invia il codice dopo il consenso.	Configura il tuo server di autorizzazione in modo che accetti solo l'URI di reindirizzamento ufficiale e registrato dalla piattaforma.
Aggiorna	/token con grant_type=refresh_token Un meccanismo che consente alla piattaforma di app connesse di ottenere un nuovo token di accesso alla scadenza di quello corrente, mantenendo l'integrazione connessa senza interruzioni e senza richiedere all'utente di accedere ripetutamente. Quando un token di accesso esistente scade, la piattaforma di app collegate invia automaticamente una richiesta POST al tuo endpoint /token. Il payload della richiesta includerà grant_type=refresh_token insieme al token di aggiornamento emesso in precedenza dal tuo server.	Il tuo server deve convalidare il token di aggiornamento fornito e restituire un nuovo token di accesso nella risposta JSON. Inoltre, per implementare il collegamento permanente, devi evitare di ruotare il token di aggiornamento durante questo scambio. Anziché emetterne uno nuovo, restituisci esattamente lo stesso token di aggiornamento nella risposta JSON ed estendi la data di scadenza nel tuo backend.
Tipo di risposta	Questo valore deve essere configurato su CODE per supportare il flusso del codice di autorizzazione.
Ambiti	L'insieme di autorizzazioni e livelli di accesso specifici che definiscono ciò che il token è autorizzato a fare. Questi devono essere predefiniti nella configurazione in modo che Google possa richiederli durante l'handshake di autorizzazione iniziale.	Dovrai fornire un elenco di ambiti predefiniti (ad esempio openid, profile, email) che la piattaforma di app collegate deve richiedere quando avvia il flusso. Gli ambiti richiesti devono essere il più ridotti possibile (principio del privilegio minimo), ma pienamente sufficienti per i Critical User Journey (CUJ) supportati dall'integrazione con MCP.
Asset UI: logo	Logo dello sviluppatore da visualizzare nelle schermate di collegamento dell'account e per il consenso.	Deve essere un'immagine vettoriale quadrata (SVG) con un aspetto circolare e di almeno 500 x 500 pixel. Ad esempio, consulta https://[partner-domain]/assets/logo.svg o il file SVG non elaborato.
Collegamento di app native (App Flip)	Per supportare il collegamento degli account direttamente dalle tue applicazioni Android o iOS native, è sconsigliato l'utilizzo di webview standard. Invece, per un'esperienza utente fluida, è vivamente consigliato implementare App Flip. Per ulteriori informazioni, consulta Collegamento dell'Account Google con App Flip basato su OAuth.	Completa la verifica del Play Store e dell'App Store e incorpora gli URI di reindirizzamento di Google direttamente nelle tue applicazioni native per garantire un passaggio di autorizzazione sicuro da app ad app.
Durata del token	(Facoltativo) Il periodo di validità di un token di accesso prima che sia necessario un aggiornamento. Utile per configurare le policy di timeout in GAL.	I tempi di scadenza comuni variano da minuti, ore, giorni, a seconda delle esigenze di sicurezza, ad esempio 30 days)

Errori di integrazione comuni

Ecco un elenco di errori comuni e potenziali soluzioni applicabili al processo di integrazione.

• Concessione "code" mancante: il sistema automatico della piattaforma Gemini controlla esplicitamente response_types_supported per il valore "code".
• Endpoint di registrazione mancante: anche se il tuo server supporta i documenti dei metadati dell'ID client, l'app Gemini (che agisce come client OAuth che si connette al tuo server) richiede attualmente la presenza di un registration_endpoint dedicato nel JSON di rilevamento.
• Errore non 200: se il meccanismo di rilevamento automatico dei metadati di Gemini raggiunge il tuo URL well-known e riceve un errore 404 o 500, non tenterà di indovinare altri URL. Assicurati che l'URL Discovery sia accessibile pubblicamente.