OAuth 2.0 para TV e aplicativos de dispositivo 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 recursos de entrada limitados.

OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo seus nomes de usuário, senhas e outras informações privadas. Por exemplo, um aplicativo de TV pode 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, presume-se que os aplicativos não podem manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está no aplicativo ou quando o aplicativo está sendo executado em segundo plano.

Alternativas

Se você estiver escrevendo um aplicativo para uma plataforma como Android, iOS, MacOS, Linux ou Windows (incluindo Windows Universal Platform), que tem acesso ao navegador e recursos de entrada inteira, utilize o fluxo OAuth 2.0 para aplicações móveis e desktop . (Você deve usar esse fluxo mesmo se seu aplicativo for uma ferramenta de linha de comando sem uma interface gráfica.)

Pré-requisitos

Habilite APIs para seu projeto

Qualquer aplicativo que chama APIs do Google precisa para permitir que essas APIs no API Console.

Para habilitar uma API para seu projeto:

  1. Open the API Library na Google API Console.
  2. If prompted, select a project, or create a new one.
  3. O API Library listas de todas as APIs disponíveis, agrupados por família de produtos e popularidade. Se a API que você deseja ativar não é visível na lista, o uso de busca para encontrá-lo, ou clique em Ver Todos na família de produtos a que pertence.
  4. Selecione a API que você deseja ativar, em seguida, clique no botão Ativar.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Crie credenciais de autorização

Qualquer aplicativo que usa OAuth 2.0 para acessar 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 então usar as credenciais para acessar APIs que você habilitou para aquele projeto.

  1. Go to the Credentials page.
  2. Clique em Criar credenciais> OAuth ID do cliente.
  3. Selecione os dispositivos de entrada TVs e limitada tipo de aplicação.
  4. Nome do seu cliente OAuth 2.0 e clique em Criar.

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permite que os usuários controlem a quantidade de acesso que concedem ao seu aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de obtenção do consentimento do usuário.

Antes de começar a implementar a autorização OAuth 2.0, recomendamos que você identifique os escopos que seu aplicativo precisará de permissão para acessar.

Veja a escopos admitidos lista de aplicativos ou dispositivos instalados.

Obtenção de tokens de acesso OAuth 2.0

Mesmo que seu aplicativo seja executado em um dispositivo com recursos de entrada limitados, os usuários devem ter acesso separado a um dispositivo com recursos de entrada mais ricos para concluir este 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 para os quais seu aplicativo solicitará permissão de acesso.
  2. O servidor responde com várias informações usadas nas etapas subsequentes, como um código de dispositivo e um código de usuário.
  3. Você exibe informações que o usuário pode inserir em um dispositivo separado para autorizar seu aplicativo.
  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 muda para um dispositivo com recursos de entrada mais avançados, inicia um navegador da web, navega até a URL exibida na etapa 3 e insere um código que também é exibido na etapa 3. O usuário pode então conceder (ou negar) acesso ao seu aplicativo.
  6. A próxima resposta à sua solicitação de pesquisa contém os tokens de que seu aplicativo precisa para autorizar solicitações em nome do usuário. (Se o usuário recusou o acesso ao seu aplicativo, a resposta não conterá tokens.)

A imagem abaixo ilustra esse processo:

O usuário faz login em um dispositivo separado que possui um navegador

As seções a seguir explicam essas etapas em detalhes. Dada a variedade de capacidades e ambientes de execução que os dispositivos podem ter, os exemplos mostrados neste documento usar a curl utilitário de linha de comando. Esses exemplos devem ser fáceis de transportar para várias linguagens e tempos de execução.

Etapa 1: Solicite o dispositivo e os códigos de usuário

Nesta etapa, o dispositivo envia uma solicitação HTTP POST para o servidor de autorização do Google, em https://oauth2.googleapis.com/device/code , que identifica a sua aplicação, bem como o acesso escopos que a sua aplicação deseja acesso on do usuário lado. Você deve recuperar essa URL do documento descoberta usando o device_authorization_endpoint valor de metadados. Inclua os seguintes parâmetros de solicitação HTTP:

Parâmetros
client_id Obrigatório

O ID do cliente para seu aplicativo. Você pode encontrar este valor no API ConsoleCredentials page.

scope Obrigatório

Uma lista de escopos delimitada por espaço que identifica os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe para o usuário. Veja a escopos admitidos lista de aplicativos ou dispositivos instalados.

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permite que os usuários controlem a quantidade de acesso que concedem ao seu aplicativo. Assim, existe uma relação inversa entre o número de escopos solicitados e a probabilidade de obtenção do consentimento do usuário.

Exemplos

O seguinte snippet 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 uma curl de comando para enviar o mesmo pedido:

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

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

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

Resposta de sucesso

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

