Łączenie konta Google z protokołem OAuth

Konta są łączone przy użyciu standardowych przepływów protokołu OAuth 2.0 i kodu autoryzacji. Twoja usługa musi obsługiwać punkty końcowe autoryzacji zgodnej z protokołem OAuth 2.0 i punkty końcowe tokena.

W ramach procesu domyślnego Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po udanym logowaniu zwracasz do Google token dostępu o dłuższej długości. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego przez Google.

W procesie kodu autoryzacji potrzebujesz 2 punktów końcowych:

  • Punkt końcowy autoryzacji, który wyświetla interfejs logowania użytkownikom, którzy jeszcze nie są zalogowani. Punkt końcowy autoryzacji tworzy też krótki kod autoryzacji do rejestrowania użytkowników i uzyskiwania zgody na żądany dostęp.

  • Punkt końcowy token Exchange, który jest odpowiedzialny za 2 typy giełd:

    1. Wymiana kodu autoryzacji dla długotrwałego tokenu odświeżania i krótkoterminowego tokena dostępu. Wymiana następuje, gdy użytkownik przeprowadzi proces łączenia kont.
    2. Wymiana tokenu odświeżania o długim czasie ważności na token dostępu o krótkim czasie ważności. Ta wymiana ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ wygasł.

Wybierz przepływ OAuth 2.0

Chociaż procedura domyślna jest prostsza, zalecamy, by tokeny dostępu domyślnie ustały. Dzieje się tak, ponieważ użytkownik jest zmuszony ponownie połączyć swoje konto po wygaśnięciu tokena w wynikowy sposób. Jeśli ze względów bezpieczeństwa zależy Ci na wygaśnięciu tokena, zdecydowanie zalecamy użycie procesu kodu autoryzacji.

Wskazówki dotyczące wyglądu

W tej sekcji opisano wymagania projektowe i zalecenia dotyczące ekranu użytkownika hostowanego przez proces łączenia OAuth. Po wywołaniu jej przez aplikację Google na Twojej platformie wyświetla się ekran logowania na stronie Google, a użytkownik wyraża zgodę na połączenie konta. Gdy użytkownik wyrazi zgodę na połączenie kont, zostanie przekierowany z powrotem do aplikacji Google.

Ten wykres przedstawia czynności, jakie musi wykonać użytkownik, aby połączyć swoje konto Google z Twoim systemem uwierzytelniania. Pierwszy zrzut ekranu przedstawia linki inicjowane przez użytkownika na Twojej platformie. Drugi obraz przedstawia logowanie użytkownika w Google, a trzeci – zgodę użytkownika i jego potwierdzenie na potrzeby połączenia konta Google z aplikacją. Ostatni zrzut ekranu przedstawia połączone konto użytkownika w aplikacji Google.
Rysunek 1. Łączenie kont loguje się w Google i na ekranach zgody.

Wymagania

  1. Musisz poinformować, że konto użytkownika zostanie połączone z Google, a nie z konkretną usługą Google, taką jak Google Home czy Asystent Google.

Zalecenia

Zalecamy wykonanie tych czynności:

  1. Wyświetl Politykę prywatności Google Podaj na ekranie zgody link do Polityki prywatności Google.

  2. Dane do udostępnienia. Stosuj jasne i zwięzłe sformułowania, których użytkownik potrzebuje, i wyjaśnij, jakich danych Google potrzebuje i dlaczego.

  3. Stosuj jednoznaczne wezwania do działania. Jasno umieść wezwanie do działania na ekranie zgody, np. „Zgadzam się i łączę”. Użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, by połączyć swoje konta.

  4. Możliwość anulowania. Zapewnij użytkownikom możliwość powrotu lub anulowania subskrypcji, jeśli nie chcą tworzyć linków.

  5. Przejrzysty proces logowania. Upewnij się, że użytkownicy mają wyraźną metodę logowania się na swoje konto Google, np. pola do wpisania nazwy użytkownika i hasła lub logowania się przez Google.

  6. Możliwość odłączenia. Udostępnij użytkownikom mechanizm odłączenia kont, na przykład URL do ustawień ich konta na Twojej platformie. Możesz też podać link do konta Google, na którym użytkownicy mogą zarządzać swoim połączonym kontem.

  7. Możliwość zmiany konta użytkownika. Zasugeruj użytkownikom zmianę swojego konta. Jest to szczególnie przydatne, gdy użytkownicy mają zwykle kilka kont.

    • Jeśli użytkownik musi zamknąć ekran zgody, aby przełączyć konta, wyślij do Google opis możliwego do odzyskania błędu, aby mógł zalogować się na wybrane konto przy użyciu łączenia OAuth i procesu domyślnego.

  8. Logo. Wyświetlaj logo swojej firmy na ekranie zgody. Umieść swoje logo zgodnie ze wskazówkami dotyczącymi stylu. Jeśli chcesz też wyświetlać logo Google, zobacz Logo i znaki towarowe.

