Visão geral
A vinculação simplificada do Login do Google com base em OAuth adiciona o Login do Google com base na vinculação de OAuth. Isso permite uma experiência de vinculação perfeita para os usuários do Google, além de permitir a criação de uma conta, o que permite que o usuário crie uma nova conta no seu serviço usando a Conta do Google.
Para realizar a vinculação de contas com o OAuth e o Login do Google, siga estas etapas gerais:
- Primeiro peça para o usuário autorizar o acesso ao perfil do Google.
- usar as informações no perfil para verificar se a conta de usuário existe.
- Para usuários atuais, vincule as contas.
- 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, crie um usuário com base nas informações do perfil contidas no token de ID.
![A figura mostra as etapas para um usuário vincular a Conta do Google usando o fluxo de vinculação simplificado. A primeira captura de tela mostra como um usuário pode selecionar seu app para a vinculação. A segunda captura permite que o usuário confirme se ele já tem uma conta no seu serviço. A terceira captura de tela permite que o usuário selecione a Conta do Google que quer vincular. A quarta mostra a confirmação da vinculação da Conta do Google ao app. A quinta mostra uma conta de usuário vinculada no Google app.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/account-linking/images/streamlined-linking-flow.png?authuser=5&hl=pt-br)
Figura 1. Vinculação de contas no smartphone de um usuário com vinculação simplificada
Requisitos para uma vinculação simplificada
- Implemente o fluxo de vinculação básica do OAuth da Web. Seu serviço precisa ser compatível com endpoints de autorização e troca de tokens compatíveis com o OAuth 2.0.
- O endpoint de troca de tokens precisa ser compatível com as declarações JSON Web Token (JWT) e implementar as intents
check
,create
eget
.
Implementar o servidor OAuth
O endpoint de troca de tokens precisa ser compatível com as intents check
, create
e get
. Veja abaixo as etapas do fluxo de vinculação da conta e indica quando as intents diferentes são chamadas:
- O usuário tem uma conta no seu sistema de autenticação? O usuário decide se SIM ou NÃO.
- SIM : o usuário usa o e-mail associado à Conta do Google para fazer login na sua plataforma? O usuário decide se SIM ou NÃO.
- SIM : o usuário tem uma conta correspondente no seu sistema de autenticação? (
check intent
é chamado para confirmar)- SIM :
get intent
é chamado, e a conta é vinculada se a intent for retornada com sucesso. - NO : Criar nova conta? O usuário decide se SIM ou NÃO.
- SIM :
create intent
será chamado, e a conta será vinculada se a intent de criação retornar. - NO : o fluxo OAuth da Web é acionado, o usuário é direcionado para seu navegador, e o usuário tem a opção de vincular com um e-mail diferente.
- SIM :
- SIM :
- NÃO : o fluxo de OAuth da Web é acionado, o usuário é direcionado para o navegador, e o usuário tem a opção de vincular com um e-mail diferente.
- SIM : o usuário tem uma conta correspondente no seu sistema de autenticação? (
- NÃO : o usuário tem uma conta correspondente no seu sistema de autenticação? (
check intent
é chamado para confirmar)- SIM:
get intent
é chamado, e a conta é vinculada se a intent for retornada com sucesso. - NO :
create intent
será chamado, e a conta será vinculada se a intent de criação retornar.
- SIM:
- SIM : o usuário usa o e-mail associado à Conta do Google para fazer login na sua plataforma? O usuário decide se SIM ou NÃO.
Verificar se já existe uma conta de usuário (verificar intent)
Depois que o usuário autoriza o acesso ao perfil, o Google envia uma solicitação com uma declaração assinada da identidade do usuário. A declaração contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário. O endpoint de troca de token configurado para seu projeto processa essa solicitação.
Se a Conta do Google correspondente já estiver presente no sistema de autenticação, o endpoint de troca de token responderá com account_found=true
. Se a
Conta do Google não corresponder a um usuário existente, o endpoint de troca de token
retornará um erro HTTP 404 Not Found 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&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
O endpoint de troca de token precisa processar os seguintes parâmetros:
Parâmetros de endpoint 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, o valor deste parâmetro é urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
Um Token da Web JSON (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário. |
client_id |
ID do cliente atribuído ao Google |
client_secret |
A chave secreta do cliente que você atribuiu ao Google |
Para responder às solicitações de intent check
, seu endpoint de troca de token precisa executar as seguintes etapas:
- Validar e decodificar a declaração JWT.
- Verifique se a Conta do Google já está presente no sistema de autenticação.
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 ehd
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.
Verificar se a Conta do Google já está presente no sistema de autenticação
Verifique se uma destas condições é verdadeira:
- O ID da Conta do Google, encontrado no campo
sub
da declaração, está no seu banco de dados de usuários. - O endereço de e-mail na declaração corresponde a um usuário no seu banco de dados de usuários.
Se uma das condições for verdadeira, o usuário já se inscreveu. Nesse caso, retorne uma resposta como esta:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
Se o ID da Conta do Google e o endereço de e-mail especificados na declaração não corresponderem a um usuário no seu banco de dados, o usuário ainda não se inscreveu. Nesse
caso, o endpoint 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", }
Handle automatic linking (get intent)
After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.
If the corresponding Google Account is already present in your authentication
system, your token exchange endpoint returns a token for the user. If the
Google Account doesn't match an existing user, your token exchange endpoint
returns a linking_error
error and optional login_hint
.
The request has the following form:
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&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Your token exchange endpoint must be able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is get . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
scope |
Optional: Any scopes that you've configured Google to request from users. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
To respond to the get
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Check if the Google account is already present in your authentication system.
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 ehd
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.
Check if the Google account is already present in your authentication system
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
In some cases, account linking based on ID token might fail for the user. If it
does so for any reason, your token exchange endpoint needs to reply with a HTTP
401 error that specifies error=linking_error
, as the following example shows:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
When Google receives a 401 error response with linking_error
, Google sends
the user to your authorization endpoint with login_hint
as a parameter. The
user completes account linking using the OAuth linking flow in their browser.
Handle account creation via Google Sign-In (create intent)
When a user needs to create an account on your service, Google makes a request
to your token exchange endpoint that specifies intent=create
.
The request has the following form:
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&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Your token exchange endpoint must able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is create . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
The JWT within the assertion
parameter contains the user's Google Account ID,
name, and email address, which you can use to create a new account on your
service.
To respond to the create
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Validate user information and create new account.
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 ehd
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.
Validate user information and create new account
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If either condition is true, prompt the user to link their existing account
with their Google Account. To do so, respond to the request with an HTTP 401 error
that specifies error=linking_error
and gives the user's email address as the
login_hint
. The following is a sample response:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
When Google receives a 401 error response with linking_error
, Google sends
the user to your authorization endpoint with login_hint
as a parameter. The
user completes account linking using the OAuth linking flow in their browser.
If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.
When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Ver o ID do cliente da API do Google
Será necessário fornecer seu ID do cliente da API do Google durante o processo de registro da vinculação de contas.
Para conseguir o ID do cliente da API usando o projeto criado durante a conclusão das etapas da vinculação do OAuth. Para isso, siga estas etapas:
- Abra a página Credenciais do Console de APIs do Google.
Crie ou selecione um projeto de APIs do Google.
Se o projeto não tiver um ID do cliente para o tipo de aplicativo da Web, clique em Criar credenciais > ID do cliente OAuth para criar um. Inclua o domínio do seu site na caixa Origens JavaScript autorizadas. Ao realizar testes ou desenvolvimento locais, é necessário adicionar
http://localhost
ehttp://localhost:<port_number>
ao campo Origens JavaScript autorizadas.
Como validar a implementação
Você pode validar a sua implementação, utilizando o Parque OAuth 2.0 ferramenta.
Na ferramenta, execute as seguintes etapas:
- Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
- No campo de fluxo OAuth, selecione do lado do cliente.
- No campo OAuth Endpoints, selecione Personalizado.
- Especifique seu ponto de extremidade OAuth 2.0 e o ID do cliente que você atribuiu ao Google nos campos correspondentes.
- 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.
- 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:
- Clique no sinal-in com o botão Google.
- Escolha a conta que deseja vincular.
- Digite o ID do serviço.
- Opcionalmente, insira um ou mais escopos para os quais você solicitará acesso.
- Clique em Iniciar demonstração.
- Quando solicitado, confirme se você pode consentir e negar a solicitação de vinculação.
- Confirme que você foi redirecionado para sua plataforma.