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:
- 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.
- 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.
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.
![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 para vincular a Conta do Google dele ao seu app. A
captura de tela final mostra uma conta de usuário vinculada com sucesso no
Google app.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/images/oauth-linking-flow.png?authuser=7&hl=pt)
Requisitos
- 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:
Exibir a Política de Privacidade do Google. Inclua 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 dizer ao usuário quais dados o Google exige e por quê.
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.
Opção de cancelamento. Ofereça aos usuários a opção de voltar ou cancelar.
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.
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.
É 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.
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.
![Esta figura mostra exemplos de telas de login e consentimento do usuário com
chamadas para os requisitos e recomendações individuais que
serão seguidas quando você criar uma tela de login e consentimento do usuário.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/images/oauth-linking-consent.png?authuser=7&hl=pt)
Criar o projeto
Para criar seu projeto e usar a vinculação de contas, faça o seguinte:
- Go to the Google API Console.
- Clique em Criar projeto .
- Digite um nome ou aceite a sugestão gerada.
- Confirme ou edite os campos restantes.
- Clique em Create .
Para visualizar o seu ID do projeto:
- Go to the Google API Console.
- 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.
- Abra a página Tela de permissão OAuth do Console de APIs do Google.
- Se solicitado, selecione o projeto que você acabou de criar.
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
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
Para suportar o fluxo implícita OAuth 2.0, o serviço faz uma endpoint autorização disponíveis por HTTPS. Este endpoint é responsável pela autenticação e obtenção do 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.
Quando um aplicativo do Google precisa chamar uma das APIs autorizadas do seu serviço, o Google usa esse ponto de extremidade para obter permissão dos usuários para chamar essas APIs em seu nome.
Uma sessão típica de fluxo implícito OAuth 2.0 iniciada pelo Google tem o seguinte fluxo:
- O Google abre seu endpoint de autorização no navegador do usuário. 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.
- Seu serviço cria um token de acesso e retorna-lo ao Google. Para fazer isso, redirecione o navegador do usuário de volta ao Google com o token de acesso anexado à solicitação.
- O Google chama suas APIs de serviço e anexa o token de acesso a cada solicitação. Seu serviço verifica se o token de acesso concede autorização ao Google para acessar a API e, em seguida, conclui a chamada da API.
Lidar com solicitações de autorização
Quando um aplicativo do Google precisa realizar a vinculação de contas por meio de um fluxo implícito 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. |
response_type | O tipo de valor a ser retornado na resposta. Para o fluxo implícito OAuth 2.0, o tipo de resposta está sempre token . |
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&response_type=token&user_locale=LOCALE
Para que seu endpoint de autorização processe solicitações de login, execute as seguintes etapas:
Verifique as
client_id
eredirect_uri
valores para evitar conceder acesso a aplicativos cliente não intencionais ou mal configurados:- Confirme se o
client_id
corresponde ao ID do cliente que você atribuiu ao Google. - 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
- Confirme se o
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.
Gere um token de acesso para o Google usar para acessar sua API. O token de acesso pode ser qualquer valor de string, mas deve representar exclusivamente o usuário e o cliente ao qual o token se destina e não pode ser adivinhado.
Enviar uma resposta HTTP que redireciona o navegador do usuário para o URL especificado pelo
redirect_uri
parâmetro. Inclua todos os seguintes parâmetros no fragmento de URL:-
access_token
: O token de acesso que você acabou de gerar -
token_type
: A seqüência debearer
-
state
: O valor estado não modificado a partir da solicitação original
O que se segue é um exemplo do URL resultante:
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
-
Manipulador de redirecionamento do Google OAuth 2.0 recebe o token de acesso e confirma que o state
valor não mudou. Depois que o Google obtém um token de acesso para o seu serviço, o Google anexa o token às chamadas subsequentes para as APIs do seu serviço.
Handle userinfo requests
The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:
- Linked Account Sign-In with Google One Tap.
- Frictionless subscription on AndroidTV.
After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.
userinfo endpoint request headers | |
---|---|
Authorization header |
The access token of type Bearer. |
For example, if your userinfo endpoint is available at
https://myservice.example.com/userinfo
, a request might look like the following:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
For your userinfo endpoint to handle requests, do the following steps:
- Extract access token from the Authorization header and return information for the user associated with the access token.
- If the access token is invalid, return an HTTP 401 Unauthorized error with using the
WWW-Authenticate
Response Header. Below is an example of a userinfo error response:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.userinfo endpoint response sub
A unique ID that identifies the user in your system. email
Email address of the user. given_name
Optional: First name of the user. family_name
Optional: Last name of the user. name
Optional: Full name of the user. picture
Optional: Profile picture of the user.
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.