Propriedades
device_code Um valor que o Google atribui exclusivamente para identificar o dispositivo que executa o aplicativo que solicita autorização. O usuário estará autorizando esse dispositivo a partir de outro dispositivo com recursos de entrada mais ricos. Por exemplo, um usuário pode usar um laptop ou telefone celular para autorizar a execução de um aplicativo em uma TV. Neste caso, o device_code identifica a TV.

Este código permite que o dispositivo que executa o aplicativo determine com segurança se o usuário concedeu ou negou acesso.

expires_in O período de tempo, em segundos, que o device_code e user_code são válidos. Se, nesse tempo, o usuário não concluir o fluxo de autorização e seu dispositivo também não pesquisar para recuperar informações sobre a decisão do usuário, pode ser necessário reiniciar este processo a partir da etapa 1.
interval O tempo, em segundos, que seu dispositivo deve aguardar entre as solicitações de polling. Por exemplo, se o valor for 5 , o dispositivo deve enviar um pedido de consulta para servidor de autorização do Google a cada cinco segundos. Veja o passo 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 de usuário instruirá o usuário a inserir esse valor em um dispositivo separado com recursos de entrada mais ricos. O Google então usa o valor para exibir o conjunto correto de escopos ao solicitar que o usuário conceda acesso ao seu aplicativo.
verification_url A URL que o usuário deve navegar para, em um dispositivo separado, para entrar no user_code e conceder ou negar acesso a sua aplicação. Sua interface de 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 suas solicitações de código de dispositivo excederem a cota associada ao seu ID de cliente, você receberá uma resposta 403, contendo o seguinte erro:

{
  "error_code": "rate_limit_exceeded"
}

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

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

Mostrar a verification_url e user_code obtido no passo 2 para o utilizador. Ambos os valores podem conter qualquer caractere imprimível do conjunto de caracteres US-ASCII. O conteúdo que você exibir para o usuário deveria instruir o usuário para navegar até o verification_url em um dispositivo separado e digite o user_code .

