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.

Create the project

To create your project to use account linking:

1. Go to the Google API Console.
2. Click Create project.
3. Enter a name or accept the generated suggestion.
4. Confirm or edit any remaining fields.
5. Click Create.

To view your project ID:

1. Go to the Google API Console.
2. Find your project in the table on the landing page. The project ID appears in the ID column.

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

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

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.

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:

1. Extrair o token de acesso do cabeçalho "Autorização" e retornar as informações do usuário associado ao token de acesso.
2. 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.

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

1. Clique em Configuração settings para abrir a janela de configuração do OAuth 2.0.
2. No campo Fluxo do OAuth, selecione Do lado do cliente.
3. No campo Endpoints OAuth, selecione Personalizado.
4. Especifique seu endpoint OAuth 2.0 e o ID do cliente atribuído ao Google nos campos correspondentes.
5. 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.
6. 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.

Na ferramenta, siga estas etapas:

1. Clique no botão Fazer login com o Google.
2. Escolha a conta que você quer vincular.
3. Insira o ID do serviço.
4. Se quiser, insira um ou mais escopos para os quais você vai solicitar acesso.
5. Clique em Iniciar demonstração.
6. Quando solicitado, confirme que você pode consentir e negar o pedido de vinculação.
7. Confirme se você foi redirecionado para sua plataforma.