Implementar um servidor OAuth 2.0

Cada ação smart home precisa incluir um mecanismo para autenticar usuários.

Com a autenticação, você pode vincular as contas Contas do Google com as contas de usuário no seu sistema de autenticação. Isso permite que você identifique seus usuários quando o fulfillment recebe uma intent de casa inteligente. A casa inteligente do Google só é compatível com o OAuth com uma fluxo do código de autorização.

Esta página descreve como configurar seu servidor OAuth 2.0 para que ele funcione com sua ação smart home.

Vinculação da Conta 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 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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

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 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.
2. 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.
3. 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.
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ê 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:

1. Verifique se client_id identifica a origem da solicitação como origem 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 à 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 uma solicitação HTTP Erro 400 Solicitação inválida 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 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.
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 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:

1. Verifique se client_id identifica a origem da solicitação como Google. 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 em a 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 Erro de solicitação inválido com {"error": "invalid_grant"} como o corpo.
4. 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.
5. Retorne o seguinte objeto JSON no corpo da solicitação resposta:

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

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

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.