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.

Requisitos

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

1. Exibir a Política de Privacidade do Google. Incluir 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 informar ao usuário quais dados o Google exige e por quê.

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

4. Possibilidade de cancelamento. Ofereça uma maneira de voltar ou cancelar, se o usuário não quiser fazer a vinculação.

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

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

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

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

Criar o projeto

Para criar um projeto que use a vinculação de contas:

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 consentimento do OAuth

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

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

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

   Nome do aplicativo:o nome do aplicativo que solicita o consentimento. O nome deve refletir com precisão seu aplicativo e ser consistente com o nome do aplicativo que os usuários veem em outros lugares. O nome do aplicativo vai aparecer na tela de consentimento da vinculação de conta.

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

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

   Escopos das APIs do Google:permitem que seu aplicativo acesse os dados particulares do Google dos usuários. Para o caso 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 fazer isso de antemão. Saiba mais.

   Domínios autorizados:para proteger você e seus usuários, o Google só permite o uso de domínios autorizados por aplicativos autenticados com o OAuth. Os links dos seus aplicativos precisam ser hospedados em domínios autorizados. Saiba mais.

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

   Link da Política de Privacidade do app:aparece na tela de consentimento da vinculação da Conta 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 para vinculação da Conta do Google de um app fictício, Tunery

4. Marque o "Status de verificação" se a inscrição precisar ser verificada, em seguida, clique no botão "Enviar para verificação". Consulte os requisitos de verificação do OAuth para mais detalhes.

Implementar seu servidor OAuth

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.

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 via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

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.

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.

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:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. 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.

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

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign-in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.