Vinculação da Conta do Google com o OAuth

As contas são vinculadas usando fluxos implícitos e de código de autorização do OAuth 2.0, que são padrões do setor.

Seu serviço precisa oferecer suporte a 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. Depois que o login é feito, você retorna um token de acesso de longa duração ao Google. Esse token de acesso agora 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 ao 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 de contas.
    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 o que ele tinha 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 por ele nunca expirem. Isso ocorre porque o usuário é forçado a vincular a conta novamente após a expiração de um token com o fluxo implícito. Se você precisar da expiração do token por motivos de segurança, recomendamos que use o fluxo do código de autorização.

Diretrizes de design

Esta seção descreve os requisitos e as recomendações de design para a tela do usuário hospedada para fluxos de vinculação do OAuth. Depois de ser chamado pelo app do Google, sua plataforma mostra uma página de login no Google e uma tela de consentimento de vinculação de contas ao usuário. O usuário é direcionado de volta ao app do Google depois de dar o 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, enquanto a terceira mostra o consentimento do usuário e a confirmação do usuário para vincular a Conta do Google ao seu app. A captura de tela final mostra uma conta de usuário vinculada com sucesso no app Google.
Figura 1. Login do usuário e telas de consentimento de vinculação de contas ao Google.

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. Mostrar a Política de Privacidade do Google Inclua um link para a Política de Privacidade do Google na tela de permissão.

  2. Dados a serem compartilhados. Use uma linguagem clara e concisa para informar ao usuário quais dados dele o Google exige e por quê.

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

  4. Capacidade de cancelar. Ofereça uma maneira para os usuários voltarem ou cancelarem, caso não queiram vincular.

  5. Processo de login claro. Garanta que os usuários tenham 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".

  6. Capacidade de desvincular. Ofereça um mecanismo para os usuários desvincularem, como um URL para as configurações da conta na sua plataforma. Como alternativa, você pode incluir um link para a Conta do Google, em que os usuários podem gerenciar a conta vinculada.

  7. Capacidade de mudar a conta de usuário. Sugira um método para os usuários trocarem as contas. Isso é especialmente útil se os usuários costumam ter várias contas.

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

  8. Incluir seu logotipo. Mostre o logotipo da sua empresa na tela de permissão. Use as diretrizes de estilo para posicionar o logotipo. Se você quiser ou precisar mostrar o logotipo do Google, consulte Logotipos e marcas registradas.

Criar o projeto

Para criar seu projeto para usar a vinculação de contas:

  1. Vá para o Console de APIs do Google.
  2. Clique em Criar projeto.
  3. Insira um nome ou aceite a sugestão gerada.
  4. Confirme ou edite os campos restantes.
  5. Clique em Criar.

Para conferir o ID do projeto:

  1. Vá para o Console de APIs do Google.
  2. Encontre seu projeto na tabela da página de destino. O ID do projeto aparece na ID coluna.

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

  1. Abra a página da 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 precisa da permissão. O nome precisa refletir com precisão o aplicativo e ser consistente com o nome que os usuários veem em outros lugares. O nome do aplicativo será mostrado na tela de permissão de 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 é mostrado na tela de permissão de vinculação de contas e nas configurações da conta

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

    Escopos para APIs Google:os escopos permitem que seu aplicativo acesse os dados do Google particulares do usuário. Para o caso de uso de vinculação de contas do Google, o escopo padrão (e-mail, perfil, openid) é suficiente. Não é necessário adicionar escopos sensíveis. 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 apenas que aplicativos autenticados usando o OAuth usem domínios autorizados. Os links dos seus aplicativos precisam ser hospedados em domínios autorizados. Saiba mais.

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

    Link da Política de Privacidade do aplicativo:mostrado na tela de permissão de vinculação de contas do Google. Precisa ser 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 permissão de vinculação de contas do Google para um aplicativo fictício, o Tunery

  4. Verifique o "Status da verificação". Se o aplicativo precisar de verificação, clique no botão "Enviar para verificação" para enviar o aplicativo. Consulte os requisitos de verificação do OAuth para mais detalhes.

Implementar o servidor OAuth

n

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

Google Account Linking: OAuth Implicit Flow

The following sequence diagram details interactions between the User, Google, and your service's endpoints.

User Google App / Browser Your Auth Endpoint 1. User initiates linking 2. Redirect to Auth Endpoint (GET) client_id, redirect_uri, state, scope 3. Display Sign-in & Consent Screen 4. User Authenticates & Grants Consent 5. Redirect back to Google with Token (GET) access_token, state 6. Store user tokens 7. Access user resources
Figure 1. The sequence of events in the OAuth 2.0 Implicit flow for Google Account Linking.

Roles and responsibilities

The following table defines the roles and responsibilities of actors in the Google Account Linking (GAL) OAuth Implicit flow. Note that in GAL, Google acts as the OAuth Client, while your service acts as the Identity/Service Provider.

Actor / Component GAL Role Responsibilities
Google App / Server OAuth Client Initiates the flow, receives the access token using a browser redirect, and securely stores it to access your service's APIs.
Your Authorization Endpoint Authorization Server Authenticates your users, obtains their consent, and issues long-lived access tokens directly to Google.
Google Redirect URI Callback Endpoint Receives the user redirect from your authorization service with the access_token and state values in the URL fragment.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
  2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
  3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking using an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.
user_locale The Google Account language setting in RFC5646 format used to localize your content in the user's preferred language.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: The access token you just generated
    • token_type: The string bearer
    • state: The unmodified state value from the original request

    The following is an example of the resulting URL: 

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

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:

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:

  1. Extrair o token de acesso do cabeçalho "Autorização" e retornar as informações do usuário associado ao token de acesso.
  2. 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.

  3. 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

Use a ferramenta OAuth 2.0 Playground para validar sua implementação.

Na ferramenta, siga estas etapas:

  1. Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
  2. No campo Fluxo do OAuth, selecione Do lado do cliente.
  3. No campo Endpoints OAuth, selecione Personalizado.
  4. Especifique seu endpoint OAuth 2.0 e o ID do cliente atribuído ao Google nos campos correspondentes.
  5. Na seção Etapa 1, não selecione nenhum escopo do Google. Em vez disso, deixe esse campo em branco ou digite um escopo válido para seu servidor (ou uma string arbitrária se você não usar escopos do OAuth). Quando terminar, clique em Autorizar APIs.
  6. Nas seções Etapa 2 e Etapa 3, siga o fluxo do OAuth 2.0 e verifique se cada etapa funciona como esperado.

Você pode validar sua implementação usando a ferramenta Demonstração da Vinculação da Conta do Google.

Na ferramenta, siga estas etapas:

  1. Clique no botão Fazer login com o Google.
  2. Escolha a conta que você quer vincular.
  3. Insira o ID do serviço.
  4. Se quiser, insira um ou mais escopos para os quais você vai solicitar acesso.
  5. Clique em Iniciar demonstração.
  6. Quando solicitado, confirme que você pode consentir e negar o pedido de vinculação.
  7. Confirme se você foi redirecionado para sua plataforma.