Implementar um servidor OAuth 2.0

Cada integração com Cloud-to-cloud precisa incluir um mecanismo para autenticar usuários.

A autenticação permite vincular as Contas do Google dos usuários às contas de usuário no seu sistema de autenticação. Isso permite identificar os usuários quando o fulfillment recebe uma intent de casa inteligente. A casa inteligente do Google só oferece suporte ao OAuth com um fluxo de código de autorização.

Esta página descreve como configurar seu servidor OAuth 2.0 para que ele funcione com a integração Cloud-to-cloud.

Vinculação de contas do Google com o OAuth

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 usuários que ainda não se conectaram. 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 tokens, 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 o que expirou.

Diretrizes de design

Nesta seção, descrevemos os requisitos e as recomendações de design para a tela do usuário que você hospeda para fluxos de vinculação do OAuth. Depois de ser chamado pelo app do Google, sua plataforma exibe ao usuário uma página de login na página do Google e uma tela de consentimento de vinculação de contas. O usuário é direcionado de volta ao app do Google após dar o consentimento para vincular as contas.

Requisitos

1. Informe que a conta do usuário será vinculada ao Google, e não a um produto específico do Google, como o Google Home ou o Google Assistente.
2. É necessário ter uma declaração de autorização do Google, como "Ao fazer login, você autoriza o Google a controlar seus dispositivos". Consulte a seção "Autorização de controle de dispositivos Google" das políticas para desenvolvedores do Google Home.
3. Ofereça uma maneira de os usuários retornarem ou cancelarem a assinatura, caso decidam não vincular.
4. Você precisa abrir a página de vinculação do OAuth da Web e garantir que os usuários tenham um método claro para fazer login na Conta do Google, como campos para o nome de usuário e a senha. Não use o método de Login do Google (GSI) que permite que os usuários se vinculem sem serem direcionados para a página de vinculação do OAuth da Web. Isso é uma violação da política do Google.

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

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

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

4. Possibilidade de desvinculação. Ofereça um mecanismo para os usuários se desvincularem, como um URL para as configurações da conta deles na sua plataforma. Outra opção é incluir um link para a Conta do Google, em que os usuários podem gerenciar a conta vinculada.

5. Possibilidade de mudar a conta de 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 entre contas, envie um erro recuperável ao Google para que ele possa fazer login na conta desejada com a vinculação do OAuth.

6. Inclua seu logotipo. Exibir o logotipo da sua empresa na tela de permissão. Use suas diretrizes de estilo para posicionar o logotipo. Se você também quiser exibir o logotipo do Google, consulte Logotipos e marcas registradas.

Fluxo do código de autorização

Uma implementação de servidor OAuth 2.0 do fluxo de código de autorização consiste em dois endpoints, que seu serviço disponibiliza por HTTPS. O primeiro endpoint é o de autorização, que é responsável por encontrar ou receber o consentimento dos usuários para acessar dados. O endpoint de autorização apresenta uma interface de login para os usuários que ainda não fizeram login e registra o consentimento para o acesso solicitado. O segundo endpoint é o de troca de token, que é usado para receber strings 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 endpoints juntos para receber 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 o seguinte fluxo:

1. O Google abre o endpoint de autorização no navegador do usuário. Se o fluxo for iniciado em um dispositivo somente por voz para uma ação, o Google transferirá a execução para um smartphone.
2. O usuário faz login, se ainda não tiver feito isso, e concede ao Google permissão para acessar os dados dele com sua API, se ainda não tiver concedido.
3. Seu serviço cria um código de autorização e o retorna 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. O Google envia o código de autorização para o endpoint de troca de token, que 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 longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando eles expiram.
5. Depois que o usuário concluir o fluxo de vinculação de contas, todas as solicitações posteriores enviadas pelo Google vão conter um token de acesso.

Processar solicitações de autorização

