Implementar um servidor OAuth 2.0

Toda integração do 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ó é compatível com o OAuth com um fluxo do código de autorização.

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

Vinculação de Contas do Google com OAuth

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 tokens, 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 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 anterior 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 uma página de login do Google e uma tela de permissão de vinculação de conta para o usuário. O usuário é direcionado de volta ao app do Google depois de dar o consentimento para vincular as 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 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 do Google.
Figura 1. Telas de login e consentimento do usuário para vinculação de contas ao Google.

Requisitos

  1. É preciso 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.
  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 do Google das Políticas para Desenvolvedores do Google Home.
  3. Abra a página de vinculação do OAuth da Web e verifique se os usuários têm 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 façam a vinculação sem serem direcionados para a página de vinculação do OAuth da Web. Isso é uma violação da política do Google.
  4. É necessário incluir pelo menos um dos seguintes itens na página de vinculação do OAuth para indicar a integração que o usuário está vinculando:
    • Logotipo da empresa
    • Nome da empresa
    • Nome da integração
    • Ícone do app

Recomendações

Portanto, recomendamos que você faça o seguinte:

  1. Mostra 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 são exigidos pelo Google e por quê, além de quais dados de uso ou interação podem ser compartilhados com você pelo Google.

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

  4. Opção de cancelamento Ofereça uma maneira de os usuários voltarem ou cancelarem, caso decidam não fazer a vinculação.

  5. Processo de login claro. Verifique se os usuários têm um método claro para fazer login na Conta do Google, como campos para o nome de usuário e a senha ou Fazer login com o Google.

  6. Capacidade de desvincular. Ofereça um mecanismo para que os usuários desvinculem as contas, 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. Se um usuário desvincular a conta da sua integração, use agentUsers.delete para notificar o Google sobre a mudança.

  7. Capacidade de mudar a conta de usuário. Sugira um método para os usuários trocarem de conta. 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 que quiser com a vinculação do OAuth.
  8. Inclua o logotipo. Mostre o logotipo da sua empresa na tela de permissão. Siga as 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, responsável por encontrar ou receber o consentimento dos usuários para o acesso aos 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 é o endpoint 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 do 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 começar 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 feito isso.
  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 expirarem.
  5. Depois que o usuário concluir o fluxo de vinculação de contas, todas as solicitações enviadas pelo Google vão conter um token de acesso.

Processar solicitações de autorização

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

Parâmetros do endpoint de autorização
client_id O ID do cliente que você atribuiu ao Google.
redirect_uri O URL para onde você envia a resposta a essa solicitação.
state Um valor de monitoramento que é retornado ao Google inalterado no URI de redirecionamento.
scope Opcional: um conjunto de strings de escopo delimitadas por espaço que especificam os dados para os quais o Google está solicitando autorização.
response_type O tipo de valor a ser retornado na resposta. Para o fluxo do código de autorização do OAuth 2.0, o tipo de resposta é sempre code.

Por exemplo, se o endpoint de autorização estiver disponível em https://myservice.example.com/auth, uma solicitação 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 cliente não intencionais ou configurados incorretamente. Se você aceita 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 estiver conectado, 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 forma exclusiva o usuário, o cliente para quem o token é destinado e o prazo de validade do código, além de não ser adivinhável. Normalmente, você emite códigos de autorização que expiram após cerca de 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 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. Veja a seguir 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 tokens do seu serviço é responsável por dois tipos de troca 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 token incluem os seguintes parâmetros:

Parâmetros do endpoint de troca de token
client_id Uma string que identifica a origem da solicitação como o Google. Essa string precisa ser registrada no seu sistema como o 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 código que o Google recebeu do endpoint de login ou de troca de token.
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 do seu endpoint de troca de tokens.

Configurar como o Google envia credenciais para seu servidor

Dependendo da implementação, o servidor de autorização espera receber credenciais de 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, configure a integração do Cloud-to-cloud da seguinte maneira:

Acesse o Console do Desenvolvedor

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

  2. Em Cloud-to-Cloud, selecione Desenvolver.

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

  4. Acesse a seção Permissões (opcional) e marque a caixa de seleção Permitir que o Google transmita o ID do cliente e a chave secreta 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 seu endpoint de autorização retorna um código de autorização de curta duração ao Google, o Google envia uma solicitação ao seu 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 valor do código de autorização que você concedeu ao Google. Veja a seguir 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, seu 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 anteriores, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como o 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 precisam representar exclusivamente o usuário e o cliente a que se destinam e não podem ser adivinháveis. Para tokens de acesso, registre também o prazo de validade do token, que normalmente é de 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 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. Veja 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 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 anteriores, retorne um erro HTTP 400 Bad Request com {"error": "invalid_grant"} como o 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 a que se destinam, além de não serem adivinháveis. Para tokens de acesso, registre também o prazo de validade do token, normalmente 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
    }

Processar solicitações de userinfo

O endpoint userinfo é um recurso protegido pelo OAuth 2.0 que retorna declarações sobre os usuários associados. A implementação e a hospedagem do endpoint userinfo são opcionais, exceto nos seguintes casos de uso:

Depois que o token de acesso for recuperado do endpoint de token, o Google vai enviar uma solicitação ao endpoint userinfo para recuperar informações básicas do perfil dos usuários associados.

Cabeçalhos da solicitação do endpoint userinfo
Authorization header O token de acesso do tipo Bearer.

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

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. Extraia o token de acesso do cabeçalho de autorização e retorne informações do usuário associado ao token de acesso.
  2. Se o token de acesso for inválido, retorne um erro HTTP 401 Não autorizado usando o cabeçalho de resposta WWW-Authenticate. Veja abaixo um exemplo de resposta de erro de 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 qualquer outra resposta de erro for retornada durante o processo de vinculação, o erro não será recuperável, o token recuperado será descartado e o usuário precisará 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 da resposta HTTPS:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    Se o endpoint userinfo retornar uma resposta de sucesso HTTP 200, o token e as declaraçõ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: nome completo do usuário.
    picture Opcional: foto do perfil do usuário.