Łączenie z kontem Google za pomocą protokołu OAuth (przepływ niejawny – zarchiwizowany)

Niebezpieczeństwo: przepływ niejawny nie jest obsługiwany w przypadku MCP, UCP i przepływów sterowanych przez agenta. Ze względów bezpieczeństwa nie zalecamy stosowania tej metody w przypadku nowych integracji. Zamiast tego użyj przepływu kodu autoryzacji.

Aby obsługiwać przepływ niejawny OAuth 2.0, usługa udostępnia punkt końcowy autoryzacji przez HTTPS. Ten punkt końcowy odpowiada za uwierzytelnianie i uzyskiwanie zgody użytkowników na dostęp do danych. Punkt końcowy autoryzacji wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestruje zgodę na żądany dostęp.

Gdy aplikacja Google musi wywołać jeden z autoryzowanych interfejsów API Twojej usługi, używa tego punktu końcowego, aby uzyskać od użytkowników pozwolenie na wywoływanie tych interfejsów API w ich imieniu.

Łączenie kont Google: przepływ niejawny OAuth

Poniższy diagram sekwencji przedstawia interakcje między użytkownikiem, Google i punktami końcowymi Twojej usługi.

Rysunek 1. Sekwencja zdarzeń w przypadku łączenia kont Google za pomocą przepływu niejawnego OAuth 2.0.

Role i obowiązki

W tabeli poniżej zdefiniowano role i obowiązki podmiotów w przypadku przepływu niejawnego protokołu OAuth w ramach łączenia z kontem Google (GAL). Pamiętaj, że w globalnej liście adresów Google pełni rolę klienta OAuth, a Twoja usługa – dostawcy tożsamości lub dostawcy usług.

Użytkownik, który wykonał czynność lub komponent	Rola GAL	Podmiot odpowiedzialny
Aplikacja / serwer Google	Klient OAuth	Inicjuje proces, odbiera token dostępu za pomocą przekierowania przeglądarki i bezpiecznie go przechowuje, aby uzyskać dostęp do interfejsów API usługi.
Punkt końcowy autoryzacji	Serwer autoryzacji	Uwierzytelnia użytkowników, uzyskuje ich zgodę i wydaje długoterminowe tokeny dostępu bezpośrednio do Google.
Identyfikator URI przekierowania Google	Punkt końcowy wywołania zwrotnego	Otrzymuje przekierowanie użytkownika z usługi autoryzacji z wartościami access_token i state w fragmencie adresu URL.

Typowa sesja przepływu niejawnego OAuth 2.0 zainicjowana przez Google przebiega w ten sposób:

1. Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Użytkownik loguje się (jeśli nie jest jeszcze zalogowany) i przyznaje Google uprawnienia dostępu do swoich danych za pomocą Twojego interfejsu API (jeśli nie zrobił tego wcześniej).
2. Usługa tworzy token dostępu i zwraca go do Google. Aby to zrobić, przekieruj przeglądarkę użytkownika z powrotem do Google, dołączając do żądania token dostępu.
3. Google wywołuje interfejsy API Twojej usługi i dołącza token dostępu do każdego żądania. Usługa sprawdza, czy token dostępu przyznaje Google autoryzację dostępu do interfejsu API, a następnie wykonuje wywołanie interfejsu API.

Przepis na wdrożenie

Aby wdrożyć przepływ niejawny, wykonaj te czynności.

Krok 1. Obsługa próśb o autoryzację

Gdy Google zainicjuje połączenie kont, przekieruje użytkownika do Twojego punktu końcowego autoryzacji. Szczegółowe informacje o umowach protokołu i wymaganiach dotyczących parametrów znajdziesz w sekcji Punkt końcowy autoryzacji.

Aby obsłużyć prośbę, wykonaj te czynności:

1. Sprawdź prośbę:

   • Sprawdź, czy client_id odpowiada identyfikatorowi klienta przypisanemu do Google.
   • Sprawdź, czy redirect_uri jest zgodny z oczekiwanym adresem URL przekierowania Google:none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
   • Sprawdź, czy wartość response_type to token.

2. Uwierzytelnij użytkownika:

   • Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze.
   • Jeśli użytkownik nie jest zalogowany, poproś go o wykonanie czynności wymaganych do zalogowania się lub zarejestrowania.

3. Wygeneruj token dostępu:

   • Utwórz unikalny, trudny do odgadnięcia token dostępu powiązany z użytkownikiem i klientem.

4. Przekierowanie z powrotem do Google:

   • Przekieruj przeglądarkę na adres URL podany w redirect_uri.
   • Dołącz te parametry do fragmentu adresu URL (hasz):
     • access_token: wygenerowany token dostępu.
     • token_type: musi mieć wartość bearer.
     • state: niezmodyfikowana wartość stanu otrzymana od Google.

Obsługa żądań informacji o użytkowniku

Punkt końcowy informacji o użytkowniku jest chronionym przez OAuth 2.0 zasobem, który zwraca deklaracje dotyczące połączonego użytkownika. Wdrożenie i hosting punktu końcowego informacji o użytkowniku jest opcjonalne. Wyjątkiem są te przypadki użycia:

• Logowanie się na połączone konto za pomocą Google One Tap
• Bezproblemowa subskrypcja na AndroidTV.

Po pobraniu tokena dostępu z punktu końcowego tokena Google wysyła żądanie do punktu końcowego informacji o użytkowniku, aby pobrać podstawowe informacje profilowe połączonego użytkownika.

nagłówki żądań punktu końcowego informacji o użytkowniku
Authorization header	Token dostępu typu okaziciela.

Jeśli na przykład punkt końcowy informacji o użytkowniku jest dostępny pod adresem https://myservice.example.com/userinfo, żądanie może wyglądać tak:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Aby punkt końcowy informacji o użytkowniku mógł obsługiwać żądania, wykonaj te czynności:

1. Wyodrębnij token dostępu z nagłówka autoryzacji i zwróć informacje o użytkowniku powiązanym z tym tokenem.
2. Jeśli token dostępu jest nieprawidłowy, zwróć błąd HTTP 401 (Brak autoryzacji) i użyj nagłówka odpowiedzi WWW-Authenticate. Poniżej znajduje się przykładowa odpowiedź na pytanie o błąd w informacjach o użytkowniku:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Jeśli podczas procesu łączenia pojawi się błąd 401 (Brak autoryzacji) lub inna nieudana próba połączenia, błędu nie będzie można odzyskać, pobrany token zostanie odrzucony, a użytkownik będzie musiał ponownie zainicjować proces łączenia.

3. Jeśli token dostępu jest prawidłowy, zwróć odpowiedź HTTP 200 z podanym niżej obiektem JSON w treści HTTPS odpowiedź:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   Jeśli punkt końcowy informacji o użytkowniku zwraca odpowiedź HTTP 200, pobrany token i żądania są rejestrowane dla konta Google użytkownika.

   odpowiedź dotycząca punktu końcowego informacji o użytkowniku
   sub	Unikalny identyfikator, który identyfikuje użytkownika w Twoim systemie.
   email	Adres e-mail użytkownika.
   given_name	Opcjonalnie: imię użytkownika.
   family_name	Opcjonalnie: nazwisko użytkownika.
   name	Opcjonalnie: pełna nazwa użytkownika.
   picture	Opcjonalnie: zdjęcie profilowe użytkownika.