Tworzenie projektu

Aby utworzyć projekt z funkcją łączenia kont:

  1. Go to the Google API Console.
  2. Kliknij Utwórz projekt .
  3. Wpisz nazwę lub zaakceptuj wygenerowaną sugestię.
  4. Potwierdź lub edytuj pozostałe pola.
  5. Kliknij Utwórz .

Aby wyświetlić identyfikator projektu:

  1. Go to the Google API Console.
  2. Znajdź swój projekt w tabeli na landing page. Identyfikator projektu pojawia się w kolumnie ID .

Proces łączenia kont Google obejmuje ekran zgody, na którym aplikacja prosi o dostęp do ich danych, rodzaj danych, o które proszą, oraz obowiązujące warunki. Przed wygenerowaniem identyfikatora klienta interfejsu API Google musisz skonfigurować ekran zgody OAuth.

  1. Otwórz stronę Ekran zgody OAuth w konsoli interfejsów API Google.
  2. Jeśli pojawi się taka prośba, wybierz właśnie utworzony projekt.

  3. Na stronie „Ekran zgody OAuth” wypełnij formularz i kliknij przycisk „Zapisz”.

    Nazwa aplikacji: nazwa aplikacji, która prosi o zgodę. Nazwa powinna dokładnie odzwierciedlać Twoją aplikację i być zgodna z nazwą, którą użytkownicy widzą w innych miejscach. Nazwa aplikacji będzie widoczna na ekranie zgody na łączenie kont.

    Logo aplikacji: obraz na ekranie zgody, który pomoże użytkownikom rozpoznać Twoją aplikację. Logo jest widoczne na ekranie zgody łączenia kont oraz w ustawieniach konta.

    Adres e-mail zespołu pomocy: umożliwia użytkownikom kontaktowanie się z Tobą w razie pytań o udzielenie zgody.

    Zakresy dla interfejsów API Google: zakresy umożliwiają aplikacji dostęp do prywatnych danych Google użytkownika. W przypadku łączenia kont Google wystarczy ustawić domyślny zakres (adres e-mail, profil, identyfikator openid) i nie musisz dodawać żadnych poufnych zakresów. Ogólnie sprawdzoną metodą jest stopniowe zgłaszanie żądań zakresów w momencie, gdy jest wymagany dostęp, a nie z góry. Więcej informacji

    Autoryzowane domeny: aby chronić Ciebie i Twoich użytkowników, Google zezwala na korzystanie z autoryzowanych domen tylko aplikacjom, które uwierzytelniają się za pomocą protokołu OAuth. Linki Twoich aplikacji muszą być hostowane w autoryzowanych domenach. Więcej informacji

    Link do strony głównej aplikacji: strona główna Twojej aplikacji. Musi być hostowany w autoryzowanej domenie.

    Link do polityki prywatności aplikacji: wyświetlany na ekranie zgody dotyczącej łączenia konta Google. Musi być hostowany w autoryzowanej domenie.

    Link do Warunków korzystania z usługi (opcjonalny): musi być hostowany w autoryzowanej domenie.

    Rysunek 1. Ekran ze zgodą na łączenie konta Google dla fikcyjnej aplikacji, Tunery

  4. Sprawdź „Stan weryfikacji”, jeśli zgłoszenie wymaga weryfikacji, a następnie kliknij przycisk „Prześlij do weryfikacji”, aby przesłać zgłoszenie do weryfikacji. Szczegółowe informacje znajdziesz w artykule Wymagania dotyczące weryfikacji OAuth.

Implementowanie serwera OAuth

授权码流的的OAuth 2.0服务器实现由两个端点，通过HTTPS，你的服务使可用的。第一个端点是授权端点，它负责查找或获得用户对数据访问的同意。授权端点向尚未登录的用户显示登录 UI，并记录对请求访问的同意。第二个端点是令牌交换端点，用于获取加密字符串，称为令牌，授权用户访问您的服务。

当 Google 应用程序需要调用您的服务的某个 API 时，Google 会结合使用这些端点来获得您的用户的许可，以代表他们调用这些 API。

