Przewodnik po implementacji protokołu OAuth 2.1

W tym przewodniku opisano, jak bezpiecznie autoryzować platformę połączonych aplikacji, aby uzyskać dostęp do usług. W przypadku integracji MCP z połączonymi aplikacjami zdecydowanie zalecamy używanie OAuth 2.1, standardu branżowego w zakresie autoryzacji delegowanej, z Proof Key for Code Exchange (PKCE), aby zapewnić najwyższy poziom bezpieczeństwa danych użytkowników i niezawodność w przepływach „agentowych”. Platforma połączonych aplikacji obsługuje typ uwierzytelnienia za pomocą kodu autoryzacji z parametrami PKCE (Proof Key for Code Exchange).

PKCE jest obowiązkowy w przypadku wszystkich protokołów OAuth 2.1 i opcjonalny w przypadku OAuth 2.0.

Aby umożliwić automatyczne wykrywanie i usprawnić proces wprowadzania, serwer autoryzacji musi obsługiwać rozszerzenie metadanych serwera autoryzacji, nazywane też OAuth Discovery.

Jak Gemini MCP pobiera kod JSON konfiguracji

Konsola Gemini MCP próbuje pobrać plik JSON konfiguracji z podanych niżej adresów URL w kolejności podanej w tej sekcji.

Jeśli adres URL serwera autoryzacji znajduje się na najwyższym poziomie domeny (np. https://auth.example.com), Gemini dołącza do domeny standardowe katalogi „well-known” i szuka serwera w tej kolejności:

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

Jeśli adres URL serwera autoryzacji znajduje się w określonym podkatalogu lub ścieżce w domenie, na przykład https://auth.example.com/realms/master, Gemini dołącza te same „dobrze znane” ścieżki bezpośrednio do tego podkatalogu w następującej kolejności.

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration (obsługa ścieżek zagnieżdżonych)

Wymagane funkcje JSON

Odpowiedź dotycząca metadanych musi zawierać te pola. Integracja nie powiedzie się, jeśli brakuje wymaganych pól lub nie znaleziono prawidłowych typów.

authorization_endpoint
Musi być prawidłowym ciągiem znaków adresu URL.
token_endpoint
Musi być prawidłowym ciągiem znaków adresu URL.
response_types_supported
Musi zawierać ciąg znaków code.
registration_endpoint

Na razie Konsola Play korzysta z klienta dynamicznego.

(RFC 7591). Musisz podać punkt końcowy rejestracji w metadanych lub wpisać identyfikator klienta i klucz tajny bezpośrednio w interfejsie Konsoli Play.

Jeśli Twój serwer autoryzacji nie obsługuje dynamicznej rejestracji klientów (DCR), musisz ręcznie zaimplementować i wypełnić pola Identyfikator klienta i Tajny klucz klienta w interfejsie Konsoli Play, aby dokończyć integrację.

Jeśli Twoja implementacja obsługuje klucz dowodu dla wymiany kodu (PKCE) lub trwałe sesje, musisz uwzględnić odpowiednie pola funkcji (takie jak Challenge Methods i Grant Types) w pliku JSON wykrywania. Pomaga to zapewnić zgodność ze standardami bezpieczeństwa i łączności Gemini. Jeśli obsługujesz zakres, musisz uwzględnić pole scopes_supported.

Przykładowa konfiguracja

Poniżej znajdziesz prawidłową odpowiedź w formacie JSON, która spełnia wymagania naszego klienta.

{
  "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"
  ]
}

W przypadku uwzględnienia PKCE poniższy fragment kodu pokazuje przykład tego, co może być zawarte w bloku JSON.

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

Jeśli uwzględnisz pole scopes_supported, poniższy fragment kodu pokazuje przykład tego, co może być zawarte w bloku JSON.

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

Przepływ kodu autoryzacji (wersja uproszczona)

