Vinculação simplificada com OAuth e Fazer login com o Google

Visão geral

O Fazer login com o Google simplificado baseado em OAuth adiciona o Fazer login com o Google além da vinculação do OAuth. Isso oferece uma experiência de vinculação perfeita para os usuários do Google e também permite a criação de contas, o que permite que o usuário crie uma nova conta no seu serviço usando a Conta do Google.

Para vincular contas com o OAuth e o Fazer login com o Google, siga estas etapas gerais:

1. Primeiro, peça ao usuário para dar consentimento de acesso ao perfil do Google dele.
2. Use as informações no perfil para verificar se a conta de usuário existe.
3. Para usuários atuais, vincule as contas.
4. Se você não encontrar uma correspondência para o usuário do Google no seu sistema de autenticação, valide o token de ID recebido do Google. Em seguida, você pode criar um usuário com base nas informações do perfil contidas no token de ID.

Vinculação de contas no smartphone de um usuário com a vinculação simplificada

Figura 1. Vinculação de conta no smartphone de um usuário com a vinculação simplificada

Vinculação simplificada: fluxo do OAuth + Fazer login com o Google

O diagrama de sequência a seguir detalha as interações entre o usuário, o Google e seu endpoint de troca de tokens para vinculação simplificada.

Figura 2. A sequência de eventos no fluxo de vinculação simplificada.

Funções e responsabilidades

A tabela a seguir define as funções e responsabilidades dos participantes no fluxo de vinculação simplificada.

Ator / componente	Função na GAL	Responsabilidades
App / servidor do Google	Cliente OAuth	Obtém o consentimento do usuário para o recurso Fazer login com o Google, transmite declarações de identidade (JWT) ao seu servidor e armazena com segurança os tokens resultantes.
Seu endpoint de troca de token	Provedor de identidade / servidor de autorização	Valida declarações de identidade, verifica se há contas, processa os intents de vinculação de contas (check, get, create) e emite tokens com base nos intents solicitados.
Sua API de serviço	Servidor de recursos	Fornece acesso aos dados do usuário quando um token de acesso válido é apresentado.

Requisitos para a vinculação simplificada

• Implemente o fluxo de vinculação básica do OAuth. Seu serviço precisa oferecer suporte a endpoints de autorização e troca de tokens compatíveis com o OAuth 2.0.
• O endpoint de troca de token precisa oferecer suporte a declarações de JSON Web Token (JWT) e implementar as intents check, create e get.

Observação: essas intents precisam ser implementadas no mesmo endpoint de troca de tokens criado para o fluxo de vinculação OAuth básica. Não crie um endpoint diferente para processar essas intents.

• Registre seu ID do cliente da API do Google.

Lógica de decisão para vinculação simplificada

A lógica a seguir determina como as intents são chamadas durante o fluxo de vinculação simplificada:

1. O usuário tem uma conta no seu sistema de autenticação? (O usuário decide selecionando SIM ou NÃO)
   1. SIM : o usuário usa o e-mail associado à Conta do Google para fazer login na sua plataforma? (O usuário decide selecionando SIM ou NÃO)
      1. SIM : o usuário tem uma conta correspondente no seu sistema de autenticação? (check intent é chamado para confirmar)
         1. SIM : get intent é chamado e a conta é vinculada se a intent de recebimento for retornada com sucesso.
         2. NÃO : Criar conta? (O usuário decide selecionando SIM ou NÃO)
            1. SIM : create intent é chamado e a conta é vinculada se a intent de criação for retornada com sucesso.
            2. NÃO : o fluxo de vinculação do OAuth é acionado, o usuário é direcionado ao navegador e tem a opção de vincular com um e-mail diferente.
      2. NÃO : o fluxo de vinculação do OAuth é acionado, o usuário é direcionado ao navegador e tem a opção de vincular com um e-mail diferente.
   2. NÃO : o usuário tem uma conta correspondente no seu sistema de autenticação? (check intent é chamado para confirmar)
      1. SIM : get intent é chamado e a conta é vinculada se a intent de recebimento for retornada com sucesso.
      2. NÃO : create intent é chamado e a conta é vinculada se a intent de criação for retornada com sucesso.