Google发起的一次OAuth 2.0授权码流会话流程如下：

  1. Google 在用户的浏览器中打开您的授权端点。如果流程在 Action 的纯语音设备上开始，Google 会将执行转移到手机。
  2. 用户登录（如果尚未登录）并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
  3. 您的服务创建一个授权码，并返回给谷歌。为此，请将用户的浏览器重定向回 Google，并将授权代码附加到请求中。
  4. 谷歌发送授权代码，您的令牌交换终结，从而验证代码的真实性，并返回一个访问令牌和刷新令牌。访问令牌是一个短期令牌，您的服务接受它作为访问 API 的凭据。刷新令牌是一个长期存在的令牌，Google 可以存储它并在它们到期时使用它来获取新的访问令牌。
  5. 用户完成帐户关联流程后，从 Google 发送的每个后续请求都包含一个访问令牌。

处理授权请求

当您需要使用 OAuth 2.0 授权代码流执行帐户关联时，Google 会将用户发送到您的授权端点，并发送一个包含以下参数的请求：

授权端点参数
client_id您分配给 Google 的客户 ID。
redirect_uri您向其发送对此请求的响应的 URL。
state传递回 Google 的簿记值在重定向 URI 中保持不变。
scope可选：以空格分隔的集合，其指定谷歌正在请求授权的数据范围的字符串。
response_type要在响应中返回的值的类型。对于的OAuth 2.0授权码流，响应类型总是code 。
user_locale在谷歌帐户语言设置RFC5646格式，用于本地化用户的首选语言内容。

例如，如果您的授权端点可在https://myservice.example.com/auth ，请求看起来像下面这样：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

对于处理登录请求的授权端点，请执行以下步骤：

  1. 验证client_id您分配给谷歌的客户ID匹配，并且该redirect_uri由谷歌为您服务提供的重定向URL匹配。这些检查对于防止授予对意外或配置错误的客户端应用程序的访问权限非常重要。如果你支持多种OAuth 2.0流程的，也确认response_type是code 。
  2. 检查用户是否已登录您的服务。如果用户未登录，请完成服务的登录或注册流程。
  3. 生成供 Google 用于访问您的 API 的授权代码。授权码可以是任何字符串值，但必须唯一代表用户、token所针对的客户端、授权码的过期时间，并且不能被猜到。您通常会发出大约 10 分钟后过期的授权代码。
  4. 确认URL指定由redirect_uri参数有以下形式： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
  5. 重定向用户的浏览器由指定的URL redirect_uri参数。当你通过附加重定向包括刚刚生成授权码和原始未修正的状态值code和state参数。以下是所得的URL的一个示例： 
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

处理令牌交换请求

您的服务的令牌交换端点负责两种令牌交换：

  • 交换访问令牌和刷新令牌的授权代码
  • 交换刷新令牌以获取访问令牌

令牌交换请求包括以下参数：

令牌交换端点参数
client_id将请求源标识为 Google 的字符串。此字符串必须在您的系统中注册为 Google 的唯一标识符。
client_secret您在 Google 上为您的服务注册的秘密字符串。
grant_type被交换的代币类型。这是不是authorization_code或refresh_token 。
code当grant_type=authorization_code ，这个参数是从您登录或令牌交换终结收到谷歌的代码。
redirect_uri当grant_type=authorization_code ，该参数是在初始授权请求中使用的URL。
refresh_token当grant_type=refresh_token ，这个参数是令牌从令牌交换终结收到谷歌的刷新。
交换访问令牌和刷新令牌的授权代码

在用户登录并且您的授权端点向 Google 返回一个短期授权代码后，Google 会向您的令牌交换端点发送请求，以交换访问令牌和刷新令牌的授权代码。

对于这些请求，价值grant_type是authorization_code ，和值code是您先前授予给谷歌授权码的值。以下是为访问令牌和刷新令牌交换授权代码的请求示例：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

要为访问Exchange授权码令牌和刷新令牌，您的令牌交换终结响应POST通过执行以下步骤要求：

  1. 验证该client_id识别为授权原点，并且所述请求源client_secret预期值相匹配。
  2. 验证授权码是否有效且未过期，以及请求中指定的客户端 ID 是否与与授权码关联的客户端 ID 匹配。
  3. 确认URL中指定由redirect_uri参数是相同的初始授权请求中使用的值。
  4. 如果您无法验证所有的上述标准，则返回一个HTTP 400错误的请求错误与{"error": "invalid_grant"}作为身体。
  5. 否则，使用授权代码中的用户 ID 生成刷新令牌和访问令牌。这些令牌可以是任何字符串值，但它们必须唯一地代表令牌所针对的用户和客户端，并且不能被猜测。对于访问令牌，还要记录令牌的到期时间，通常是您发出令牌后的一个小时。刷新令牌不会过期。
  6. 返回以下JSON对象在HTTPS响应的主体：
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google 为用户存储访问令牌和刷新令牌，并记录访问令牌的到期时间。当访问令牌过期时，Google 使用刷新令牌从您的令牌交换端点获取新的访问令牌。