Projete sua interface de usuário (IU) com as seguintes regras em mente:

  • user_code
    • O user_code deve ser exibido em um campo que pode lidar com 15 'W' caracteres de tamanho. Em outras palavras, se você pode exibir o código WWWWWWWWWWWWWWW corretamente, sua interface é válida, e nós recomendamos usar esse valor de seqüência ao testar a forma como os user_code exibe em sua UI.
    • O user_code é caso-sensível e não deve ser modificado de qualquer maneira, tal como alterar o caso ou a inserção de outros caracteres de formatação.
  • verification_url
    • O espaço onde você exibir o verification_url deve ser grande o suficiente para lidar com uma cadeia de URL que é de 40 caracteres.
    • Você não deve modificar o verification_url de qualquer forma, exceto para remover opcionalmente o esquema para exibição. Se você fizer plano para retirar o esquema (por exemplo, https:// ) do URL por razões de exibição, certifique-se seu aplicativo pode manipular tanto http e https variantes.

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

Desde o usuário estará usando um dispositivo separado para navegar para o verification_url e concessão (ou negar) acesso, o dispositivo solicitante não é notificado automaticamente quando o usuário responde ao pedido 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 deve continuar a enviar pedidos de votação até receber uma resposta indicando que o usuário tenha respondido ao pedido de acesso ou até que o device_code e user_code obtido na etapa 2 ter expirado. O interval retornado na etapa 2 especifica a quantidade de tempo, em segundos, para aguardar entre pedidos.

O URL do ponto de extremidade para votação é https://oauth2.googleapis.com/token . A solicitação de sondagem contém os seguintes parâmetros:

Parâmetros
client_id O ID do cliente para seu aplicativo. Você pode encontrar este valor no API ConsoleCredentials page.
client_secret O segredo do cliente para o fornecido client_id . Você pode encontrar este valor no API ConsoleCredentials page.
device_code O device_code devolvido pelo servidor de autorização no passo 2 .
grant_type Defina esse valor como urn:ietf:params:oauth:grant-type:device_code .

Exemplos

O seguinte snippet 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 uma curl de comando para enviar o mesmo pedido:

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" \
         /token

Etapa 5: o usuário responde à solicitação de acesso

Os seguintes imagem mostra uma página semelhante ao que os usuários vêem quando navegar para o verification_url que você exibido na etapa 3 :

Conecte um dispositivo digitando um código

Depois de entrar no user_code e, se já não estiver conectado, fazer login no Google, o usuário vê uma tela de consentimento, como a mostrada abaixo:

Exemplo de tela de consentimento para um cliente de dispositivo

Etapa 6: lidar com as respostas às solicitações de sondagem

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

Acesso concedido

Se o concedido usuário o acesso ao dispositivo (clicando com o botão Allow na tela de consentimento), então a resposta contém um token de acesso e um token de atualização. Os tokens permitem que o dispositivo para acessar o Google APIs em nome do usuário. (O scope propriedade nos determina a resposta que apis o acesso ao dispositivo de lata).

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 você pode usar para obter um novo token de acesso. Os tokens de atualização são válidos até que o usuário revogue o acesso. Observe que os tokens de atualização sempre são retornados para os dispositivos.
scope Os escopos de acesso concedida pelo access_token expressa como uma lista de delimitado por espaço, cordas maiúsculas de minúsculas.
token_type O tipo de token retornado. Neste 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 uma vida útil limitada. Se seu aplicativo precisa de acesso a uma API durante um longo período de tempo, pode usar o token de atualização para obter um novo token de acesso. Se seu aplicativo precisa desse tipo de acesso, ele deve armazenar o token de atualização para uso posterior.

Acesso negado

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

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

Autorização pendente

Se o usuário ainda não tenha concluído o fluxo de autorização, então o servidor retorna um 428 HTTP código de status de resposta ( Precondition Required ). A resposta contém o seguinte erro:

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

Sondagem com muita frequência

Se o dispositivo envia pedidos de votação com muita freqüência, então o servidor retorna um 403 código de status de 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 retorna erros se a solicitação de sondagem estiver faltando algum parâmetro obrigatório ou tiver um valor de parâmetro incorreto. Estes pedidos geralmente têm um 400 ( Bad Request ) ou 401 ( Unauthorized ) HTTP código de status de resposta. Esses erros incluem:

Erro Código de status HTTP Descrição
invalid_client 401 O cliente OAuth não foi encontrado. Por exemplo, este erro ocorre se o client_id valor do parâmetro é inválido.
invalid_grant 400 O code valor do parâmetro é inválido.
unsupported_grant_type 400 O grant_type valor do parâmetro é inválido.

Chamando APIs do Google

Depois que seu aplicativo obtém um token de acesso, você pode usar o token para fazer chamadas para uma API do Google em nome de uma determinada conta de usuário, se o (s) escopo (s) de acesso exigido pela API tiver sido concedido. Para fazer isso, inclua o token de acesso em uma solicitação para a API, incluindo tanto uma access_token parâmetro de consulta ou um Authorization HTTP cabeçalho Bearer de valor. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ser visíveis nos logs do servidor. Na maioria dos casos, você pode usar uma biblioteca cliente para configurar suas chamadas para APIs do Google (por exemplo, quando chamar a API arquivos da unidade ).

Você pode experimentar todo o Google APIs e exibir seus escopos no OAuth 2.0 Playground .

Exemplos HTTP GET

Uma chamada para a drive.files endpoint (a API Arquivos Drive) utilizando o Authorization: Bearer cabeçalho HTTP pode parecer o seguinte. Observe que você precisa especificar seu próprio token de acesso:

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

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

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

curl exemplos

Você pode testar esses comandos com a curl aplicativo de linha de comando. Aqui está 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 de parâmetro de string de consulta:

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

Atualizando um token de acesso

Os tokens de acesso expiram periodicamente e se tornam credenciais inválidas para uma solicitação de API relacionada. Você pode atualizar um token de acesso sem solicitar permissão do usuário (incluindo quando o usuário não está presente) se você solicitou acesso offline aos escopos associados ao token.

Para atualizar um token de acesso, o aplicativo envia um HTTPS POST pedido 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 obtido a partir da API Console.
client_secret O segredo do cliente obtido a partir da API Console.
grant_type Como definido na especificação OAuth 2.0 , o valor deste campo deve ser configurado para refresh_token .
refresh_token O token de atualização retornado da troca do código de autorização.

O seguinte snippet 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

Desde que o usuário não revogue 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 de resposta:

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

Observe que 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 outro por usuário em todos os clientes. Você deve salvar tokens de atualização no armazenamento de longo prazo e continuar a usá-los enquanto permanecerem válidos. Se o seu aplicativo solicitar muitos tokens de atualização, ele pode atingir esses limites e, nesse caso, os tokens de atualização mais antigos deixarão de funcionar.

Revogando um token

Em alguns casos, um usuário pode desejar revogar o acesso concedido a um aplicativo. Um usuário pode revogar o acesso, visitando Configurações de Conta . Veja a seção de acesso Remover site ou aplicativo de sites e aplicativos de terceiros com acesso à sua conta documento de suporte para mais informações.

Também é possível que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante nos casos em que um usuário cancela a assinatura, remove um aplicativo ou os recursos de API exigidos por um aplicativo 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 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 um token de atualização. Se o token for um token 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 êxito, em seguida, o código de status HTTP da resposta é 200 . Para as condições de erro, um código de status HTTP 400 é devolvido junto com um código de erro.

Escopos permitidos

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

OpenID Ligação , Google Sign-In

  • email
  • openid
  • profile

API do Drive

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

API do YouTube

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