Implementar um servidor OAuth 2.0

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

Com a autenticação, é possível vincular as Contas do Google dos usuários às contas de usuário no seu sistema de autenticação. Isso permite identificar seus usuários quando seu atendimento recebe uma intent de casa inteligente. A casa inteligente do Google só aceita OAuth com um fluxo do código de autorização.

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

Vinculação de Contas do Google com OAuth

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.

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.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
2. You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
3. You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.
4. You must include at least one of the following items in the OAuth linking page to indicate the integration to which the user is linking:
   • Company logo
   • Company name
   • Integration name
   • App icon

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why, and what usage or interaction data may be shared with you by Google.

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

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have a clear method for signing in to their Google Account, such as fields for their username and password or Sign in with Google.

6. 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. If a user unlinks from your integration, use agentUsers.delete to notify Google of the change.

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

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

Fluxo do código de autorização

Uma implementação de 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 de autorização, responsável por encontrar ou receber o consentimento dos usuários para acesso a 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 tokens, 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 permissão dos usuários para chamar essas APIs em nome deles.

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

1. O Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo tiver sido iniciado em um dispositivo somente de voz para uma ação, o Google vai transferir a execução para um smartphone.
2. O usuário faz login, se ainda não tiver feito, e concede ao Google permissão para acessar os dados dele com sua API, se ainda não tiver concedido permissão.
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 tokens, 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 subsequentes enviadas pelo Google vão conter um token de acesso.

Processar solicitações de autorização

Quando você precisa realizar a vinculação de contas usando o fluxo do código de autorização do OAuth 2.0, o Google envia o usuário para o 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

Para que o endpoint de autorização processe solicitações de login, siga estas etapas:

1. Verifique se o client_id corresponde ao ID do cliente que você atribuiu 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 a concessão de acesso a apps clientes não intencionais ou mal configurados. Se você oferece suporte a vários fluxos do OAuth 2.0, confirme também se o response_type é code.
2. Verifique se o usuário fez login no seu serviço. Se o usuário não tiver feito login, conclua o fluxo de login ou inscrição do seu 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 de maneira exclusiva o usuário, o cliente para o qual o token é destinado e o tempo de expiração do código, e 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. Redirecione o navegador do usuário para o URL especificado pelo redirect_uri parâmetro. 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 tokens

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

• 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 tokens 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 credenciais do cliente no corpo 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, você precisará configurar sua Cloud-to-cloud integração de acordo com o seguinte:

Acessar o Developer Console

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

2. Em Nuvem para 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 Fazer com que o Google transmita o ID e a chave 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 fizer login e o endpoint de autorização retornar um código de autorização de curta duração para o Google, o Google vai enviar uma solicitação ao endpoint de troca de tokens 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 valor do código de autorização que você concedeu anteriormente ao Google. 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 tokens responde a 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 maneira exclusiva o usuário e o cliente para o qual o token é destinado, e eles não podem ser adivinháveis. Para tokens de acesso, registre também o tempo de expiração do token, que normalmente é uma hora após a emissão do token. 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 do usuário e registra 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 ao endpoint de troca de tokens 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 que você concedeu anteriormente ao Google. Confira abaixo 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 a solicitações POST executando as seguintes etapas:

1. Verifique se o client_id identifica a origem da solicitação como o 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 maneira exclusiva o usuário e o cliente para o qual o token é destinado, e não podem ser adivinháveis. Para tokens de acesso, registre também o tempo de expiração do token, que normalmente é uma hora após a emissão do token.
5. Retorne o seguinte objeto JSON no corpo da resposta HTTPS:

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

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:

• Login da conta vinculada com o Google One Tap.
• Assinatura sem atrito no AndroidTV.

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.

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.