Vinculação da Conta do Google com o OAuth

As contas são vinculadas usando fluxos implícitos e de código de autorização do OAuth 2.0, que são padrões do setor.

Seu serviço precisa oferecer suporte a endpoints de autorização e troca de tokens compatíveis com o OAuth 2.0.

No fluxo implícito, o Google abre o endpoint de autorização no navegador do usuário. Depois que o login é feito, você retorna um token de acesso de longa duração ao Google. Esse token de acesso agora está incluído em todas as solicitações enviadas pelo Google.

No fluxo do código de autorização, você precisa de dois endpoints:

O endpoint de autorização, que apresenta a interface de login aos usuários que ainda não fizeram login. O endpoint de autorização também cria um código de autorização de curta duração para registrar o consentimento dos usuários ao acesso solicitado.
O endpoint de troca de token, responsável por dois tipos de trocas:
1. Troca um código de autorização por um token de atualização de longa duração e um token de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação de contas.
2. Troca um token de atualização de longa duração por um token de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque o que ele tinha expirou.

Escolher um fluxo do OAuth 2.0

Embora o fluxo implícito seja mais simples de implementar, o Google recomenda que os tokens de acesso emitidos por ele nunca expirem. Isso ocorre porque o usuário é forçado a vincular a conta novamente após a expiração de um token com o fluxo implícito. Se você precisar da expiração do token por motivos de segurança, recomendamos que use o fluxo do código de autorização.

Diretrizes de design

Esta seção descreve os requisitos e as recomendações de design para a tela do usuário hospedada para fluxos de vinculação do OAuth. Depois de ser chamado pelo app do Google, sua plataforma mostra uma página de login no Google e uma tela de consentimento de vinculação de contas ao usuário. O usuário é direcionado de volta ao app do Google depois de dar o consentimento para vincular contas.

Esta figura mostra as etapas para um usuário vincular a Conta do Google
ao seu sistema de autenticação. A primeira captura de tela mostra
a vinculação iniciada pelo usuário na sua plataforma. A segunda imagem mostra
o login do usuário no Google, enquanto a terceira mostra o consentimento do usuário e a
confirmação do usuário para vincular a Conta do Google ao seu app. A
captura de tela final mostra uma conta de usuário vinculada com sucesso no
app Google. — **Figura 1.** Login do usuário e telas de consentimento de vinculação de contas ao Google.

Requisitos

Você precisa comunicar que a conta do usuário será vinculada ao Google, não a um produto específico do Google, como o Google Home ou o Google Assistente.

Recomendações

Portanto, recomendamos que você faça o seguinte:

Mostrar a Política de Privacidade do Google Inclua um link para a Política de Privacidade do Google na tela de permissão.
Dados a serem compartilhados. Use uma linguagem clara e concisa para informar ao usuário quais dados dele o Google exige e por quê.
Call-to-action clara. Declare uma call-to-action clara na tela de consentimento, como "Concordar e vincular". Isso ocorre porque os usuários precisam entender quais dados são necessários para compartilhar com o Google para vincular as contas.
Capacidade de cancelar. Ofereça uma maneira para os usuários voltarem ou cancelarem, caso não queiram vincular.
Processo de login claro. Garanta que os usuários tenham um método claro para fazer login na Conta do Google, como campos para nome de usuário e senha ou "Fazer login com o Google".
Capacidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta na sua plataforma. Como alternativa, você pode incluir um link para a Conta do Google, em que os usuários podem gerenciar a conta vinculada.
Capacidade de mudar a conta de usuário. Sugira um método para os usuários trocarem as contas. Isso é especialmente útil se os usuários costumam ter várias contas.
- Se um usuário precisar fechar a tela de permissão para trocar de conta, envie um erro recuperável ao Google para que ele possa fazer login na conta selecionada com a vinculação do OAuth e o fluxo implícito.
Incluir seu logotipo. Mostre o logotipo da sua empresa na tela de permissão. Use as diretrizes de estilo para posicionar o logotipo. Se você quiser ou precisar mostrar o logotipo do Google, consulte Logotipos e marcas registradas.

Criar o projeto

Para criar seu projeto para usar a vinculação de contas:

Vá para o Console de APIs do Google.
Clique em Criar projeto.
Insira um nome ou aceite a sugestão gerada.
Confirme ou edite os campos restantes.
Clique em Criar.

Para conferir o ID do projeto:

Vá para o Console de APIs do Google.
Encontre seu projeto na tabela da página de destino. O ID do projeto aparece na ID coluna.

Configurar a tela de permissão OAuth

O processo de conexão de contas do Google inclui uma tela de permissão que informa aos usuários o aplicativo que está solicitando acesso aos dados deles, o tipo de dados que estão pedindo e os termos aplicáveis. Você precisa configurar a tela de permissão OAuth antes de gerar um ID do cliente da API Google.

Abra a página da tela de permissão OAuth do console de APIs do Google.
Se solicitado, selecione o projeto que você acabou de criar.
Na página "Tela de permissão 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 o aplicativo e ser consistente com o nome que os usuários veem em outros lugares. O nome do aplicativo será mostrado na tela de permissão de vinculação de contas.

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

E-mail de suporte:para que os usuários entrem em contato com você para esclarecer dúvidas sobre o consentimento deles.

Escopos para APIs Google:os escopos permitem que seu aplicativo acesse os dados do Google particulares do usuário. Para o caso de uso de vinculação de contas 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 antecipadamente. Saiba mais.

