LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Perspektywy
Kalendarz Google
Dołącz do społeczności SlackCzęste błędy Google OAuth i Gmail API (i jak je naprawić)
Każdy programista integrujący Gmail lub Kalendarz Google z Google OAuth napotka co najmniej jeden z tych błędów Google OAuth. Ten przewodnik grupuje wszystkie 7 powszechnych błędów Google OAuth w jednym miejscu – z dokładną przyczyną i krok po kroku, jak je naprawić. Zrozumienie tych błędów Google OAuth pozwoli zaoszczędzić godziny debugowania.
# – wymiana tokenów Google OAuth
import żądania
token_odpowiedź = requests.post(
"https://oauth2.googleapis.com/token",
dane={
"kod"kod autoryzacyjny,
"client_id": CLIENT_ID,
"client_secret": TAJNY_KLUCZ_KLIENTA,
"przekieruj_uri": URI_PRZEKIEROWANIA,
"typ_grantu": "kod_autoryzacyjny"
}
)Szybki przegląd: błędy Google OAuth w skrócie
Tabelaryczne podsumowanie wszystkich 7 błędów Google OAuth omówionych w tym przewodniku – etap wystąpienia, przyczyna źródłowa i link do szybkiej poprawki w szczegółowej sekcji poniżej. Zapisz tę tabelę jako punkt odniesienia podczas debugowania błędów Google OAuth w środowisku deweloperskim lub produkcyjnym.
| Komunikat o błędzie | Scena | Przyczyna główna | Szybka poprawka |
|---|---|---|---|
| redirect_uri_mismatch | Authorization | URI przekierowania w Twoim żądaniu nie zgadza się dokładnie z jednym zarejestrowanym w Google Cloud Console | Napraw to |
| admin_policy_enforced | Authorization | Superadministrator w Workspace ograniczył, którym aplikacjom OAuth lub zakresom użytkownicy w organizacji mogą udzielić dostępu | Napraw to |
| odmowa_dostępu | Authorization | Aplikacja jest w trybie testowym, a użytkownik nie jest użytkownikiem testowym lub aplikacja żąda niedostępnych zakresów bez weryfikacji | Napraw to |
| nieprawidłowe_poświadczenie | Odświeżanie tokena | Token odświeżania wygasł, został unieważniony lub użyty więcej niż raz (jednorazowy kod uwierzytelniający) | Napraw to |
| Brak ekranu zgody | Konsola Google Cloud | Nowy interfejs Google Cloud przeniósł ekran zgody OAuth; wymaga również roli właściciela/edytora w projekcie | Napraw to |
| nieprawidłowy_zakres | Authorization | URL zakresu jest błędny lub odpowiednie API Google nie jest włączone w projekcie | Napraw to |
| Google nie zweryfikował | Authorization | Aplikacja używa wrażliwych/ograniczonych zakresów, ale nie ukończyła weryfikacji Google; tryb testowy ogranicza się do 100 użytkowników | Napraw to |
Błąd 400: niezgodność adresów redirect_uri
To najczęstszy błąd Google OAuth dla deweloperów konfigurujących nową integrację. Występuje podczas kroku autoryzacji – zanim zostanie wydany jakikolwiek token.
Dokładny komunikat o błędzie
Błąd 400: niezgodność adresu URL przekierowania
Adres URL przekierowania w żądaniu nie pasował do zarejestrowanego adresu URL przekierowania.
błąd=niezgodność_adresu_url_przekierowania
Przyczyna
Google porównuje przekierowanie_uri parametr, który przekazujesz w swoim adresie URL autoryzacji, wraz z listą autoryzowanych URI przekierowania zarejestrowanych u Twojego klienta OAuth w Google Cloud Console. Nawet jednokrotna różnica w znaku – ukośnik na końcu, http vs https, lub inny port - wywołuje ten błąd.
Napraw (krok po kroku)
https://yourapp.com/oauth/callback. Wartość musi być identyczna znak po znaku, uwzględniając schemat, port i ukośnik końcowy.
przekierowanie_uri wartość, którą przekazujesz do punktu końcowego autoryzacji i do punktu końcowego wymiany tokenów, są identyczne.
redirect_uri_mismatch na localhost
Podczas lokalnego rozwoju zarejestruj dokładne URI localhost, którego używasz - na przykład http://localhost:3000/callback. Google pozwala http:// nie tylko https://) dla identyfikatorów URI localhost. Jeśli zmienisz port deweloperski, pamiętaj o zaktualizowaniu zarejestrowanego identyfikatora URI.
Są to dwa odrębne pola i służą różnym celom. Autoryzowane źródła JavaScript są używane dla przepływów OAuth po stronie przeglądarki (przepływ niejawny, Google Identity Services). Autoryzowane identyfikatory URI przekierowania są używane dla przepływów kodu autoryzacji po stronie serwera. Dodanie identyfikatora URI do źródeł JavaScript NIE rozwiąże problemu redirect_uri_mismatch błąd - musisz dodać go do pola adresów URI przekierowania. Klient Google OAuth może mieć zarejestrowane do 100 adresów URI przekierowania.
Błąd 400: Polityka administratora wymuszona
Ten błąd nie jest błędem w Twoim kodzie. Jest to polityka organizacyjna narzucana przez administratora Google Workspace. Zwykły programista nie może jej samodzielnie naprawić.
Dokładny komunikat o błędzie
Błąd 400: admin_policy_enforced
Konto Google nie może zostać użyte do autoryzacji z powodu zasad Twojej organizacji. Skontaktuj się z administratorem, aby uzyskać więcej informacji.
błąd=admin_policy_enforced
Przyczyna
Superadministrator Google Workspace zablokował dostęp do określonych aplikacji zewnętrznych lub zakresów protokołu OAuth, którym użytkownicy w organizacji mogą udzielać dostępu. Jest to skonfigurowane przez Kontrolki API w konsoli administracyjnej Google. Kiedy aplikacja nie znajduje się na liście zatwierdzonych, każdy użytkownik w danym obszarze roboczym zobaczy ten błąd podczas próby jej autoryzacji – niezależnie od jej statusu weryfikacji.
To jest zgodność i kontrola bezpieczeństwa, nie błąd konfiguracji po stronie programisty. Właściwe rozwiązanie leży zawsze po stronie administratora.
Napraw (tylko po stronie administratora)
Użytkownik, który napotyka admin_policy_enforced nie mogą rozwiązać tego samodzielnie. Muszą skontaktować się ze swoim superadministratorem Google Workspace i poprosić o oznaczenie konkretnej aplikacji OAuth jako zaufanej. Jeśli użytkownik jest administratorem, może postępować zgodnie z powyższymi krokami. Jeśli domena wymusza rygorystyczną politykę "Zezwalaj na określone aplikacje", aplikacja musi najpierw zostać jawnie dodana do listy zatwierdzonych, zanim będzie można ustawić ją jako zaufaną.
Jeśli tworzysz narzędzia wewnętrzne i chcesz całkowicie uniknąć uzyskiwania zgody OAuth od każdego użytkownika, alternatywą jest konto usługi z upoważnieniem w skali domeny – sprawdź nasze Konto usługi Gmail i przewodnik DWD.
odmowa_dostępu & "Ta aplikacja jest zablokowana" (niezweryfikowana aplikacja)
Użytkownicy widzą ekran "Ta aplikacja jest zablokowana" lub otrzymują odmowa_dostępu w powiadomieniu zwrotnym OAuth. Może mieć wiele przyczyn źródłowych, w zależności od tego, czy aplikacja jest nadal w trybie testowania, czy też celuje w ograniczony zakres uprawnień.
Dokładny komunikat o błędzie
Dostęp zablokowany: [Nazwa Twojej Aplikacji] nie ukończyła procesu weryfikacji Google
error=access_denied
— lub —
Ta aplikacja jest zablokowana.
Ta aplikacja próbowała uzyskać dostęp do poufnych informacji na Twoim koncie Google.
Skontaktuj się z deweloperem, aby uzyskać więcej informacji.
Przyczyny
Gdy Twoja aplikacja OAuth ma status publikacji "Testowanie", tylko użytkownicy dodani jawnie jako użytkownicy testowi mogą ją autoryzować. Każdy inny użytkownik natychmiast otrzymuje odmowę dostępu (`access_denied`).
Tryb testowania jest ograniczony do 100 unikalnych użytkowników testowych w danym momencie. Po osiągnięciu 100, nowi użytkownicy nie będą mogli autoryzować aplikacji, nawet jeśli zostaną dodani.
Zakresy takie jak gmail.zmodyfikuj lub gmail.wyślij są wrażliwymi zakresami. Aplikacje o nie proszące muszą przejść proces weryfikacji aplikacji Google, zanim rzeczywisti użytkownicy będą mogli udzielić dostępu.
Niewielka liczba zakresów (np. pełny dostęp do Gmaila) jest Ograniczona i wymaga, oprócz weryfikacji, audytu bezpieczeństwa strony trzeciej (CASA).
Naprawić
invalid_grant: "ponownie połącz swoje konto Gmail"
The gmail api nieprawidłowy przyznanie błąd jest jednym z najbardziej mylących w produkcji – działa błędnie po cichu dla części użytkowników i wymaga nowego przepływu OAuth do naprawienia. Kluczem do właściwego jego obsługi jest zrozumienie cyklu życia tokenu odświeżania.
Dokładny komunikat o błędzie
{"error": "invalid_grant", "error_description": "Token wygasł lub został unieważniony."}
-- albo --
{"error": "invalid_grant", "error_description": "Niepoprawne żądanie"}
Przyczyna: cykl życia tokenu odświeżania
Napraw: ponowne autoryzowanie z access_type=offline + prompt=consent
z google_auth_oauthlib.flow import Przepływ
przepływ = Flow.from_client_secrets_file(
'client_secrets.json',
zakresy=['https://www.googleapis.com/auth/gmail.readonly'],
redirect_uri=PARAMETR_PRZEKIEROWANIA
)
# access_type=offline → pobierz token odświeżający
# prompt=consent → wymusza ponowne wyrażenie zgody, zawsze zwraca nowy token odświeżający
auth_url, stan = przepływ.url_autoryzacji(
typ_dostępu='nieaktywny',
polecenie='zgoda'
)
# Zapisz NOWY token odświeżający z odpowiedzi
Stary token # stracił ważność — zaktualizuj swoją bazę danychAby uniknąć nieprawidłowe_poświadczenie w produkcji: zawsze używaj typ_dostępu=offline oraz zgoda podczas inicjowania przepływu OAuth, zaktualizuj zapisany token odświeżania za każdym razem, gdy użytkownik ponownie autoryzuje, wykryj nieprawidłowe_poświadczenie błędy i wywołać przejrzysty interfejs ponownej autoryzacji (komunikat "połącz ponownie konto Gmail") oraz przenieść aplikację z trybu testowego, aby uzyskać stałe tokeny.
Ekran zgody OAuth nie wyświetli się w Google Cloud Console
Jest to najczęściej wyszukiwane zapytanie w tym klastrze (ponad 390 wyszukiwań miesięcznie). Strona "Ekran zgody OAuth" najwyraźniej zniknęła z Google Cloud Console dla wielu programistów w latach 2024-2026 z powodu przeprojektowania interfejsu użytkownika. Nie została ona usunięta – przeniosła się.
Objaw
Otwierasz Konsolę Google Cloud i przechodzisz do API i usługi, ale pozycja menu "Ekran zgody OAuth" albo zniknęła, albo kliknięcie jej przekierowuje Cię do nowej "Przegląd OAuth" strona, która wyświetla panel podsumowujący zamiast oczekiwanego formularza konfiguracji.
Przyczyny
Napraw (krok po kroku)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Ten głęboki link omija stronę przeglądu i prowadzi bezpośrednio do konfiguracji ekranu zgody. Pełne omówienie wszystkich pól konfiguracyjnych, wyboru typu użytkownika i limitu testów 100 użytkowników znajdziesz w naszym Przewodnik konfiguracji ekranu zgody OAuth.
Tygodnie weryfikacji.
Użycie Klucz Unipile i zacznij teraz.
Nie trać klientów przez czekanie na recenzje Google. Połącz konta Gmail w 5 minut dzięki naszym wstępnie zweryfikowanym danym deweloperskim.
nieprawidłowy_zakres
Błąd w adresie URL zakresu lub wyłączone API spowoduje, że Google odrzuci całą prośbę autoryzacyjną zanim dojdzie do jakiejkolwiek interakcji z użytkownikiem.
Dokładny komunikat o błędzie
{"error": "invalid_scope",
"error_description": "Niektóre z żądanych zakresów były nieprawidłowe.
{ważne=[https://mail.google.com/], nieważne=[gmail.readonly]}"}
-- lub na ekranie potwierdzenia URL --
error=invalid_scope&error_description=Niektóre+z+żądanych+zakresów+były+nieprawidłowe
Przyczyna
Dwie częste przyczyny: (1) wartość zakresu jest krótką nazwą, taką jak gmail.tylko_do_odczytu zamiast pełnego adresu URL https://www.googleapis.com/auth/gmail.readonly, albo (2) interfejs Gmail API (lub dowolne inne Google API, które określasz) nie jest włączony w projekcie Google Cloud.
Najczęstsze zakresy Gmail i ich prawidłowe adresy URL
| URL zakresu (użyj pełnego adresu URL) | Co to umożliwia | Typ |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Przeczytaj wszystkie wiadomości i wątki | Wrażliwy |
| https://www.googleapis.com/auth/gmail.send | Wyślij e-mail w imieniu użytkownika | Wrażliwy |
| https://www.googleapis.com/auth/gmail.modify | Czytaj, kompozytuj, wysyłaj, usuwaj wątki | Wrażliwy |
| https://mail.google.com/ | Pełny dostęp do skrzynki pocztowej (IMAP/SMTP) | Ograniczony |
| https://www.googleapis.com/auth/userinfo.email | Witaj w moim świecie. Bądź sobą. | Podstawowy |
Naprawić
https://www.googleapis.com/auth/ lub https://mail.google.com/Nigdy nie używaj formy skróconej, takiej jak gmail.tylko_do_odczytu.
"Google nie zweryfikował tej aplikacji" i limit 100 użytkowników
Ekran ostrzeżenia "Google nie zweryfikował tej aplikacji" pojawia się, gdy zweryfikowana aplikacja próbuje uzyskać dostęp do wrażliwych lub ograniczonych zakresów. Chociaż użytkownicy mogą kontynuować, klikając "Zaawansowane", a następnie "Przejdź do [nazwa aplikacji] (niebezpieczne)", nie jest to odpowiednie rozwiązanie dla produkcji — a tryb testowy ogranicza aplikację do maksymalnie 100 unikalnych użytkowników.
Przyczyna
Kiedy Twoja aplikacja prosi o wrażliwe zakresy (jak gmail.tylko_do_odczytu lub gmail.wyślij), Google wyświetla ten ekran ostrzeżenia każdemu użytkownikowi, dopóki nie zakończy się przegląd weryfikacyjny. W przypadku zakresów ograniczonych wymagany jest również audyt bezpieczeństwa przeprowadzony przez stronę trzecią (CASA Tier 2).
Podczas publikowania w stanie "Testowanie", ten ekran ostrzegawczy jest wyświetlany nawet dla użytkowników testowych, a całkowita liczba dozwolonych użytkowników testowych jest ograniczona do 100. Tokeny dla użytkowników testowych wygasają po 7 dniach.
Naprawić
https://mail.google.com/dodatkowo dokończ CASA Poziom 2 ocena bezpieczeństwa przez asesora zatwierdzonego przez Google.
Te błędy znikają, gdy projekt OAuth jest już certyfikowany
Ekran "Google nie zweryfikował tej aplikacji", limit 100 użytkowników i wygaśnięcie tokenu po 7 dniach w trybie testowym to wszystko objawy posiadanie i zarządzanie własnym projektem Google Cloud. Niezależny pośrednik techniczny, który działa w imieniu każdego uwierzytelnionego użytkownika - i które już ukończyło certyfikację CASA poziomu 2 - usuwa to całe obciążenie z Waszej strony. Państwa użytkownicy autoryzują się raz; cykl życia tokena, zgodność zakresu i ponowna weryfikacja są obsługiwane na poziomie platformy.
To nie jest obejście weryfikacji bezpieczeństwa Google. Unipile samodzielnie ukończyło CASA Tier 2 i nie jest powiązane, wspierane ani sponsorowane przez Google.
Statek na już certyfikowanym Google OAuthJak unikać tej całej klasy błędów Google OAuth
Rozpatrując wszystkie 7 błędów Google OAuth z tego przewodnika, wyłania się pewien wzorzec. Każdy z nich, bez wyjątku, ma to samo źródło: samodzielne zarządzanie własnym projektem Google Cloud i jego konfiguracją OAuth. Te błędy Google OAuth nie są przypadkowe – są one strukturalnymi konsekwencjami posiadania niezweryfikowanego projektu OAuth, od niedopasowań adresów URI przekierowania i błędów rotacji tokenów, po limit 100 użytkowników i odrzucenia ekranu zgody.
Istnieje inny sposób. Używanie niezależny pośrednik techniczny że działa w imieniu każdego uwierzytelnionego użytkownika - który przeszedł już weryfikację Google i certyfikację bezpieczeństwa CASA Tier 2 - przenosi wszystkie te tryby awarii z Twojej głowy. Poniższe porównanie pokazuje dokładnie, które błędy znikają, a którą infrastrukturę obsługuje Unipile. Zobacz Dokumentacja Google OAuth Unipile po pełny przewodnik integracji.
Każdy błąd w tym przewodniku: kto jest odpowiedzialny za naprawę?
7 błędów Google OAuth omówionych powyżej ma wspólne źródło: Ty posiadasz projekt Google Cloud, a więc ponosisz odpowiedzialność za każdy przypadek awarii. Oto zestawienie tego, co oznacza to w praktyce.
Kluczowa różnica: Unipile ma już za sobą przegląd bezpieczeństwa Google i ocenę CASA Tier 2 dla połączeń, które pośredniczy w Twoim imieniu. Nie jest to obejście przeglądu bezpieczeństwa Google – Unipile już go ukończył. Twoi użytkownicy otrzymują czysty ekran zgody (bez ostrzeżenia "niezweryfikowana aplikacja"), Twoja aplikacja jest wdrażana natychmiast, a Ty możesz równolegle przeprowadzić własną weryfikację Google Cloud bez presji terminu produkcji.
Uwaga dotycząca zgodności: Unipile to niezależny pośrednik techniczny, niepowiązany, zatwierdzony ani sponsorowany przez Google. Klient OAuth Google firmy Unipile posiada certyfikat CASA Tier 2, umożliwiający użytkownikom autoryzację dostępu do Gmaila bez ostrzeżenia o "niezweryfikowanej aplikacji" w przypadku połączeń pośredniczonych przez Unipile. Nie jest to obejście procesu weryfikacji bezpieczeństwa Google – Unipile już go przeszedł dla obsługiwanych połączeń. w imieniu każdego uwierzytelnionego użytkownika. Użytkownicy mogą w dowolnym momencie cofnąć dostęp poprzez stronę uprawnień swojego Konta Google.
Często zadawane pytania dotyczące błędów Google OAuth
Odpowiedzi na najczęstsze pytania dotyczące błędów Google OAuth i błędów interfejsu API Gmail, obejmujące cykl życia tokenów, zasady administracyjne, adresy URI przekierowania i konfigurację Google Cloud Console.
admin_policy_enforced oznacza, że super administrator Google Workspace zablokował Twoją aplikację lub konkretne zakresy OAuth, o które prosi, przed autoryzacją przez użytkowników w tej organizacji. Jest to polityka kontroli dostępu na poziomie organizacji, a nie błąd w Twoim kodzie. Rozwiązanie wymaga działania ze strony super administratora Workspace w Konsoli administracyjnej Google w sekcji Bezpieczeństwo > Kontrola API > Zarządzanie dostępem aplikacji zewnętrznych.
Nie. Zwykły użytkownik nie może naprawić `admin_policy_enforced`. Tylko administrator Google Workspace superadministrator Ten błąd można rozwiązać, zaznaczając aplikację jako zaufaną w Konsoli administracyjnej. Użytkownik, którego problem dotyczy, musi skontaktować się ze swoim administratorem IT lub administratorem Workspace i poprosić o dodanie konkretnej aplikacji OAuth do listy zatwierdzonych.
The redirect_uri_mismatch na localhost występuje wtedy, gdy adres URI zarejestrowany w Google Cloud Console nie pasuje dokładnie do adresu URI używanego przez lokalny serwer deweloperski. Na przykład, rejestracja http://localhost:3000/callback ale działający na porcie 3001 lub brakujący ukośnik. Google pozwala http:// nie tylko https://) dla URI localhost. Zarejestruj dokładny URI używany przez Twój lokalny serwer, w tym poprawny numer portu.
Nie. Autoryzowane pochodzenie JavaScript i autoryzowane identyfikatory URI przekierowania to dwa oddzielne pola. Pochodzenie JavaScript jest używane tylko w przepływach OAuth po stronie przeglądarki. Aby naprawić redirect_uri_mismatch, musisz dodać URI do Autoryzowane identyfikatory URI przekierowania pole, nie do pochodzenia JavaScript.
Pojedynczy klient Google OAuth 2.0 może mieć do 100 Dozwolonych URI przekierowania zarejestrowany. Pozwala to na rejestrowanie identyfikatorów URI dla różnych środowisk (lokalny rozwój, staging, produkcja) oraz różnych ścieżek zwrotnych w obrębie tego samego klienta.
Jeśli Twoja aplikacja jest w Testowanie statusu publikacji, tokeny odświeżania Google wygasają po 7 dni niezależnie od wykorzystania. Dzieje się tak celowo w przypadku niezweryfikowanych aplikacji. Przełącz na status Produkcja klikając Opublikuj aplikację na stronie ekranu zgody OAuth w celu uzyskania długoterminowych tokenów. W środowisku produkcyjnym tokeny odświeżania pozostają ważne tak długo, jak długo użytkownik korzysta z aplikacji co najmniej raz na 6 miesięcy. Alternatywne rozwiązanie zarządzane znajdziesz na naszej stronie zarządzane rozwiązanie Gmail API.
Google unieważnia tokeny odświeżania, które nie były używane przez 6 miesięcy (około 180 dni). Tokeny są również unieważniane, gdy: użytkownik zmieni hasło do swojego konta Google, użytkownik cofnie dostęp aplikacji w ustawieniach bezpieczeństwa swojego Konta Google, ponownie autoryzujesz z innymi zakresami lub łączna liczba tokenów odświeżania dla pary użytkownik-aplikacja przekroczy 50 (najstarsze są unieważniane jako pierwsze). Pełny obraz na temat tworzenia niezawodnych integracji e-mail znajdziesz w naszym Kompletny przewodnik po API poczty e-mail.
Google przeprojektował Cloud Console w 2024 roku. Konfiguracja ekranu zgody OAuth znajduje się teraz wewnątrz API i usługi > Przegląd OAuth. Kliknij Edytuj aplikację lub użyj kart Branding, Audience i Scopes. Sprawdź również: potrzebujesz Edytor lub Właściciel w projekcie (Widok nie ma dostępu do formularza) i upewnij się, że jesteś w odpowiednim projekcie, korzystając z selektora projektu u góry konsoli.
Nadal występują błędy Google OAuth niewymienione tutaj? Pomiń debugowanie i pozwól Unipile zająć się integracją Gmail OAuth.
Buduj teraz
PL 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
TR