Todo(a) smart home Action must include a mechanism for authenticating users.
Com a autenticação, é possível vincular as Contas do Google dos seus usuários a contas de usuário no seu sistema de autenticação. Isso permite identificar os usuários quando o fulfillment receber uma intent de casa inteligente. A casa inteligente do Google só oferece suporte ao OAuth com um fluxo de código de autorização.
Nesta página, descrevemos como configurar o servidor OAuth 2.0 para que ele funcione com a ação smart home.
Fluxo do código de autorização
Uma implementação do servidor do OAuth 2.0 do fluxo de código de autorização consiste em dois endpoints, que o serviço disponibiliza por HTTPS. O primeiro endpoint é o endpoint de autorização, que é responsável por encontrar ou receber o consentimento dos usuários para o acesso aos dados. O endpoint de autorização apresenta uma IU de login aos seus usuários que ainda não estão conectados e registra o consentimento para o acesso solicitado. O segundo endpoint é o endpoint de troca de tokens, usado para receber strings criptografadas, chamadas 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 solicitar a permissão dos usuários para chamar essas APIs em nome deles.
Uma sessão do fluxo de código de autorização do OAuth 2.0 iniciada pelo Google tem o seguinte fluxo:
- O Google abre o endpoint de autorização no navegador do usuário. Se o fluxo for iniciado em um dispositivo somente de voz para uma ação, o Google transferirá a execução para um smartphone.
- O usuário faz login, caso ainda não tenha feito isso, e concede permissão ao Google para acessar os dados dele com a API, caso ainda não tenha concedido permissão.
- 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 para o Google com o código de autorização anexado à solicitação.
- 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 é de curta duração, aceito pelo serviço 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 expirarem.
- Depois que o usuário concluir o fluxo de vinculação da conta, cada solicitação subsequente enviada do Google 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:
Parâmetros do endpoint de autorização | |
---|---|
client_id |
O ID do cliente que você atribuiu ao Google. |
redirect_uri |
O URL a que você envia a resposta para essa solicitação. |
state |
Um valor de contabilidade que é retornado de volta ao Google no URI de redirecionamento. |
scope |
Opcional:um conjunto de strings de escopo delimitado por espaço que especifica 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 de código de autorização do OAuth 2.0, o tipo de resposta é sempre code .
|
user_locale |
Configuração de idioma da Conta do Google no formato RFC5646, usada para localizar seu conteúdo no idioma preferido do usuário. |
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:
- Verifique se o
client_id
corresponde ao ID do cliente atribuído ao Google e se oredirect_uri
corresponde ao URL de redirecionamento fornecido pelo Google para o serviço. Essas verificações são importantes para impedir a concessão de acesso a apps clientes indesejados ou configurados incorretamente. Se você oferece suporte a vários fluxos do OAuth 2.0, também confirme se oresponse_type
écode
. - Verifique se o usuário fez login no serviço. Se o usuário não estiver conectado, conclua o fluxo de login ou inscrição do seu serviço.
- Gere um código de autorização para o Google 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, o prazo de validade do código e não deve ser adivinhado. Geralmente, você emite códigos de 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 ao URL especificado pelo parâmetro
redirect_uri
. Inclua o código de autorização que você acabou de gerar e o valor do estado original não modificado ao redirecionar anexando os parâmetroscode
estate
. 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 trocas de tokens:
- Trocar códigos de autorização para 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:
Parâmetros de endpoints de troca de tokens | |
---|---|
client_id |
Uma string que identifica a origem da solicitação como Google. Esta 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 seu endpoint de login
ou troca de tokens. |
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 token. |
Trocar códigos de autorização para tokens de acesso e de atualização
Depois que o usuário fizer login e seu endpoint de autorização retornar ao Google um código de autorização de curta duração, o Google enviará uma solicitação ao 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 de code
é o valor do código de autorização que você concedeu anteriormente ao Google. Veja a seguir um exemplo de solicitação de troca de um código de autorização por um token de acesso e de 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:
- Verifique se o
client_id
identifica a origem da solicitação como uma origem autorizada e se oclient_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 ao 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 um erro HTTP 400 Bad Request com
{"error": "invalid_grant"}
como o corpo. - 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 para o qual o token é destinado e eles não podem ser adivinhados. Para tokens de acesso, registre também o prazo de validade do token, que costuma ser uma hora após a emissão dele. 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 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 expira, o Google usa 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 ao endpoint de troca de token para trocar um token por um novo.
Para essas solicitações, o valor de grant_type
é refresh_token
, e o de refresh_token
é o valor do token de atualização que você concedeu anteriormente ao Google. Veja a seguir um exemplo de solicitação de troca de 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 de acesso, o endpoint de troca de token responde a solicitações POST
executando as seguintes etapas:
- Verifique se o
client_id
identifica a origem da solicitação como Google e seclient_secret
corresponde ao valor esperado. - 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.
- Se não for possível verificar todos os critérios acima, retorne um erro HTTP 400
Bad Request com
{"error": "invalid_grant"}
como o corpo. - 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 exclusivamente o usuário e o cliente a que o token se destina e não podem ser adivinháveis. Para tokens de acesso, registre também o prazo de validade do token, normalmente uma hora após a emissão dele.
- 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 informações do usuário
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 de informações do usuário é opcional, exceto nos seguintes casos de uso:
- Fazer login na conta vinculada com o Google One Tap.
- Assinatura simples no Android TV.
Depois que o token de acesso for recuperado do seu endpoint de token, o Google enviará uma solicitação ao seu 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 de informações do usuário | |
---|---|
Authorization header |
O token de acesso do tipo Bearer. |
Por exemplo, se o endpoint de informações do usuário estiver disponível em
https://myservice.example.com/userinfo
, uma solicitação poderá ter a seguinte aparência:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
Para que o endpoint de informações do usuário processe solicitações, siga estas etapas:
- Extraia o token de acesso do cabeçalho Authorization e retorne informações para o usuário associado ao token de acesso.
- Se o token de acesso for inválido, retorne um erro HTTP 401 Authorize usando o cabeçalho de resposta
WWW-Authenticate
. Veja abaixo um exemplo de resposta de erro de informações do usuário: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 malsucedida for retornada durante o processo de vinculação, o erro não poderá ser recuperado, o token recuperado será descartado e o usuário precisará iniciar o processo de vinculação novamente. 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 de informações do usuário retornar uma resposta de êxito HTTP 200, o token recuperado e as reivindicações serão registrados na Conta do Google do usuário.resposta do endpoint de informações do usuário sub
Um código 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.