Quando você precisa vincular uma conta usando o fluxo de código de autorização do OAuth 2.0, o Google envia o usuário ao endpoint de autorização com uma solicitação que inclui os seguintes parâmetros:

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação poderá ser semelhante a esta:

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, siga estas etapas:

1. 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 evitar o acesso a apps de cliente não intencionais ou configurados incorretamente. Se você oferece suporte a vários fluxos OAuth 2.0, confirme também se o response_type é code.
2. Verifique se o usuário fez login no serviço. Se o usuário não tiver feito login, conclua o fluxo de login ou inscrição do 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 precisa representar exclusivamente o usuário, o cliente para o qual o token é destinado e o tempo de expiração do código. Ele não pode ser adivinhável. Normalmente, você emite códigos de autorização que expiram após aproximadamente 10 minutos.
4. 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
     

5. Redireciona o navegador do usuário para o URL especificado pelo parâmetro redirect_uri. Inclua o código de autorização que você acabou de gerar e o valor de estado original e não modificado ao redirecionar anexando os parâmetros code e state. Confira abaixo um 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 trocas de token:

• 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:

Configurar como o Google envia credenciais para seu servidor

Dependendo da implementação, o servidor de autorização espera receber as credenciais do cliente no corpo da solicitação ou no cabeçalho da solicitação.

Por padrão, o Google envia as credenciais no corpo da solicitação. Se o servidor de autorização exigir que as credenciais do cliente estejam no cabeçalho da solicitação, configure a integração Cloud-to-cloud da seguinte maneira:

Acessar o console do desenvolvedor

1. Na lista de projetos, clique em Abrir ao lado do projeto com que você quer trabalhar.

2. Em Da nuvem para a nuvem, selecione Desenvolver.

3. Clique em Abrir ao lado da integração.

4. Role para baixo até a seção Permissões (opcional) e marque a caixa de seleção Permitir que o Google transmita o ID e a chave secreta do cliente pelo cabeçalho de autenticação básica HTTP.

5. Clique em Salvar.

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

Depois que o usuário faz login e o endpoint de autorização retorna um código de autorização de curta duração para o Google, o Google envia uma solicitação para o 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 essas solicitações, o valor de grant_type é authorization_code, e o valor de code é o código de autorização que você concedeu ao Google anteriormente. Confira abaixo um exemplo de 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 códigos de autorização por um token de acesso e um token de atualização, o endpoint de troca de token responde às solicitações POST executando as seguintes etapas:

1. Verifique se o client_id identifica a origem da solicitação como uma origem autorizada e se 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 parâmetro redirect_uri é idêntico ao valor usado na solicitação de autorização inicial.
4. Se não for possível verificar todos os critérios acima, retorne um erro HTTP 400 de solicitação inválida com {"error": "invalid_grant"} como 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 eles precisam representar de forma exclusiva o usuário e o cliente para o qual o token é destinado e não podem ser adivinhados. Para tokens de acesso, também registre o tempo de expiração do token, que geralmente é uma hora após a emissão. Os tokens de atualização não expiram.
6. 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 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 expirar, o Google vai usar o token de atualização para receber um novo token de acesso do endpoint de troca de token.

Trocar tokens de atualização por tokens de acesso

Quando um token de acesso expira, o Google envia uma solicitação para o endpoint de troca de token 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 do token de atualização que você concedeu anteriormente ao Google. Confira a seguir um exemplo de 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 um token de atualização por um token de acesso, o endpoint de troca de tokens responde às solicitações POST executando as seguintes etapas:

1. Verifique se o client_id identifica a origem da solicitação como Google e se 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 não for possível verificar todos os critérios acima, retorne um erro HTTP 400 de solicitação inválida com {"error": "invalid_grant"} como 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 precisam representar de forma exclusiva o usuário e o cliente para o qual o token é destinado e não podem ser adivinhados. Para tokens de acesso, registre também o tempo de expiração do token, geralmente uma hora após a emissão.
5. Retorne o seguinte objeto JSON no corpo da resposta HTTPS:

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

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.