As contas são vinculadas usando os fluxos implícitos e de código de autorização do OAuth 2.0 padrão do setor. Seu serviço precisa oferecer suporte a endpoints de autorização e troca de token compatíveis com o OAuth 2.0.
No fluxo implícito, o Google abre o endpoint de autorização no navegador do usuário. Após o login, você retorna um token de acesso de longa duração para o Google. Agora, esse token de acesso está incluído em todas as solicitações enviadas pelo Google.
No fluxo do código de autorização, você precisa de dois endpoints:
O endpoint de autorização, que apresenta a interface de login aos usuários que ainda não fizeram login. 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 endpoint de troca de token, que é responsável por dois tipos de trocas:
- Troca um código de autorização por um token de atualização de longa duração e um de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação de conta.
- Troca um token de atualização de longa duração por um de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque o anterior expirou.
Escolher um fluxo do 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 a 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 de código de autorização.
Diretrizes de design
Esta seção descreve os requisitos de design e as recomendações para a tela do usuário que você hospeda para fluxos de vinculação do OAuth. Depois de ser chamada pelo app do Google, a plataforma mostra uma página de login no Google e uma tela de consentimento de vinculação de conta para o usuário. O usuário é direcionado de volta ao app do Google depois de dar consentimento para vincular contas.

Requisitos
- É necessário informar que a conta do usuário será vinculada ao Google, não a um produto específico, como o Google Home ou o Google Assistente.
Recomendações
Portanto, recomendamos que você faça o seguinte:
Exibir a Política de Privacidade do Google. Incluir um link para a Política de Privacidade do Google na tela de consentimento.
Dados a serem compartilhados. Use uma linguagem clara e concisa para informar ao usuário quais dados o Google exige e por quê.
Call-to-action clara. Informe uma call-to-action clara na tela de consentimento, como "Concordar e vincular". Isso é necessário porque os usuários precisam entender quais dados eles precisam compartilhar com o Google para vincular as contas.
Possibilidade de cancelamento. Ofereça uma maneira de voltar ou cancelar, se o usuário não quiser fazer a vinculação.
Processo de login claro. Os usuários precisam ter um método claro para fazer login na Conta do Google, como campos para nome de usuário e senha ou Fazer login com o Google.
Possibilidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta deles na sua plataforma. Como alternativa, é possível incluir um link para a Conta do Google, onde os usuários podem gerenciar a conta vinculada.
Capacidade de mudar a conta do usuário. Sugira um método para os usuários trocarem 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 alternar contas, envie um erro recuperável para o Google para que o usuário possa fazer login na conta desejada com a vinculação OAuth e o fluxo implícito.
Inclua seu logotipo. Mostre o logotipo da sua empresa na tela de consentimento. Use as diretrizes de estilo para posicionar o logotipo. Se você quiser mostrar também o logotipo do Google, consulte Logos e marcas registradas.

