OAuth 2.0 para TV e aplicativos para dispositivos de entrada limitada

Este documento explica como implementar a autorização OAuth 2.0 para acessar as APIs do Google por apps executados em dispositivos como TVs, consoles de jogos e impressoras. Mais especificamente, esse fluxo foi projetado para dispositivos que não têm acesso a um navegador ou têm recursos de entrada limitados.

O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo a privacidade de nomes, senhas e outras informações. Por exemplo, um aplicativo de TV pode usar o OAuth 2.0 para receber permissão para selecionar um arquivo armazenado no Google Drive.

Como os aplicativos que usam esse fluxo são distribuídos para dispositivos individuais, presume-se que eles não podem manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está presente no app ou quando ele está em execução em segundo plano.

Alternativas

Se você estiver criando um app para uma plataforma como Android, iOS, macOS, Linux ou Windows (incluindo a plataforma Windows Universal), que tenha acesso ao navegador e aos recursos de entrada completos, use o fluxo OAuth 2.0 para aplicativos para dispositivos móveis e computadores. Use esse fluxo mesmo que seu app seja uma ferramenta de linha de comando sem uma interface gráfica.

Se você só quer fazer login com as Contas do Google e usar o token de ID JWT para receber informações básicas do perfil do usuário, consulte Fazer login em TVs e dispositivos de entrada limitados.

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame as APIs do Google precisa ativar essas APIs no API Console.

Para ativar uma API para um projeto, faça o seguinte:

1. Open the API Library no Google API Console.
2. If prompted, select a project, or create a new one.
3. O API Library lista todas as APIs disponíveis, agrupadas por família de produtos e popularidade. Se a API que você quer ativar não estiver visível na lista, use a pesquisa para encontrá-la ou clique em Ver tudo na família de produtos a que ela pertence.
4. Selecione aquela que você quer habilitar e clique no botão Ativar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Criar credenciais de autorização

Qualquer aplicativo que use o OAuth 2.0 para acessar as APIs do Google precisa ter credenciais de autorização que identifiquem o aplicativo para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para seu projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou para esse projeto.

1. Go to the Credentials page.
2. Clique em Criar credenciais > ID do cliente OAuth.
3. Selecione o tipo de aplicativo TVs e dispositivos de entrada limitados.
4. Dê um nome ao cliente OAuth 2.0 e clique em Criar.

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao seu aplicativo. Portanto, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário.

Antes de começar a implementar a autorização do OAuth 2.0, recomendamos identificar os escopos que o app vai precisar de permissão para acessar.

Consulte a lista de escopos permitidos para apps ou dispositivos instalados.

Como conseguir tokens de acesso do OAuth 2.0

Mesmo que o app seja executado em um dispositivo com recursos de entrada limitados, os usuários precisam ter acesso separado a um dispositivo com recursos de entrada mais avançados para concluir esse fluxo de autorização. O fluxo tem as seguintes etapas:

1. O aplicativo envia uma solicitação ao servidor de autorização do Google que identifica os escopos que ele vai solicitar permissão para acessar.
2. O servidor responde com várias informações usadas nas etapas seguintes, como um código do dispositivo e um código do usuário.
3. Você exibe informações que o usuário pode inserir em um dispositivo separado para autorizar seu app.
4. O aplicativo começa a consultar o servidor de autorização do Google para determinar se o usuário autorizou o app.
5. O usuário alterna para um dispositivo com recursos de entrada mais avançados, abre um navegador da Web, navega até o URL mostrado na etapa 3 e insere um código que também aparece na etapa 3. O usuário pode conceder (ou negar) o acesso ao seu aplicativo.
6. A próxima resposta à solicitação de pesquisa contém os tokens necessários para que o app autorize as solicitações em nome do usuário. Se o usuário recusou o acesso ao seu app, a resposta não contém tokens.

A imagem abaixo ilustra esse processo:

As seções a seguir explicam essas etapas em detalhes. Considerando a variedade de recursos e ambientes de execução que os dispositivos podem ter, os exemplos mostrados neste documento usam o utilitário de linha de comando curl. Esses exemplos precisam ser fáceis de portar para vários idiomas e ambientes de execução.

Etapa 1: solicitar códigos de dispositivo e de usuário

