Łączenie konta Google z OAuth

Konta są łączone za pomocą standardowego w branży przepływu kodu autoryzacji OAuth 2.0.

OAuth 2.1 i PKCE w przypadku agentów

W przypadku bezstanowych agentów AI i wielomodowych potoków zalecane jest egzekwowanie OAuth 2.1.

PKCE (Proof Key for Code Exchange): musi być używany do zabezpieczania przepływu kodu autoryzacji, co zapobiega atakom polegającym na przechwytywaniu.
Brak przepływu niejawnego: przepływ niejawny udostępnia tokeny dostępu w adresie URL, co stanowi zagrożenie dla bezpieczeństwa środowisk agentów.

Usługa musi obsługiwać punkty końcowe autoryzacji i wymiany tokenów zgodne z OAuth 2.0/2.1.

Tworzenie projektu

Aby utworzyć projekt do łączenia kont:

Otwórz konsolę interfejsów API Google.
Kliknij Utwórz projekt.
Wpisz nazwę lub zaakceptuj wygenerowaną sugestię.
Potwierdź lub edytuj pozostałe pola.
Kliknij Utwórz.

Aby wyświetlić identyfikator projektu:

Otwórz konsolę interfejsów API Google.
Znajdź swój projekt w tabeli na stronie docelowej. Identyfikator projektu jest wyświetlany w kolumnie Identyfikator.

Konfigurowanie ekranu zgody OAuth

Proces łączenia z kontem Google obejmuje ekran zgody, na którym użytkownicy mogą zobaczyć, która aplikacja prosi o dostęp do ich danych, jakich danych żąda i jakie warunki mają zastosowanie. Zanim wygenerujesz identyfikator klienta interfejsu API Google, musisz skonfigurować ekran zgody OAuth.

Otwórz stronę ekranu zgody OAuth w konsoli interfejsów API Google.
Jeśli pojawi się prośba, wybierz projekt, który właśnie utworzyłeś.
Na stronie „Ekran zgody OAuth” wypełnij formularz i kliknij przycisk „Zapisz”.

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

Logo aplikacji: obraz na ekranie zgody, który pomoże użytkownikom rozpoznać Twoją aplikację. Logo jest wyświetlane na ekranie zgody na łączenie kont i w ustawieniach konta.

Adres e-mail pomocy: dla użytkowników, którzy chcą się z Tobą skontaktować w sprawie pytań o ich zgodę.

Zakresy interfejsów API Google: zakresy umożliwiają aplikacji dostęp do prywatnych danych Google użytkownika. W przypadku łączenia z kontem Google wystarczy domyślny zakres (e-mail, profil, OpenID). Nie musisz dodawać żadnych zakresów wrażliwych. Zasadniczo najlepszym rozwiązaniem jest żądanie zakresów przyrostowo, w momencie, gdy wymagany jest dostęp, a nie z góry. Więcej informacji.

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

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

Link do polityki prywatności aplikacji: Wyświetlany na ekranie zgody na łączenie kont Google. Musi być hostowana w autoryzowanej domenie.

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

Rysunek 1. Ekran zgody na łączenie z kontem Google w przypadku fikcyjnej aplikacji Tunery
Sprawdź „Stan weryfikacji”. Jeśli Twoja aplikacja wymaga weryfikacji, kliknij przycisk „Prześlij do weryfikacji”, aby przesłać aplikację do weryfikacji. Szczegółowe informacje znajdziesz w wymaganiach dotyczących weryfikacji OAuth.

Wdrażanie serwera OAuth

OAuth 2.0 服务器的 授权代码流程实现包含两个端点，您的服务通过 HTTPS 提供这两个端点。第一个端点是授权端点，负责查找用户或征得用户同意以获取数据访问权限。授权端点会向尚未登录的用户显示登录界面，并记录用户对所请求访问权限的同意情况。第二个端点是令牌交换端点，用于获取加密字符串（称为令牌），这些令牌授权用户访问您的服务。

当 Google 应用需要调用您服务的某个 API 时，Google 会同时使用这些端点，以获取用户授权代表他们调用这些 API。

Google 账号关联：OAuth 授权代码流程

以下序列图详细介绍了用户、Google 和您服务的端点之间的交互。

图 1.Google 账号关联的 OAuth 2.0 授权代码流程中的事件序列。

角色和职责

