Vinculação de conta do Google com OAuth

As contas são vinculadas usando fluxos de código de autorização e implícito OAuth 2.0 padrão da indústria. Seu serviço deve suportar autorização compatível com OAuth 2.0 e endpoints de troca de token .

No fluxo implícito , o Google abre seu endpoint de autorização no navegador do usuário. Após o login bem-sucedido, você retorna um token de acesso de longa duração ao Google. Este token de acesso agora está incluído em todas as solicitações enviadas do Google.

No fluxo do código de autorização , você precisa de dois endpoints:

  • O endpoint de autorização , que apresenta a IU de login para seus usuários que ainda não estão conectados. 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 ponto de extremidade 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 token de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação de contas.
    2. Troca um token de atualização de longa duração por um token de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque aquele que havia expirado.

Escolha um fluxo 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 sua 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 do código de autorização .

Diretrizes de design

Esta seção descreve os requisitos de design e recomendações para a tela do usuário que você hospeda para fluxos de vinculação OAuth. Depois de ser chamada pelo aplicativo do Google, sua plataforma exibe um login na página do Google e uma tela de consentimento de vinculação de conta para o usuário. O usuário é direcionado de volta ao aplicativo do Google após dar seu consentimento para vincular contas.

Esta figura mostra as etapas para um usuário vincular sua conta do Google ao seu sistema de autenticação. A primeira captura de tela mostra links iniciados pelo usuário em sua plataforma. A segunda imagem mostra o login do usuário no Google, enquanto a terceira mostra o consentimento e a confirmação do usuário para vincular sua conta do Google ao seu aplicativo. A captura de tela final mostra uma conta de usuário vinculada com sucesso no Google app.
Figura 1. Conta que vincula o login do usuário ao Google e as telas de consentimento.

Requisitos

  1. Você deve comunicar que a conta do usuário será vinculada ao Google, não a um produto específico do Google, como o Google Home ou o Google Assistente.

Recomendações

Recomendamos que você faça o seguinte:

  1. Exibir a política de privacidade do Google. Inclua 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 do Google exige e por quê.

  3. Apelo à ação claro. Defina uma frase de chamariz clara em sua tela de consentimento, como “Concordar e vincular”. Isso ocorre porque os usuários precisam entender quais dados são obrigados a compartilhar com o Google para vincular suas contas.

  4. Capacidade de cancelar. Fornece uma maneira para os usuários voltarem ou cancelarem, caso optem por não vincular.

  5. Processo de login claro. Certifique-se de que os usuários tenham um método claro para fazer login em suas contas do Google, como campos para seu nome de usuário e senha ou Login com o Google .

  6. Capacidade de desvincular. Oferece um mecanismo para os usuários se desvincularem, como um URL para as configurações de sua conta em sua plataforma. Como alternativa, você pode incluir um link para a Conta do Google, onde os usuários podem gerenciar suas contas vinculadas.

  7. Capacidade de alterar a conta do usuário. Sugira um método para os usuários mudarem 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 trocar de conta, envie um erro recuperável ao Google para que o usuário possa fazer login na conta desejada com o link OAuth e o fluxo implícito .
  8. Inclua seu logotipo. Exiba o logotipo de sua empresa na tela de consentimento. Use suas diretrizes de estilo para colocar seu logotipo. Se você deseja exibir também o logotipo do Google, consulte Logotipos e marcas registradas .

Crie o projeto

Para criar seu projeto para usar 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 .