创建项目
如需创建项目以使用账号关联功能,请执行以下操作:
配置 OAuth 同意屏幕
Google 账号关联流程包含一个权限请求页面,用于告知用户请求访问其数据的应用、应用请求访问的数据类型以及适用的条款。您需要先配置 OAuth 权限请求页面,然后才能生成 Google API 客户端 ID。
- 打开 Google API 控制台的 OAuth 同意屏幕页面。
- 如果出现提示,请选择您刚刚创建的项目。
在“OAuth 同意屏幕”页面上,填写表单,然后点击“保存”按钮。
应用名称:征求用户同意的应用的名称。该名称应准确反映您的应用,并与用户在其他地方看到的应用名称一致。应用名称将显示在账号关联意见征求界面上。
应用徽标:权限请求页面上显示的一张图片,用以让用户认出您的应用。该徽标会显示在账号关联意见征求页面和账号设置中
支持电子邮件:供用户就其是否同意的问题与您联系。
Google API 的范围:借助范围,您的应用可以访问用户的私密 Google 数据。对于 Google 账号关联用例,默认范围(电子邮件地址、个人资料、openid)已足够,您无需添加任何敏感范围。通常,最佳做法是在需要访问权限时逐步请求相应权限范围,而不是提前请求。了解详情。
已获授权的网域:为了保护您和您的用户,Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。
应用首页链接:应用的首页。必须托管在已获授权的网域上。
应用隐私权政策链接:显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。
应用服务条款链接(可选):必须托管在已获授权的网域上。
图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面
查看“验证状态”,如果您的应用需要验证,请点击“提交以供验证”按钮,以提交您的应用以供验证。如需了解详情,请参阅 OAuth 验证要求。
Implementar seu servidor OAuth
Uma implementação do servidor OAuth 2.0 do fluxo do código de autorização consiste em: dois endpoints, que seu serviço disponibiliza por HTTPS. O primeiro endpoint é o endpoint de autorização, responsável por encontrar ou conseguir o consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma interface de login para os usuários que ainda não estão conectados e registra o consentimento para o acesso solicitado. O segundo endpoint é a troca de tokens, é usado para obter strings criptografadas, chamadas de tokens, que autorizam um usuário a para acessar seu serviço.
Quando um aplicativo do Google precisa chamar uma das APIs do seu serviço, o Google usa esses endpoints juntos para conseguir a permissão dos usuários para chamar essas APIs em nome deles.
Uma sessão do fluxo do código de autorização do OAuth 2.0 iniciada pelo Google tem seguinte fluxo:
- O Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo iniciada em um dispositivo somente de voz para uma ação, o Google transfere a execução em um smartphone.
- Caso ainda não tenha feito login, o usuário faz login e concede ao Google permissão para acessar os dados com a API, caso ainda não tenham concedido permissão.
- Seu serviço cria um código de autorização e o retorna ao Google. Afazeres Por isso, redirecione o navegador do usuário de volta para o Google com o código de autorização anexada à solicitação.
- O Google envia o código de autorização para seu endpoint de troca de token, 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 atualização token que o Google pode armazenar e usar para adquirir novos tokens de acesso e depois ela expira.
- Depois que o usuário tiver concluído o fluxo de vinculação à conta, todas as solicitação enviada pelo Google contém um token de acesso.
Processar solicitações de autorização
Quando você precisa vincular a conta usando o código de autorização do OAuth 2.0. fluxo, o Google envia o usuário para 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 Client-ID que você atribuiu ao Google. |
redirect_uri |
O URL para o qual você envia a resposta para essa solicitação. |
state |
Um valor de contabilidade que é retornado ao Google inalterado na URI de redirecionamento. |
scope |
Opcional:um conjunto delimitado por espaços de strings de escopo que especifica o dados para os quais o Google está solicitando autorização. |
response_type |
O tipo de valor a ser retornado na resposta. Para a solicitação OAuth 2.0,
fluxo do código de autorização, o tipo de resposta será sempre code .
|
user_locale |
A configuração de idioma da Conta do Google no RFC5646 usado para localizar seu conteúdo no idioma de preferência do usuário. |
Por exemplo, se o endpoint de autorização estiver disponível em
https://myservice.example.com/auth
, uma solicitação terá esta 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 o endpoint de autorização processe solicitações de login, faça o seguinte: etapas:
- Verifique se o
client_id
corresponde ao ID do cliente atribuído ao Google e se oredirect_uri
corresponde ao URL de redirecionamento fornecido pelo Google para seu serviço. Essas verificações são importantes para impedir a concessão o acesso a apps clientes não intencionais ou configurados incorretamente. Se você oferece suporte a vários Fluxos do OAuth 2.0. Confirme também se oresponse_type
écode
. - Verifique se o usuário está conectado ao seu serviço. Se o usuário não estiver conectado, para concluir o fluxo de login ou inscrição do serviço.
- Gere um código de autorização para o Google usar no acesso à API. O código de autorização pode ser qualquer valor de string, mas deve ser representar o usuário, o cliente a que o token se destina e a expiração do código tempo de resposta e não deve ser adivinhado. Você normalmente emite uma autorização que expiram após aproximadamente 10 minutos.
- 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
- Redirecione o navegador do usuário para o URL especificado pelo
parâmetro
redirect_uri
. Inclua o código de autorização que você e o valor do estado original e inalterado ao redirecionar anexando os parâmetroscode
estate
. Confira a seguir exemplo do URL resultante:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
Processar solicitações de troca de token
O endpoint de troca de token do seu serviço é responsável por dois tipos de token trocas:
- Trocar códigos de autorização por tokens de acesso e de atualização
- Trocar tokens de atualização por 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 o Google. Essa string precisa ser registrado 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 , esse parâmetro é o
O código que o Google recebeu do seu login ou da troca de tokens
endpoint do Google Cloud. |
redirect_uri |
Quando grant_type=authorization_code , esse parâmetro é o
URL usado na solicitação de autorização inicial. |
refresh_token |
Quando grant_type=refresh_token , esse parâmetro é o
token de atualização que o Google recebeu de seu endpoint de troca de token. |
Trocar códigos de autorização por tokens de acesso e de atualização
Depois que o usuário fizer login e o endpoint de autorização retornar um endereço de e-mail código de autorização ao Google, ele envia uma solicitação à troca de token para trocar o código de autorização por um token de acesso e uma atualização com base no token correto anterior.
Para essas solicitações, o valor de grant_type
é authorization_code
, e a
o valor de code
é o valor do código de autorização concedido anteriormente
para o Google. Veja a seguir um exemplo de solicitação para trocar um
código de autorização para 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 por um token de acesso e um token de atualização, seu
endpoint de troca de token responde a solicitações POST
executando o seguinte
etapas:
- Verifique se
client_id
identifica a origem da solicitação como origem e se oclient_secret
corresponde ao valor esperado. - 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 à código de autorização.
- Confirme se o URL especificado pelo parâmetro
redirect_uri
é idêntico ao valor usado na solicitação de autorização inicial. - Se não for possível verificar todos os critérios acima, retorne uma solicitação HTTP
Erro 400 Solicitação inválida com
{"error": "invalid_grant"}
como o corpo. - Caso contrário, use o ID do usuário do código de autorização para gerar uma atualização e um token de acesso. Esses tokens podem ser de qualquer valor de string, devem representar exclusivamente o usuário e o cliente a que o token se destina, e elas não pode ser adivinhado. Para tokens de acesso, registre também o tempo de expiração o token, que normalmente é uma hora após a emissão do token. Os tokens de atualização não expiram.
- 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 os tokens de acesso e de atualização do usuário e dos registros a expiração do token de acesso. Quando o token de acesso expira, o Google usa o token de atualização para receber um novo token de acesso do endpoint de troca de tokens.
Trocar tokens de atualização por tokens de acesso
Quando um token de acesso expira, o Google envia uma solicitação à troca de tokens endpoint para trocar um token de atualização por um novo token de acesso.
Para essas solicitações, o valor de grant_type
é refresh_token
, e o valor
de refresh_token
é o valor do token de atualização concedido anteriormente para
Google. Este é um exemplo de solicitação para trocar um token de atualização
para 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 de acesso, o endpoint de troca de token
responde a solicitações POST
executando as seguintes etapas:
- Verifique se
client_id
identifica a origem da solicitação como Google. se oclient_secret
corresponde ao valor esperado. - Verifique se o token de atualização é válido e se o ID do cliente especificado em a solicitação corresponde ao ID do cliente associado ao token de atualização.
- Se não for possível verificar todos os critérios acima, retorne um erro HTTP 400
Erro de solicitação inválido com
{"error": "invalid_grant"}
como o corpo. - Caso contrário, use o ID de usuário do token de atualização para gerar um acesso com base no token correto anterior. Esses tokens podem ser de qualquer valor de string, mas devem ser representam o usuário e o cliente a que o token se destina, e eles não devem ser pode ser adivinhado. Para tokens de acesso, registre também o tempo de expiração do token. geralmente uma hora após a emissão do token.
- Retorne o seguinte objeto JSON no corpo da solicitação
resposta:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
处理 userinfo 请求
userinfo 端点是受 OAuth 2.0 保护的资源,会返回关联用户的声明。实现和托管 userinfo 端点是可选的,但以下用例除外:
从您的令牌端点成功检索到访问令牌后,Google 会向您的 userinfo 端点发送请求,以检索关联用户的基本个人资料信息。
userinfo 端点请求标头 | |
---|---|
Authorization header |
Bearer 类型的访问令牌。 |
例如,如果您的 userinfo 端点可通过
https://myservice.example.com/userinfo
时,请求可能如下所示:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
为了让 userinfo 端点能够处理请求,请执行以下步骤:
- 从 Authorization 标头中提取访问令牌,并返回与访问令牌相关联的用户的信息。
- 如果访问令牌无效,则使用
WWW-Authenticate
响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应,该错误将无法恢复,检索到的令牌将被舍弃,并且用户必须重新开始关联流程。 如果访问令牌有效,则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回复:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
如果您的 userinfo 端点返回 HTTP 200 成功响应,则系统会针对用户的 Google 账号注册检索到的令牌和声明。userinfo 端点响应 sub
系统中用于识别用户的唯一 ID。 email
用户的电子邮件地址。 given_name
可选:用户的名字。 family_name
可选:用户的姓氏。 name
可选:用户的全名。 picture
可选:用户的个人资料照片。
Como validar a implementação
您可以使用 OAuth 2.0 Playground 工具验证您的实现。
在该工具中,执行以下步骤:
- 点击配置 以打开 OAuth 2.0 配置窗口。
- 在 OAuth flow 字段中,选择 Client-side(客户端)。
- 在 OAuth 端点字段中,选择自定义。
- 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
- 在第 1 步部分,不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围(如果您不使用 OAuth 范围,则可以输入任意字符串)。完成后,点击授权 API。
- 在 Step 2 和 Step 3 部分中,完成 OAuth 2.0 流程,并验证每个步骤是否按预期运行。
您可以使用 Google 账号关联演示版工具验证您的实现。
在该工具中,执行以下步骤:
- 点击使用 Google 账号登录按钮。
- 选择您要关联的账号。
- 输入服务 ID。
- (可选)输入您要请求访问权限的一个或多个范围。
- 点击开始演示。
- 当系统提示时,请确认您同意或拒绝关联请求。
- 确认您已被重定向到您的平台。