下表定义了 Google 账号关联 (GAL) OAuth 流程中参与者的角色和职责。请注意，在 GAL 中，Google 充当 OAuth 客户端 ，而您的服务充当 身份/服务提供方 。

参与者 / 组件	GAL 角色	职责
Google 应用 / 服务器	OAuth 客户端	发起流程，接收授权代码，将其交换为令牌，并安全地存储这些令牌以访问您服务的 API。
您的授权端点	授权服务器	对用户进行身份验证，并征得用户同意与 Google 分享其数据访问权限。
您的令牌交换端点	授权服务器	验证授权代码和刷新令牌，并向 Google 服务器颁发访问令牌。
Google 重定向 URI	回调端点	接收来自您的授权服务的用户重定向，其中包含 `code` 和 `state` 值。

由 Google 发起的 OAuth 2.0 授权代码流程会话具有以下流程：

Google 在用户的浏览器中打开您的授权端点。如果流程是在仅支持语音的设备上为 Action 启动的，Google 会将执行转移到手机。
用户登录（如果尚未登录），并授予 Google 权限以使用您的 API 访问其数据（如果尚未授予权限）。
您的服务会创建 授权代码并将其返回给 Google。为此，请将用户的浏览器重定向回 Google，并将授权代码附加到请求中。
Google 会将授权代码发送到您的令牌交换端点，该端点会验证代码的真实性并返回 访问令牌和 刷新令牌。访问令牌是一种短期令牌，您的服务会将其作为访问 API 的凭据。刷新令牌是一种长期令牌，Google 可以存储该令牌，并在访问令牌过期时使用它来获取新的访问令牌。
用户完成账号关联流程后，Google 发送的每个后续请求都包含访问令牌。

实现方案

请按照以下步骤实现授权代码流程。

第 1 步：处理授权请求

当 Google 发起账号关联时，它会将用户重定向到您的授权端点。如需了解详细的协议合同和参数要求，请参阅授权端点。

如需处理请求，请执行以下操作：

验证请求：
- 确认 client_id 与分配给 Google 的客户端 ID 相匹配。
- 确认 redirect_uri 与预期的 Google 重定向网址： none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID相匹配
- 验证 response_type 是否为 code。
对用户进行身份验证：
- 检查用户是否已登录您的服务。
- 如果用户未登录，请提示他们完成您的登录或注册流程。
生成授权代码：
- 创建与用户和客户端关联的唯一且难以猜测的授权代码。
- 将代码设置为在约 10 分钟后过期。
重定向回 Google：
- 将浏览器重定向到 redirect_uri 中提供的网址。
- 附加以下查询参数：
  - code：您生成的授权代码。
  - state：从 Google 收到的未修改的状态值。

第 2 步：处理令牌交换请求

您的令牌交换端点会处理两种类型的请求：将代码交换为令牌，以及刷新过期的访问令牌。如需了解详细的协议合同和参数要求，请参阅令牌交换端点。

A. 将授权代码交换为令牌

当 Google 收到授权代码时，它会调用您的令牌交换端点 (POST) 以检索令牌。

验证请求：
- 验证 client_id 和 client_secret。
- 验证授权代码是否有效且未过期。
- 确认 redirect_uri 与第 1 步中使用的值相匹配。
- 如果验证失败，则返回 HTTP 400 Bad Request，并返回 {"error": "invalid_grant"}。
颁发令牌：
- 生成长期有效的 refresh_token 和短期有效的 access_token（通常为 1 小时）。
- 返回 HTTP 200 OK，并返回标准 JSON 令牌响应。

B. 刷新访问令牌

当访问令牌过期时，Google 会使用刷新令牌请求新的访问令牌。

验证请求：
- 验证 client_id、client_secret 和 refresh_token。
- 如果验证失败，则返回 HTTP 400 Bad Request，并返回 {"error": "invalid_grant"}。
颁发新的访问令牌：
- 生成新的短期有效的 access_token。
- 返回 HTTP 200 OK，并返回 JSON 令牌响应（可以选择包含新的刷新令牌）。

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:

Wyodrębnij token dostępu z nagłówka autoryzacji i zwróć informacje o użytkowniku powiązanym z tym tokenem.
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.

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.

Sprawdzanie poprawności implementacji

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

点击配置以打开“OAuth 2.0 配置”窗口。
在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
在 OAuth Endpoints 字段中，选择 Custom。
在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。