Receita de implementação

Seu endpoint de troca de token precisa implementar as intents check, get e create para oferecer suporte à vinculação simplificada.

Siga estas etapas para processar as diferentes intents:

Verificar se já existe uma conta de usuário (finalidade de verificação)

O Google chama o endpoint de troca de tokens para verificar se o usuário do Google existe no seu sistema. Para detalhes dos parâmetros, consulte Finalidades de vinculação simplificada.

Receita de implementação

Para processar a finalidade check, faça o seguinte:

1. Validar a solicitação:

   • Verifique client_id, client_secret e grant_type (precisa ser urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Valide o assertion (JWT) usando os critérios em Validação de JWT.

2. Pesquisar usuário:

   • Verifique se o ID da Conta do Google (sub) ou o endereço de e-mail no JWT corresponde a um usuário no seu banco de dados.

3. Responder:

   • Se encontrado: retorne HTTP 200 OK com {"account_found": "true"}.
   • Se não encontrado: retorne HTTP 404 Not Found com {"account_found": "false"}.

Processar a vinculação automática (receber a intent)

Se a conta existir, o Google vai chamar seu endpoint com intent=get para recuperar tokens. Para detalhes dos parâmetros, consulte Intents de vinculação simplificada.

Receita de implementação

Para processar a intent get, faça o seguinte:

1. Validar a solicitação:

   • Verifique client_id, client_secret e grant_type.
   • Valide a assertion (JWT).

2. Pesquisar o usuário:

   • Verifique se o usuário existe usando a declaração sub ou email.

3. Responder:

   • Se a operação for bem-sucedida: gere e retorne access_token, refresh_token e expires_in em uma resposta JSON (HTTP 200 OK).
   • Se a vinculação falhar: retorne HTTP 401 Unauthorized com {"error": "linking_error"} e um login_hint opcional para voltar à vinculação OAuth padrão.

Processar a criação de contas usando o recurso Fazer login com o Google (criar intent)

Se não houver uma conta, o Google vai chamar seu endpoint com intent=create para criar um novo usuário. Para detalhes sobre os parâmetros, consulte Intenções de vinculação simplificada.

Receita de implementação

Para processar a intent create, faça o seguinte:

1. Valide a solicitação:

   • Verifique client_id, client_secret e grant_type.
   • Valide o assertion (JWT).

2. Verifique se o usuário não existe:

   • Verifique se o sub ou email já está no seu banco de dados.
   • Se o usuário existir: retorne HTTP 401 Unauthorized com {"error": "linking_error", "login_hint": "USER_EMAIL"} para forçar o fallback à vinculação do OAuth.

3. Criar conta:

   • Use as declarações sub, email, name e picture do JWT para criar um novo registro de usuário.

4. Responder:

   • Gere e retorne tokens em uma resposta JSON (HTTP 200 OK).

Receber seu ID do cliente da API do Google

Você precisará fornecer seu ID do cliente da API do Google durante o processo de registro da vinculação de contas. Para receber o ID do cliente da API usando o projeto criado ao concluir as etapas de vinculação do OAuth. Para fazer isso, siga estas etapas:

1. Acesse a página "Clientes".

2. Crie ou selecione um projeto das APIs do Google.

   Se o projeto não tiver um ID do cliente para o tipo de aplicativo da Web, clique em Criar cliente para criar um. Inclua o domínio do seu site na caixa Origens JavaScript autorizadas. Ao realizar testes ou desenvolvimento local, adicione http://localhost e http://localhost:<port_number> ao campo Origens JavaScript autorizadas.

   Importante: adicione http://localhost e http://localhost:<port_number> ao campo Origens JavaScript autorizadas para testes ou desenvolvimento locais.

   Observação:um ID do cliente é semelhante ao exemplo a seguir:

   1234567890-abc123def456.apps.googleusercontent.com
   

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