Esta página foi traduzida pela API Cloud Translation.
Switch to English

Vinculação simplificada com OAuth e login do Google

O link simplificado do Login do Google baseado em OAuth adiciona o Login do Google ao link do OAuth . Isso fornece uma experiência de vinculação perfeita para os usuários do Google e também permite a vinculação de contas para usuários que se registraram em seu serviço com uma identidade que não seja do Google.

Para realizar a vinculação de contas com OAuth e Login do Google, siga estas etapas gerais:

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

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 oferecer suporte a autorização compatível com OAuth 2.0 e pontos de extremidade de troca de token . Além disso, seu ponto de extremidade de troca de token deve suportar asserções JSON Web Token (JWT) e implementar as intenções de check , create e get .

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 .

Configure o projeto

Para configurar seu projeto para usar a vinculação de contas OAuth:

  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 .

Implementar seu servidor OAuth

Uma implementação de servidor OAuth 2.0 do fluxo de código de autorização consiste em dois pontos de extremidade, que seu serviço disponibiliza por HTTPS. O primeiro endpoint é o endpoint de autorização, que é responsável por localizar ou obter o 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. O segundo ponto de extremidade é o ponto de extremidade de troca de tokens, que é usado para obter strings criptografadas, chamadas 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 terminais juntos para obter permissão dos usuários para chamar essas APIs em seu nome.

Uma sessão de fluxo de código de autorização 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 começou em um dispositivo apenas de voz para uma ação, o Google transfere a execução para um telefone.
  2. O usuário faz login, se ainda não estiver conectado, e concede ao Google permissão para acessar seus 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 devolve 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 seu ponto de extremidade de troca de token, 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 expirarem.
  5. Depois que o usuário conclui o fluxo de vinculação da conta, cada solicitação subsequente enviada do Google contém um token de acesso.

Lidar com solicitações de autorização

Quando você precisa vincular contas usando o fluxo do código de autorização 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 de cliente do Google que você registrou no 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.
scope Opcional: um conjunto de strings de escopo delimitado por espaço que especifica os dados para os quais o Google está solicitando autorização.
response_type O tipo de valor a ser retornado na resposta. Para o fluxo de código de autorização OAuth 2.0, o tipo de resposta é sempre code .
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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

Para que seu endpoint de autorização processe solicitações de login, execute as seguintes etapas:

  1. Verifique se client_id corresponde ao ID do cliente do Google que você registrou no Google e se redirect_uri corresponde ao URL de redirecionamento fornecido pelo Google para o seu serviço. Essas verificações são importantes para evitar a concessão de acesso a aplicativos cliente não intencionais ou configurados incorretamente. Se você oferece suporte a vários fluxos OAuth 2.0, confirme também se o response_type é um code .
  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 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 deve representar exclusivamente o usuário, o cliente ao qual o token se destina e o tempo de expiração do código e não deve ser adivinhado. 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 parâmetro redirect_uri . 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 o code e state parâmetros de state . A seguir está um exemplo do URL resultante:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Lidar com solicitações de troca de tokens

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

  • Trocar códigos de autorização para tokens de acesso e tokens de atualização
  • Tokens de atualização do Exchange para tokens de acesso

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

Parâmetros de endpoint de troca de token
client_id Uma string que identifica a origem da solicitação como Google. Esta string deve ser registrada em seu sistema como identificador exclusivo do Google.
client_secret Uma string secreta que você registrou no Google para seu serviço.
grant_type O tipo de token que está sendo trocado. É authorization_code ou refresh_token .
code Quando grant_type=authorization_code , este parâmetro é o código que o Google recebeu de seu ponto de extremidade de login ou troca de token.
redirect_uri Quando grant_type=authorization_code , este parâmetro é o URL usado na solicitação de autorização inicial.
refresh_token Quando grant_type=refresh_token , este parâmetro é o token de atualização que o Google recebeu de seu ponto de extremidade de troca de tokens.
Trocar códigos de autorização para tokens de acesso e tokens de atualização

Depois que o usuário faz login e seu endpoint de autorização retorna um código de autorização de curta duração ao Google, o Google envia uma solicitação ao endpoint de troca de token 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. A seguir está um exemplo de uma 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 para um token de acesso e um token de atualização, seu ponto de extremidade de troca de token responde às 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 a URL especificada pelo parâmetro redirect_uri é idêntica ao valor usado na solicitação de autorização inicial.
  4. Se você não puder verificar todos os critérios acima, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como o 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 devem representar exclusivamente o usuário e o cliente ao qual o token se destina e não podem ser adivinhados. Para tokens de acesso, registre também 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 para o 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 obter um novo token de acesso de seu ponto de extremidade de troca de tokens.