O processo de vinculação de contas do Google inclui uma tela de consentimento que informa aos usuários o aplicativo que está solicitando acesso aos seus dados, que tipo de dados eles estão solicitando e os termos que se aplicam. Você precisará configurar sua tela de consentimento OAuth antes de gerar um ID de cliente da API do Google.

  1. Abra a página da tela de consentimento OAuth do console de APIs do Google.
  2. Se 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 consentimento. O nome deve refletir com precisão o seu aplicativo e ser consistente com o nome do aplicativo que os usuários veem em outros lugares. O nome do aplicativo será mostrado na tela de consentimento de vinculação de conta.

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

    Email de suporte: para que os usuários entrem em contato com você com perguntas sobre seu consentimento.

    Escopos para APIs do Google: os escopos permitem que seu aplicativo acesse os dados privados do Google de seu usuário. Para o caso de uso de vinculação de contas do Google, o escopo padrão (e-mail, perfil, openid) é suficiente, você não precisa adicionar nenhum escopo confidencial. Geralmente, é uma prática recomendada solicitar escopos de forma incremental, no momento em que o acesso é necessário, em vez de no início. Aprenda mais .

    Domínios autorizados: para proteger você e seus usuários, o Google só permite que aplicativos que se autenticam usando OAuth usem Domínios autorizados. Os links de seus aplicativos devem ser hospedados em Domínios autorizados. Saiba mais .

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

    Link da política de privacidade do aplicativo: mostrado na tela de consentimento de vinculação de contas do Google. Deve ser hospedado em um domínio autorizado.

    Link dos termos de serviço do aplicativo (opcional): deve ser hospedado em um domínio autorizado.

    Figura 1 . Tela de consentimento para vinculação de contas do Google para um aplicativo fictício, Tunery

  4. Marque "Status de verificação", se sua inscrição precisar de verificação, clique no botão "Enviar para verificação" para enviar sua inscrição para verificação. Consulte os requisitos de verificação do OAuth para obter detalhes.

Implementar seu servidor OAuth

Para oferecer suporte ao fluxo implícito OAuth 2.0, seu serviço disponibiliza um endpoint de autorização por HTTPS. Este endpoint é responsável pela autenticação e obtenção do consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma IU de login para seus usuários que ainda não estão conectados 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 obter permissão dos usuários para chamar essas APIs em seu nome.

Uma sessão típica de fluxo implícito OAuth 2.0 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 seus dados com sua API, se ainda não tiver concedido permissão.
  2. Seu serviço cria um token de acesso e o devolve 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 suas APIs de 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, em seguida, conclui a chamada da API.

Lidar com solicitações de autorização

Quando um aplicativo do Google precisa realizar a vinculação de contas por meio de um fluxo implícito OAuth 2.0, o Google envia o usuário ao seu endpoint de autorização com uma solicitação que inclui 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 a esta solicitação.
state Um valor contábil que é passado 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 formato RFC5646 usado para localizar seu conteúdo no idioma de preferência do usuário.

Por exemplo, se o seu endpoint de autorização estiver disponível em https://myservice.example.com/auth , uma solicitação pode ter a seguinte 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 seu endpoint de autorização processe solicitações de login, execute as seguintes etapas:

  1. Verifique os valores client_id e redirect_uri para evitar a concessão de acesso a aplicativos cliente não intencionais ou configurados incorretamente:

    • 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 está conectado ao seu serviço. Se o usuário não estiver conectado, 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 deve representar exclusivamente o usuário e o cliente ao qual o token se destina e não pode ser adivinhado.

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

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

    A seguir está 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 manipulador de redirecionamento OAuth 2.0 do Google recebe o token de acesso e confirma que o valor do state não mudou. Depois que o Google obtém um token de acesso para o seu serviço, ele anexa o token às chamadas subsequentes para as APIs do seu serviço.

Validando sua implementação

Você pode validar a sua implementação, utilizando o Parque OAuth 2.0 ferramenta.

Na ferramenta, execute as seguintes etapas:

  1. Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
  2. No campo de fluxo OAuth, selecione do lado do cliente.
  3. No campo OAuth Endpoints, selecione Personalizado.
  4. Especifique seu ponto de extremidade OAuth 2.0 e o ID do cliente que você atribuiu ao Google nos campos correspondentes.
  5. Na secção Passo 1, não selecione quaisquer âmbitos do Google. Em vez disso, deixe este campo em branco ou digite um escopo válido para o seu servidor (ou uma string arbitrária se você não usar escopos OAuth). Quando estiver pronto, clique em Autorizar APIs.
  6. Nas secções Passo 2 e Passo 3, ir por meio do fluxo OAuth 2.0 e verificar que cada passo funciona como pretendido.

Você pode validar sua implementação usando a Conta do Google Linking Demonstração ferramenta.

Na ferramenta, execute as seguintes etapas:

  1. Clique no sinal-in com o botão Google.
  2. Escolha a conta que deseja vincular.
  3. Digite o ID do serviço.
  4. Opcionalmente, insira um ou mais escopos para os quais você solicitará acesso.
  5. Clique em Iniciar demonstração.
  6. Quando solicitado, confirme se você pode consentir e negar a solicitação de vinculação.
  7. Confirme que você foi redirecionado para sua plataforma.