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.

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

In the authorization code flow, you need two endpoints:

The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.
The token exchange endpoint, which is responsible for two types of exchanges:
1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

This figure shows the steps for a user to link their Google account
to your authentication system. The first screenshot shows
user-initiated linking from your platform. The second image shows
user sign-in to Google, while the third shows the user consent and
confirmation for linking their Google account with your app. The
final screenshot shows a successfully linked user account in the
Google app. — **Figure 1.** Account linking user sign in to Google and consent screens.

Requirements

You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.
Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.
Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.
Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.
Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.
- If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.
Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

Criar o projeto

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

Clique em Criar projeto.
Digite um nome ou aceite a sugestão gerada.
Confirme ou edite os campos restantes.
Clique em Criar.

Para conferir o ID do projeto:

Encontre seu projeto na tabela da 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, o tipo de dados que está sendo pedido e os termos aplicáveis. É necessário configurar a tela de consentimento do OAuth antes de gerar um ID do cliente da API do Google.

Abra a página Tela de consentimento OAuth no console de APIs do Google.
Se solicitado, selecione o projeto que você acabou de criar.
Na página "Tela de consentimento 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 seu aplicativo e ser consistente com o nome que os usuários veem em outros lugares. O nome do aplicativo vai aparecer na tela de consentimento da vinculação de contas.

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

E-mail de suporte:para que os usuários entrem em contato com você a respeito do consentimento.

Escopos para APIs do Google:os escopos permitem que seu aplicativo acesse os dados particulares do Google do usuário. Para o caso de uso da vinculação de Conta 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 antecipadamente. Saiba mais.

Domínios autorizados:para proteger você e seus usuários, o Google permite apenas que aplicativos que autenticam 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 consentimento da vinculação de Contas do Google. Precisa ser hospedado em um domínio autorizado.

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

Figura 1. Tela de consentimento para vinculação de contas do Google para um aplicativo fictício, o Tunery
Verifique o "Status da verificação". Se o aplicativo precisar de verificação, clique no botão "Enviar para verificação". Consulte os requisitos de verificação do OAuth para mais detalhes.

Implementar seu servidor OAuth

Uma implementação do servidor OAuth 2.0 do fluxo do código de autorização consiste em: dois endpoints, que seu serviço disponibiliza por HTTPS. O primeiro endpoint é o endpoint de autorização, responsável por encontrar ou conseguir o consentimento dos usuários para acesso aos dados. O endpoint de autorização apresenta uma interface de login para os usuários que ainda não estão conectados e registra o consentimento para o acesso solicitado. O segundo endpoint é a troca de tokens, é usado para obter strings criptografadas, chamadas de tokens, que autorizam um usuário a para acessar seu serviço.

Quando um aplicativo do Google precisa chamar uma das APIs do seu serviço, o Google usa esses endpoints juntos para conseguir a permissão dos usuários para chamar essas APIs em nome deles.

Uma sessão do fluxo do código de autorização do OAuth 2.0 iniciada pelo Google tem seguinte fluxo:

O Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo iniciada em um dispositivo somente de voz para uma ação, o Google transfere a execução em um smartphone.
Caso ainda não tenha feito login, o usuário faz login 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 código de autorização e o retorna ao Google. Afazeres Por isso, redirecione o navegador do usuário de volta para o Google com o código de autorização anexada à solicitação.
O Google envia o código de autorização para seu endpoint de troca de token, verifica a autenticidade do código e retorna um token de acesso e um token de atualização. 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 atualização token que o Google pode armazenar e usar para adquirir novos tokens de acesso e depois ela expira.
Depois que o usuário tiver concluído o fluxo de vinculação à conta, todas as solicitação enviada pelo Google contém um token de acesso.

Processar solicitações de autorização

Quando você precisa vincular a conta usando o código de autorização do OAuth 2.0. fluxo, o Google envia o usuário para 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 Client-ID 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.
`scope`	Opcional:um conjunto delimitado por espaços de strings de escopo que especifica o dados para os quais o Google está solicitando autorização.
`response_type`	O tipo de valor a ser retornado na resposta. Para a solicitação OAuth 2.0, fluxo do código de autorização, o tipo de resposta será sempre `code`.
`user_locale`	A configuração de idioma da Conta do Google no RFC5646 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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

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

Verifique se o client_id corresponde ao ID do cliente atribuído ao Google e se o redirect_uri corresponde ao URL de redirecionamento fornecido pelo Google para seu serviço. Essas verificações são importantes para impedir a concessão o acesso a apps clientes não intencionais ou configurados incorretamente. Se você oferece suporte a vários Fluxos do OAuth 2.0. Confirme também se o response_type é code.
Verifique se o usuário está conectado ao seu serviço. Se o usuário não estiver conectado, para concluir o fluxo de login ou inscrição do serviço.
Gere um código de autorização para o Google usar no acesso à API. O código de autorização pode ser qualquer valor de string, mas deve ser representar o usuário, o cliente a que o token se destina e a expiração do código tempo de resposta e não deve ser adivinhado. Você normalmente emite uma autorização que expiram após aproximadamente 10 minutos.

