Este documento explica como implementar a autorização OAuth 2.0 para acessar a API YouTube Data 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.
O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo a privacidade de nomes de usuário, senhas e outras informações. Por exemplo, um aplicativo de TV pode usar o OAuth 2.0 para receber permissão e 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 apps não podem manter secrets. Eles podem acessar as APIs do Google enquanto o usuário está usando o app ou quando o app está sendo executado 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 para dispositivos móveis e computador. Use esse fluxo mesmo que seu app seja uma ferramenta de linha de comando sem interface gráfica.
Se você quiser apenas fazer login de usuários com as Contas do Google deles e usar o token de ID do JWT para receber informações básicas do perfil do usuário, consulte 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 em 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 Data. Encontre e ative outras APIs que seu aplicativo vai usar.
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 o projeto. Seus aplicativos podem usar as credenciais para acessar as APIs ativadas para o 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 necessários e, ao mesmo tempo, permitem que os usuários controlem a quantidade de acesso que concedem ao aplicativo. Portanto, 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 o app 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 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 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:
- 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 subsequentes, como um código do dispositivo e um código do usuário.
- Mostre informações que o usuário pode inserir em um dispositivo separado para autorizar seu app.
- O aplicativo começa a sondar 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, inicia um navegador da Web, navega para o URL exibido na etapa 3 e insere um código que também é exibido na etapa 3. O usuário pode conceder (ou negar) acesso ao aplicativo.
- A próxima resposta à solicitação de pesquisa contém os tokens necessários para que o app autorize solicitações em nome do usuário. Se o usuário tiver recusado o acesso ao 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 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 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 o aplicativo, bem como os escopos de acesso que o aplicativo quer acessar em nome do usuário.
Recupere esse URL no 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 Escopos permitidos para saber quais apps ou dispositivos instalados. Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários, além de permitir que os usuários controlem a quantidade de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário. A API YouTube Data v3 utiliza os seguintes escopos:
O documento Escopos da API OAuth 2.0 apresenta uma lista completa dos escopos que podem ser usados para acessar as APIs do Google. |
||||||||||||||||
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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl
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%2Fyoutube.force-ssl" \
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 as seguintes propriedades:
| Propriedades | |
|---|---|
device_code |
Um valor atribuído pelo Google de maneira exclusiva para identificar o dispositivo que executa o app que solicita
autorização. O usuário vai autorizar o dispositivo a partir de outro 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 acesso. |
expires_in |
Por quanto tempo, em segundos, 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 também não pesquisar informações sobre a
decisão do usuário, talvez seja necessário reiniciar esse processo na etapa 1. |
interval |
O tempo, em segundos, que o dispositivo deve aguardar entre as solicitações de sondagem. Por exemplo, se o valor for 5, o dispositivo precisará 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 que 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. 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 precisa acessar, em um dispositivo separado, para inserir o
user_code e conceder ou negar o acesso ao aplicativo. A interface do usuário
também vai mostrar 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 seu 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 ao usuário o verification_url e a user_code da etapa 2. Ambos os valores podem conter qualquer caractere para impressão do conjunto de caracteres US-ASCII. O conteúdo
mostrado precisa instruir o usuário a navegar até o
verification_url em um dispositivo separado e inserir o user_code.
Projete sua interface do usuário (IU) tendo em mente as seguintes regras:
user_code- O
user_codeprecisa ser mostrado em um campo que pode processar 15 caracteres "W". Em outras palavras, se você consegue mostrar o códigoWWWWWWWWWWWWWWWcorretamente, sua interface é válida, e 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, como alterar maiúsculas e minúsculas ou inserir outros caracteres de formatação.
- O
verification_url- O espaço em que você exibe o
verification_urlprecisa ser largo o suficiente para processar uma string de URL com 40 caracteres. - Não modifique
verification_url, exceto para 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ê exibe o
Etapa 4: pesquisar o servidor de autorização do Google
Como o usuário usará um dispositivo separado para navegar até 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 consultar 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 os device_code e os user_code recebidos 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 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 o client_id fornecido. 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 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 verá uma tela de consentimento como esta:
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 seguintes respostas:
Acesso concedido
Se o usuário tiver concedido 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 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 |
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é que o usuário revogue 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, ele pode usar o token de atualização para receber um novo token de acesso. Caso seu aplicativo precise desse tipo de acesso, ele deve 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 vai conter o
seguinte erro:
{
"error": "access_denied",
"error_description": "Forbidden"
}
Autorização pendente
Se o usuário ainda não concluiu o fluxo de autorização, o servidor retorna 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 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 os 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 |
|---|---|---|
admin_policy_enforced |
400 |
A Conta do Google não pode autorizar um ou mais escopos solicitados devido às políticas do administrador do Google Workspace. Consulte o artigo de ajuda para admins 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 a escopos até que ele 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 para o 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 do Google Cloud específica. Confirme a configuração do tipo de usuário do aplicativo OAuth. |
Como chamar APIs do Google
Depois que o aplicativo recebe um token de acesso, é possível usá-lo para fazer chamadas a 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 Bearer de cabeçalho HTTP Authorization. Recomendamos usar o cabeçalho HTTP sempre que possível, porque as strings de consulta costumam ficar visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca de cliente para configurar chamadas para as APIs do Google (por exemplo, ao chamar a API de transmissão do YouTube ao vivo).
A API de transmissão do YouTube ao vivo não é compatível com o fluxo da conta de serviço. Como não
há uma forma de vincular uma conta de serviço a uma conta do YouTube, as tentativas de autorizar solicitações com esse
fluxo gerarão um erro NoLinkedYouTubeAccount.
É possível testar todas as APIs do Google e ver os escopos delas no OAuth 2.0 Playground.
Exemplos GET HTTP
Uma chamada para o endpoint
liveBroadcasts.list (a API YouTube Live Streaming) usando o cabeçalho HTTP Authorization: Bearer pode ter a seguinte aparência: É necessário especificar seu próprio token de acesso:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Veja abaixo uma chamada para a mesma API para o usuário autenticado com o parâmetro de string de consulta access_token:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Exemplos com 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/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Ou, alternativamente, a opção do parâmetro da string de consulta:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=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 pedir a permissão do usuário (mesmo quando ele não está presente) caso você tenha solicitado acesso off-line aos escopos associados ao token.
Para atualizar um token de acesso, o 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 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 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 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 esses tokens em um armazenamento de longo prazo e continue a usá-los enquanto permanecerem 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 deixarão 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 visitando 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 nos casos em que um usuário cancela a inscrição, remove um aplicativo ou quando os recursos da API exigidos por um app 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 um token de forma programática, 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 for um token de acesso e tiver um token de atualização correspondente, este 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 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
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