LinkedIn
Instagram
WhatsApp
Telegramma
Gmail
Prospettiva
Calendario di Google
Partecipare alla comunità SlackErrori comuni di Google OAuth e API di Gmail (e come risolverli uno per uno)
Ogni sviluppatore che integra Gmail o Google Calendar con Google OAuth incontrerà almeno uno di questi errori di Google OAuth. Questa guida consolida tutti i 7 errori comuni di Google OAuth in un unico posto, con la causa esatta e la soluzione passo dopo passo per ciascuno. La comprensione di questi errori di Google OAuth ti farà risparmiare ore di debug.
# Scambio di token OAuth di Google
import richieste
token_risposta = richieste.post(
"https://oauth2.googleapis.com/token",
dati={
"codice"codice_autorizzazione,
"client_id": ID_CLIENTE,
"client_secret"SEGRETO_CLIENT,
"uri_di_reindirizzamento": URI_DI_REDIRECIONAMENTO,
"grant_type": "codice_autorizzazione"
}
)Riferimento rapido: ogni errore di Google OAuth a colpo d'occhio
Una tabella riassuntiva di tutti i 7 errori di Google OAuth trattati in questa guida: fase in cui si verifica, causa principale e link alla correzione rapida nella sezione dettagliata sottostante. Segna questa tabella come riferimento quando esegui il debug degli errori di Google OAuth in fase di sviluppo o produzione.
| Messaggio di errore | Palcoscenico | Causa principale | Riparazione veloce |
|---|---|---|---|
| redirect_uri_mismatch | Authorization | L'URI di reindirizzamento nella tua richiesta non corrisponde esattamente a uno registrato nella Google Cloud Console | Riparalo |
| admin_policy_enforced | Authorization | Un super amministratore di Workspace ha limitato le app OAuth o gli ambiti a cui gli utenti dell'organizzazione possono concedere l'accesso. | Riparalo |
| accesso_negato | Authorization | L'app è in modalità di test e l'utente non è un utente di test, o l'app richiede ambiti ristretti senza verifica | Riparalo |
| concessione_non_valida | Aggiornamento del gettone | Token di aggiornamento scaduto, revocato o utilizzato più di una volta (codice di autenticazione a uso singolo) | Riparalo |
| Schermata di consenso mancante | Console Google Cloud | La nuova interfaccia di Google Cloud ha spostato la schermata di consenso OAuth; richiede inoltre il ruolo di Proprietario/Editor sul progetto | Riparalo |
| ambito_non_valido | Authorization | Errore nell'URL dello scope o l'API di Google corrispondente non è abilitata nel progetto | Riparalo |
| Google non ha verificato | Authorization | L'app utilizza ambiti sensibili/restretti ma non ha completato la verifica di Google; la modalità di test è limitata a 100 utenti | Riparalo |
Errore 400: redirect_uri_mismatch
Questo è l'errore OAuth di Google più comune per gli sviluppatori che configurano una nuova integrazione. Si verifica durante il passaggio di autorizzazione, prima che venga emesso alcun token.
Il messaggio di errore esatto
Errore 400: redirect_uri_mismatch
L'URI di reindirizzamento nella richiesta non corrispondeva a un URI di reindirizzamento registrato.
error=redirect_uri_mismatch
Causa
Google confronta il uri_di_reindirizzamento parametro che passi nell'URL di autorizzazione con l'elenco degli URI di reindirizzamento autorizzati registrati nel tuo client OAuth nella Google Cloud Console. Anche una singola differenza di carattere, una barra finale, http vs https, o una porta diversa - innesca questo errore.
Correggere (passo dopo passo)
https://yourapp.com/oauth/callback. Il valore deve essere identico carattere per carattere, inclusi schema, porta, e slash finale.
uri_di_reindirizzamento il valore che passi all'endpoint di autorizzazione e all'endpoint di scambio del token sono identici.
redirect_uri_mismatch su localhost
Durante lo sviluppo locale, registra l'URI esatto di localhost che utilizzi - ad esempio http://localhost:3000/callback. Google consente http:// (non solo https://) per le URI di localhost. Se modifichi la porta di sviluppo, ricordati di aggiornare l'URI registrata.
Questi sono due campi separati e servono scopi diversi. Le origini JavaScript autorizzate vengono utilizzate per i flussi OAuth lato browser (flusso implicito, Google Identity Services). Gli URI di reindirizzamento autorizzati vengono utilizzati per i flussi di codice di autorizzazione lato server. Aggiungere un URI alle origini JavaScript NON risolverà un redirect_uri_mismatch errore - devi aggiungerlo al campo URI di reindirizzamento. Un client OAuth di Google può avere fino a 100 URI di reindirizzamento registrati.
Errore 400: policy_admin_imposta
Questo errore non è un bug nel tuo codice. È una politica organizzativa imposta da un super amministratore di Google Workspace. Uno sviluppatore normale non può risolverlo da solo.
Il messaggio di errore esatto
Errore 400: admin_policy_enforced
L'account Google non può essere utilizzato per l'autorizzazione a causa delle policy della tua organizzazione. Contatta il tuo amministratore per maggiori informazioni.
error=admin_policy_enforced
Causa
Un super amministratore di Google Workspace ha limitato quali applicazioni di terze parti o ambiti OAuth gli utenti dell'organizzazione possono concedere l'accesso. Questa configurazione avviene tramite Controlli API nella Google Admin Console. Quando un'app non è nell'elenco delle app approvate, ogni utente di Workspace riceverà questo errore quando tenterà di autorizzarla, indipendentemente dallo stato di verifica dell'app.
Questo è un controllo di conformità e sicurezza, non un'errata configurazione lato sviluppatore. La risoluzione corretta è sempre lato amministratore.
Correzione (solo lato amministratore)
Un utente che incontra admin_policy_enforced non possono risolverlo da soli. Devono contattare il proprio super amministratore di Google Workspace e richiedere che la specifica app OAuth venga contrassegnata come "Trusted" (Fidato). Se l'utente è l'amministratore, può seguire i passaggi sopra indicati. Se il dominio applica una rigida policy "Consenti app specifiche", l'app deve prima essere aggiunta esplicitamente all'elenco delle approvate prima di poter essere impostata come "Trusted" (Fidato).
Se stai realizzando strumenti interni e vuoi evitare del tutto il consenso OAuth per utente, un account di servizio con delega a livello di dominio è l'alternativa - vedi la nostra Account di servizio Gmail e guida DWD.
access_denied & "Questa app è bloccata" (app non verificata)
Gli utenti vedono una schermata "Questa app è bloccata" o ricevono accesso_negato nella callback OAuth. Questa presenta molteplici cause principali a seconda che la tua app sia ancora in modalità Test o stia richiedendo ambiti ristretti.
Il messaggio di errore esatto
Accesso bloccato: [Nome della tua app] non ha completato il processo di verifica di Google
errore=access_denied
-- oppure --
Questa app è bloccata.
Questa app ha tentato di accedere a informazioni sensibili nel tuo Account Google.
Contatta lo sviluppatore per maggiori informazioni.
Cause
Mentre la tua app OAuth è nello stato "In prova", solo gli utenti aggiunti esplicitamente come utenti di test possono autorizzarla. Chiunque altro riceve immediatamente un "accesso negato".
La modalità di test è limitata a 100 utenti di test unici in qualsiasi momento. Una volta raggiunto il limite di 100, i nuovi utenti non potranno autorizzare l'app anche se aggiunti.
Ambiti come modifica gmail o gmail.invia sono Ambienti sensibili. Le app che li richiedono devono completare il processo di verifica dell'app di Google prima che gli utenti effettivi possano concedere l'accesso.
Un numero limitato di ambiti (ad esempio, accesso completo a Gmail) sono Restretti e richiedono un audit di sicurezza di terze parti (CASA) oltre alla verifica.
Risolvi
invalid_grant: "riconnetti il tuo account Gmail"
Il concessione non valida l'errore è uno dei più confusi in produzione: si interrompe silenziosamente per un sottoinsieme di utenti e richiede un nuovo flusso OAuth per il ripristino. Comprendere il ciclo di vita del token di aggiornamento è la chiave per gestirlo correttamente.
Il messaggio di errore esatto
{"error": "invalid_grant", "error_description": "Token scaduto o revocato."}
-- o --
{"error": "invalid_grant", "error_description": "Richiesta non valida"}
Causa: il ciclo di vita del token di aggiornamento
Correggi: riautorizza con access_type=offline + prompt=consent
from google_auth_oauthlib.flow import Flusso
flusso = Flow.from_client_secrets_file(
'client_secrets.json',
scope=['https://www.googleapis.com/auth/gmail.readonly'],
redirect_uri=REDIRECT_URI
)
# access_type=offline → ottenere un token di aggiornamento
# prompt=consent → richiede un nuovo consenso, restituisce sempre un nuovo token di aggiornamento
auth_url, stato = flusso.url_autorizzazione(
tipo_di_accesso='offline',
prompt'consenso'
)
# Salva il NUOVO refresh_token contenuto nella risposta
Il vecchio token # non è più valido: aggiorna il tuo databasePer evitare concessione_non_valida in produzione: usa sempre access_type=offline e consenso Quando si avvia il flusso OAuth, aggiorna il token di aggiornamento memorizzato ogni volta che l'utente riautorizza, rileva concessione_non_valida errori e attivare un'interfaccia utente di riautorizzazione graduale (un prompt "ricollegare il tuo account Gmail"), e spostare la tua app dalla modalità di test per ottenere token permanenti.
La schermata di consenso OAuth non viene visualizzata nella Google Cloud Console
Questa è la query di ricerca con il volume più elevato in questo cluster (oltre 390 ricerche mensili). La pagina "Schermata di consenso OAuth" sembra essere scomparsa dalla Google Cloud Console per molti sviluppatori nel periodo 2024-2026 a causa di una riprogettazione dell'interfaccia utente. Non è stata rimossa, si è spostata.
Sintomo
Apri la Google Cloud Console e navighi su API e servizi, ma la voce di menu "Schermata di consenso OAuth" è mancante o facendo clic su di essa si viene reindirizzati a una nuova "Panoramica su OAuth" pagina che mostra un dashboard riassuntivo anziché il modulo di configurazione che ti aspettavi.
Cause
Correggere (passo dopo passo)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Questo deep link bypassa la pagina di panoramica e va direttamente alla configurazione della schermata di consenso. Per una guida completa su ogni campo di configurazione, la selezione del tipo di utente e il limite di 100 utenti per i test, consulta la nostra Guida alla configurazione della schermata di consenso di OAuth.
Settimane di verifica.
Utilizzo Chiave di Unipile e inizia adesso.
Non perdere clienti in attesa delle recensioni di Google. Collega gli account Gmail in 5 minuti con le nostre credenziali sviluppatore pre-verificate.
ambito_non_valido
Un errore di battitura nell'URL dello scope o un'API disabilitata faranno sì che Google rifiuti l'intera richiesta di autorizzazione prima che avvenga qualsiasi interazione con l'utente.
Il messaggio di errore esatto
{"errore": "ambito_non_valido",
"descrizione_errore": "Alcuni ambiti richiesti non erano validi.
{valid=[https://mail.google.com/], invalid=[gmail.readonly]}"}
-- o sull'URL della schermata di consenso --
errore=ambito_non_valido&descrizione_errore=Alcuni+ambiti+richiesti+non+erano+validi
Causa
Due cause profonde comuni: (1) il valore scope è un nome breve come gmail.solodlettura invece dell'URL completo https://www.googleapis.com/auth/gmail.readonly, o (2) l'API di Gmail (o qualsiasi altra API di Google a cui stai facendo riferimento) non è abilitata nel progetto Google Cloud.
Gmail ambito comuni e i loro URL corretti
| URL di ambito (utilizzare l'URL completo) | Ciò che permette | Tipo |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Leggi tutti i messaggi e i thread | Sensibile |
| https://www.googleapis.com/auth/gmail.send | Invia email per conto dell'utente | Sensibile |
| https://www.googleapis.com/auth/gmail.modify | Leggi, componi, invia, elimina thread | Sensibile |
| https://mail.google.com/ | Accesso completo alla casella di posta (IMAP/SMTP) | Restricted |
| https://www.googleapis.com/auth/userinfo.email | Leggere solo l'indirizzo email dell'utente | Base |
Risolvi
https://www.googleapis.com/auth/ o https://mail.google.com/. Non usare mai la forma abbreviata come gmail.solodlettura.
"Google non ha verificato questa app" e il limite di 100 utenti
La schermata di avviso "Google non ha verificato questa app" appare quando un'app non verificata richiede ambiti sensibili o riservati. Sebbene gli utenti possano procedere facendo clic su "Avanzate" e poi su "Vai a [nome app] (non sicuro)", questa soluzione non è adatta per la produzione e la modalità di test limita l'app a un massimo di 100 utenti unici in totale.
Causa
Quando la tua app richiede ambiti sensibili (come gmail.solodlettura o gmail.invia), Google mostra questa schermata di avviso a ogni utente finché non completerai la revisione di verifica. Per gli ambiti limitati, sarà inoltre necessario superare un audit di sicurezza di terze parti (CASA Livello 2).
Mentre lo stato di pubblicazione è "In test", questa schermata di avviso viene visualizzata anche per gli utenti di test e il numero totale di utenti di test consentiti è limitato a 100. I token per gli utenti di test scadono dopo 7 giorni.
Risolvi
https://mail.google.com/inoltre completa un CASA Livello 2 valutazione di sicurezza da parte di un valutatore approvato da Google.
Questi errori scompaiono quando il progetto OAuth è già certificato
La schermata "Google non ha verificato questa app", il limite di 100 utenti e la scadenza del token di 7 giorni in modalità Test sono tutti sintomi di possedere e gestire il proprio progetto Google Cloud. Un intermediario tecnico indipendente che agisce per conto di ciascun utente autenticato - e ha già completato la certificazione CASA di Livello 2 - rimuove completamente questo overhead dal tuo lato. I tuoi utenti autorizzano una volta; il ciclo di vita del token, la conformità all'ambito e la verifica ripetuta vengono gestiti a livello di piattaforma.
Questo non è un workaround per la revisione di sicurezza di Google. Unipile ha completato in modo indipendente il livello 2 CASA e non è affiliata, approvata o sponsorizzata da Google.
Nave su OAuth Google già certificatoCome evitare questa intera classe di errori di Google OAuth
Osservando tutti e 7 gli errori di Google OAuth in questa guida, emerge uno schema. Ognuno di essi ha la stessa origine: la gestione manuale del proprio progetto Google Cloud e della sua configurazione OAuth. Questi errori di Google OAuth non sono casuali: sono conseguenze strutturali della proprietà di un progetto OAuth non verificato, da discrepanze negli URI di reindirizzamento e fallimenti nella rotazione dei token al limite dei 100 utenti e ai rifiuti della schermata di consenso.
C'è un altro modo. Usando un intermediario tecnico indipendente che agisce per conto di ciascun utente autenticato - uno che ha già completato la revisione di verifica di Google e la certificazione di sicurezza CASA Tier 2 - elimina tutte queste modalità di errore dal tuo carico di lavoro. Il confronto sottostante mostra esattamente quali errori scompaiono e quale infrastruttura gestisce Unipile. Vedi il Documentazione Unipile su Google OAuth per la guida completa all'integrazione.
Ogni errore in questa guida: chi possiede la correzione?
I 7 errori di Google OAuth trattati sopra condividono una radice comune: possiedi il progetto Google Cloud, quindi possiedi ogni modalità di errore. Ecco un confronto affiancato di cosa ciò significa in pratica.
La distinzione chiave: Unipile ha già completato la revisione di sicurezza di Google e la valutazione di livello 2 CASA per le connessioni che gestisce per tuo conto. Non si tratta di un aggiramento della revisione di sicurezza di Google: Unipile l'ha già superata. I tuoi utenti ottengono una schermata di consenso pulita (nessun avviso di "app non verificata"), la tua app viene distribuita immediatamente e puoi procedere con la tua verifica Google Cloud in parallelo senza alcuna pressione di scadenze di produzione.
Nota sulla conformità: Unipile è un intermediario tecnico indipendente, non affiliata, approvata o sponsorizzata da Google. Il client OAuth di Google di Unipile è certificato CASA di Livello 2, consentendo ai tuoi utenti di autorizzare l'accesso a Gmail senza un avviso di "app non verificata" per le connessioni mediate da Unipile. Questa non è una soluzione alternativa alla revisione di sicurezza di Google: Unipile l'ha già superata per le connessioni che media. per conto di ciascun utente autenticato. Gli utenti possono revocare l'accesso in qualsiasi momento tramite la pagina delle autorizzazioni del loro Account Google.
Domande frequenti sugli errori di Google OAuth
Risposte alle domande più comuni sugli errori di Google OAuth e sugli errori dell'API Gmail, che coprono il ciclo di vita dei token, le policy degli amministratori, gli URI di reindirizzamento e la configurazione della Google Cloud Console.
admin_policy_enforced significa che un super amministratore di Google Workspace ha impedito che la tua app o gli specifici ambiti OAuth da essa richiesti vengano autorizzati dagli utenti di tale organizzazione. È una policy di controllo degli accessi organizzativi, non un bug nel tuo codice. La soluzione richiede un'azione da parte del super amministratore di Workspace nella Google Admin Console alla voce Sicurezza > Controlli API > Gestisci accesso app di terze parti.
No. Un utente normale non può risolvere admin_policy_enforced. Solo un Google Workspace superamministratore puoi risolvere questo errore contrassegnando l'app come attendibile nella Console di amministrazione. L'utente interessato deve contattare il proprio amministratore IT o l'amministratore principale di Workspace e richiedere che la specifica app OAuth venga aggiunta all'elenco approvato.
Il redirect_uri_mismatch su localhost accade quando l'URI che registri nella Google Cloud Console non corrisponde esattamente all'URI utilizzato dal tuo server di sviluppo locale. Ad esempio, registrando http://localhost:3000/callback ma in esecuzione sulla porta 3001, o dimenticando uno slash finale. Google consente http:// (non solo https://per le URI di localhost. Registra l'URI esatta utilizzata dal tuo server locale, incluso il numero di porta corretto.
No. Le origini JavaScript autorizzate e gli URI di reindirizzamento autorizzati sono due campi separati. Le origini JavaScript sono utilizzate solo per i flussi OAuth lato browser. Per risolvere redirect_uri_mismatch, devi aggiungere l'URI a URI di reindirizzamento autorizzati campo, non alle origini di JavaScript.
Un singolo client OAuth 2.0 di Google può avere fino a 100 URI di reindirizzamento autorizzati registrato. Ciò consente di registrare URI per diversi ambienti (sviluppo locale, staging, produzione) e diversi percorsi di callback all'interno dello stesso client.
Se la tua app è in Test dello stato di pubblicazione, i token di aggiornamento di Google scadono dopo 7 giorni indipendentemente dall'uso. Questo è intenzionale per le app non verificate. Passa allo stato Produzione facendo clic su Pubblica App nella pagina della schermata di consenso OAuth per ottenere token di lunga durata. In produzione, i token di aggiornamento rimangono validi finché l'utente utilizza la tua app almeno una volta ogni 6 mesi. Per un'alternativa gestita, visita il nostro soluzione Gmail API gestita.
Google revoca i token di aggiornamento che non sono stati utilizzati per 6 mesi (circa 180 giorni). I token vengono revocati anche quando: l'utente cambia la password del proprio account Google, l'utente revoca l'accesso all'app nelle impostazioni di sicurezza del proprio account Google, si autorizza nuovamente con ambiti diversi o il numero totale di token di aggiornamento per una singola coppia utente-app supera 50 (i più vecchi vengono revocati per primi). Per una panoramica completa sulla creazione di integrazioni email robuste, consulta il nostro Guida completa all'API email.
Google ha ridisegnato la Cloud Console nel 2024. La configurazione della schermata di consenso OAuth è ora all'interno API e Servizi > Panoramica OAuth. Clicca Modifica app o utilizza le schede Branding, Audience e Scopes. Controlla anche: hai bisogno Ruolo di Editor o Proprietario sul progetto (Lo spettatore non può accedere al modulo) e assicurati di essere sul progetto corretto utilizzando il selettore del progetto in cima alla console.
Stai ancora riscontrando un errore di Google OAuth non elencato qui? Salta il debug e lascia che Unipile gestisca l'autenticazione OAuth di Gmail per te.
Crea ora
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR