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 APIs do Google por meio de aplicativos executados em dispositivos como TVs, consoles de jogos e impressoras Mais especificamente, esse fluxo é projetado para dispositivos que não têm acesso a um navegador ou têm capacidades de entrada limitadas.

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

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

Alternativas

Se você está criando um app para uma plataforma como Android, iOS, macOS, Linux ou Windows (incluindo a Plataforma Universal do Windows), que tem acesso ao navegador e à entrada completa use o fluxo do OAuth 2.0 para dispositivos móveis e aplicativos para computador. Use esse fluxo mesmo se seu aplicativo for uma linha de comando sem uma interface gráfica.

Se você quiser apenas fazer login dos usuários com as Contas do Google deles e usar Token de ID do JWT para conseguir as informações básicas do perfil do usuário, consulte Login em TVs e dispositivos de entrada limitada.

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame 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. API Library lista todas as APIs disponíveis agrupadas por produto família e popularidade. Se a API que você quer ativar não aparecer 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 deve ter credenciais de autorização que identificam 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 nesse 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 limitada.
4. Nomeie seu 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 permitindo que os usuários controlem a quantidade de acesso que eles concedem ao aplicativo. Portanto, há pode ser uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário.

Antes de começar a implementar a autorização do OAuth 2.0, recomendamos que você identifique os escopos que o app precisa de permissão para acessar.

Consulte a lista Escopos permitidos para saber quais apps ou dispositivos instalados.

Como conseguir tokens de acesso do OAuth 2.0

Mesmo que seu aplicativo seja executado em um dispositivo com capacidades de entrada limitadas, 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. Seu aplicativo envia uma solicitação ao servidor de autorização do Google que identifica os escopos que o aplicativo solicitará permissão de acesso.
2. O servidor responde com várias informações usadas em etapas subsequentes, como uma código do dispositivo e um código de usuário.
3. Mostre informações que o usuário pode inserir em outro dispositivo para autorizar sua app.
4. Seu aplicativo começa a sondar o servidor de autorização do Google para determinar se o usuário autorizou seu aplicativo.
5. O usuário troca para um dispositivo com recursos de entrada mais avançados, inicia um navegador da Web, navega até o URL exibido na etapa 3 e insere um código que também é exibido na etapa 3. O o usuário poderá conceder (ou negar) acesso ao seu aplicativo.
6. A próxima resposta à solicitação de sondagem contém os tokens que o app precisa autorizar solicitações em nome do usuário. Se o usuário tiver recusado o acesso ao seu aplicativo, 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 tempo de execução ambientes que os dispositivos podem ter, os exemplos mostrados neste documento usam a classe curl utilitário de linha de comando. Esses exemplos precisam ser fáceis de transferir para várias linguagens e ambientes de execução.

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

Nesta etapa, o dispositivo envia uma solicitação POST HTTP para o servidor de autorização do Google, em https://oauth2.googleapis.com/device/code, que identifica seu aplicativo e os escopos que seu aplicativo deseja acessar em nome do usuário. Você deve recuperar esse URL na Documento de descoberta usando o Valor de metadados device_authorization_endpoint. Inclua a seguinte solicitação HTTP parâmetros:

Parâmetros
client_id	Obrigatório O ID do cliente do aplicativo. É possível encontrar esse valor API Console Credentials page.
scope	Obrigatório Um delimitado por espaço lista de escopos que identificam os recursos que seu aplicativo pode acessar na em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário. Consulte a Lista de escopos permitidos para apps ou dispositivos instalados. Os escopos permitem que o aplicativo solicite acesso apenas aos recursos necessários além de permitir que os usuários controlem a quantidade de acesso que eles concedem aos seus para o aplicativo. Desse modo, há uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário.

Exemplos

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

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, sua resposta será um objeto JSON contendo o seguinte propriedades:

