Vinculação da Conta do Google com o OAuth

As contas são vinculadas usando os fluxos implícitos e de código de autorização do OAuth 2.0 padrão do setor. Seu serviço precisa oferecer suporte a endpoints de autorização e troca de token compatíveis com o OAuth 2.0.

在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您将向 Google 返回一个长期访问令牌。现在，此访问令牌会包含在 Google 发送的每个请求中。

在授权代码流程中，您需要两个端点：

授权端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码，以记录用户对所请求访问权限的同意情况。
令牌交换端点，负责两种类型的交换：
1. 使用授权代码换取长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，就会发生此交换。
2. 将长期有效的刷新令牌换成短期有效的访问令牌。当 Google 需要新的访问令牌（因为现有访问令牌已过期）时，就会发生这种交换。

选择 OAuth 2.0 流程

虽然隐式流程更易于实现，但 Google 建议通过隐式流程签发的访问令牌永不过期。这是因为，在隐式流程中，令牌过期后，系统会强制用户重新关联其账号。如果您出于安全考虑需要令牌过期，我们强烈建议您改用授权码流程。

设计准则

本部分介绍了您为 OAuth 关联流程托管的用户屏幕的设计要求和建议。在 Google 应用调用该 API 后，您的平台会向用户显示登录 Google 页面和账号关联意见征求界面。同意关联账号后，系统会将用户重定向回 Google 的应用。

此图展示了用户将其 Google 账号与您的身份验证系统相关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片显示用户登录 Google，第三张图片显示用户同意并确认将其 Google 账号与您的应用相关联。最后一张屏幕截图显示 Google 应用中成功关联的用户账号。 — **图 1.**账号关联用户登录 Google 和同意屏幕。

要求

您必须说明用户的账号将与 Google 相关联，而非 Google Home 或 Google 助理等特定 Google 产品相关联。

建议

建议您执行以下操作：

显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。
要共享的数据。使用清晰简洁的语言告知用户 Google 需要哪些用户数据以及原因。
添加醒目的号召性用语。在用户同意页面上提供明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 分享哪些数据才能关联账号。
可以取消。为用户提供返回或取消链接的途径，如果用户选择不进行关联。
明确的登录流程。确保用户有明确的 Google 账号登录方法，例如用户名和密码字段或使用 Google 账号登录。
能够解除关联。提供一种可让用户解除关联的机制，例如指向您平台上账号设置的网址。或者，您也可以添加指向 Google 账号的链接，以便用户管理其关联的账号。
能够更改用户账号。建议用户切换账号的方法。如果用户通常拥有多个账号，这种做法尤为有益。
- 如果用户必须关闭意见征求界面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联和隐式流程登录所需的账号。
添加您的徽标。在意见征求页面上显示您的公司徽标。按照您的样式准则放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。

Criar o projeto

Para criar um projeto que use a vinculação de contas:

Clique em Criar projeto.
Digite um nome ou aceite a sugestão gerada.
Confirme ou edite os campos restantes.
Clique em Criar.

Para conferir o ID do projeto:

Encontre seu projeto na tabela da página de destino. O ID do projeto aparece na coluna ID.

Configurar a tela de permissão OAuth

O processo de vinculação de contas do Google inclui uma tela de consentimento que informa aos usuários o aplicativo que está solicitando acesso aos dados, o tipo de dados que está sendo pedido e os termos aplicáveis. É necessário configurar a tela de consentimento do OAuth antes de gerar um ID do cliente da API do Google.

Abra a página Tela de consentimento OAuth no console de APIs do Google.
Se solicitado, selecione o projeto que você acabou de criar.
Na página "Tela de consentimento OAuth", preencha o formulário e clique no botão "Salvar".

Nome do aplicativo:o nome do aplicativo que precisa da permissão. O nome precisa refletir com precisão seu aplicativo e ser consistente com o nome que os usuários veem em outros lugares. O nome do aplicativo vai aparecer na tela de consentimento da vinculação de contas.

Logotipo do aplicativo:uma imagem na tela de permissão que ajuda os usuários a reconhecerem seu app. O logotipo aparece na tela de permissão para vinculação de contas e nas configurações da conta.

E-mail de suporte:para que os usuários entrem em contato com você a respeito do consentimento.

Escopos para APIs do Google:os escopos permitem que seu aplicativo acesse os dados particulares do Google do usuário. Para o caso de uso da vinculação de Conta do Google, o escopo padrão (e-mail, perfil, openid) é suficiente. Não é necessário adicionar escopos sensíveis. Geralmente, é uma prática recomendada solicitar escopos de forma incremental, no momento em que o acesso é necessário, em vez de fazer isso antecipadamente. Saiba mais.

Domínios autorizados:para proteger você e seus usuários, o Google permite apenas que aplicativos que autenticam usando o OAuth usem domínios autorizados. Os links dos seus aplicativos precisam ser hospedados em domínios autorizados. Saiba mais.

Link da página inicial do aplicativo:página inicial do seu aplicativo. Precisa ser hospedado em um domínio autorizado.

Link da Política de Privacidade do aplicativo:mostrado na tela de consentimento da vinculação de Contas do Google. Precisa ser hospedado em um domínio autorizado.

