Este documento explica como implementar a autorização OAuth 2.0 para acessar as 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 o 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, supõe-se que os aplicativos não podem manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está presente 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 a Plataforma Universal do Windows), que tenha acesso ao navegador e recursos de entrada completos, use o fluxo OAuth 2.0 para aplicativos móveis e de desktop . (Você deve usar esse fluxo mesmo que seu aplicativo seja uma ferramenta de linha de comando sem uma interface gráfica.)
Se você quiser apenas fazer login de usuários com suas contas do Google e usar o token de ID JWT para obter informações básicas de perfil de usuário, consulte Login em TVs e dispositivos de entrada limitados .
Pré-requisitos
Habilite APIs para seu projeto
Qualquer aplicativo que chame as APIs do Google precisa ativar essas APIs no API Console.
Para habilitar uma API para seu projeto:
- Open the API Library no Google API Console.
- If prompted, select a project, or create a new one.
- O API Library lista todas as APIs disponíveis, agrupadas por família de produtos e popularidade. Se a API que você deseja ativar não estiver visível na lista, use a pesquisa para encontrá-la ou clique em Visualizar tudo na família de produtos à qual ela pertence.
- Selecione a API que deseja habilitar e clique no botão Habilitar .
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Criar credenciais de autorização
Qualquer aplicativo que use OAuth 2.0 para acessar as APIs do Google deve 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ê habilitou para esse projeto.
- Go to the Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth .
- Selecione o tipo de aplicativo TVs e dispositivos de entrada limitada .
- 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 de que precisa, ao mesmo tempo em que permitem 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 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 seu aplicativo precisará de permissão para acessar.
Consulte a lista de escopos permitidos para aplicativos ou dispositivos instalados.
Como obter 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 avançados para concluir esse fluxo de autorização. O fluxo tem as seguintes etapas:
- Seu aplicativo envia uma solicitação ao servidor de autorização do Google que identifica os escopos que seu aplicativo solicitará permissão para acessar.
- 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.
- Você exibe informações que o usuário pode inserir em um dispositivo separado para autorizar seu aplicativo.
- Seu aplicativo começa a pesquisar o servidor de autorização do Google para determinar se o usuário autorizou seu aplicativo.
- O usuário alterna 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 conceder (ou negar) acesso ao seu aplicativo.
- A próxima resposta à sua solicitação de pesquisa contém os tokens 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 contém tokens.)
A imagem abaixo ilustra esse processo:
As seções a seguir explicam essas etapas em detalhes. Dada a variedade de recursos e ambientes de tempo de execução que os dispositivos podem ter, os exemplos mostrados neste documento usam o utilitário de linha de comando curl . Esses exemplos devem ser fáceis de portar para vários idiomas e tempos de execução.
Etapa 1: solicitar códigos de dispositivo e usuário
Nesta etapa, seu dispositivo envia uma solicitação HTTP POST ao servidor de autorização do Google, em https://oauth2.googleapis.com/device/code , que identifica seu aplicativo, bem como os escopos de acesso que seu aplicativo deseja acessar no usuário lado. Você deve recuperar essa URL do documento Discovery usando o valor de metadados device_authorization_endpoint . Inclua os seguintes parâmetros de solicitação HTTP:
| Parâmetros | |
|---|---|
client_id | Requeridos O ID do cliente para seu aplicativo. Você pode encontrar esse valor no API ConsoleCredentials page. |
scope | Requeridos 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 ao usuário. Consulte a lista de escopos permitidos para aplicativos ou dispositivos instalados. Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo em que permitem que os usuários controlem a quantidade de acesso que concedem ao seu aplicativo. Assim, 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 uma solicitação de amostra:
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: 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 a autorização. O usuário autorizará esse dispositivo a partir de outro dispositivo com recursos de entrada mais avançados. Por exemplo, um usuário pode usar um laptop ou celular para autorizar um aplicativo 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 ou negou acesso. |
expires_in | O período de tempo, em segundos, que device_code e user_code são válidos. Se, nesse período, o usuário não concluir o fluxo de autorização e seu dispositivo também não fizer uma pesquisa para recuperar informações sobre a decisão do usuário, talvez seja necessário reiniciar esse processo a partir da etapa 1. |
interval | O tempo, em segundos, que seu dispositivo deve esperar entre as solicitações de sondagem. Por exemplo, se o valor for 5 , seu dispositivo deverá enviar uma solicitação de pesquisa ao servidor de autorização do Google a cada cinco segundos. Consulte a etapa 3 para obter mais detalhes. |
user_code | Um valor que diferencia maiúsculas de minúsculas que identifica ao 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 avançados. O Google usa o valor para exibir o conjunto correto de escopos ao solicitar que o usuário conceda acesso ao seu aplicativo. |
verification_url | Um URL para o qual o usuário deve navegar, em um dispositivo separado, para inserir o user_code e conceder ou negar acesso ao seu aplicativo. 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 as solicitações de código do seu dispositivo excederam 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
Exiba o URL de verification_url e o user_code de usuário obtidos na etapa 2 para o usuário. Ambos os valores podem conter qualquer caractere imprimível do conjunto de caracteres US-ASCII. O conteúdo que você exibe para o usuário deve instruí-lo a navegar até a verification_url em um dispositivo separado e inserir o user_code .
Projete sua interface do usuário (IU) com as seguintes regras em mente:
-
user_code- O
user_codedeve ser exibido em um campo que possa lidar com 15 caracteres de tamanho 'W'. Em outras palavras, se você puder exibir o códigoWWWWWWWWWWWWWWWcorretamente, sua interface do usuário é válida e recomendamos usar esse valor de string ao testar a maneira como ouser_codeexibido em sua interface do usuário. - O
user_codefaz distinção entre maiúsculas e minúsculas e não deve ser modificado de forma alguma, como alterar o caso ou inserir outros caracteres de formatação.
- O
-
verification_url- O espaço em que você exibe o
verification_urldeve ser amplo o suficiente para lidar com uma string de URL com 40 caracteres. - Você não deve modificar o
verification_urlde forma alguma, exceto para remover opcionalmente o esquema para exibição. Se você planeja remover o esquema (por exemplo,https://) do URL por motivos de exibição, certifique-se de que seu aplicativo possa lidar com varianteshttpehttps.
- O espaço em que você exibe o
Etapa 4: faça uma pesquisa no servidor de autorização do Google
Como o usuário usará um dispositivo separado para navegar até o URL de verification_url e conceder (ou negar) acesso, o dispositivo solicitante não será notificado automaticamente quando o usuário responder à solicitação de acesso. Por esse motivo, o dispositivo solicitante precisa sondar o servidor de autorização do Google para determinar quando o usuário respondeu à solicitação.
O dispositivo solicitante deve continuar enviando solicitações de polling 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, de espera 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 para seu aplicativo. Você pode encontrar esse valor no API ConsoleCredentials page. |
client_secret | O segredo do cliente para o client_id fornecido. Você pode encontrar esse valor no API ConsoleCredentials page. |
device_code | O device_code retornado pelo servidor de autorização na etapa 2 . |
grant_type | Defina esse valor como urn:ietf:params:oauth:grant-type:device_code . |
Exemplos
O snippet a seguir mostra uma solicitação de amostra:
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" \
/tokenEtapa 5: o usuário responde à solicitação de acesso
A imagem a seguir mostra uma página semelhante à que os usuários veem quando navegam até o URL de verification_url que você exibiu na etapa 3 :
Após inserir o user_code e, se ainda não estiver logado, fazer login no Google, o usuário vê uma tela de consentimento como a mostrada abaixo:
Etapa 6: lidar com respostas a solicitações de sondagem
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 contém um token de acesso e um token de atualização. Os tokens permitem que seu dispositivo acesse as 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:
| Campos | |
|---|---|
access_token | O token que seu aplicativo envia para autorizar uma solicitação de API do Google. |
expires_in | O tempo de vida 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 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. Neste momento, o valor deste 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 precisar de acesso a uma API por um longo período de tempo, ele poderá usar o token de atualização para obter um novo token de acesso. Se seu aplicativo precisar desse tipo de acesso, ele deverá 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 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"
}Sondagem com muita frequência
Se o dispositivo enviar solicitações de sondagem com muita frequência, o servidor retornará um código de status de resposta HTTP 403 ( 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 não tiver 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:
| Erro | Código de status HTTP | Descrição |
|---|---|---|
invalid_client | 401 | O cliente OAuth não foi encontrado. Por exemplo, esse erro ocorre se o valor do parâmetro client_id for inválido. |
invalid_grant | 400 | O valor do parâmetro de code é inválido. |
unsupported_grant_type | 400 | O valor do parâmetro grant_type é inválido. |
Chamando APIs do Google
Depois que seu aplicativo obtiver um token de acesso, você poderá usar o token 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 à API incluindo um parâmetro de consulta access_token ou um valor de Bearer do cabeçalho HTTP de Authorization . 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 as APIs do Google (por exemplo, ao chamar a API Drive Files ).
Você pode experimentar todas as APIs do Google e visualizar seus escopos no OAuth 2.0 Playground .
Exemplos de HTTP GET
Uma chamada para o endpoint drive.files (a API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ter a seguinte aparência. 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 parâmetro de string de consulta access_token :
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
exemplos curl
Você pode testar esses comandos com o aplicativo de linha de comando curl . 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 ao usuário (inclusive quando o usuário não estiver presente) se tiver solicitado acesso offline aos escopos associados ao token.
Para atualizar um token de acesso, seu aplicativo envia uma solicitação HTTPS POST 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 do API Console. |
client_secret | O segredo do cliente obtido do API Console. |
grant_type | Conforme definido na especificação OAuth 2.0 , o valor desse campo deve ser definido como refresh_token . |
refresh_token | O token de atualização retornado da troca de código de autorização. |
O snippet a seguir mostra uma solicitação de amostra:
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 tenha revogado o acesso concedido ao aplicativo, o servidor de token 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",
"token_type": "Bearer"
}Observe que 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. Você deve salvar os tokens de atualização no armazenamento de longo prazo e continuar a usá-los enquanto permanecerem válidos. Se seu aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites e, nesse caso, os tokens de atualização mais antigos deixarão de funcionar.
Revogar um token
Em alguns casos, um usuário pode querer revogar o acesso dado a um aplicativo. Um usuário pode revogar o acesso visitando Configurações da conta . Consulte a seção Remover acesso ao site ou aplicativo dos sites e aplicativos de terceiros com acesso ao documento de suporte da sua conta para obter 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 inscrição, remove um aplicativo ou os recursos de API exigidos por um aplicativo foram significativamente alterados. 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 programaticamente, seu aplicativo faz uma solicitação para https://oauth2.googleapis.com/revoke e inclui o token como 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, 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 OAuth 2.0 para dispositivos é compatível apenas com os seguintes escopos:
OpenID Connect , Login do Google
-
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