Este documento explica como implementar a autorização OAuth 2.0 para acessar a API Data do YouTube 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, é 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á 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 se seu aplicativo for uma linha de comando sem uma interface gráfica.
Se você só quer fazer login dos usuários com as Contas do Google deles 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 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.
- Use a página "Biblioteca" para encontrar e ativar a API YouTube Content ID. Encontre outras APIs que seu pelo aplicativo vai usá-los e ativá-los.
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 nesse projeto.
- Go to the Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth.
- Selecione o tipo de aplicativo TVs e dispositivos de entrada limitados.
- 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, 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.
A API YouTube Data v3 utiliza os seguintes escopos:
| Escopos | |
|---|---|
| https://www.googleapis.com/auth/youtube | Gerenciar sua conta do YouTube |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Ver uma lista dos membros ativos atuais do canal, do nível deles e de quando se tornaram membros |
| https://www.googleapis.com/auth/youtube.force-ssl | Ver, editar e excluir permanentemente vídeos, classificações, comentários e legendas do YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Visualize sua conta do YouTube |
| https://www.googleapis.com/auth/youtube.upload | Gerenciar seus vídeos do YouTube |
| https://www.googleapis.com/auth/youtubepartner | Ver e gerenciar seus ativos e conteúdos associados no YouTube |
| https://www.googleapis.com/auth/youtubepartner-channel-audit | Visualiza as informações particulares do seu canal que são relevantes para o processo de auditoria com um parceiro do YouTube |
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 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:
- 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.
- 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.
- Você exibe informações que o usuário pode inserir em um dispositivo separado para autorizar seu app.
- O aplicativo começa a consultar o servidor de autorização do Google para determinar se o usuário autorizou o app.
- 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.
- 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 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 transferir para várias linguagens e ambientes de execução.
Etapa 1: solicitar códigos de dispositivo e de 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 os seguintes parâmetros de solicitação
HTTP:
| Parâmetros | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente do seu aplicativo. Esse valor está no API Console Credentials page. |
||||||||||||||||
scope |
Obrigatório
Uma lista de escopos delimitada por espaços que identifica os recursos que o aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google mostra 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. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário. A API YouTube Data v3 usa os seguintes escopos:
O documento Escopos da API OAuth 2.0 (em inglês) fornece uma lista completa de escopos que podem ser usados para acessar as APIs do Google. |
||||||||||||||||
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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutubepartner
Este exemplo mostra um comando curl para enviar a mesma solicitação:
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutubepartner" \
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 em outro dispositivo com recursos de entrada
mais avançados. 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 app determine com segurança se o usuário concedeu ou negou o acesso. |
expires_in |
O tempo, em segundos, em 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 o dispositivo não consultar para recuperar informações sobre a
decisão do usuário, talvez seja necessário reiniciar o processo a partir da etapa 1. |
interval |
O tempo, em segundos, que seu dispositivo deve aguardar entre as solicitações de sondagem. 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. Consulte
etapa 3 para mais detalhes. |
user_code |
Um valor que diferencia maiúsculas de minúsculas e identifica ao Google os escopos a que 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, 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 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.
Ao projetar a interface do usuário (IU), siga estas regras:
user_code- O
user_codeprecisa ser exibido em um campo que possa processar 15 caracteres de tamanho 'W'. Em outras palavras, se você conseguir mostrar o códigoWWWWWWWWWWWWWWWcorretamente, a interface é válida. Recomendamos usar esse valor de string ao testar a forma como ouser_codeé mostrado na interface. - 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ê mostra o
verification_urlprecisa ser largo o suficiente para processar uma string de URL de 40 caracteres. - Não modifique
verification_url, exceto para opcionalmente e remover o esquema para exibição. Se você planeja 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ê mostra o
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 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 o tempo de espera, em segundos, entre as solicitações.
O URL do endpoint a ser consultado é 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 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 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 a solicitações de pesquisa
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
acesso às 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 são sempre retornados para dispositivos. |
scope |
Os escopos de acesso concedidos pelo access_token são expressos como uma lista de
strings delimitadas por espaços e diferenciadas por maiúsculas e 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 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 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 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 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 código de status de 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 consegue autorizar um ou mais escopos solicitados devido às 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 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
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 um determinado Organização do Google Cloud. Confirme a configuração do tipo de usuário para seu app OAuth. |
Como chamar APIs do Google
Depois que o aplicativo receber um token de acesso, ele poderá ser usado 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 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 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 YouTube Content ID.
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
contentOwners.list
(a API Content ID do YouTube) usando o cabeçalho HTTP
Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:
GET /youtubepartner/v1/contentOwners?fetchMine=true 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/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true
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/youtubepartner/v1/contentOwners?fetchMine=true
Ou, alternativamente, a opção do parâmetro da string de consulta:
curl https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true
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 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
definido na
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 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",
"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 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.
Revogar 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 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 para um aplicativo revogar 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, 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 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 OAuth 2.0 para dispositivos tem suporte apenas para 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
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 assinar notificações de eventos de segurança que fornecem informações ao seu app sobre mudanças importantes na conta do usuário. Você pode então usar as informações para tomar medidas dependendo como você decide responder aos eventos.
Confira alguns exemplos de tipos de eventos enviados ao seu app pelo serviço de proteção entre contas do Google:
-
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 página Proteger contas de usuários com a Proteção entre contas para mais informações sobre como implementar a Proteção entre contas e a lista completa de eventos disponíveis.