Propriedades
device_code	Um valor que o Google atribui exclusivamente para identificar o dispositivo que executa o app que solicita autorização. O usuário vai autorizar esse dispositivo a partir de outro dispositivo com mais capacidades de entrada. Por exemplo, um usuário pode usar um laptop ou celular para autorizar um em execução em uma TV. Nesse caso, o device_code identifica a TV. Esse código permite que o dispositivo que executa o aplicativo determine com segurança se o usuário concedeu acesso ou negado.
expires_in	O período, em segundos, que device_code e user_code são válidos. Se, nesse período, o usuário não completar o fluxo de autorização e seu dispositivo não fizer enquetes para recuperar informações sobre o decisão do usuário, talvez seja necessário reiniciar esse processo na etapa 1.
interval	O tempo, em segundos, que seu dispositivo deve aguardar entre as solicitações de sondagem. Para exemplo, se o valor for 5, seu dispositivo deverá enviar uma solicitação de pesquisa para o servidor de autorização do Google a cada cinco segundos. Consulte etapa 3 para mais detalhes.
user_code	Um valor que diferencia maiúsculas de minúsculas que identifica para o Google os escopos aos quais o aplicativo está solicitando acesso. Sua interface do usuário instruirá o usuário a inserir esse valor em um dispositivos separados com recursos de entrada mais avançados. O Google usa o valor para exibir o conjunto correto de escopos ao solicitar que o usuário conceda acesso ao aplicativo.
verification_url	Um URL que o usuário deve acessar, em um dispositivo separado, para inserir o user_code e conceda ou negue acesso ao seu aplicativo. Sua interface do usuário também exibirá esse valor.

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, será receberá uma resposta 403, contendo 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: exibir o código do usuário

Mostre a verification_url e a user_code da etapa 2 à usuário. Ambos os valores podem conter qualquer caractere para impressão do conjunto de caracteres US-ASCII. O conteúdo que você mostrar ao usuário deve instruir o usuário a navegar até a verification_url em um dispositivo separado e digite o user_code.

Projete sua interface do usuário (IU) tendo em mente as seguintes regras:

• user_code
  • O user_code precisa ser mostrado em um campo que possa lidar com 15 "W" tamanho caracteres. Em outras palavras, se for possível exibir o código WWWWWWWWWWWWWWW corretamente, sua interface é válida, e recomendamos usar esse valor de string ao testar a forma o user_code é exibido na IU.
  • O user_code diferencia maiúsculas de minúsculas e não pode ser modificado, como como alterar a capitalização ou inserir outros caracteres de formatação.
