Vinculação de Conta do Google com OAuth

As contas são vinculadas usando fluxos implícitos e de código de autorização padrão do setor 2.0. Seu serviço precisa ser compatível com endpoints de autorização e troca de tokens 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 ao Google. Agora, esse token de acesso está incluído em todas as solicitações enviadas do Google.

No fluxo de código de autorização, você precisa de dois endpoints:

• o endpoint de autorização, que apresenta a IU de login aos seus 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 usuários e consentir com o acesso solicitado.

• O endpoint de troca de token, 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 da conta.
  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 ele 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.

Observação: use os botões a seguir para escolher qual fluxo do OAuth 2.0 você quer implementar. Se necessário, o conteúdo deste guia será atualizado para corresponder à sua escolha.

Fluxo implícito Código de autorização

Diretrizes de design

Esta seção descreve os requisitos de projeto e as recomendações para a tela do usuário hospedada para fluxos de vinculação do OAuth. Depois de ser chamado pelo app do Google, sua plataforma exibe um login na página do Google e na tela de consentimento de vinculação da conta ao usuário. O usuário é redirecionado de volta ao app do Google depois de autorizar a vinculação das contas.

Figura 1. Login do usuário: login na conta do Google e telas de consentimento.

Requisitos

1. Você precisa 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

Portanto, 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 dizer ao usuário quais dados o Google exige e por quê.

3. Call-to-action clara. Insira uma call-to-action clara na tela de consentimento, como "Aceitar e vincular". Isso ocorre porque os usuários precisam entender quais dados eles precisam compartilhar com o Google para vincular as contas.

4. Opção de cancelamento. Ofereça aos usuários a opção de voltar ou cancelar.

5. Limpar o processo de login. Verifique se os usuários têm um método claro para fazer login na Conta do Google, como campos de nome de usuário e senha ou Fazer login com o Google.

6. Capacidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta na plataforma. Se preferir, inclua um link para a Conta do Google em que os usuários possam gerenciar a conta vinculada.

7. É possível mudar a conta de usuário. Sugerir um método para os usuários trocarem de conta. Isso é útil principalmente quando os usuários costumam ter várias contas.

   • Se um usuário precisar fechar a tela de consentimento para alternar entre contas, envie um erro recuperável ao Google para que o usuário possa fazer login na conta desejada com vinculação do OAuth e o fluxo implícito.

8. Inclua seu logotipo. Exiba o logotipo da sua empresa na tela de consentimento. Use suas diretrizes de estilo para inserir o logotipo. Se você também quiser exibir o logotipo do Google, consulte Logotipos e marcas registradas.

Figura 2. Diretrizes de design para o login de usuários no Google e em telas de consentimento.

Criar o projeto

Observação :é possível reutilizar um projeto atual sem precisar criar um novo principalmente para vincular contas.

Para criar seu projeto e usar a vinculação de contas, faça o seguinte:

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 .

Configurar a tela de permissão OAuth

O processo de vinculação de Contas do Google inclui uma tela de consentimento que informa aos usuários o aplicativo que está solicitando acesso aos dados deles, o tipo de dado solicitado e os termos aplicáveis. Você precisa configurar a tela de permissão OAuth antes de gerar um ID do cliente da API do Google.

1. Abra a página Tela de permissão OAuth do Console de APIs do Google.
2. Se solicitado, selecione o projeto que você acabou de criar.

3. Na página "Tela de permissão OAuth", preencha o formulário e clique no botão "Salvar".

   Nome do aplicativo: o nome do aplicativo que está solicitando o consentimento. O nome precisa refletir com precisão o aplicativo e ser consistente com o nome do aplicativo que os usuários veem em outros lugares. O nome do aplicativo vai ser mostrado na tela de permissão da vinculação de contas.

   Logotipo do aplicativo:uma imagem na tela de permissão que ajuda os usuários a reconhecer seu app. O logotipo é exibido na tela de permissão para vinculação de contas e nas configurações da conta.

   E-mail de suporte:para os usuários entrarem em contato com você para esclarecer dúvidas sobre o consentimento.

   Escopos para APIs do Google:os escopos permitem que seu aplicativo acesse os dados particulares do usuário do Google. Para o caso de uso de vinculação de Conta do Google, o escopo padrão (e-mail, perfil, OpenID) é suficiente. Não é necessário adicionar escopos confidenciais. Geralmente, é uma prática recomendada solicitar escopos de forma incremental no momento em que o acesso é necessário, em vez de antecipadamente. Saiba mais.

   Domínios autorizados:para proteger você e seus usuários, o Google permite que apenas aplicativos com autenticação OAuth usem os domínios autorizados. Os links dos seus aplicativos precisam estar hospedados em domínios autorizados. Saiba mais.

   Link da página inicial do aplicativo: página inicial do seu aplicativo. Precisa estar hospedado em um domínio autorizado.

   Link da Política de Privacidade do aplicativo:aparece na tela de permissão para vinculação de Contas do Google. Precisa estar hospedado em um domínio autorizado.

   Link dos Termos de Serviço do aplicativo (opcional): precisa ser hospedado em um domínio autorizado.

   

   Figura 1. Tela de consentimento de vinculação de Conta do Google para um aplicativo fictício, o Tunery

4. Marque o "Status da verificação" se o seu aplicativo precisar de verificação e clique no botão "Enviar para verificação" para enviá-lo para verificação. Consulte os requisitos de verificação do OAuth para ver mais detalhes.