Nesta etapa, o dispositivo envia uma solicitação HTTP POST ao servidor de autorização do Google, em https://oauth2.googleapis.com/device/code, que identifica o aplicativo e os escopos de acesso que ele quer acessar em nome do usuário. É necessário extrair esse URL do documento de descoberta usando o valor de metadados device_authorization_endpoint. Inclua os seguintes parâmetros de solicitação HTTP:

Exemplos

O snippet a seguir mostra uma solicitação de exemplo:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

Este exemplo mostra um comando curl para enviar a mesma solicitação:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

Etapa 2: processar a resposta do servidor de autorização

O servidor de autorização vai retornar uma das seguintes respostas:

Resposta de sucesso

Se a solicitação for válida, a resposta será um objeto JSON contendo as seguintes propriedades:

O snippet a seguir mostra um exemplo de resposta:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Resposta de cota excedida

Se as solicitações de código do dispositivo excederem a cota associada ao ID do cliente, você vai receber uma resposta 403 com o seguinte erro:

{
  "error_code": "rate_limit_exceeded"
}

Nesse caso, use uma estratégia de espera para reduzir a taxa de solicitações.

Etapa 3: mostrar o código do usuário

Mostre ao usuário o verification_url e o user_code obtidos na etapa 2. Ambos os valores podem conter qualquer caractere imprimível do conjunto de caracteres US-ASCII. O conteúdo mostrado ao usuário precisa instruir o usuário a navegar até o verification_url em um dispositivo separado e inserir o user_code.

Ao projetar a interface do usuário (IU), siga estas regras:

• user_code
  • O user_code precisa ser exibido em um campo que possa processar 15 caracteres de tamanho 'W'. Em outras palavras, se você conseguir mostrar o código WWWWWWWWWWWWWWW corretamente, a interface é válida. Recomendamos usar esse valor de string ao testar a forma como o user_code é mostrado na interface.
  • O user_code diferencia maiúsculas de minúsculas e não pode ser modificado de nenhuma forma, como mudar a caixa ou inserir outros caracteres de formatação.