Confirme se o URL especificado pelo parâmetro 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

Redirecione o navegador do usuário para o URL especificado pelo parâmetro redirect_uri. Inclua o código de autorização que você e o valor do estado original e inalterado ao redirecionar anexando os parâmetros code e state. Confira a seguir exemplo do URL resultante:
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
```

Processar solicitações de troca de token

O endpoint de troca de token do seu serviço é responsável por dois tipos de token trocas:

Trocar códigos de autorização por tokens de acesso e de atualização
Trocar tokens de atualização por 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 o Google. Essa string precisa ser registrado 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. É `authorization_code` ou `refresh_token`.
`code`	Quando `grant_type=authorization_code`, esse parâmetro é o O código que o Google recebeu do seu login ou da troca de tokens endpoint do Google Cloud.
`redirect_uri`	Quando `grant_type=authorization_code`, esse parâmetro é o URL usado na solicitação de autorização inicial.
`refresh_token`	Quando `grant_type=refresh_token`, esse parâmetro é o token de atualização que o Google recebeu de seu endpoint de troca de token.

Trocar códigos de autorização por tokens de acesso e de atualização

Depois que o usuário fizer login e o endpoint de autorização retornar um endereço de e-mail código de autorização ao Google, ele envia uma solicitação à troca de token para trocar o código de autorização por um token de acesso e uma atualização com base no token correto anterior.

Para essas solicitações, o valor de grant_type é authorization_code, e a o valor de code é o valor do código de autorização concedido anteriormente para o Google. Veja a seguir um exemplo de solicitação para trocar um código de autorização para 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 códigos de autorização por um token de acesso e um token de atualização, seu endpoint de troca de token responde a solicitações POST executando o seguinte etapas:

Verifique se client_id identifica a origem da solicitação como origem e se o client_secret corresponde ao valor esperado.
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 à código de autorização.
Confirme se o URL especificado pelo parâmetro redirect_uri é idêntico ao valor usado na solicitação de autorização inicial.
Se não for possível verificar todos os critérios acima, retorne uma solicitação HTTP Erro 400 Solicitação inválida com {"error": "invalid_grant"} como o corpo.
Caso contrário, use o ID do usuário do código de autorização para gerar uma atualização e um token de acesso. Esses tokens podem ser de qualquer valor de string, devem representar exclusivamente o usuário e o cliente a que o token se destina, e elas não pode ser adivinhado. Para tokens de acesso, registre também o tempo de expiração o token, que normalmente é uma hora após a emissão do token. Os tokens de atualização não expiram.

Retorne 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 os tokens de acesso e de atualização do usuário e dos registros a expiração do token de acesso. Quando o token de acesso expira, o Google usa o token de atualização para receber um novo token de acesso do endpoint de troca de tokens.

Trocar tokens de atualização por tokens de acesso

Quando um token de acesso expira, o Google envia uma solicitação à troca de tokens endpoint para trocar um token de atualização por um novo token de acesso.

Para essas solicitações, o valor de grant_type é refresh_token, e o valor de refresh_token é o valor do token de atualização concedido anteriormente para Google. Este é um exemplo de solicitação para trocar um token de atualização para 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 um token de atualização por um de acesso, o endpoint de troca de token responde a solicitações POST executando as seguintes etapas:

Verifique se client_id identifica a origem da solicitação como Google. se o client_secret corresponde ao valor esperado.
Verifique se o token de atualização é válido e se o ID do cliente especificado em a solicitação corresponde ao ID do cliente associado ao token de atualização.
Se não for possível verificar todos os critérios acima, retorne um erro HTTP 400 Erro de solicitação inválido com {"error": "invalid_grant"} como o corpo.
Caso contrário, use o ID de usuário do token de atualização para gerar um acesso com base no token correto anterior. Esses tokens podem ser de qualquer valor de string, mas devem ser representam o usuário e o cliente a que o token se destina, e eles não devem ser pode ser adivinhado. Para tokens de acesso, registre também o tempo de expiração do token. geralmente uma hora após a emissão do token.

Retorne o seguinte objeto JSON no corpo da solicitação resposta:

{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

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

É possível validar sua implementação usando a ferramenta OAuth 2.0 Playground.

Na ferramenta, siga estas etapas:

Clique em Configuração para abrir a janela de configuração do OAuth 2.0.
No campo Fluxo do OAuth, selecione Lado do cliente.
No campo Endpoints OAuth, selecione Personalizado.
Especifique o endpoint OAuth 2.0 e o ID do cliente atribuído ao Google nos campos correspondentes.
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.
Nas seções Etapa 2 e Etapa 3, siga o fluxo OAuth 2.0 e verifique se cada etapa funciona conforme o esperado.

É possível validar sua implementação usando a ferramenta Demo de vinculação de Contas do Google.