Domínios autorizados:para proteger você e seus usuários, o Google permite apenas que aplicativos autenticados 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 permissão de vinculação de contas do Google. Precisa ser hospedado em um domínio autorizado.

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

Figura 1. Tela de permissão de 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" para enviar o aplicativo. Consulte os requisitos de verificação do OAuth para mais detalhes.

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

处理授权请求

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

授权端点参数
`client_id`	您分配给 Google 的客户端 ID。
`redirect_uri`	您将对此请求的响应发送到的网址。
`state`	一种簿记值，在重定向 URI 中原封不动地传递回 Google。
`scope`	可选：一组以空格分隔的范围字符串，用于指定 Google 请求授权的数据。
`response_type`	要在响应中返回的值的类型。对于 OAuth 2.0 授权代码流程，响应类型始终为 `code`。
`user_locale`	采用 RFC5646 格式的 Google 账号语言设置，用于以用户的首选语言本地化您的内容。

例如，如果您的授权端点位于 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

如需让授权端点处理登录请求，请执行以下步骤：

验证 client_id 是否与您分配给 Google 的客户端 ID 一致，以及 redirect_uri 是否与 Google 为您的服务提供的重定向网址一致。这些检查对于防止向意外或配置错误的客户端应用授予访问权限非常重要。如果您支持多个 OAuth 2.0 流程，还需确认 response_type 是否为 code。
检查用户是否已登录您的服务。如果用户未登录，请完成服务的登录或注册流程。
生成一个授权代码，供 Google 用于访问您的 API。授权代码可以是任何字符串值，但必须唯一表示用户、令牌所针对的客户端和代码的过期时间，并且不得可猜测。您通常会签发大约 10 分钟后过期的授权码。

确认 redirect_uri 参数指定的网址具有以下格式：

  https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

将用户的浏览器重定向到 redirect_uri 参数指定的网址。通过附加 code 和 state 参数进行重定向时，请添加您刚刚生成的授权代码和原始的未修改状态值。以下是生成的网址示例：
```
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`，则此参数是 Google 从您的登录或令牌交换端点收到的代码。
`redirect_uri`	如果值为 `grant_type=authorization_code`，则此参数是初始授权请求中使用的网址。
`refresh_token`	如果值为 `grant_type=refresh_token`，则此参数是 Google 从您的令牌交换端点收到的刷新令牌。

将授权代码交换为访问令牌和刷新令牌

用户登录后，您的授权端点会向 Google 返回一个时效很短的授权代码，然后 Google 会向您的令牌交换端点发送请求，以将该授权代码换成访问令牌和刷新令牌。

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

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

如需使用授权代码换取访问令牌和刷新令牌，令牌交换端点会通过执行以下步骤来响应 POST 请求：

验证 client_id 是否将请求来源标识为授权来源，以及 client_secret 是否与预期值匹配。
验证授权代码是否有效且未过期，以及请求中指定的客户端 ID 是否与授权代码关联的客户端 ID 相符。
确认 redirect_uri 参数指定的网址与初始授权请求中使用的值完全相同。
如果您无法验证上述所有条件，请返回 HTTP 400 Bad Request 错误，并将 {"error": "invalid_grant"} 作为正文。
否则，使用授权代码中的用户 ID 生成刷新令牌和访问令牌。这些令牌可以是任何字符串值，但必须唯一表示用户和令牌所针对的客户端，并且不得可猜测。对于访问令牌，还要记录令牌的过期时间，该时间通常是在您发放令牌后一小时。刷新令牌不会过期。

在 HTTPS 响应的正文中返回以下 JSON 对象：

{
"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 的值为您之前授予 Google 的刷新令牌的值。以下是将刷新令牌换成访问令牌的请求示例：

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 请求：

验证 client_id 是否将请求源标识为 Google，以及 client_secret 是否与预期值一致。
验证刷新令牌是否有效，以及请求中指定的客户端 ID 是否与刷新令牌关联的客户端 ID 相符。
如果您无法验证上述所有条件，请返回 HTTP 400 Bad Request 错误，并将 {"error": "invalid_grant"} 作为正文。
否则，请使用刷新令牌中的用户 ID 生成访问令牌。这些令牌可以是任何字符串值，但必须唯一表示用户和令牌所针对的客户端，并且不得可猜测。对于访问令牌，还要记录令牌的过期时间，通常是在您发放令牌后一小时。

在 HTTPS 响应的正文中返回以下 JSON 对象：

{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

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

Use a ferramenta OAuth 2.0 Playground para validar sua implementação.

Na ferramenta, siga estas etapas:

Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
No campo Fluxo do OAuth, selecione Do lado do cliente.
No campo Endpoints OAuth, selecione Personalizado.
Especifique seu endpoint OAuth 2.0 e o ID do cliente atribuído ao Google nos campos correspondentes.
Na seção Etapa 1, não selecione nenhum escopo do Google. Em vez disso, deixe esse campo em branco ou digite um escopo válido para seu servidor (ou uma string arbitrária se você não usar escopos do OAuth). Quando terminar, clique em Autorizar APIs.
Nas seções Etapa 2 e Etapa 3, siga o fluxo do OAuth 2.0 e verifique se cada etapa funciona como esperado.

Você pode validar sua implementação usando a ferramenta Demonstração da Vinculação da Conta do Google.