LinkedIn
Instagram
WhatsApp
Telegramm
Google Mail
Ausblick
Google Kalender
Slack-Gemeinschaft beitretenHäufige Fehler bei Google OAuth & Gmail API (und wie man jeden behebt)
Jeder Entwickler, der Gmail oder Google Kalender mit Google OAuth integriert, wird mindestens einen dieser Google OAuth-Fehler feststellen. Dieser Leitfaden fasst alle 7 gängigen Google OAuth-Fehler an einem Ort zusammen – mit der genauen Ursache und der Schritt-für-Schritt-Lösung für jeden einzelnen. Das Verständnis dieser Google OAuth-Fehler spart Stunden beim Debuggen.
# Google OAuth-Token-Austausch
import Anfragen
Token-Antwort = requests.post(
"https://oauth2.googleapis.com/token",
daten={
"code"Berechtigungscode,
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"weiterleitungs_uri": UMLEITUNGS_ZIEL,
"grant_type": "autorisierungscode"
}
)Schnellreferenz: Jeder Google OAuth Fehler auf einen Blick
Eine Einzeltabellenübersicht aller 7 Google OAuth-Fehler, die in dieser Anleitung behandelt werden – Stadium, in dem sie auftreten, Ursache und Link zur schnellen Fehlerbehebung im Detailabschnitt unten. Lesezeichen für diese Tabelle als Referenz bei der Fehlerbehebung von Google OAuth-Fehlern in Entwicklung oder Produktion.
| Fehlermeldung | Bühne | Ursache | Schnelle Lösung |
|---|---|---|---|
| redirect_uri_mismatch | Authorization | Die Weiterleitungs-URI in Ihrer Anfrage stimmt nicht genau mit einer in der Google Cloud Console registrierten überein | Reparariere es |
| admin_policy_enforced | Authorization | Ein Workspace-Superadministrator hat eingeschränkt, auf welche OAuth-Apps oder -Bereiche Nutzer in der Organisation Zugriff gewähren können | Reparariere es |
| Zugriff verweigert | Authorization | App befindet sich im Testmodus und der Nutzer ist kein Testnutzer, oder die App fordert verifizierungslose eingeschränkte Gültigkeitsbereiche an | Reparariere es |
| ungültiger_grant | Token aktualisieren | Aktualisierungstoken abgelaufen, widerrufen oder mehrfach verwendet (einmalig verwendbarer Autorisierungscode) | Reparariere es |
| Zustimmungsbildschirm fehlt | Google Cloud-Konsole | Die neue Google Cloud UI hat den OAuth-Zustimmungsbildschirm verschoben; erfordert nun auch die Rolle "Besitzer" oder "Editor" für das Projekt | Reparariere es |
| ungültiger_Bereich | Authorization | Umfangs-URL-Tippfehler oder die entsprechende Google API ist im Projekt nicht aktiviert | Reparariere es |
| Google hat nicht bestätigt | Authorization | App verwendet sensible/eingeschränkte Bereiche, hat Google-Verifizierung aber noch nicht abgeschlossen; Testmodus ist auf 100 Benutzer beschränkt | Reparariere es |
Fehler 400: redirect_uri_mismatch
Das ist der häufigste Google OAuth-Fehler für Entwickler, die eine neue Integration einrichten. Er tritt während des Autorisierungsschritts auf – bevor ein Token ausgestellt wird.
Die genaue Fehlermeldung
Fehler 400: redirect_uri_mismatch
Die Umleitungs-URI in der Anfrage stimmte nicht mit einer registrierten Umleitungs-URI überein.
error=redirect_uri_mismatch
Ursache
Google vergleicht die redirect_uri Parameter, den Sie in Ihrer Autorisierungs-URL übergeben, mit der Liste der autorisierten Weiterleitungs-URIs, die in Ihrem OAuth-Client in der Google Cloud Console registriert sind. Schon ein einziger Zeichenunterschied – ein abschließender Schrägstrich, http gegen https, oder einen anderen Port – löst diesen Fehler aus.
Korrigieren (Schritt für Schritt)
https://yourapp.com/oauth/callback. Der Wert muss Zeichen für Zeichen identisch sein, einschließlich Schema, Port und abschließendem Schrägstrich.
redirect_uri Der Wert, den Sie an den Autorisierungsendpunkt und an den Token-Austausch-Endpunkt übergeben, ist identisch.
redirect_uri_mismatch auf localhost
Registrieren Sie während der lokalen Entwicklung die genaue localhost-URI, die Sie verwenden – zum Beispiel http://localhost:3000/callback. Google erlaubt http:// nicht nur https://) für URIs von localhost. Wenn Sie Ihren Entwicklungsport ändern, vergessen Sie nicht, die registrierte URI zu aktualisieren.
Dies sind zwei getrennte Felder und sie dienen unterschiedlichen Zwecken. Autorisierte JavaScript-Ursprünge werden für Browser-OAuth-Flows (Implicit Flow, Google Identity Services) verwendet. Autorisierte Umleitungs-URIs werden für serverseitige Authorization-Code-Flows verwendet. Das Hinzufügen einer URI zu JavaScript-Ursprüngen wird eine nicht beheben redirect_uri_mismatch Fehler – Sie müssen es dem Feld „Redirect URIs“ hinzufügen. Ein Google OAuth Client kann bis zu 100 registrierte Redirect URIs haben.
Fehler 400: admin_policy_enforced
Dieser Fehler ist kein Fehler in Ihrem Code. Es handelt sich um eine organisatorische Richtlinie, die von einem Google Workspace Superadministrator durchgesetzt wird. Ein normaler Entwickler kann ihn nicht allein beheben.
Die genaue Fehlermeldung
Fehler 400: admin_policy_enforced
Ihr Google-Konto kann aufgrund der Richtlinien Ihrer Organisation nicht zur Autorisierung verwendet werden. Kontaktieren Sie Ihren Administrator für weitere Informationen.
error=admin_policy_enforced
Ursache
Ein Google Workspace Superadministrator hat eingeschränkt, auf welche Drittanbieteranwendungen oder OAuth-Bereiche Benutzer in der Organisation zugreifen können. Dies wird konfiguriert über API-Steuerelemente in der Google Admin Console. Wenn eine App nicht auf der zugelassenen Liste steht, erhalten alle Nutzer in diesem Workspace diese Fehlermeldung, wenn sie versuchen, sie zu autorisieren – unabhängig vom Verifizierungsstatus der App.
Das ist ein Compliance und Sicherheitskontrolle, nicht eine Fehlkonfiguration auf Entwicklerseite. Die richtige Lösung ist immer auf Administratorseite.
Beheben (nur Admin-Seite)
Ein Nutzer, der auf etwas stößt admin_policy_enforced können es nicht selbst lösen. Sie müssen sich an ihren Google Workspace Super-Admin wenden und beantragen, dass die spezifische OAuth-App als "vertrauenswürdig" eingestuft wird. Wenn der Nutzer der Administrator ist, kann er die oben genannten Schritte ausführen. Wenn die Domain eine strikte Richtlinie „Nur bestimmte Apps zulassen“ erzwingt, muss die App zuerst explizit zur zugelassenen Liste hinzugefügt werden, bevor sie als „vertrauenswürdig“ festgelegt werden kann.
Wenn Sie interne Tools entwickeln und die OAuth-Zustimmung pro Benutzer vollständig vermeiden möchten, ist ein Dienstkonto mit Domainweiter Berechtigung die Alternative – siehe unser Gmail-Dienstkonto & DWD-Anleitung.
Zugriff verweigert & "Diese App ist blockiert" (nicht verifizierte App)
Benutzer sehen einen Bildschirm mit der Meldung "Diese App ist blockiert" oder erhalten Zugriff verweigert im OAuth-Callback. Diese hat mehrere Ursachen, je nachdem, ob sich Ihre App noch im Testmodus befindet oder auf eingeschränkte Bereiche abzielt.
Die genaue Fehlermeldung
Zugriff blockiert: [Dein App-Name] hat den Google-Verifizierungsprozess nicht abgeschlossen
error=access_denied
-- oder --
Diese App ist blockiert.
Diese App hat versucht, auf sensible Informationen in deinem Google-Konto zuzugreifen.
Kontaktiere den Entwickler für weitere Informationen.
Ursachen
Solange Ihre OAuth-App im Veröffentlichungsstatus "Test" ist, können nur explizit als Testbenutzer hinzugefügte Benutzer sie autorisieren. Alle anderen erhalten sofort access_denied.
Der Testmodus ist auf 100 eindeutige Testnutzer gleichzeitig beschränkt. Sobald Sie 100 erreicht haben, können neue Benutzer die App nicht mehr autorisieren, auch wenn sie hinzugefügt werden.
Bereiche wie Gmail ändern oder Gmail senden sind sensible Bereiche. Apps, die diese anfordern, müssen den App-Verifizierungsprozess von Google durchlaufen, bevor echte Nutzer den Zugriff gewähren können.
Eine kleine Anzahl von Scopes (z. B. vollständiger Gmail-Zugriff) sind eingeschränkt und erfordern zusätzlich zur Verifizierung eine unabhängige Sicherheitsüberprüfung (CASA).
Korrigieren
Ungültiger Grant: "Verbinden Sie Ihr Gmail-Konto neu"
Die Ungültige Berechtigung Fehler sind in der Produktion eines der verwirrendsten Probleme – sie treten stillschweigend für eine Teilmenge von Benutzern auf und erfordern einen neuen OAuth-Flow zur Behebung. Das Verständnis des Lebenszyklus von Refresh-Tokens ist der Schlüssel zur ordnungsgemäßen Handhabung.
Die genaue Fehlermeldung
{"error": "invalid_grant", "error_description": "Token ist abgelaufen oder wurde widerrufen."}
-- oder --
{"error": "invalid_grant", "error_description": "Ungültige Anfrage"}
Ursache: Der Lebenszyklus des Refresh-Tokens
Beheben: erneut autorisieren mit access_type=offline + prompt=consent
from google_auth_oauthlib.flow import Fluss
Fluss = Flow.von_client_secrets_datei(
'client_secrets.json',
scopes=['https://www.googleapis.com/auth/gmail.readonly'],
redirect_uri=REDIRECT_URI
)
# access_type=offline → Aktualisierungstoken abrufen
# prompt=consent → erzwingt erneute Zustimmung, gibt immer ein neues Aktualisierungstoken zurück
auth_url, status = Fluss.Autorisierungs-URL(
Zugriffstyp='offline',
Aufforderung'Zustimmung'
)
# Speichere das NEUE refresh_token aus der Antwort
Das alte Token „#“ ist nun ungültig – aktualisieren Sie Ihre DatenbankUm zu vermeiden ungültiger_grant In der Produktion: Verwenden Sie immer access_type=offline und Zustimmung Aktualisieren Sie Ihren gespeicherten Erfrischungstoken jedes Mal, wenn der Benutzer neu autorisiert, wenn Sie den OAuth-Flow initiieren, erkennen ungültiger_grant Fehler auslösen und eine Benutzeroberfläche zur ordnungsgemäßen Reautorisierung anzeigen (eine Aufforderung zum "Wiederverbinden Ihres Gmail-Kontos") und Ihre App aus dem Testmodus herausnehmen, um permanente Token zu erhalten.
Das OAuth-Zustimmungsbildschirm wird in der Google Cloud Console nicht angezeigt
Dies ist die Suchanfrage mit dem höchsten Volumen in diesem Cluster (über 390 monatliche Suchanfragen). Die Seite "OAuth-Zustimmungsbildschirm" scheint Anfang 2024 im Rahmen einer UI-Neugestaltung für viele Entwickler aus der Google Cloud Console verschwunden zu sein. Sie wurde nicht entfernt – sie wurde verschoben.
Symptom
Sie öffnen die Google Cloud Console und navigieren zu APIs & Services, aber der Menüpunkt "OAuth-Zustimmungsbildschirm" fehlt entweder oder das Klicken darauf leitet Sie zu einem neuen "OAuth-Übersicht" Seite, die ein Übersichts-Dashboard anstelle des erwarteten Konfigurationsformulars anzeigt.
Ursachen
Korrigieren (Schritt für Schritt)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Dieser Deep Link umgeht die Übersichtsseite und führt direkt zur Konfiguration des Zustimmungsbildschirms. Für eine vollständige Anleitung zu jedem Konfigurationsfeld, der Auswahl des Benutzertyps und der Begrenzung auf 100 Benutzer finden Sie unsere OAuth-Einwilligungsbildschirm-Einrichtungsanleitung.
Wochen der Verifizierung.
Verwenden Sie Unipiles Schlüssel und jetzt beginnen.
Verlieren Sie keine Kunden, weil sie auf eine Google-Bewertung warten. Verbinden Sie Gmail-Konten in 5 Minuten mit unseren vorab geprüften Entwickleranmeldedaten.
ungültiger_Bereich
Ein Tippfehler in der Scope-URL oder eine deaktivierte API führt dazu, dass Google die gesamte Autorisierungsanfrage ablehnt, bevor es zu einer Benutzerinteraktion kommt.
Die genaue Fehlermeldung
{"error": "invalid_scope",
"error_description": "Einige angeforderte Bereiche waren ungültig.
{gültig=[https://mail.google.com/], ungültig=[gmail.readonly]}"}
-- oder auf der URL des Zustimmungsbildschirms --
error=invalid_scope&error_description=Einige+angeforderte+Bereiche+waren+ungültig
Ursache
Zwei häufige Ursachen: (1) Der Geltungsbereichswert ist ein kurzer Name wie gmail.readonly anstatt der vollständigen URL https://www.googleapis.com/auth/gmail.readonly, oder (2) die Gmail API (oder eine andere von Ihnen angesprochene Google API) ist in dem Google Cloud-Projekt nicht aktiviert.
Gängige Gmail-Bereiche und ihre korrekten URLs
| Scope-URL (verwenden Sie die vollständige URL) | Was es erlaubt | Typ |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Alle Nachrichten und Threads lesen | Empfindlich |
| https://www.googleapis.com/auth/gmail.send | E-Mail im Namen des Benutzers senden | Empfindlich |
| https://www.googleapis.com/auth/gmail.modify | Lesen, verfassen, senden, Threads löschen | Empfindlich |
| https://mail.google.com/ | Vollzugriff auf das Postfach (IMAP/SMTP) | Eingeschränkt |
| https://www.googleapis.com/auth/userinfo.email | Lesen Sie nur die E-Mail-Adresse des Benutzers | Grundlegend |
Korrigieren
https://www.googleapis.com/auth/ oder https://mail.google.com/). Benutzen Sie niemals die Kurzform wie gmail.readonly.
"Google hat diese App nicht verifiziert" und die 100-Nutzer-Obergrenze
Der Warnbildschirm "Google hat diese App nicht verifiziert" wird angezeigt, wenn eine nicht verifizierte App sensible oder eingeschränkte Bereiche anfordert. Während Benutzer fortfahren können, indem sie auf "Erweitert" und dann auf "Zu [App-Name] (unsicher)" klicken, ist dies für die Produktion nicht geeignet, und der Testmodus begrenzt Ihre App auf insgesamt 100 einzelne Benutzer.
Ursache
Wenn Ihre App sensible Bereiche (wie gmail.readonly oder Gmail senden), Google zeigt diesen Warnbildschirm jedem Nutzer an, bis Sie das Verifizierungsverfahren abgeschlossen haben. Für eingeschränkte Bereiche (Restricted scopes) benötigen Sie außerdem eine Sicherheitsprüfung durch Dritte (CASA Tier 2).
Im Publishing-Status „Test“ wird dieser Warnbildschirm auch für Testbenutzer angezeigt, und die Gesamtzahl der zulässigen Testbenutzer ist auf 100 begrenzt. Token für Testbenutzer laufen nach 7 Tagen ab.
Korrigieren
https://mail.google.com/zusätzlich vervollständigen CASA Stufe 2 Sicherheitsbewertung durch einen von Google genehmigten Gutachter.
Diese Fehler verschwinden, wenn das OAuth-Projekt bereits zertifiziert ist
Bildschirme wie "Google hat diese App nicht verifiziert", die Obergrenze von 100 Nutzern und die Token-Ablaufzeit von 7 Tagen im Testmodus sind alles Symptome von Besitz und Verwaltung Ihres eigenen Google Cloud-Projekts. Ein unabhängiger technischer Vermittler, der als im Namen jedes authentifizierten Benutzers - und CASA Tier 2-Zertifizierung bereits abgeschlossen hat - nimmt diesen gesamten Aufwand von Ihrer Seite ab. Ihre Benutzer autorisieren einmal; Token-Lebenszyklus, Scope-Konformität und erneute Verifizierung werden auf Plattformebene gehandhabt.
Dies ist keine Umgehung der Sicherheitsüberprüfung von Google. Unipile hat CASA Tier 2 unabhängig abgeschlossen und ist nicht mit Google verbunden, wird von Google nicht unterstützt und nicht von Google gesponsert.
Schiff auf bereits zertifiziertem Google OAuthWie man diese gesamte Klasse von Google OAuth-Fehlern vermeidet
Wenn man sich alle 7 Google OAuth-Fehler in dieser Anleitung ansieht, zeichnet sich ein Muster ab. Jeder einzelne entstammt der gleichen Ursache: der manuellen Verwaltung Ihres eigenen Google Cloud-Projekts und dessen OAuth-Konfiguration. Diese Google OAuth-Fehler sind nicht zufällig – sie sind strukturelle Folgen eines nicht verifizierten OAuth-Projekts, von falschen Weiterleitungs-URIs und fehlgeschlagener Token-Rotation bis hin zur 100-Nutzer-Grenze und Ablehnungen des Zustimmungsbildschirms.
Es gibt einen anderen Weg. Mit einem unabhängiger technischer Vermittler das wirkt im Namen jedes authentifizierten Benutzers - eine, die bereits die Verifizierungsprüfung von Google und die CASA Tier 2-Sicherheitszertifizierung abgeschlossen hat - verlagert all diese Fehlermodi von Ihnen weg. Der nachstehende Vergleich zeigt genau, welche Fehler verschwinden und welche Infrastruktur Unipile stattdessen übernimmt. Siehe Unipile Google OAuth Dokumentation für die vollständige Integrationsanleitung.
Jeder Fehler in diesem Leitfaden: Wem gehört die Korrektur?
Die oben behandelten 7 Google OAuth-Fehler haben eine gemeinsame Wurzel: Sie besitzen das Google Cloud-Projekt, daher sind Sie für jede Ausfallart verantwortlich. Hier ist ein Vergleich, was das in der Praxis bedeutet.
Der entscheidende Unterschied: Unipile hat bereits die Sicherheitsüberprüfung von Google und die CASA Tier 2-Bewertung für die von Ihnen vermittelten Verbindungen abgeschlossen. Dies ist kein Workaround für die Sicherheitsüberprüfung von Google – Unipile hat diese bereits bestanden. Ihre Nutzer erhalten einen sauberen Zustimmungsbildschirm (keine Warnung "nicht verifizierte App"), Ihre App wird sofort bereitgestellt, und Sie können Ihre eigene Verifizierung von Google Cloud parallel verfolgen, ohne Druck von Produktions-Deadlines.
Compliance-Hinweis: Unipile ist ein unabhängiger technischer Vermittler, nicht verbunden mit, unterstützt oder gesponsert von Google. Unipiles Google OAuth-Client ist CASA Tier 2-zertifiziert, wodurch Ihre Benutzer den Zugriff auf Gmail autorisieren können, ohne eine Warnung "unverifizierte App" für über Unipile vermittelte Verbindungen zu erhalten. Dies ist kein Workaround für die Sicherheitsüberprüfung von Google – Unipile hat diese bereits für die von ihr vermittelten Verbindungen bestanden. im Namen jedes authentifizierten Benutzers. Nutzer können den Zugriff jederzeit über die Seite "Berechtigungen" ihres Google-Kontos widerrufen.
Google OAuth Fehler FAQ
Antworten auf die häufigsten Fragen zu Google OAuth-Fehlern und Gmail API-Fehlern, die den Lebenszyklus von Token, Administratorrichtlinien, Weiterleitungs-URIs und die Konfiguration der Google Cloud Console abdecken.
admin_policy_enforced bedeutet, dass ein Google Workspace Superadministrator Ihre App oder die spezifischen OAuth-Bereiche, die sie anfordert, für die Autorisierung durch Nutzer in dieser Organisation blockiert hat. Es handelt sich um eine organisatorische Zugriffskontrollrichtlinie, nicht um einen Fehler in Ihrem Code. Die Behebung erfordert Maßnahmen vom Workspace Superadministrator in der Google Admin-Konsole unter Sicherheit > API-Steuerelemente > Zugriff auf Drittanbieter-Apps verwalten.
Nein. Ein normaler Benutzer kann admin_policy_enforced nicht beheben. Nur ein Google Workspace Superadministrator Sie können diesen Fehler beheben, indem Sie die App in der Admin-Konsole als vertrauenswürdig markieren. Der betroffene Benutzer muss seinen IT-Administrator oder Workspace-Superadministrator kontaktieren und darum bitten, dass die spezifische OAuth-App zur genehmigten Liste hinzugefügt wird.
Die redirect_uri_mismatch auf localhost passiert, wenn die URI, die Sie in der Google Cloud Console registrieren, nicht exakt mit der URI übereinstimmt, die Ihr lokaler Entwicklungsserver verwendet. Zum Beispiel, wenn Sie registrieren http://localhost:3000/callback aber auf Port 3001 läuft, oder einen nachgestellten Schrägstrich vergessen. Google erlaubt http:// nicht nur https://) für localhost-URIs. Registrieren Sie die exakte URI, die Ihr lokaler Server verwendet, einschließlich der korrekten Portnummer.
Nein. Authorisierte JavaScript-Ursprünge und autorisierte Weiterleitungs-URIs sind zwei separate Felder. JavaScript-Ursprünge werden nur für OAuth-Flows auf der Browserseite verwendet. Um zu beheben redirect_uri_mismatch, Sie müssen die URI hinzufügen Autorisierte Weiterleitungs-URIs Feld, nicht auf JavaScript-Ursprünge.
Ein einzelner Google OAuth 2.0 Client kann bis zu 100 autorisierte Weiterleitungs-URIs registriert. Dies ermöglicht es Ihnen, URIs für verschiedene Umgebungen (lokale Entwicklung, Staging, Produktion) und verschiedene Callback-Pfade innerhalb desselben Clients zu registrieren.
Wenn Ihre App in Veröffentlichungsstatus testen, Google-Aktualisierungstoken laufen nach 7 Tage unabhängig von der Nutzung. Dies ist bei nicht bestätigten Apps beabsichtigt. Wechseln Sie zum Produktionsstatus, indem Sie auf klicken App veröffentlichen Auf der OAuth-Einwilligungs-Bildschirm-Seite, um langlebige Token zu erhalten. In der Produktion bleiben Refresh-Token gültig, solange der Nutzer Ihre App mindestens alle 6 Monate nutzt. Für eine verwaltete Alternative besuchen Sie unsere verwaltete Gmail API-Lösung.
Google widerruft Refresh-Tokens, die nicht verwendet wurden für 6 Monate (ca. 180 Tage). Tokens werden ebenfalls widerrufen, wenn: der Nutzer sein Google-Konto-Passwort ändert, der Nutzer den App-Zugriff in den Sicherheitseinstellungen seines Google-Kontos widerruft, Sie mit anderen Geltungsbereichen eine erneute Autorisierung durchführen oder die Gesamtzahl der Refresh-Tokens für ein einzelnes Nutzer-App-Paar 50 überschreitet (die ältesten werden zuerst widerrufen). Für ein vollständiges Bild zum Erstellen robuster E-Mail-Integrationen siehe unsere Vollständiger Leitfaden zur E-Mail-API.
Google hat die Cloud Console 2024 neu gestaltet. Die Konfiguration der OAuth-Zustimmungsbildschirme befindet sich nun unter APIs & Services > OAuth Übersicht. Klicken App bearbeiten oder nutzen Sie die Tabs "Branding", "Zielgruppe" und "Bereiche". Prüfen Sie auch: Sie benötigen Herausgeber oder Besitzer Rolle auf dem Projekt (Viewer kann nicht auf das Formular zugreifen) und stellen Sie sicher, dass Sie sich im richtigen Projekt befinden, indem Sie den Projektauswähler oben in der Konsole verwenden.
Stoßen Sie immer noch auf einen Google OAuth-Fehler, der hier nicht aufgeführt ist? Überspringen Sie das Debugging und lassen Sie Unipile das Gmail OAuth für Sie übernehmen.
Jetzt bauen
DE 
EN 
FR 
ES 
IT 
BR 
NL 
PL 
TR