Tokens de atualização do Exchange para tokens de acesso

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

Para estes pedidos, o valor de grant_type é refresh_token , eo valor de refresh_token é o valor do token de atualização anteriormente concedida ao Google. A seguir está um exemplo de uma 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, seu ponto de extremidade de troca de token responde às solicitações POST executando as seguintes etapas:

  1. Verifique se client_id identifica a origem da solicitação como Google e se 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 puder verificar todos os critérios acima, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como o 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 devem representar exclusivamente o usuário e o cliente ao qual o token se destina e não podem ser adivinhados. Para tokens de acesso, registre também o tempo de expiração do token, normalmente uma hora depois de emitir o token.
  5. Retorne o seguinte objeto JSON no corpo da resposta HTTPS:
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Verifique se há uma conta de usuário existente

Depois que o usuário dá consentimento para acessar seu perfil do Google, o Google envia uma solicitação que contém uma declaração assinada da identidade do usuário do Google. A declaração contém informações que incluem a ID, o nome e o endereço de e-mail da Conta do Google do usuário. O ponto de extremidade de troca de token configurado para seu projeto lida com essa solicitação.

Se a conta do Google correspondente já estiver presente em seu sistema de autenticação, seu ponto de extremidade de troca de token responde com account_found=true . Se a conta do Google não corresponder a um usuário existente, seu ponto de extremidade de troca de token retornará um erro HTTP 404 não encontrado com account_found=false .

A solicitação tem o seguinte formato:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES

Seu ponto de extremidade de troca de token deve ser capaz de lidar com os seguintes parâmetros:

Parâmetros de terminal de token
intent Para essas solicitações, o valor desse parâmetro é check .
grant_type O tipo de token que está sendo trocado. Para essas solicitações, esse parâmetro tem o valor urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion Um JSON Web Token (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações que incluem a ID, o nome e o endereço de e-mail da Conta do Google do usuário.

Quando seu ponto de extremidade de troca de token recebe a solicitação de check , ele precisa validar e decodificar a asserção JWT.

Valide e decodifique a asserção JWT

Você pode validar e decodificar a declaração JWT usando uma biblioteca de decodificação JWT para o seu idioma . Use as chaves públicas do Google, disponíveis nos formatos JWK ou PEM , para verificar a assinatura do token.

Quando decodificada, a declaração JWT se parece com o seguinte exemplo:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Além de verificar a assinatura do token, verifique se o emissor da declaração (campo iss ) é https://accounts.google.com , se o público (campo aud ) é seu ID de cliente atribuído e se o token não expirou ( exp campo).

Usando os campos email , email_verified e hd , você pode determinar se o Google hospeda e se tem autoridade para um endereço de e-mail. Nos casos em que o Google tem autoridade, o usuário é atualmente conhecido como o proprietário legítimo da conta e você pode pular a senha ou outros métodos de desafio. Caso contrário, esses métodos podem ser usados ​​para verificar a conta antes da vinculação.

Casos em que o Google é autoritário:

  • email - email tem um sufixo @gmail.com , esta é uma conta do Gmail.
  • email_verified é true e hd está definido, esta é uma conta do G Suite.

Os usuários podem se registrar em Contas do Google sem usar o Gmail ou o G Suite. Quando o email não contém um sufixo @gmail.com e hd está ausente, o Google não é autoritativo e senha ou outros métodos de desafio são recomendados para verificar o usuário. email_verfied também pode ser verdadeiro, já que o Google verificou inicialmente o usuário quando a conta do Google foi criada; no entanto, a propriedade da conta de e-mail de terceiros pode ter mudado.

Verifique se a conta do Google já está presente em seu sistema de autenticação

Verifique se alguma das seguintes condições é verdadeira:

  • O ID da conta do Google, encontrado no sub da declaração, está no banco de dados do usuário.
  • O endereço de e-mail na declaração corresponde a um usuário em seu banco de dados do usuário.

Se qualquer uma das condições for verdadeira, o usuário já se inscreveu. Nesse caso, retorne uma resposta como a seguinte:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

O Google então exibe uma caixa de diálogo de consentimento de vinculação para o usuário e solicita consentimento para os escopos desejados a fim de continuar com a vinculação. Depois que o Google obtém o consentimento do usuário, ele envia uma solicitação get ao endpoint do token para continuar a vinculação.

Se nem o ID da conta do Google nem o endereço de e-mail especificado na declaração corresponder a um usuário em seu banco de dados, o usuário ainda não se inscreveu. Nesse caso, seu ponto de extremidade de troca de token precisa responder com um erro HTTP 404 que especifica "account_found": "false" , como no exemplo a seguir:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}
Quando o Google recebe a resposta de erro 404 com um erro "account_found": "false" , o Google exibe uma caixa de diálogo para o usuário solicitar consentimento para criar uma nova conta e acesso aos escopos desejados. Depois que o Google obtém o consentimento do usuário, ele chama seu ponto de extremidade de troca de tokens com o valor do parâmetro intent definido para create e inclui um token de ID que contém as informações de perfil do usuário com a solicitação.

