Esta é a Central do desenvolvedor do Google Home, a nova plataforma para aprender a desenvolver ações de casa inteligente. Observação: você continua criando ações no Console do Actions.

Implementar um servidor OAuth 2.0

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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:

  1. 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.
  2. 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.
  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 para o 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 é 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.
  5. 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:

  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 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 o response_type é code.
  2. 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.
  3. 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.
  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 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â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 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:

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

  1. Verifique se o client_id identifica a origem da solicitação como Google e se 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 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 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.
  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 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:

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:

  1. Extraia o token de acesso do cabeçalho Authorization e retorne informações para o usuário associado ao token de acesso.
  2. 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.

  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 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.
Anterior
Lista de verificação do desenvolvedor
Próxima
Criar um projeto do Actions