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

Visão geral

O login com o Google simplificado baseado em OAuth adiciona o login com o Google além da vinculação OAuth. Isso oferece uma experiência de vinculação perfeita para usuários do Google e, opcionalmente, 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 não for possível encontrar uma correspondência para o usuário do Google no seu sistema de autenticação, valide o token de ID recebido do Google. Se o serviço aceitar a criação de contas, você poderá criar um usuário com base nas informações do perfil contidas no token de ID.

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.

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 da 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 contas existentes, processa os intents de vinculação de conta obrigatórios (check, get) e o intent create opcional, além de emitir tokens com base nos intents solicitados.
Sua API de serviço	Servidor de recursos	Fornece acesso aos dados do usuário quando apresentado com um token de acesso válido.

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 e get necessárias, além da intent create opcional.

• 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 ao selecionar 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? (A intenção check é chamada para confirmação)
         1. SIM : a intenção get é chamada e a conta é vinculada se a intenção de recebimento for retornada.
         2. NÃO : Criar conta? (O usuário decide selecionando SIM ou NÃO; aplicável apenas se o serviço aceitar a criação de contas)
            1. SIM : a intent create é chamada 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 recebe 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? (A intenção check é chamada para confirmação)
      1. SIM : a intenção get é chamada e a conta é vinculada se get intent for retornado com sucesso.
      2. NÃO : se o serviço for compatível com a criação de contas, a intent create será chamada, e a conta será vinculada se a intent de criação for retornada com sucesso. Se a criação de conta não for compatível, seu endpoint vai retornar HTTP 401 linking_error para acionar o fluxo de vinculação OAuth de substituição.

Receita de implementação

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

Siga estas etapas para processar as diferentes intents:

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"account_found": "false"}.

Processar a vinculação automática (receber 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 necessária, faça o seguinte:

1. Validar a solicitação:

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

2. Pesquisar usuário:

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

3. Responder:

   • Em caso de sucesso: 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.

Handle account creation using Sign in with Google (create intent)

If your service supports account creation and no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the optional create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (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.

Validar sua implementação

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.