Este documento explica como implementar a autorização do 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 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 dos nomes de usuários, senhas e outras informações. Por exemplo, um aplicativo para 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, é pressuposto que os aplicativos não podem manter secrets. Eles podem acessar as APIs do Google enquanto o usuário está no app ou quando o app 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 Universal Windows), que tenha acesso ao navegador e a todos os recursos de entrada, use o fluxo do OAuth 2.0 para aplicativos de dispositivos móveis e de computador. Use esse fluxo mesmo que o app seja uma ferramenta de linha de comando sem uma interface gráfica.
Se você só quiser fazer login dos usuários com a Conta do Google e usar o token de ID do JWT para receber informações básicas de perfil do usuário, consulte Fazer 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:
- Open the API Library no Google API Console.
- If prompted, select a project, or create a new one.
- A 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 à qual ela pertence.
- Selecione aquela que você quer habilitar e clique no botão Ativar.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Criar credenciais de autorização
Qualquer aplicativo que usa 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 o projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou nesse projeto.
- Go to the Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth.
- Selecione o tipo de aplicativo TVs and Input Input Devices.
- Nomeie seu cliente OAuth 2.0 e clique em Criar.
Identificar escopos de acesso
Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de consentimento do usuário.
Antes de começar a implementar a autorização OAuth 2.0, recomendamos que você identifique os escopos que seu app 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 seu aplicativo 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:
- O 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 do dispositivo e um do usuário.
- Você mostra informações que o usuário pode inserir em um dispositivo diferente para autorizar o app.
- 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 para o URL exibido 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 aplicativo.
- A próxima resposta à solicitação de pesquisa contém os tokens que seu app precisa para autorizar solicitações em nome do usuário. Se o usuário tiver recusado o acesso ao seu aplicativo, a resposta não conterá 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
dos dispositivos, os exemplos mostrados neste documento usam o utilitário de
linha de comando curl. Esses exemplos devem ser fáceis de transferir para vários idiomas e ambientes de execução.
Etapa 1: solicitar códigos de dispositivo e usuário
Nesta etapa, seu dispositivo envia uma solicitação HTTP POST para o servidor de autorização do Google, em
https://oauth2.googleapis.com/device/code, que identifica seu aplicativo
e os escopos de acesso que ele quer acessar em nome do usuário.
É necessário recuperar esse URL do
documento de descoberta usando o
valor de metadados device_authorization_endpoint. Inclua os seguintes parâmetros de solicitação HTTP:
| Parâmetros | |
|---|---|
client_id |
Obrigatório
O ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials page. |
scope |
Obrigatório
Uma lista de escopos delimitada por espaços que identificam 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 apps ou dispositivos instalados. Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de receber 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: 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 de forma exclusiva para identificar o dispositivo que executa o app solicitando
autorização. O usuário autorizará o dispositivo a partir de outro dispositivo com recursos de entrada
mais avançados. Por exemplo, um usuário pode usar um laptop ou smartphone para autorizar um
app executado em uma TV. Nesse caso, o device_code identifica a TV.
Esse código permite que o dispositivo que executa o app determine com segurança se o usuário concedeu ou negou o acesso. |
expires_in |
O período de tempo, em segundos, em que device_code e user_code são válidos. Se, nesse momento, 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, talvez seja necessário reiniciar esse processo da etapa 1. |
interval |
O tempo, em segundos, que o dispositivo deve aguardar entre solicitações de pesquisa. Por
exemplo, se o valor for 5, o dispositivo vai enviar uma solicitação de pesquisa ao
servidor de autorização do Google a cada cinco segundos. Veja mais detalhes na etapa 3. |
user_code |
Um valor que diferencia maiúsculas de minúsculas e identifica para o Google os escopos aos quais o aplicativo está solicitando acesso. A interface do usuário vai instruir o usuário a inserir esse valor em um dispositivo separado com recursos de entrada mais avançados. Em seguida, 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 em que o usuário precisa navegar, em um dispositivo diferente, para inserir a
user_code e conceder ou negar o acesso ao aplicativo. A 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
}
Cota excedida de resposta
Se as solicitações de código do dispositivo excederem a cota associada ao ID do cliente, você 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: exibir o código do usuário
Mostre o verification_url e a user_code recebidos na etapa 2 ao
usuário. Os dois valores podem conter qualquer caractere imprimível do conjunto de caracteres ASCII dos EUA. O conteúdo
exibido precisa orientar o usuário a navegar até o
verification_url em um dispositivo diferente e inserir a user_code.
Projete a interface do usuário (IU) com as seguintes regras em mente:
user_code- O
user_codeprecisa ser exibido em um campo que processe 15 caracteres "W". Em outras palavras, se você pode exibir o códigoWWWWWWWWWWWWWWWcorretamente, a IU é válida. Recomendamos usar esse valor de string ao testar a forma comouser_codeé exibido na IU. - O
user_codediferencia 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.
- O
verification_url- O espaço em que você exibe
verification_urlprecisa ser grande o suficiente para processar uma string de URL com 40 caracteres. - Não modifique o
verification_urlde nenhuma forma, exceto para remover o esquema para exibição. Se você pretende remover o esquema (por exemplo,https://) do URL por motivos de exibição, verifique se o app pode processar as varianteshttpehttps.
- O espaço em que você exibe
Etapa 4: fazer uma pesquisa no servidor de autorização do Google
Como o usuário 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
responder à solicitação de acesso. Por isso, o dispositivo solicitante precisa pesquisar 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 as
device_code e user_code recebidas na
etapa 2 tenham expirado. O interval retornado na etapa 2 especifica o tempo, em segundos, de espera entre solicitações.
O URL do endpoint a ser pesquisado é https://oauth2.googleapis.com/token. A solicitação de pesquisa
contém os seguintes parâmetros:
| Parâmetros | |
|---|---|
client_id |
O ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials page. |
client_secret |
A chave secreta do cliente para a client_id fornecida. Esse valor pode ser encontrado no
API Console
Credentials 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 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 ao navegar para a
verification_url exibida na etapa 3:
Depois de inserir o user_code e, se ainda não tiver feito login, fazer login no Google,
o usuário verá uma tela de consentimento como a mostrada abaixo:
Etapa 6: lidar com as respostas às 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 vai conter um token de acesso e um de atualização. Os tokens permitem que o dispositivo acesse 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 ciclo de vida 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é que o usuário revogue o acesso. Os tokens de atualização são sempre retornados para dispositivos. |
scope |
Os escopos de acesso concedidos pelo access_token expressos como uma lista de
strings delimitadas por espaços, que diferenciam maiúsculas de minúsculas. |
token_type |
O tipo de token retornado. No momento, o valor desse campo está 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 um ciclo de vida limitado. Se o aplicativo precisar de acesso a uma API durante um longo período, ele poderá usar o token de atualização para receber um novo token. Caso seu aplicativo precise desse tipo de acesso, ele precisa 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 incluirá o
erro a seguir:
{
"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
conterá o seguinte erro:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
Pesquisas frequentes
Se o dispositivo enviar solicitações de pesquisa com muita frequência, o servidor retornará um código de status da 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 pesquisa 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 da resposta HTTP 400 (Bad Request) ou 401 (Unauthorized). Esses erros incluem:
| Erro | Código de status HTTP | Descrição |
|---|---|---|
admin_policy_enforced |
400 |
A Conta do Google não autoriza um ou mais escopos solicitados devido às políticas do administrador do Google Workspace. Consulte o artigo de ajuda do administrador do Google Workspace Controlar quais apps internos e de terceiros acessam os dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso aos escopos até que o acesso seja explicitamente concedido ao ID do cliente OAuth. |
invalid_client |
401 |
O cliente OAuth não foi encontrado. Por exemplo, esse erro ocorrerá se o valor do parâmetro O tipo de cliente OAuth está incorreto. Confira se o tipo de aplicativo do ID do cliente está definido como TVs e dispositivos de entrada limitada. |
invalid_grant |
400 |
O valor do parâmetro code é inválido, já foi reivindicado ou não pode ser
analisado. |
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 uma organização específica do Google Cloud. Confirme a configuração do tipo de usuário para seu aplicativo OAuth. |
Como chamar APIs do Google
Depois que seu aplicativo recebe um token de acesso, é possível 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 ser visíveis nos registros do servidor. Na maioria
dos casos, você pode usar uma biblioteca de cliente para configurar as chamadas para APIs do Google, por exemplo, ao
chamar a API Drive Files.
É possível testar todas as APIs do Google e ver os escopos delas 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 ser semelhante a esta. Você precisa 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 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. Veja 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 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. É possível atualizar um token de acesso sem solicitar permissão ao usuário (inclusive quando ele 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
para o 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 do API Console. |
grant_type |
Conforme definido na especificação do 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ódigo 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
Se o usuário não tiver revogado o acesso concedido ao aplicativo, o servidor do 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"
}
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. Salve tokens de atualização no armazenamento de longo prazo e continue usando-os, desde que permaneçam válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos vão parar de funcionar.
Como revogar um token
Em alguns casos, o usuário pode querer revogar o acesso dado a um aplicativo. Um usuário pode revogar o acesso acessando as Configurações da conta. Consulte a seção Remover o acesso do site ou app dos sites e apps de terceiros com acesso à sua conta para mais informações.
Também é possível que um aplicativo revogue de forma programática 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 da 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 de acesso ou de atualização. Se 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, 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
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
API YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly