Esta página foi traduzida pela API Cloud Translation.

Vinculação da Conta do Google com o OAuth

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:
1. 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.
2. 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.

Esta figura mostra as etapas para um usuário vincular a Conta do Google
ao seu sistema de autenticação. A primeira captura de tela mostra a vinculação iniciada pelo usuário na sua plataforma. A segunda imagem mostra o login do usuário no Google, e a terceira mostra o consentimento e a confirmação do usuário para vincular a Conta do Google ao seu app. A última captura de tela mostra uma conta de usuário vinculada no app Google. — **Figura 1.** Telas de login do usuário e de vinculação de contas ao Google.

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.

创建项目

如需创建使用账号关联的项目，请执行以下操作：

点击 Create project。
输入名称或接受生成的建议。
确认或修改所有剩余字段。
点击创建。

如需查看项目 ID，请执行以下操作：

在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

配置 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

Para oferecer suporte ao fluxo implícito do OAuth 2.0, seu serviço faz uma autorização de destino disponível por HTTPS. Esse endpoint é responsável pela autenticação e obter consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma interface de login aos usuários que ainda não estão conectados e registra consentir com o acesso solicitado.

Quando um aplicativo do Google precisar chamar uma das APIs autorizadas do seu serviço, O Google usa esse endpoint para receber permissão dos usuários e chamar essas APIs em nome deles.

Uma sessão de fluxo implícito do OAuth 2.0 típica iniciada pelo Google tem o seguinte fluxo:

O Google abre seu endpoint de autorização no navegador do usuário. A o usuário faz login, caso ainda não tenha feito, 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 token de acesso e o retorna para Google. Para fazer isso, redirecione o navegador do usuário de volta para o Google com o acesso token anexado à solicitação.
O Google chama as APIs do seu serviço e anexa o token de acesso com cada solicitação. O serviço verifica se o token de acesso concede ao Google autorização para acessar a API e, em seguida, conclui a chamada de API.

Processar solicitações de autorização

Quando um aplicativo do Google precisa vincular uma conta usando um OAuth 2.0. fluxo implícito, o Google envia o usuário para seu endpoint de autorização com um que inclua os seguintes parâmetros:

Parâmetros de endpoint de autorização
`client_id`	O ID do cliente 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.
`response_type`	O tipo de valor a ser retornado na resposta. Para a implementação implícita do OAuth 2.0 fluxo, o tipo de resposta será sempre `token`.
`user_locale`	A configuração de idioma da Conta do Google no RFC5646 formato 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&response_type=token&user_locale=LOCALE

Para que o endpoint de autorização processe solicitações de login, faça o seguinte: etapas:

Verifique os valores client_id e redirect_uri para impedir a concessão de acesso a apps clientes não intencionais ou configurados incorretamente:
- Confirme se o client_id corresponde ao ID do cliente que você atribuídas ao Google.
- Confirme se o URL especificado pelo 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
```
Verifique se o usuário está conectado ao seu serviço. Se o usuário não tiver feito login conclua o fluxo de login ou inscrição do serviço.
Gere um token de acesso para o Google acessar sua API. A token de acesso pode ser qualquer valor de string, mas deve representar exclusivamente o usuário e o cliente a que o token se destina e não pode ser adivinhado.
Envia uma resposta HTTP que redireciona o navegador do usuário para o URL especificado pelo parâmetro redirect_uri. Inclua todos os elementos parâmetros a seguir no fragmento de URL:
- access_token: o token de acesso que você acabou de gerar
- token_type: a string bearer
- state: o valor de estado não modificado do original. solicitação
Veja a seguir um exemplo de URL resultante:
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
```

O gerenciador de redirecionamento do OAuth 2.0 do Google recebe o token de acesso e confirma que o valor state não mudou. Depois que o Google tiver token de acesso do seu serviço, o Google o anexa às chamadas subsequentes às APIs de serviço.

Processar solicitações userinfo

O endpoint userinfo é um recurso protegido pelo OAuth 2.0 que retorna declarações sobre o usuário vinculado. A implementação e hospedagem do endpoint userinfo é opcional, exceto nos seguintes casos de uso:

Login da conta vinculada com o Google One Tap.
Assinatura sem atrito no AndroidTV.

Depois que o token de acesso for recuperado do endpoint do token, o Google enviará uma solicitação ao endpoint de informações do usuário para recuperar informações básicas de perfil sobre o usuário vinculado.

cabeçalhos de solicitação do endpoint userinfo
`Authorization header`	O token de acesso do tipo Bearer.

Por exemplo, se seu ponto de extremidade de informações do usuário estiver disponível em https://myservice.example.com/userinfo, uma solicitação terá esta aparência:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Para que o endpoint userinfo processe solicitações, siga estas etapas:

Extrair o token de acesso do cabeçalho "Autorização" e retornar as informações do usuário associado ao token de acesso.
Se o token de acesso for inválido, retorne o erro "HTTP 401 Unused" ao usar o cabeçalho de resposta WWW-Authenticate. Veja abaixo um exemplo de resposta de erro userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Se uma resposta de erro "401 Não autorizado" ou outra resposta de erro for retornada durante o processo de vinculação, o erro não poderá ser recuperado, o token recuperado será descartado e o usuário terá que iniciar o processo de vinculação novamente.

Se o token de acesso for válido, retorne uma resposta HTTP 200 com o seguinte objeto JSON no corpo do HTTPS resposta:

{
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}

Se o seu endpoint de informações do usuário retornar uma resposta HTTP 200 bem-sucedida, o token e as reivindicações recuperados serão registrados na Conta do Google do usuário.

resposta do endpoint userinfo
`sub`	Um ID exclusivo que identifica o usuário no seu sistema.
`email`	Endereço de e-mail do usuário.
`given_name`	Opcional:nome do usuário.
`family_name`	Opcional:sobrenome do usuário.
`name`	Opcional:o nome completo do usuário.
`picture`	Opcional:foto do perfil do usuário.

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 账号关联演示版工具验证您的实现。