Visão geral
A vinculação simplificada do Login do Google baseado em OAuth adiciona o Login do Google aos Vinculação do OAuth. Isso proporciona uma experiência de vinculação perfeita para 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 própria Conta do Google.
Para vincular a conta com o OAuth e o Login do Google, siga estas instruções etapas:
- Primeiro, peça ao usuário que dê consentimento para acessar o perfil do Google dele.
- Use as informações no perfil para verificar se a conta de usuário existe.
- Vincule as contas dos usuários atuais.
- Se você não encontrar uma correspondência para o usuário do Google no seu sistema de autenticação, validar o token de ID recebido do Google. Em seguida, é possível criar um nas informações de perfil contidas no token de ID.
Figura 1. Vinculação de contas no smartphone do usuário com a vinculação simplificada
Requisitos para a vinculação simplificada
- Implemente o fluxo de vinculação OAuth da Web básica. Seu serviço precisa ser compatível com OAuth 2.0 autorização e troca de token.
- O endpoint de troca de token precisa oferecer suporte a declarações JSON Web Token (JWT) e implementar as intents
check
,create
eget
.
Implementar seu servidor OAuth
Seu endpoint de troca de token precisa oferecer suporte às intents check
, create
e get
. Confira abaixo as etapas concluídas no fluxo de vinculação de contas e indique quando as diferentes intents são chamadas:
- O usuário tem uma conta no seu sistema de autenticação? (O usuário decide selecionando SIM ou NÃO)
- SIM : o usuário utiliza o e-mail associado à Conta do Google para fazer login na sua plataforma? (O usuário decide selecionando SIM ou NÃO)
- SIM : o usuário tem uma conta correspondente no sistema de autenticação? (
check intent
é chamado para confirmar)- SIM :
get intent
será chamado, e a conta será vinculada se a intent recebida retornar. - NÃO : criar uma nova conta? (O usuário decide selecionando SIM ou NÃO)
- SIM :
create intent
será chamado, e a conta será vinculada se a intent criar retornar. - NÃO : o fluxo de OAuth da Web é acionado, o usuário é direcionado para o navegador e tem a opção de vincular com um e-mail diferente.
- SIM :
- SIM :
- NÃO : o fluxo OAuth da Web é acionado, o usuário é direcionado para o navegador e tem a opção de vincular com um e-mail diferente.
- SIM : o usuário tem uma conta correspondente no 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
será chamado, e a conta será vinculada se a intent recebida retornar. - NÃO :
create intent
é chamado, e a conta é vinculada se a intent de criação retornar.
- SIM :
- SIM : o usuário utiliza o e-mail associado à Conta do Google para fazer login na sua plataforma? (O usuário decide selecionando 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 do Google, o Google envia uma solicitação que contém uma declaração assinada sobre a identidade do usuário do Google. A contém informações que incluem o ID da Conta do Google do usuário, nome e endereço de e-mail. O endpoint de troca de token configurado para sua projeto lida com essa solicitação.
Se a Conta do Google correspondente já estiver presente na sua autenticação
seu endpoint de troca de token responderá com account_found=true
. Se o
A Conta do Google não corresponde a um usuário atual, seu endpoint de troca de token
retorna 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&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Seu endpoint de troca de token precisa ser capaz de lidar com 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,
tem o valor urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
Um JSON Web Token (JWT) que fornece uma declaração assinada do identidade do usuário. O JWT contém informações que incluem o endereço de e-mail ID, nome e endereço de e-mail da Conta do Google. |
client_id |
O ID do cliente que você atribuiu ao Google. |
client_secret |
A chave secreta do cliente que você atribuiu ao Google. |
Para responder às solicitações da intent check
, o endpoint de troca de token precisa executar as seguintes etapas:
- Valide e decodifique a declaração do JWT.
- Verifique se a Conta do Google já está no seu sistema de autenticação.
Valide e decodifique a declaração do JWT
É possível validar e decodificar a declaração do JWT usando um Biblioteca de decodificação JWT para sua linguagem. Usar as chaves públicas do Google, disponíveis em 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 a propriedade
emissor (campo iss
) é https://accounts.google.com
, que o público-alvo
(campo aud
) é seu ID de cliente atribuído e que o token não expirou
(campo exp
).
Use os campos email
, email_verified
e hd
para determinar se
O Google hospeda e é autoritativo para um endereço de e-mail. Nos casos em que o Google
autoritativo, 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, estes métodos
pode ser usada para verificar a conta antes da vinculação.
Casos em que o Google é confiável:
email
tem o sufixo@gmail.com
. Esta é uma conta do Gmail.- A opção
email_verified
é verdadeira ehd
foi definida. Esta é uma conta do G Suite.
Os usuários podem se registrar para Contas do Google sem usar o Gmail ou o G Suite. Quando
email
não contém um sufixo @gmail.com
e hd
está ausente, o Google não está
com autoridade e senha ou outros métodos de desafio
o usuário. email_verified
também pode ser verdadeiro porque o Google verificou inicialmente o
usuário quando a Conta do Google foi criada, mas a propriedade do terceiro
pode ter mudado desde então.
Verificar se a Conta do Google já está no sistema de autenticação
Verifique se uma das condições a seguir é verdadeira:
- O ID da Conta do Google, encontrado no campo
sub
da declaração, está no seu nome de usuário no seu banco de dados. - 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, retornar uma resposta como esta:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
Se nem o ID da Conta do Google nem o endereço de e-mail especificado no
corresponde a um usuário em seu banco de dados, o usuário ainda não se inscreveu. Em
nesse caso, seu endpoint de troca de token precisará 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 declaração do JWT
É possível validar e decodificar a declaração do JWT usando um Biblioteca de decodificação JWT para sua linguagem. Usar as chaves públicas do Google, disponíveis em 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 a propriedade
emissor (campo iss
) é https://accounts.google.com
, que o público-alvo
(campo aud
) é seu ID de cliente atribuído e que o token não expirou
(campo exp
).
Use os campos email
, email_verified
e hd
para determinar se
O Google hospeda e é autoritativo para um endereço de e-mail. Nos casos em que o Google
autoritativo, 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, estes métodos
pode ser usada para verificar a conta antes da vinculação.
Casos em que o Google é confiável:
email
tem o sufixo@gmail.com
. Esta é uma conta do Gmail.- A opção
email_verified
é verdadeira ehd
foi definida. Esta é uma conta do G Suite.
Os usuários podem se registrar para Contas do Google sem usar o Gmail ou o G Suite. Quando
email
não contém um sufixo @gmail.com
e hd
está ausente, o Google não está
com autoridade e senha ou outros métodos de desafio
o usuário. email_verified
também pode ser verdadeiro porque o Google verificou inicialmente o
usuário quando a Conta do Google foi criada, mas a propriedade do terceiro
pode ter mudado desde então.
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.
通过 Google 登录功能处理账号创建(创建 intent)
当用户需要在您的服务中创建账号时,Google 会发出请求
发送到指定 intent=create
的令牌交换端点。
请求的格式如下:
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
您的令牌交换端点必须能够处理以下参数:
令牌端点参数 | |
---|---|
intent |
对于这些请求,此参数的值为 create 。 |
grant_type |
所交换的令牌的类型。对于这类请求
参数的值为 urn:ietf:params:oauth:grant-type:jwt-bearer 。 |
assertion |
一个 JSON Web 令牌 (JWT),提供 Google 用户身份。JWT 包含的信息包括用户 Google 账号 ID、姓名和电子邮件地址。 |
client_id |
您分配给 Google 的客户 ID。 |
client_secret |
您分配给 Google 的客户端密钥。 |
assertion
参数中的 JWT 包含用户的 Google 账号 ID。
姓名和电子邮件地址,可用于在 Gmail 中创建新账号
服务。
如需响应 create
intent 请求,您的令牌交换端点必须执行以下步骤:
- 验证和解码 JWT 断言。
- 验证用户信息并创建新账号。
Valide e decodifique a declaração do JWT
É possível validar e decodificar a declaração do JWT usando um Biblioteca de decodificação JWT para sua linguagem. Usar as chaves públicas do Google, disponíveis em 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 a propriedade
emissor (campo iss
) é https://accounts.google.com
, que o público-alvo
(campo aud
) é seu ID de cliente atribuído e que o token não expirou
(campo exp
).
Use os campos email
, email_verified
e hd
para determinar se
O Google hospeda e é autoritativo para um endereço de e-mail. Nos casos em que o Google
autoritativo, 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, estes métodos
pode ser usada para verificar a conta antes da vinculação.
Casos em que o Google é confiável:
email
tem o sufixo@gmail.com
. Esta é uma conta do Gmail.- A opção
email_verified
é verdadeira ehd
foi definida. Esta é uma conta do G Suite.
Os usuários podem se registrar para Contas do Google sem usar o Gmail ou o G Suite. Quando
email
não contém um sufixo @gmail.com
e hd
está ausente, o Google não está
com autoridade e senha ou outros métodos de desafio
o usuário. email_verified
também pode ser verdadeiro porque o Google verificou inicialmente o
usuário quando a Conta do Google foi criada, mas a propriedade do terceiro
pode ter mudado desde então.
验证用户信息并创建新账号
请检查以下任一条件是否成立:
- Google 账号 ID(可在断言的
sub
字段中找到)位于您的用户中 数据库。 - 断言中的电子邮件地址与用户数据库中的用户匹配。
如果满足上述任一条件,请提示用户关联其现有账号
与其 Google 账号关联。为此,请使用 HTTP 401 错误响应请求
该参数指定 error=linking_error
并将用户的电子邮件地址作为
login_hint
。以下是示例响应:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
当 Google 收到包含 linking_error
的 401 错误响应时,会发送
使用 login_hint
作为参数将用户发送到您的授权端点。通过
用户在浏览器中使用 OAuth 关联流程完成账号关联。
如果以上两个条件都不满足,请使用相应信息创建一个新的用户账号 。新账号通常不会设置密码。时间是 建议您将 Google 登录功能添加到其他平台,以便用户 使用 Google 账号登录。或者 可以通过电子邮件向用户发送链接,启动密码恢复流程,以允许 用户设置密码,以便在其他平台上登录。
创建完成后,发出一个访问令牌 并在 HTTPS 响应的正文,如以下示例所示:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Receber seu ID do cliente da API do Google
Será necessário fornecer o 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 que você criou durante as etapas de vinculação 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. Certifique-se de incluir o domínio do site na caixa Origens JavaScript autorizadas. Quando você realiza testes ou desenvolvimentos locais, é preciso adicionar
http://localhost
ehttp://localhost:<port_number>
no 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.