Link dos Termos de Serviço do aplicativo (opcional): precisa estar hospedado em um domínio autorizado.

Figura 1. Tela de consentimento para vinculação de contas do Google para um aplicativo fictício, o Tunery
Verifique o "Status da verificação". Se o aplicativo precisar de verificação, clique no botão "Enviar para verificação". Consulte os requisitos de verificação do OAuth para mais detalhes.

Implementar seu servidor OAuth

为了支持 OAuth 2.0 隐式流，您的服务会进行授权端点。此端点负责进行身份验证，就数据访问征得用户同意。授权端点向尚未登录的用户显示登录界面，并记录同意所请求的访问。

当 Google 应用需要调用您的某项服务获得授权的 API 时， Google 使用此端点从您的用户处获取调用这些 API 的权限。

由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征：以下流程：

Google 会在用户的浏览器中打开您的授权端点。通过如果用户尚未登录，则直接登录，然后授予 Google 以下权限：访问您的 API 访问其数据（如果尚未授权）。
您的服务会创建一个访问令牌并将其返回给 Google。为此，请将用户的浏览器重定向回 Google，并提供相应的访问权限令牌。
Google 调用您的服务的 API，并附加带有。您的服务会验证访问令牌是否向 Google 授予访问 API 的授权，然后完成 API 调用。

处理授权请求

当 Google 应用需要通过 OAuth 2.0 执行账号关联时隐式流程，Google 会通过请求，其中包含以下参数：

授权端点参数
`client_id`	您分配给 Google 的客户 ID。
`redirect_uri`	此请求的响应发送到的网址。
`state`	将一个在重定向 URI。
`response_type`	要在响应中返回的值的类型。对于 OAuth 2.0 隐式则响应类型始终为 `token`。
`user_locale`	“Google 账号语言设置” RFC5646 用于将您的内容本地化为用户首选语言的格式。

例如，如果您的授权端点位于 https://myservice.example.com/auth 时，请求可能如下所示：

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

为了让授权端点能够处理登录请求，请执行以下操作步骤：

验证 client_id 和 redirect_uri 值，防止向意外或配置错误的客户端应用授予访问权限：
- 确认 client_id 是否与您的客户端 ID 匹配分配给 Google。
- 确认 redirect_uri 指定的网址参数的格式如下：
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
```
检查用户是否已登录您的服务。如果用户未登录中，完成服务的登录或注册流程。
生成访问令牌，以供 Google 用于访问您的 API。通过访问令牌可以是任何字符串值，但必须唯一地表示令牌对应的用户和客户端，且不得被猜到。
发送 HTTP 响应，将用户浏览器重定向到相应网址由 redirect_uri 参数指定。添加所有以下参数：
- access_token：您刚刚生成的访问令牌
- token_type：字符串 bearer
- state：原始状态的未修改状态值请求
以下是生成的网址示例：
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
```

Google 的 OAuth 2.0 重定向处理程序收到访问令牌并确认 state 值没有更改。在 Google 获得访问令牌，则 Google 会将该令牌附加到后续调用服务 API

Processar solicitações userinfo

O endpoint userinfo é um recurso protegido pelo OAuth 2.0 que retorna declarações sobre o usuário vinculado. A implementação e hospedagem do endpoint userinfo é opcional, exceto nos seguintes casos de uso:

Login da conta vinculada com o Google One Tap.
Assinatura sem atrito no AndroidTV.

Depois que o token de acesso for recuperado do endpoint do token, o Google enviará uma solicitação ao endpoint de informações do usuário para recuperar informações básicas de perfil sobre o usuário vinculado.

cabeçalhos de solicitação do endpoint userinfo
`Authorization header`	O token de acesso do tipo Bearer.

Por exemplo, se seu ponto de extremidade de informações do usuário estiver disponível em https://myservice.example.com/userinfo, uma solicitação terá esta aparência:

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

Para que o endpoint userinfo processe solicitações, siga estas etapas:

Extrair o token de acesso do cabeçalho "Autorização" e retornar as informações do usuário associado ao token de acesso.
Se o token de acesso for inválido, retorne o erro "HTTP 401 Unused" ao usar o cabeçalho de resposta WWW-Authenticate. Veja abaixo um exemplo de resposta de erro userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Se uma resposta de erro "401 Não autorizado" ou outra resposta de erro for retornada durante o processo de vinculação, o erro não poderá ser recuperado, o token recuperado será descartado e o usuário terá que iniciar o processo de vinculação novamente.

Se o token de acesso for válido, retorne uma resposta HTTP 200 com o seguinte objeto JSON no corpo do HTTPS resposta:

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

Se o seu endpoint de informações do usuário retornar uma resposta HTTP 200 bem-sucedida, o token e as reivindicações recuperados serão registrados na Conta do Google do usuário.

resposta do endpoint userinfo
`sub`	Um ID exclusivo que identifica o usuário no seu sistema.
`email`	Endereço de e-mail do usuário.
`given_name`	Opcional:nome do usuário.
`family_name`	Opcional:sobrenome do usuário.
`name`	Opcional:o nome completo do usuário.
`picture`	Opcional:foto do perfil do usuário.

Como validar a implementação

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

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

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

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