• verification_url
  • O espaço em que você mostra o verification_url precisa ser largo o suficiente para processar uma string de URL de 40 caracteres.
  • Não modifique o verification_url de nenhuma forma, exceto para remover o esquema de exibição opcionalmente. Se você planeja remover o esquema (por exemplo, https://) do URL por motivos de exibição, verifique se o app pode processar as variantes http e https.

Etapa 4: consultar o servidor de autorização do Google

Como o usuário vai usar um dispositivo separado para navegar até a verification_url e conceder (ou negar) o acesso, o dispositivo solicitante não é notificado automaticamente quando o usuário responde à solicitação de acesso. Por esse motivo, o dispositivo solicitante precisa consultar o servidor de autorização do Google para determinar quando o usuário respondeu à solicitação.

O dispositivo solicitante precisa continuar enviando solicitações de pesquisa até receber uma resposta indicando que o usuário respondeu à solicitação de acesso ou até que o device_code e o user_code obtidos na etapa 2 tenham expirado. O interval retornado na etapa 2 especifica o tempo, em segundos, para aguardar entre as solicitações.

O URL do endpoint a ser consultado é https://oauth2.googleapis.com/token. A solicitação de pesquisa contém os seguintes parâmetros:

Exemplos

O snippet a seguir mostra uma solicitação de exemplo:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Este exemplo mostra um comando curl para enviar a mesma solicitação:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Etapa 5: o usuário responde ao pedido de acesso

A imagem a seguir mostra uma página semelhante à que os usuários veem ao navegar até a verification_url que você exibiu na etapa 3:

Depois de inserir o user_code e, se ainda não tiver feito login, de fazer login no Google, o usuário vai ver uma tela de consentimento como a mostrada abaixo:

Etapa 6: processar respostas a solicitações de pesquisa

O servidor de autorização do Google responde a cada solicitação de pesquisa com uma das seguintes respostas:

Acesso concedido

Se o usuário concedeu acesso ao dispositivo (clicando em Allow na tela de consentimento), a resposta conterá um token de acesso e um token de atualização. Os tokens permitem que seu dispositivo acesso às APIs do Google em nome do usuário. A propriedade scope na resposta determina quais APIs o dispositivo pode acessar.

Nesse caso, a resposta da API contém os seguintes campos:

O snippet a seguir mostra um exemplo de resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Os tokens de acesso têm uma vida útil limitada. Se o aplicativo precisar de acesso a uma API por um longo período, ele poderá usar o token de atualização para receber um novo token de acesso. Se o aplicativo precisar desse tipo de acesso, ele precisará armazenar o token de atualização para uso posterior.

Acesso negado

Se o usuário se recusar a conceder acesso ao dispositivo, a resposta do servidor terá um código de status de resposta HTTP 403 (Forbidden). A resposta contém o seguinte erro:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Autorização pendente

Se o usuário ainda não tiver concluído o fluxo de autorização, o servidor vai retornar um código de status de resposta HTTP 428 (Precondition Required). A resposta vai conter o seguinte erro:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Enquetes muito frequentes

Se o dispositivo enviar solicitações de pesquisa com muita frequência, o servidor retornará um código de status de resposta HTTP 403 (Forbidden). A resposta conterá o seguinte erro:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Outros erros

O servidor de autorização também retorna erros se a solicitação de pesquisa estiver sem parâmetros obrigatórios ou tiver um valor de parâmetro incorreto. Essas solicitações geralmente têm um código de status de resposta HTTP 400 (Bad Request) ou 401 (Unauthorized). Esses erros incluem:

Como chamar APIs do Google

Depois que o aplicativo receber um token de acesso, ele poderá usá-lo para fazer chamadas para uma API do Google em nome de uma determinada conta de usuário, se os escopos de acesso exigidos pela API tiverem sido concedidos. Para fazer isso, inclua o token de acesso em uma solicitação para a API incluindo um parâmetro de consulta access_token ou um valor Bearer de cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, é possível usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google. Por exemplo, ao chamar a API Drive Files.

Teste todas as APIs do Google e confira os escopos delas no OAuth 2.0 Playground.

Exemplos de GET HTTP

Uma chamada para o endpoint drive.files (a API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta é uma chamada para a mesma API do usuário autenticado usando o parâmetro de string de consulta access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Exemplos de curl

É possível testar esses comandos com o aplicativo de linha de comando curl. Confira um exemplo que usa a opção de cabeçalho HTTP (preferencial):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Ou, como alternativa, a opção de parâmetro de string de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Atualização do token de acesso

Os tokens de acesso expiram periodicamente e se tornam credenciais inválidas para uma solicitação de API relacionada. É possível atualizar um token de acesso sem solicitar a permissão do usuário (inclusive quando o usuário não está presente) se você solicitou acesso off-line aos escopos associados ao token.

Para atualizar um token de acesso, o aplicativo envia uma solicitação POST HTTPS ao servidor de autorização do Google (https://oauth2.googleapis.com/token) que inclui os seguintes parâmetros:

O snippet a seguir mostra uma solicitação de exemplo:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Enquanto o usuário não tiver revogado o acesso concedido ao aplicativo, o servidor de tokens vai retornar um objeto JSON que contém um novo token de acesso. O snippet a seguir mostra um exemplo de resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Há limites no número de tokens de atualização que serão emitidos: um limite por combinação de cliente/usuário e outro por usuário em todos os clientes. Salve os tokens de atualização no armazenamento de longo prazo e continue a usá-los enquanto eles permanecerem válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá encontrar esses limites. Nesse caso, os tokens de atualização mais antigos vão deixar de funcionar.

Revogar um token

Em alguns casos, o usuário pode querer revogar o acesso concedido a um app. Um usuário pode revogar o acesso acessando as Configurações da conta. Consulte a seção Remover acesso a sites ou apps do documento de suporte "Sites e apps de terceiros com acesso à sua conta" para mais informações.

Também é possível que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante em casos em que um usuário cancela a inscrição, remove um aplicativo ou os recursos da API exigidos por um app mudaram significativamente. Em outras palavras, parte do processo de remoção pode incluir uma solicitação de API para garantir que as permissões concedidas anteriormente ao aplicativo sejam removidas.

Para revogar um token de forma programática, seu app faz uma solicitação para https://oauth2.googleapis.com/revoke e inclui o token como um parâmetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

O token pode ser de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, ele também será revogado.

Se a revogação for processada, o código de status HTTP da resposta será 200. Para condições de erro, um código de status HTTP 400 é retornado com um código de erro.

Escopos permitidos

O fluxo OAuth 2.0 para dispositivos tem suporte apenas para os seguintes escopos: