Vinculação da Conta do Google com o OAuth

As contas são vinculadas usando o fluxo padrão do setor de código de autorização do OAuth 2.0.

OAuth 2.1 e PKCE para agentes

Para agentes de IA sem estado e pipelines multimodais, é recomendável usar a aplicação do OAuth 2.1.

PKCE (chave de prova para troca de código): precisa ser usado para proteger o fluxo do código de autorização, evitando ataques de interceptação.
Sem fluxo implícito: o fluxo implícito expõe tokens de acesso no URL, o que é um risco de segurança para ambientes de agentes.

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

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 seu servidor OAuth

Uma implementação de servidor OAuth 2.0 do fluxo de código de autorização consiste em dois endpoints, que seu serviço disponibiliza por HTTPS. O primeiro endpoint é o de autorização, responsável por encontrar ou obter consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma interface de login para usuários que ainda não fizeram login e registra o consentimento para o acesso solicitado. O segundo endpoint é o de troca de tokens, usado para receber strings criptografadas, chamadas de tokens, que autorizam um usuário a acessar seu serviço.

Quando um aplicativo do Google precisa chamar uma das APIs do seu serviço, o Google usa esses endpoints juntos para receber permissão dos usuários e chamar essas APIs em nome deles.

Vinculação de contas do Google: fluxo do código de autorização OAuth

O diagrama de sequência a seguir detalha as interações entre o usuário, o Google e os endpoints do seu serviço.

Figura 1. A sequência de eventos no fluxo do código de autorização do OAuth 2.0 para a vinculação de Contas do Google.

Funções e responsabilidades

A tabela a seguir define as funções e responsabilidades dos atores no fluxo do OAuth de vinculação de contas do Google (GAL, na sigla em inglês). Observação: no GAL, o Google atua como o cliente do OAuth, enquanto seu serviço atua como o provedor de identidade/serviço.

Ator / componente	Função na GAL	Responsabilidades
App / servidor do Google	Cliente OAuth	Inicia o fluxo, recebe o código de autorização, troca por tokens e os armazena com segurança para acessar as APIs do seu serviço.
Seu endpoint de autorização	Servidor de autorização	Autentica seus usuários e obtém o consentimento deles para compartilhar o acesso aos dados com o Google.
Seu endpoint de troca de token	Servidor de autorização	Valida códigos de autorização e tokens de atualização e emite tokens de acesso para o servidor do Google.
URI de redirecionamento do Google	Endpoint de callback	Recebe o redirecionamento do usuário do seu serviço de autorização com os valores `code` e `state`.

Uma sessão de fluxo do código de autorização do OAuth 2.0 iniciada pelo Google tem o seguinte fluxo:

O Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo começar em um dispositivo somente de voz para uma ação, o Google vai transferir a execução para um smartphone.
O usuário faz login, se ainda não tiver feito isso, e concede ao Google permissão para acessar os dados dele com sua API, se ainda não tiver concedido permissão.
Seu serviço cria um código de autorização e o retorna ao Google. Para isso, redirecione o navegador do usuário de volta ao Google com o código de autorização anexado à solicitação.
O Google envia o código de autorização para seu endpoint de troca de token, que verifica a autenticidade do código e retorna um token de acesso e um token de atualização. O token de acesso é um token de curta duração que seu serviço aceita como credenciais para acessar APIs. O token de atualização é um token de longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando eles expiram.
Depois que o usuário concluir o fluxo de vinculação de contas, cada solicitação subsequente enviada pelo Google vai conter um token de acesso.

Receita de implementação

Siga estas etapas para implementar o fluxo do código de autorização.

Etapa 1: processar solicitações de autorização

Quando o Google inicia a vinculação de contas, ele redireciona o usuário para seu endpoint de autorização. Para ver contratos de protocolo detalhados e requisitos de parâmetros, consulte o endpoint de autorização.

Para processar a solicitação, faça o seguinte:

Valide a solicitação:
- Confirme se o client_id corresponde ao ID do cliente atribuído ao Google.
- Confirme se o redirect_uri corresponde ao URL de redirecionamento do Google esperado: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- Verifique se response_type é code.
Autentique o usuário:
- Verifique se o usuário fez login no seu serviço.
- Se o usuário não estiver conectado, peça que ele conclua o fluxo de login ou inscrição.
Gerar código de autorização:
- Crie um código de autorização exclusivo e não adivinhável associado ao usuário e ao cliente.
- Defina a expiração do código em aproximadamente 10 minutos.
Redirecionar de volta para o Google:
- Redirecione o navegador para o URL fornecido em redirect_uri.
- Anexe os seguintes parâmetros de consulta:
  - code: o código de autorização gerado.
  - state: o valor de estado não modificado recebido do Google.

Etapa 2: processar solicitações de troca de token

O endpoint de troca de tokens processa dois tipos de solicitações: troca de códigos por tokens e atualização de tokens de acesso expirados. Para ver contratos de protocolo detalhados e requisitos de parâmetros, consulte o endpoint de troca de tokens.

A. Trocar códigos de autorização por tokens

Quando o Google recebe o código de autorização, ele chama seu endpoint de troca de token (POST) para recuperar tokens.

Valide a solicitação:
- Verifique client_id e client_secret.
- Verifique se o código de autorização é válido e não expirou.
- Confirme se redirect_uri corresponde ao valor usado na Etapa 1.
- Se a validação falhar, retorne um HTTP 400 Bad Request com {"error": "invalid_grant"}.
Tokens de problema:
- Gere um refresh_token de longa duração e um access_token de curta duração (normalmente 1 hora).
- Retorne um HTTP 200 OK com a resposta padrão do token JSON.

B. Atualizar tokens de acesso

Quando o token de acesso expira, o Google solicita um novo usando o token de atualização.

Valide a solicitação:
- Verifique client_id, client_secret e refresh_token.
- Se a validação falhar, retorne um HTTP 400 Bad Request com {"error": "invalid_grant"}.
Emitir um novo token de acesso:
- Gere um novo access_token de curta duração.
- Retorne um HTTP 200 OK com a resposta do token JSON (opcionalmente incluindo um novo token de atualização).

处理 userinfo 请求

userinfo 端点是受 OAuth 2.0 保护的资源，会返回关联用户的声明。实现和托管 userinfo 端点是可选的，但以下用例除外：

使用 Google One Tap 登录关联的账号。
Android TV 提供顺畅的订阅体验。

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

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

例如，如果您的 userinfo 端点可通过 https://myservice.example.com/userinfo 时，请求可能如下所示：

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

为了让 userinfo 端点能够处理请求，请执行以下步骤：

从 Authorization 标头中提取访问令牌，并返回与访问令牌相关联的用户的信息。
如果访问令牌无效，则使用 WWW-Authenticate 响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例：
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应，该错误将无法恢复，检索到的令牌将被舍弃，并且用户必须重新开始关联流程。

如果访问令牌有效，则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应回答：

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

如果您的 userinfo 端点返回 HTTP 200 成功响应，则系统会针对用户的 Google 账号注册检索到的令牌和声明。

userinfo 端点响应
`sub`	系统中用于识别用户的唯一 ID。
`email`	用户的电子邮件地址。
`given_name`	可选：用户的名字。
`family_name`	可选：用户的姓氏。
`name`	可选：用户的全名。
`picture`	可选：用户的个人资料照片。

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.