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:

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

Para conferir o ID do projeto:

1. Vá para o Console de APIs do Google.
2. 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.

1. Abra a página da tela de permissão OAuth do console de APIs do Google.
2. Se solicitado, selecione o projeto que você acabou de criar.

3. 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

4. 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.

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.

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

1. 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.

2. 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.

3. 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.

4. 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.

1. 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"}.

2. 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.

1. 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"}.

2. 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).

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

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

For your userinfo endpoint to handle requests, do the following steps:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

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

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   userinfo endpoint response
   sub	A unique ID that identifies the user in your system.
   email	Email address of the user.
   given_name	Optional: First name of the user.
   family_name	Optional: Last name of the user.
   name	Optional: Full name of the user.
   picture	Optional: Profile picture of the user.

Como validar a implementação

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.