Vinculação da Conta do Google com o OAuth

As contas são vinculadas usando os fluxos implícitos e de código de autorização do OAuth 2.0 padrão do setor. Seu serviço precisa oferecer suporte a endpoints de autorização e troca de token compatíveis com o OAuth 2.0.

No fluxo implícito, o Google abre o endpoint de autorização no navegador do usuário. Após o login, você retorna um token de acesso de longa duração para o Google. Agora, esse token de acesso 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 para o acesso solicitado.

• O endpoint de troca de token, que é 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 de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação de conta.
  2. Troca um token de atualização de longa duração por um de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque o anterior 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 pelo fluxo implícito nunca expirem. Isso ocorre porque o usuário é forçado a vincular a conta novamente depois que um token expira com o fluxo implícito. Se você precisar da expiração do token por motivos de segurança, é altamente recomendável usar o fluxo de código de autorização.

Observação: use os botões a seguir para escolher o fluxo do OAuth 2.0 que você quer implementar. Se necessário, o conteúdo deste guia será atualizado para se adaptar à sua escolha.

Fluxo implícito Código de autorização

Diretrizes de design

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

Figura 1. Telas de login do usuário e de vinculação de contas ao Google.

Requisitos

1. É necessário informar que a conta do usuário será vinculada ao Google, não a um produto específico, como o Google Home ou o Google Assistente.

Recomendações

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

1. Exibir a Política de Privacidade do Google. Incluir um link para a Política de Privacidade do Google na tela de consentimento.

2. Dados a serem compartilhados. Use uma linguagem clara e concisa para informar ao usuário quais dados o Google exige e por quê.

3. Call-to-action clara. Informe uma call-to-action clara na tela de consentimento, como "Concordar e vincular". Isso é necessário porque os usuários precisam entender quais dados eles precisam compartilhar com o Google para vincular as contas.

4. Possibilidade de cancelamento. Ofereça uma maneira de voltar ou cancelar, se o usuário não quiser fazer a vinculação.

5. Processo de login claro. Os usuários precisam ter 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.

6. Possibilidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta deles na sua plataforma. Como alternativa, é possível incluir um link para a Conta do Google, onde os usuários podem gerenciar a conta vinculada.

7. Capacidade de mudar a conta do usuário. Sugira um método para os usuários trocarem de conta. Isso é especialmente benéfico se os usuários tendem a ter várias contas.

   • Se um usuário precisar fechar a tela de consentimento para alternar contas, envie um erro recuperável para o Google para que o usuário possa fazer login na conta desejada com a vinculação OAuth e o fluxo implícito.

8. Inclua seu logotipo. Mostre o logotipo da sua empresa na tela de consentimento. Use as diretrizes de estilo para posicionar o logotipo. Se você quiser mostrar também o logotipo do Google, consulte Logos e marcas registradas.

Figura 2. Diretrizes de design para fazer login do usuário no Google e telas de consentimento.

Criar o projeto

Observação: é possível reutilizar um projeto existente e não é necessário criar um novo projeto principalmente para vincular contas.

Para criar um projeto que use a vinculação de contas:

1. Go to the Google API Console.
2. Clique em Criar projeto .
3. Digite um nome ou aceite a sugestão gerada.
4. Confirme ou edite os campos restantes.
5. Clique em Create .

Para visualizar o seu ID do projeto:

1. Go to the Google API Console.
2. Encontre seu projeto na tabela na página de destino. O ID do projeto aparece na coluna ID .

Configurar a tela de consentimento do OAuth

O processo de vinculação da Conta do Google inclui uma tela de consentimento que informa aos usuários o aplicativo que está solicitando acesso aos dados deles, o tipo de dados solicitado e os termos aplicáveis. Você vai precisar configurar sua tela de consentimento do OAuth antes de gerar um ID do cliente da API do Google.

1. Abra a página Tela de consentimento do OAuth do console de APIs do Google.
2. Se for solicitado, selecione o projeto que você acabou de criar.

