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.

Atenção: o fluxo implícito indisponível para fluxos orientados por MCP, UCP e agentes. Ele geralmente não é recomendado para todas as novas integrações. Use o fluxo do código de autorização.

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

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

Note: Use the following buttons to choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide will reload to match your choice.

Implicit flow Authorization code

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Figure 1. Account linking user sign in to Google and consent screens.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.

6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

Figure 2. Design guidelines for user sign in to Google and consent screens.

Create the project

Note: You can reuse an existing project and do not need to create a new project primarily for account linking.

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

n

Perigo: o fluxo implícito indisponível para fluxos orientados por MCP, UCP e agentes. Ele geralmente é desaconselhado para todas as novas integrações devido a considerações de segurança. Use o fluxo do código de autorização em vez disso.

Para oferecer suporte ao fluxo implícito do OAuth 2.0, seu serviço disponibiliza um endpoint de autorização por HTTPS. Esse endpoint é responsável pela autenticação e pela obtenção do 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.

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

Vinculação da Conta do Google: fluxo implícito do 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 implícito do OAuth 2.0 para vinculação da Conta do Google.

Funções e responsabilidades

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

Ator / componente	Função do GAL	Responsabilidades
App / servidor do Google	Cliente OAuth	Inicia o fluxo, recebe o token de acesso usando um redirecionamento do navegador, e o armazena com segurança para acessar as APIs do seu serviço.
Endpoint de autorização	Servidor de autorização	Autentica os usuários, recebe o consentimento deles e emite tokens de acesso de longa duração diretamente para o Google.
URI de redirecionamento do Google	Endpoint de retorno de chamada	Recebe o redirecionamento do usuário do seu serviço de autorização com os access_token e state valores no fragmento de URL.

Uma sessão de fluxo implícito do OAuth 2.0 típica iniciada pelo Google tem o seguinte fluxo:

1. O Google abre seu endpoint de autorização no navegador do usuário. O usuário faz login, se ainda não tiver feito, e concede ao Google permissão para acessar os dados dele com sua API, se ainda não tiver concedido permissão.
2. Seu serviço cria um token de acesso e o retorna ao Google. Para fazer isso, redirecione o navegador do usuário de volta ao Google com o token de acesso anexado à solicitação.
3. O Google chama as APIs do seu serviço e anexa o token de acesso a cada solicitação. Seu serviço verifica se o token de acesso concede autorização ao Google para acessar a API e conclui a chamada de API.

Processar solicitações de autorização

Quando um aplicativo do Google precisa realizar a vinculação de contas usando um fluxo implícito do OAuth 2.0, o Google envia o usuário para o endpoint de autorização com uma solicitação que inclui os seguintes parâmetros:

Parâmetros do endpoint de autorização
client_id	O ID do cliente que você atribuiu ao Google.
redirect_uri	O URL para o qual você envia a resposta a essa solicitação.
state	Um valor de monitoramento que é transmitido de volta ao Google inalterado no URI de redirecionamento.
response_type	O tipo de valor a ser retornado na resposta. Para o fluxo implícito do OAuth 2.0 o tipo de resposta é sempre token.
user_locale	A configuração de idioma da Conta do Google no RFC5646 usada para localizar seu conteúdo no idioma preferido do usuário.

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação poderá ser semelhante a esta:

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

Para que o endpoint de autorização processe solicitações de login, siga estas etapas:

1. Verifique os valores client_id e redirect_uri para evitar conceder acesso a apps cliente não intencionais ou mal configurados:

   • Confirme se o client_id corresponde ao ID do cliente que você atribuiu ao Google.
   • Confirme se o URL especificado pelo parâmetro redirect_uri tem o seguinte formato:

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

2. Verifique se o usuário fez login no seu serviço. Se o usuário não tiver feito login, conclua o fluxo de login ou inscrição do seu serviço.

3. Gere um token de acesso para o Google usar para acessar sua API. O token de acesso pode ser qualquer valor de string, mas precisa representar exclusivamente o usuário e o cliente para o qual o token é destinado e não pode ser adivinhado.

4. Envie uma resposta HTTP que redirecione o navegador do usuário para o URL especificado pelo redirect_uri parâmetro. Inclua todos os parâmetros a seguir no fragmento do URL:

   • access_token: o token de acesso que você acabou de gerar
   • token_type: a string bearer
   • state: o valor de estado não modificado da solicitação original

   Confira a seguir um exemplo do URL resultante:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

O handler de redirecionamento do OAuth 2.0 do Google recebe o token de acesso e confirma se o valor state não mudou. Depois que o Google tiver um token de acesso para seu serviço, ele vai anexar o token a chamadas subsequentes para as APIs do serviç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.

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:

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