Poniżej opisujemy standardowy przepływ kodu autoryzacji. Ta sekwencja pokazuje dokładnie, jak platforma połączonych aplikacji bezpiecznie uzyskuje z Twojego serwera niezbędne tokeny dostępu, aby działać w imieniu użytkownika.

  1. Prośba o autoryzację: platforma Google stwierdza, że musi wywołać Twoją funkcję, ale użytkownik nie jest jeszcze autoryzowany. Chatbot inicjuje proces, przekierowując przeglądarkę użytkownika (lub wyświetlając link) do punktu końcowego autoryzacji.

    To żądanie zawiera Twój identyfikator klienta (lub wygenerowany automatycznie za pomocą DCR), identyfikator URI przekierowania Gemini i kluczowe parametry PKCE (code_challenge i code_challenge_method).

    Dodaj te adresy URL do listy dozwolonych na potrzeby konfiguracji protokołu 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. Zgoda użytkownika: serwer autoryzacji sprawdza poprawność żądania, uwierzytelnia użytkownika (logowanie) i prosi go o przyznanie platformie Google uprawnień dostępu do jego danych lub usługi.

  3. Przyznanie kodu: gdy użytkownik wyrazi zgodę, serwer przekierowuje przeglądarkę użytkownika z powrotem do RedirectURI Gemini, dodając do adresu URL tymczasowy kod autoryzacji.

  4. Wymiana tokena: backend Gemini wysyła żądanie POST do punktu końcowego tokena, wymieniając kod autoryzacji na token dostępu.

  5. Przyznanie dostępu: punkt końcowy tokena weryfikuje kod i parametry PKCE, wydaje token dostępu i opcjonalnie token odświeżania, a następnie zwraca je do Gemini.

Główne wymagania dotyczące PKCE

PKCE dodaje warstwę zabezpieczeń, która zapobiega nieautoryzowanemu przechwytywaniu kodów autoryzacji.

  • code_verifier: kryptograficznie losowy ciąg znaków wygenerowany przez Gemini na początku procesu. Te informacje są prywatne.
  • code_challenge: przekształcenie code_verifier, zwykle haszowanie SHA256. Jest on wysyłany publicznie, jak opisano w kroku 1 przepływu kodu autoryzacji.
  • Weryfikacja: Twój punkt końcowy tokena (opisany w kroku 4 przepływu kodu autoryzacji) musi zweryfikować, czy otrzymany parametr code_verifier po przekształceniu jest zgodny z pierwotnym parametrem code_challenge.

Debugowanie

Szczegółowe informacje o błędach łączenia są dostępne w Eksploratorze logów. Aby włączyć i wyświetlić błędy, postępuj zgodnie z instrukcjami podanymi w artykule Monitorowanie błędów łączenia kont w projekcie w konsoli Google.

Wymagania dotyczące konfiguracji łączenia z kontem Google

Informacje o konfiguracji łączenia z kontem Google znajdziesz w tych wskazówkach dotyczących interfejsu API.

Aby pomyślnie zarejestrować integrację OAuth, musisz skonfigurować określone szczegóły dotyczące serwera autoryzacji. Upewnij się, że masz przygotowane te punkty końcowe, dane logowania i zasoby.

Pole konfiguracji

Opis

Odpowiedzialność dewelopera

Identyfikator klienta i obiekt tajny

Unikalne dane logowania, które serwer autoryzacji generuje specjalnie dla platformy połączonych aplikacji. Tajny klucz klienta to bezpieczne dane uwierzytelniające (hasło) powiązane z identyfikatorem klienta.

Uwaga: jeśli identyfikator klienta został wydany przez dewelopera, musi on go podać. Jeśli identyfikator klienta został wydany przez Google, deweloper może musieć zarejestrować lub zweryfikować klucz tajny.

Używaj identyfikatora podanego przez platformę we wszystkich żądaniach autoryzacji.

Authorization Endpoint

URL, na który użytkownicy są przekierowywani w celu uwierzytelnienia i wyrażenia zgody

Hostuj punkt końcowy, na przykład https://yourdomain.com/oauth/authorize.

Token Endpoint (Punkt końcowy tokena)

Punkt końcowy backendu do wymiany kodów autoryzacji na tokeny dostępu/tokeny odświeżania i odświeżania wygasłych tokenów.

Hostuj ten punkt końcowy, np. https://yourdomain.com/oauth/token.

Punkt końcowy unieważnienia
Opcjonalny

Adres URL, który powiadamia system o unieważnieniu tokena, gdy użytkownik się rozłączy.

Gdy użytkownik odłączy Twoją integrację na platformie Connected Apps Platform, wyślemy żądanie POST do punktu końcowego /revoke zawierającego token dostępu lub token odświeżania.

Więcej informacji znajdziesz w artykule Odłączanie kont.

Hostuj punkt końcowy, na przykład https://yourdomain.com/oauth/revoke.

Serwer musi obsłużyć to żądanie, trwale unieważniając podany token. Dzięki temu wszelkie kolejne próby użycia tego tokena przez platformę połączonych aplikacji zakończą się niepowodzeniem, co zapewni bezpieczeństwo danych użytkownika po rozłączeniu.

Identyfikator URI przekierowania