• verification_url
  • O espaço em que você exibe a verification_url precisa ser largo o suficiente para manipulam uma string de URL com 40 caracteres.
  • Não modifique verification_url, exceto para opcionalmente e remover o esquema para exibição. Se você planeja eliminar o esquema (por exemplo, https://) do URL por motivos de exibição, verifique se o app consegue processar as variantes http e https.

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

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

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

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

Parâmetros
client_id	O ID do cliente do aplicativo. É possível encontrar esse valor API Console Credentials page.
client_secret	A chave secreta do cliente para o client_id fornecido. É possível encontrar esse valor API Console Credentials page.
device_code	O device_code retornado pelo servidor de autorização etapa 2.
grant_type	Defina esse valor como urn:ietf:params:oauth:grant-type:device_code.

Exemplos

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

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 à solicitação de acesso

A imagem a seguir mostra uma página semelhante à que os usuários veem quando acessam o verification_url exibido na etapa 3:

Depois de inserir o user_code e fazer login no Google, caso ainda não tenha feito isso, O usuário vê uma tela de consentimento como a mostrada abaixo:

Etapa 6: processar respostas às solicitações de sondagem

O servidor de autorização do Google responde a cada solicitação de sondagem com uma das opções a seguir: 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 acessar as APIs do Google em nome do usuário. (O scope) na resposta determina para quais APIs dispositivo pode acessar.

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

Campos
access_token	O token que seu aplicativo envia para autorizar uma solicitação de API do Google.
expires_in	A vida útil restante do token de acesso em segundos.
refresh_token	Um token que pode ser usado para receber um novo token de acesso. Os tokens de atualização são válidos até o usuário revoga o acesso. Os tokens de atualização sempre são retornados para dispositivos.
scope	Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaço e que diferenciam maiúsculas de minúsculas.
token_type	O tipo de token retornado. No momento, o valor desse campo é sempre definido como Bearer:

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 vida útil limitada. Caso seu aplicativo precise acessar uma API por um longo período período, ele pode usar o token de atualização para obter um novo acesso com base no token correto anterior. Se o seu aplicativo precisa desse tipo de acesso, então ele deve armazenar o token de atualização para 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 retornará um Código de status de resposta HTTP 428 (Precondition Required). A resposta contém o seguinte erro:

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

Pesquisando com muita frequência

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

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

Outros erros

O servidor de autorização também retornará erros se a solicitação de sondagem estiver faltando algum parâmetros ou tiver um valor de parâmetro incorreto. Essas solicitações geralmente têm um 400 Status da resposta HTTP (Bad Request) ou 401 (Unauthorized) o código-fonte. Esses erros incluem:

Erro	Código de status HTTP	Descrição
admin_policy_enforced	400	A Conta do Google não pode autorizar um ou mais escopos solicitados devido à políticas do administrador do Google Workspace. Consulte a Ajuda para admins do Google Workspace artigo Controlar quais terceiros e os apps internos acessam os dados do Google Workspace. administrador pode restringir o acesso a escopos até que o acesso seja explicitamente concedido ao seu ID do cliente.
invalid_client	401	O cliente OAuth não foi encontrado. Por exemplo, esse erro ocorre se o O valor do parâmetro client_id é inválido. O tipo de cliente OAuth está incorreto. Assegure-se de que tipo de aplicativo para o ID do cliente é definido como TVs and Limited Input devices.
invalid_grant	400	O valor do parâmetro code é inválido, já foi reivindicado ou não pode ser analisados.
unsupported_grant_type	400	O valor do parâmetro grant_type é inválido.
org_internal	403	O ID do cliente OAuth na solicitação faz parte de um projeto que limita o acesso às Contas do Google em um determinado Organização do Google Cloud. Confirme os tipo de usuário do aplicativo para seu aplicativo OAuth.

Como chamar APIs do Google

Depois que o aplicativo obtém um token de acesso, você pode usá-lo para fazer chamadas a um serviço em nome de um determinado 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 à API incluindo uma consulta access_token ou um valor Bearer do cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ser visíveis nos registros do servidor. Na maioria casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google (por exemplo, quando chamando a API Drive Files).

Você pode experimentar todas as APIs do Google e visualizar seus escopos em OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada ao drive.files endpoint (a API Drive Files) usando a API 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 para o usuário autenticado com o access_token parâmetro da string de consulta:

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. Este é 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, alternativamente, a opção do parâmetro da 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. Você podem atualizar um token de acesso sem solicitar a permissão do usuário (inclusive quando o usuário é ausente) se você solicitou acesso off-line aos escopos associados ao token.

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

Campos
client_id	O ID do cliente recebido do API Console.
client_secret	A chave secreta do cliente recebida de API Console.
grant_type	Conforme definidas no especificação OAuth 2.0, o valor desse campo precisa ser definido como refresh_token.
refresh_token	O token de atualização retornado da troca de códigos de autorização.

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

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

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

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

Há limites para o número de tokens de atualização que serão emitidos. um limite por combinação de cliente/usuário e outra por usuário em todos os clientes. Salvar tokens de atualização no armazenamento a longo prazo e continuarão a usá-los enquanto permanecerem válidos. Se o seu aplicativo solicitar muitos tokens de atualização, poderá atingir esses limites; nesse caso, tokens de atualização mais antigos vão parar de funcionar.

Revogação de um token

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

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

Para revogar programaticamente um token, o aplicativo 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 um token de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, o token de atualização também será revogado.

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

Escopos permitidos

O fluxo do OAuth 2.0 para dispositivos é compatível apenas com os seguintes escopos:

OpenID Connect, Login do Google

• email
• openid
• profile

API Drive

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

API YouTube

• https://www.googleapis.com/auth/youtube
• https://www.googleapis.com/auth/youtube.readonly

Como implementar a Proteção entre contas

Uma etapa adicional que você deve tomar para proteger as informações está implementando o usando o serviço de proteção entre contas do Google. Esse serviço permite que você inscrever-se em notificações de ocorrências de segurança, que fornecem informações ao aplicativo sobre grandes mudanças na conta do usuário. Você pode então usar as informações para tomar medidas dependendo como você decide responder aos eventos.

Alguns exemplos dos tipos de evento enviados ao seu app pelo serviço de Proteção entre contas do Google são:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulte a Proteger contas de usuário com a página "Proteção entre contas" para mais informações sobre como implementar a Proteção entre contas e para conferir a lista completa de eventos disponíveis.