交换刷新令牌以获取访问令牌

当访问令牌过期时，Google 会向您的令牌交换端点发送请求，以将刷新令牌交换为新的访问令牌。

对于这些请求，价值grant_type被refresh_token ，和值refresh_token是令牌先前授予谷歌刷新的值。以下是将刷新令牌交换为访问令牌的请求示例：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

要交换令牌的访问令牌刷新，您的令牌交换终结响应POST通过执行以下步骤要求：

  1. 验证client_id标识请求起源谷歌，那client_secret预期值相符。
  2. 验证刷新令牌是否有效，以及请求中指定的客户端 ID 是否与与刷新令牌关联的客户端 ID 匹配。
  3. 如果您无法验证所有的上述标准，则返回一个HTTP 400错误的请求错误与{"error": "invalid_grant"}作为身体。
  4. 否则，使用刷新令牌中的用户 ID 生成访问令牌。这些令牌可以是任何字符串值，但它们必须唯一地代表令牌所针对的用户和客户端，并且它们不能被猜测。对于访问令牌，还要记录令牌的到期时间，通常是在您发出令牌后的一个小时。
  5. 在 HTTPS 响应的正文中返回以下 JSON 对象：
    {
"token_type": "Bearer",
"access_token": " ACCESS_TOKEN ",
"expires_in": SECONDS_TO_EXPIRATION
}
处理用户信息请求

该用户信息终端是一个OAuth 2.0保护的资源，对链接的用户返回的权利要求。实现和托管 userinfo 端点是可选的，以下用例除外：

从您的令牌端点成功检索访问令牌后，Google 会向您的 userinfo 端点发送请求，以检索有关链接用户的基本个人资料信息。

userinfo 端点请求标头
Authorization header Bearer 类型的访问令牌。

例如，如果你的用户信息终端可在https://myservice.example.com/userinfo ，请求看起来像下面这样：

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

要让您的 userinfo 端点处理请求，请执行以下步骤：

  1. 从 Authorization 标头中提取访问令牌并返回与访问令牌关联的用户的信息。
  2. 如果访问令牌无效，返回HTTP 401错误未经授权使用的WWW-Authenticate响应头。下面是一个userinfo的错误响应的一个示例：
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    如果一个401未经授权，或任何其它不成功错误响应在关联过程返回时，误差将是不可恢复的，所检索的令牌将被丢弃，并且用户将必须再次启动链接过程。

  3. 如果访问令牌是有效的，回国与以下JSON对象在HTTPS响应的身体HTTP 200回应： 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
    如果你的用户信息端点返回一个HTTP 200成功响应，检索到的令牌和索赔登记针对用户的谷歌帐户。

    用户信息端点响应
    sub标识系统中用户的唯一 ID。
    email用户的电子邮件地址。
    given_name可选：用户的名字。
    family_name可选：用户的姓氏。
    name可选：用户的全名。
    picture可选：用户的档案图片。

Sprawdzanie poprawności implementacji

Można sprawdzić poprawność implementacji za pomocą OAuth 2.0 Playground narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij konfiguracji , aby otworzyć okno konfiguracji OAuth 2.0.
  2. W dziedzinie przepływu OAuth, wybierz Client-side.
  3. W polu OAuth Endpoints wybierz Niestandardowy.
  4. W odpowiednich polach określ punkt końcowy OAuth 2.0 i identyfikator klienta przypisany do Google.
  5. W sekcji Krok 1, nie zaznaczaj żadnych zakresów Google. Zamiast tego pozostaw to pole puste lub wpisz zakres poprawny dla Twojego serwera (lub dowolny ciąg, jeśli nie używasz zakresów OAuth). Kiedy skończysz, kliknij autoryzacji API.
  6. W etapie 2 i etapem 3 części, przechodzą przepływu OAuth 2.0 i upewnić się, że każdy etap działa zgodnie z zamierzeniem.

Można sprawdzić poprawność implementacji za pomocą konta Google Linking Demo narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij Sign-in z przycisku Google.
  2. Wybierz konto, które chcesz połączyć.
  3. Wprowadź identyfikator usługi.
  4. Opcjonalnie wprowadź co najmniej jeden zakres, do którego poprosisz o dostęp.
  5. Kliknij Start Demo.
  6. Po wyświetleniu monitu potwierdź, że możesz wyrazić zgodę i odrzucić prośbę o połączenie.
  7. Potwierdź, że zostałeś przekierowany na swoją platformę.