Konkretny adres URL wywołania zwrotnego podany przez platformę, na który serwer autoryzacji odsyła kod po wyrażeniu zgody.

Skonfiguruj serwer autoryzacji tak, aby akceptował tylko oficjalny, zarejestrowany identyfikator URI przekierowania z platformy.

Odświeżanie

/token i grant_type=refresh_token

Mechanizm, który umożliwia platformie połączonych aplikacji uzyskanie nowego tokena dostępu po wygaśnięciu bieżącego, co pozwala na bezproblemowe utrzymanie integracji bez konieczności wielokrotnego logowania się przez użytkownika.

Gdy istniejący token dostępu wygaśnie, platforma połączonych aplikacji automatycznie wyśle żądanie POST do Twojego punktu końcowego /token. Ładunek żądania będzie zawierać grant_type=refresh_token oraz token odświeżania, który został wcześniej wydany przez Twój serwer.

Serwer musi zweryfikować podany token odświeżania i zwrócić nowy token dostępu w odpowiedzi JSON. Aby wdrożyć trwałe połączenie, musisz unikać rotacji tokena odświeżania podczas tej wymiany. Zamiast wydawać nowy, zwróć dokładnie ten sam token odświeżania w odpowiedzi JSON i przedłuż jego datę ważności w backendzie.

Typ odpowiedzi

Aby obsługiwać przepływ kodu autoryzacji, należy skonfigurować tę wartość jako CODE.

Zakresy

Zestaw określonych uprawnień i poziomów dostępu, które określają, do czego token jest upoważniony. Muszą one być wstępnie zdefiniowane w konfiguracji, aby Google mogło o nie poprosić podczas początkowego uzgadniania autoryzacji.

Musisz podać listę domyślnych zakresów (np. openid, profile, email), o które platforma połączonych aplikacji powinna prosić podczas inicjowania procesu.

Żądane zakresy powinny być jak najmniejsze (zasada jak najmniejszych uprawnień), ale w pełni wystarczające do obsługi głównych ścieżek użytkownika, które obsługuje integracja z MCP.

Zasoby interfejsu: logo

Logo dewelopera, które będzie wyświetlane na ekranach łączenia kont i zgody.

Musi to być kwadratowy obraz wektorowy (SVG) o okrągłym wyglądzie i rozmiarze co najmniej 500 x 500 pikseli. Zobacz na przykład https://[partner-domain]/assets/logo.svg lub nieprzetworzony plik SVG.

Łączenie aplikacji natywnej (przejście do aplikacji)

Aby obsługiwać łączenie kont bezpośrednio z natywnych aplikacji na Androida lub iOS, zdecydowanie odradzamy korzystanie ze standardowych komponentów WebView. Zamiast tego zdecydowanie zalecamy wdrożenie funkcji Przejście do aplikacji, aby zapewnić użytkownikom płynne działanie.

Więcej informacji znajdziesz w artykule Łączenie z kontem Google za pomocą funkcji Przejście do aplikacji opartej na protokole OAuth.

Przejdź weryfikację w Sklepie Play i sklepie z aplikacjami oraz umieść identyfikatory URI przekierowania Google bezpośrednio w aplikacjach natywnych, aby zapewnić bezpieczne przekierowanie autoryzacji między aplikacjami.

Czas ważności tokena

(Opcjonalnie) Okres ważności tokena dostępu, po którym wymagane jest odświeżenie. Przydatne do konfigurowania zasad dotyczących limitu czasu w GAL.

W zależności od potrzeb związanych z bezpieczeństwem okres ważności może wynosić od kilku minut do kilku godzin lub dni (np. 30 days).

Typowe błędy integracji

Oto lista typowych błędów i potencjalnych rozwiązań dotyczących procesu integracji.

  • Brak uprawnienia „code”: automatyczny system platformy Gemini wyraźnie sprawdza, czy parametr response_types_supported ma wartość „code”.
  • Brak punktu końcowego rejestracji: nawet jeśli Twój serwer obsługuje dokumenty metadanych identyfikatora klienta, aplikacja Gemini (działająca jako klient OAuth łączący się z Twoim serwerem) wymaga obecnie, aby w pliku JSON wykrywania znajdował się dedykowany punkt końcowy registration_endpoint.
  • Błąd inny niż 200: jeśli automatyczny mechanizm wykrywania metadanych Gemini trafi na adres URL well-known i otrzyma błąd 404 lub 500, nie będzie próbował odgadnąć innych adresów URL. Upewnij się, że adres URL wykrywania jest publicznie dostępny.