Lidar com vinculação automática

Depois que o usuário dá consentimento para acessar seu perfil do Google, o Google envia uma solicitação que contém uma declaração assinada da identidade do usuário do Google. A declaração contém informações que incluem o ID da Conta do Google do usuário, o nome e o endereço de e-mail. O ponto de extremidade de troca de token configurado para seu projeto lida com essa solicitação.

Se a conta do Google correspondente já estiver presente em seu sistema de autenticação, seu ponto de extremidade de troca de token retorna um token para o usuário. Se a conta do Google não corresponder a um usuário existente, seu ponto de extremidade de troca de token retornará um erro linking_error e login_hint opcional.

O pedido tem o seguinte formato:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES

Seu ponto de extremidade de troca de token deve ser capaz de lidar com os seguintes parâmetros:

Parâmetros de terminal de token
intent Para essas solicitações, o valor desse parâmetro é get .
grant_type O tipo de token que está sendo trocado. Para essas solicitações, esse parâmetro tem o valor urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion Um JSON Web Token (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações que incluem a ID, o nome e o endereço de e-mail da Conta do Google do usuário.
scope Opcional: todos os escopos que você configurou o Google para solicitar dos usuários.

Quando seu ponto de extremidade de troca de token recebe a solicitação de vinculação, ele precisa validar e decodificar a declaração JWT.

Valide e decodifique a asserção JWT

Você pode validar e decodificar a declaração JWT usando uma biblioteca de decodificação JWT para o seu idioma . Use as chaves públicas do Google, disponíveis nos formatos JWK ou PEM , para verificar a assinatura do token.

Quando decodificada, a declaração JWT se parece com o seguinte exemplo:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Além de verificar a assinatura do token, verifique se o emissor da declaração (campo iss ) é https://accounts.google.com , se o público (campo aud ) é seu ID de cliente atribuído e se o token não expirou ( exp campo).

Usando os campos email , email_verified e hd , você pode determinar se o Google hospeda e se tem autoridade para um endereço de e-mail. Nos casos em que o Google tem autoridade, o usuário é atualmente conhecido como o proprietário legítimo da conta e você pode pular a senha ou outros métodos de desafio. Caso contrário, esses métodos podem ser usados ​​para verificar a conta antes da vinculação.

Casos em que o Google é autoritário:

  • email - email tem um sufixo @gmail.com , esta é uma conta do Gmail.
  • email_verified é true e hd está definido, esta é uma conta do G Suite.

Os usuários podem se registrar em Contas do Google sem usar o Gmail ou o G Suite. Quando o email não contém um sufixo @gmail.com e hd está ausente, o Google não é autoritativo e senha ou outros métodos de desafio são recomendados para verificar o usuário. email_verfied também pode ser verdadeiro, já que o Google verificou inicialmente o usuário quando a conta do Google foi criada; no entanto, a propriedade da conta de e-mail de terceiros pode ter mudado.

Verifique se a conta do Google já está presente em seu sistema de autenticação

Verifique se alguma das seguintes condições é verdadeira:

  • O ID da conta do Google, encontrado no sub da declaração, está no banco de dados do usuário.
  • O endereço de e-mail na declaração corresponde a um usuário em seu banco de dados do usuário.

Em alguns casos, a vinculação de contas com base no token de ID pode falhar para o usuário. Se isso acontecer por qualquer motivo, seu ponto de extremidade de troca de token precisa responder com um erro HTTP 401 que especifica error=linking_error , como mostra o exemplo a seguir:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}
Quando o Google recebe uma resposta de erro 401 com linking_error , o Google chama seu endpoint de troca de token com o seguinte na solicitação:

  • O parâmetro de intent definido para create
  • Um JWT com o token de ID e informações de perfil do usuário

Lidar com a criação de contas por meio do Login do Google

Quando um usuário precisa criar uma conta em seu serviço, o Google faz uma solicitação ao seu ponto de extremidade de troca de token que especifica intent=create .

O pedido tem o seguinte formato:

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

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT[&NEW_ACCOUNT_INFO]