Implementar o servidor OAuth

Um OAuth implementação de servidor 2.0 do fluxo de código de autorização consiste em dois pontos finais, que o 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 cadeias de caracteres criptografadas, chamadas de 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 pontos de extremidade 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 tiver feito, e concede ao Google permissão para acessar seus dados com sua API, caso ainda não tenha concedido permissão.
3. Seu serviço cria um código de autorização e devolve-lo 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. Google envia o código de autorização para o seu endpoint troca simbólica, que verifica a autenticidade do código e retorna um token e uma atualização de token de acesso. 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 do cliente que você atribuiu ao 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 delimitada por espaços de cordas de escopo que especificam os dados do Google está solicitando autorização para.
response_type	O tipo de valor a ser retornado na resposta. Para o código de autorização OAuth fluxo 2.0, o tipo de resposta é sempre code .
user_locale	A configuração de idioma Conta do Google em RFC5646 formato, usado para localizar o seu conteúdo no idioma de preferência do usuário.

Por exemplo, se o seu endpoint de autorização está disponível no https://myservice.example.com/auth , um pedido pode parecer o seguinte:

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 o client_id corresponde ao ID do cliente que você atribuiu ao Google, e que o 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ê suportar múltiplos OAuth fluxos de 2,0, também confirmam que o response_type é 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 pode ser adivinhado. Normalmente, você emite códigos de autorização que expiram após aproximadamente 10 minutos.
4. Confirme se o URL especificado pelo redirect_uri parâmetro tem a seguinte forma:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. Redirecionar o navegador do usuário para o URL especificado pelo redirect_uri parâmetro. Incluir o código de autorização que você acabou de gerar e original, valor estado não modificado quando você redirecionar anexando os code e state parâmetros. O que se segue é 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. É tanto authorization_code ou refresh_token .
code	Quando grant_type=authorization_code , este parâmetro é o código do Google recebeu a partir do seu início de sessão ou token de endpoint de câmbio.
redirect_uri	Quando grant_type=authorization_code , este parâmetro é o URL usado no pedido de autorização inicial.
refresh_token	Quando grant_type=refresh_token , este parâmetro é o token de atualização Google recebeu do seu endpoint troca simbólica.

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 estes pedidos, o valor de grant_type é authorization_code , eo valor de code é o valor do código de autorização anteriormente concedida 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 os códigos de autorização para um token de acesso e um token de atualização, seu token responde endpoint Exchange para POST solicitações executando os seguintes passos:

1. Verifique se os client_id identifica a origem do pedido como uma origem autorizada, e que 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 o URL especificado pelo redirect_uri parâmetro é idêntico ao valor utilizado no pedido de autorização inicial.
4. Se você não pode verificar todos os critérios acima, retornar um pedido inválido de erro HTTP 400 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 devem 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. Retornaria 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 uma atualização de token para um token de acesso, o token responde endpoint Exchange para POST solicitações executando os seguintes passos:

1. Verifique se os client_id identifica a origem do pedido, como Google, e que o 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 pode verificar todos os critérios acima, retornar um pedido inválido de erro HTTP 400 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 devem 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
   }

Nota: Você pode opcionalmente retornar um novo refresh_token em sua resposta. Para mais informações sobre quando retornar um novo refresh_token é o preferido, consulte Trabalho com símbolos .

Lidar com solicitações de informações do usuário

O ponto final userinfo é um recurso protegido OAuth 2.0 que reivindicações de retorno sobre o utilizador ligado. Implementar e hospedar o endpoint userinfo é opcional, exceto para os seguintes casos de uso:

• Linked Conta Entrar com o Google One Tap.
• Assinatura sem atrito em AndroidTV.

Depois que o token de acesso for recuperado com êxito de seu endpoint de token, o Google envia uma solicitação ao endpoint de userinfo para recuperar informações básicas de perfil sobre o usuário vinculado.

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

Por exemplo, se o seu userinfo endpoint está disponível em https://myservice.example.com/userinfo , um pedido pode parecer o seguinte:

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

Para que seu endpoint userinfo lide com solicitações, execute as seguintes etapas:

1. Extraia o token de acesso do cabeçalho de autorização e retorne as informações do usuário associado ao token de acesso.
2. Se o token de acesso é inválido, retornará um erro não autorizado HTTP 401 com o uso do WWW-Authenticate cabeçalho de resposta. Abaixo está um exemplo de uma resposta de erro userinfo:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Se um 401 Unauthorized, ou qualquer outro tipo de resposta de erro vencida é devolvido durante o processo de ligação, o erro será não-recuperável, o token recuperado será descartado e o utilizador terá para iniciar o processo de vinculação novamente.

3. Se o token de acesso é válido, de retorno e resposta HTTP 200 com o seguinte objeto JSON no corpo da resposta HTTPS:

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

   Se o seu userinfo endpoint retorna uma resposta sucesso HTTP 200, o recuperado token e reivindicações são registradas contra a Google do usuário conta.

   resposta do endpoint userinfo
   sub	Um ID exclusivo que identifica o usuário em seu sistema.
   email	Endereço de e-mail do usuário.
   given_name	Opcional: Primeiro nome do usuário.
   family_name	Opcional: Último nome do usuário.
   name	Opcional: nome completo do usuário.
   picture	Foto do perfil do usuário: opcional.

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:

1. Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
2. No campo de fluxo OAuth, selecione do lado do cliente.
3. No campo OAuth Endpoints, 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 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.
6. 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:

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