3. Na página "Tela de consentimento do OAuth", preencha o formulário e clique no botão "Salvar".

   Nome do aplicativo:o nome do aplicativo que solicita o consentimento. O nome deve refletir com precisão seu aplicativo e ser consistente com o nome do aplicativo que os usuários veem em outros lugares. O nome do aplicativo vai aparecer na tela de consentimento da vinculação de conta.

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

   E-mail de suporte:para os usuários entrarem em contato com você com perguntas sobre o consentimento.

   Escopos das APIs do Google:permitem que seu aplicativo acesse os dados particulares do Google dos usuários. Para o caso 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 fazer isso de antemão. Saiba mais.

   Domínios autorizados:para proteger você e seus usuários, o Google só permite o uso de domínios autorizados por aplicativos autenticados com o OAuth. Os links dos seus aplicativos precisam ser hospedados em domínios autorizados. Saiba mais.

   Link da página inicial do aplicativo:a página inicial do seu aplicativo. Precisa ser hospedado em um domínio autorizado.

   Link da Política de Privacidade do app:aparece na tela de consentimento da vinculação da Conta do Google. Precisa estar 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 consentimento para vinculação da Conta do Google de um app fictício, Tunery

4. Marque o "Status de verificação" se a inscrição precisar ser verificada, em seguida, clique no botão "Enviar para verificação". Consulte os requisitos de verificação do OAuth para mais detalhes.

Implementar seu servidor OAuth

Para oferecer suporte ao fluxo implícito do OAuth 2.0, seu serviço faz uma autorização de destino disponível por HTTPS. Esse endpoint é responsável pela autenticação e obter consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma interface de login aos usuários que ainda não estão conectados e registra consentir com o acesso solicitado.

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

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. A o usuário faz login, caso ainda não tenha feito, e concede ao Google permissão para acessar os dados com a API, caso ainda não tenham concedido permissão.
2. Seu serviço cria um token de acesso e o retorna para Google. Para fazer isso, redirecione o navegador do usuário de volta para o Google com o acesso token anexado à solicitação.
3. O Google chama as APIs do seu serviço e anexa o token de acesso com cada solicitação. O serviço verifica se o token de acesso concede ao Google autorização para acessar a API e, em seguida, conclui a chamada de API.

Processar solicitações de autorização

Quando um aplicativo do Google precisa vincular uma conta usando um OAuth 2.0. fluxo implícito, o Google envia o usuário para seu endpoint de autorização com um que inclua os seguintes parâmetros:

Parâmetros de 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 para essa solicitação.
state	Um valor de contabilidade que é retornado ao Google inalterado na URI de redirecionamento.
response_type	O tipo de valor a ser retornado na resposta. Para a implementação implícita do OAuth 2.0 fluxo, o tipo de resposta será sempre token.
user_locale	A configuração de idioma da Conta do Google no RFC5646 formato usado para localizar seu conteúdo no idioma de preferência do usuário.

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação terá esta aparência:

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, faça o seguinte: etapas:

1. Verifique os valores client_id e redirect_uri para impedir a concessão de acesso a apps clientes não intencionais ou configurados incorretamente:

   • Confirme se o client_id corresponde ao ID do cliente que você atribuídas ao Google.
   • Confirme se o URL especificado pelo 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 está conectado ao seu serviço. Se o usuário não tiver feito login conclua o fluxo de login ou inscrição do serviço.

3. Gere um token de acesso para o Google acessar sua API. A token de acesso pode ser qualquer valor de string, mas deve representar exclusivamente o usuário e o cliente a que o token se destina e não pode ser adivinhado.

4. Envia uma resposta HTTP que redireciona o navegador do usuário para o URL especificado pelo parâmetro redirect_uri. Inclua todos os elementos parâmetros a seguir no fragmento de 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 do original. solicitação

   Veja a seguir um exemplo de URL resultante:

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

O gerenciador de redirecionamento do OAuth 2.0 do Google recebe o token de acesso e confirma que o valor state não mudou. Depois que o Google tiver token de acesso do seu serviço, o Google o anexa às chamadas subsequentes às APIs de serviç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.

userinfo endpoint request headers
Authorization header	The access token of type Bearer.

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

É possível validar sua implementação usando a ferramenta OAuth 2.0 Playground.

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 Lado do cliente.
3. No campo Endpoints OAuth, selecione Personalizado.
4. Especifique o 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 OAuth 2.0 e verifique se cada etapa funciona conforme o esperado.

É possível validar sua implementação usando a ferramenta Demo de vinculação de Contas 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. Opcionalmente, 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 a plataforma.