Seu ponto de extremidade de troca de token deve ser capaz de lidar com os seguintes parâmetros:

Parâmetros de terminal de token
intent Para essas solicitações, o valor desse parâmetro é create .
grant_type O tipo de token que está sendo trocado. Para essas solicitações, esse parâmetro tem o valor urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion Um JSON Web Token (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações que incluem a ID, o nome e o endereço de e-mail da Conta do Google do usuário.

O JWT no parâmetro assertion contém o ID, o nome e o endereço de e-mail da Conta do Google do usuário, que você pode usar para criar uma nova conta em seu serviço.

Para responder às solicitações de criação de conta, seu ponto de extremidade de troca de token deve executar as etapas nas duas seções a seguir.

Valide e decodifique a asserção JWT

Você pode validar e decodificar a declaração JWT usando uma biblioteca de decodificação JWT para o seu idioma . Use as chaves públicas do Google, disponíveis nos formatos JWK ou PEM , para verificar a assinatura do token.

Quando decodificada, a declaração JWT se parece com o seguinte exemplo:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Além de verificar a assinatura do token, verifique se o emissor da declaração (campo iss ) é https://accounts.google.com , se o público (campo aud ) é seu ID de cliente atribuído e se o token não expirou ( exp campo).

Usando os campos email , email_verified e hd , você pode determinar se o Google hospeda e se tem autoridade para um endereço de e-mail. Nos casos em que o Google tem autoridade, o usuário é atualmente conhecido como o proprietário legítimo da conta e você pode pular a senha ou outros métodos de desafio. Caso contrário, esses métodos podem ser usados ​​para verificar a conta antes da vinculação.

Casos em que o Google é autoritário:

  • email - email tem um sufixo @gmail.com , esta é uma conta do Gmail.
  • email_verified é true e hd está definido, esta é uma conta do G Suite.

Os usuários podem se registrar em Contas do Google sem usar o Gmail ou o G Suite. Quando o email não contém um sufixo @gmail.com e hd está ausente, o Google não é autoritativo e senha ou outros métodos de desafio são recomendados para verificar o usuário. email_verfied também pode ser verdadeiro, já que o Google verificou inicialmente o usuário quando a conta do Google foi criada; no entanto, a propriedade da conta de e-mail de terceiros pode ter mudado.

Valide as informações do usuário e crie uma nova conta

Verifique se alguma das seguintes condições é verdadeira:

  • O ID da conta do Google, encontrado no sub da declaração, está no banco de dados do usuário.
  • O endereço de e-mail na declaração corresponde a um usuário em seu banco de dados de usuário.

Se alguma das condições for verdadeira, solicite ao usuário que vincule sua conta existente à Conta do Google. Para fazer isso, responda à solicitação com um erro HTTP 401 que especifica error=linking_error e fornece o endereço de e-mail do usuário como login_hint . A seguir está um exemplo de resposta:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Quando o Google recebe uma resposta de erro 401 com linking_error , o Google envia o usuário ao seu endpoint de autorização com login_hint como parâmetro. O usuário conclui a vinculação da conta usando o fluxo de vinculação OAuth em seu navegador.

Se nenhuma das condições for verdadeira, crie uma nova conta de usuário com as informações fornecidas no JWT. Normalmente, as novas contas não têm uma senha definida. É recomendável adicionar o Login do Google a outras plataformas para permitir que os usuários façam login com o Google nas superfícies de seu aplicativo. Como alternativa, você pode enviar um e-mail ao usuário com um link que inicia seu fluxo de recuperação de senha para permitir que o usuário defina uma senha para fazer login em outras plataformas.

Quando a criação for concluída, emita um token de acesso e atualize o token e retorne os valores em um objeto JSON no corpo de sua resposta HTTPS, como no exemplo a seguir:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Validando sua implementação

Você pode validar sua implementação usando a ferramenta OAuth 2.0 Playground .

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 Lado do cliente .
  3. No campo Pontos de extremidade OAuth , 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 seção Etapa 1 , não selecione nenhum escopo do Google. Em vez disso, deixe este campo em branco ou digite um escopo válido para seu servidor (ou uma string arbitrária se você não usar escopos OAuth). Quando terminar, clique em Autorizar APIs .
  6. Nas seções Etapa 2 e Etapa 3 , passe pelo fluxo do OAuth 2.0 e verifique se cada etapa funciona conforme o esperado.

Você pode validar sua implementação usando a ferramenta de demonstração de vinculação de contas do Google .

Na ferramenta, execute as seguintes etapas:

  1. Clique no botão Sign-in with 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.