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.

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.

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.

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.

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 o 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 receber o 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 para chamar essas APIs em nome deles.

Vinculação de Conta do Google: fluxo de código de autorização 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.

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). No GAL, o Google atua como o OAuth cliente, enquanto seu serviço atua como o provedor de identidade/serviço.

Uma sessão de fluxo de 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 tiver sido iniciado 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, e concede ao Google permissão para acessar os dados 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 fazer 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 o endpoint de troca de tokens, 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.

Processar solicitações de autorização

Quando você precisa realizar a vinculação de contas usando o fluxo de código de autorização 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:

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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

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

1. Verifique se o client_id corresponde ao ID do cliente que você atribuiu ao Google e se o redirect_uri corresponde ao URL de redirecionamento fornecido pelo Google para seu serviço. Essas verificações são importantes para evitar a concessão de acesso a apps clientes não intencionais ou mal configurados. Se você oferece suporte a vários fluxos do OAuth 2.0, também confirme se o response_type é code.
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 código de autorização para o Google usar para acessar sua API. O código de autorização pode ser qualquer valor de string, mas precisa representar de maneira exclusiva o usuário, o cliente para o qual o token é destinado e o tempo de expiração do código, e não pode ser adivinhável. Normalmente, você emite códigos de autorização que expiram após aproximadamente 10 minutos.
4. 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
     

5. Redirecione o navegador do usuário para o URL especificado pelo redirect_uri parâmetro. Inclua o código de autorização que você acabou de gerar e o valor de estado original e não modificado ao redirecionar, anexando os parâmetros code e state. Confira abaixo um exemplo do URL resultante:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Processar solicitações de troca de tokens

O endpoint de troca de tokens do seu serviço é responsável por dois tipos de trocas de tokens:

• Trocar códigos de autorização por tokens de acesso e tokens de atualização
• Trocar tokens de atualização por tokens de acesso

As solicitações de troca de tokens incluem os seguintes parâmetros:

Trocar códigos de autorização por tokens de acesso e tokens de atualização

Depois que o usuário faz login e o endpoint de autorização retorna um código de autorização de curta duração para o Google, o Google envia uma solicitação ao endpoint de troca de tokens para trocar o código de autorização por um token de acesso e um token de atualização.

Para essas solicitações, o valor de grant_type é authorization_code, e o valor de code é o valor do código de autorização que você concedeu anteriormente ao Google. Confira abaixo um exemplo de solicitação para trocar um código de autorização por um token de acesso e um token de atualização:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Para trocar códigos de autorização por um token de acesso e um token de atualização, o endpoint de troca de tokens responde a solicitações POST executando as seguintes etapas:

1. Verifique se o client_id identifica a origem da solicitação como uma origem autorizada e se o client_secret corresponde ao valor esperado.
2. Verifique se o código de autorização é válido e não expirou e se o ID do cliente especificado na solicitação corresponde ao ID do cliente associado ao código de autorização.
3. Confirme se o URL especificado pelo parâmetro redirect_uri é idêntico ao valor usado na solicitação de autorização inicial.
4. Se você não conseguir verificar todos os critérios anteriores, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como corpo.
5. Caso contrário, use o ID do usuário do código de autorização para gerar um token de atualização e um token de acesso. Esses tokens podem ser qualquer valor de string, mas precisam representar de maneira exclusiva o usuário e o cliente para o qual o token é destinado, e não podem ser adivinháveis. Para tokens de acesso, também registre o tempo de expiração do token, que normalmente é uma hora após a emissão do token. Os tokens de atualização não expiram.
6. Retorne o seguinte objeto JSON no corpo da resposta HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

O Google armazena o token de acesso e o token de atualização do usuário e registra a expiração do token de acesso. Quando o token de acesso expira, o Google usa o token de atualização para receber um novo token de acesso do endpoint de troca de tokens.

Trocar tokens de atualização por tokens de acesso

Quando um token de acesso expira, o Google envia uma solicitação ao endpoint de troca de tokens para trocar um token de atualização por um novo token de acesso.

Para essas solicitações, o valor de grant_type é refresh_token, e o valor de refresh_token é o valor do token de atualização que você concedeu anteriormente ao Google. Confira abaixo um exemplo de solicitação para trocar um token de atualização por um token de acesso:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Para trocar um token de atualização por um token de acesso, o endpoint de troca de tokens responde a solicitações POST executando as seguintes etapas:

1. Verifique se o client_id identifica a origem da solicitação como o Google e se o client_secret corresponde ao valor esperado.
2. Verifique se o token de atualização é válido e se o ID do cliente especificado na solicitação corresponde ao ID do cliente associado ao token de atualização.
3. Se você não conseguir verificar todos os critérios anteriores, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como corpo.
4. Caso contrário, use o ID do usuário do token de atualização para gerar um token de acesso. Esses tokens podem ser qualquer valor de string, mas precisam representar de maneira exclusiva o usuário e o cliente para o qual o token é destinado, e não podem ser adivinháveis. Para tokens de acesso, também registre o tempo de expiração do token, normalmente uma hora após a emissão do token.
5. Retorne o seguinte objeto JSON no corpo da resposta HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

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.