OAuth 2.0 Flow: Installed apps

Este fluxo de OAuth 2.0 foi desenvolvido para aplicativos instalados em um dispositivo, como um telefone celular ou computador. Esses aplicativos podem acessar o YouTube Data API enquanto o usuário está interagindo com o aplicativo ou enquanto o aplicativo é executado em segundo plano por um período prolongado de tempo, sem interação direta do usuário.

O fluxo assume que o aplicativo não pode armazenar com segurança os tokens que permitem ao usuário interagir com YouTube Data API. Este fluxo também exige que o aplicativo tenha acesso ao navegador do sistema ou possa incorporar um controle de navegador. Se o aplicativo não cumprir qualquer uma dessas condições, consulte as instruções para dispositivos do OAuth 2.0 clicando na guia Dispositivos acima.

Important: You need to obtain authorization credentials in the Google Developers Console to be able to use OAuth 2.0 authorization.

This document contains the following sections:

Obtaining OAuth 2.0 access tokens

Este fluxo tem as seguintes etapas:

  1. Registrar seu aplicativo como um aplicativo instalado

    Ao registrar seu aplicativo, especifique que se trata de um aplicativo instalado. Isso gera um valor padrão diferente para o parâmetro redirect_uri.

  2. Adquirir um token de acesso

    Observação: as solicitações ao servidor de autorização do Google devem usar https em vez de http, pois o servidor é acessível somente por meio do protocolo SSL (HTTPS) e recusa conexões HTTP.

    Na primeira vez que o usuário tenta efetuar uma ação que requer autenticação do API, será necessário direcioná-lo ao servidor de autorização do Google em https://accounts.google.com/o/oauth2/auth. A tabela abaixo identifica os parâmetros do pedido que você precisa (ou pode) incluir no URL. O URI do pedido desenvolvido por você precisa conter valores de parâmetros com escape de URL apropriados.

    Parâmetros
    client_id Obrigatório. O ID do cliente OAuth 2.0 para seu aplicativo. É possível encontrar este valor no APIs Console .
    redirect_uri Obrigatório. Um redirect_uri registrado para seu ID de cliente. Ao registrar um aplicativo instalado, dois valores de redirect_uri são criados automaticamente: http://localhost:port e urn:ietf:wg:oauth:2.0:oob. As descrições abaixo ajudam você a escolher o valor apropriado para seu aplicativo.

    http://localhost:port
    Este valor indica que o servidor de autorização do Google deve retornar o código de autorização como parâmetro de string de consulta ao servidor Web do dispositivo do cliente. É necessário especificar o número da porta sem alterar a configuração no Google APIs console.

    Para receber um código de autorização para este URL, seu aplicativo deve estar conectado no servidor Web local. Se sua plataforma for compatível com esta abordagem, este será o mecanismo recomendado para adquirir o código de autorização. Note, porém, que algumas plataformas não são compatíveis com esta abordagem e que, mesmo se uma plataforma não for compatível, outro software (como o firewall do Windows, por exemplo) pode impedir o envio da mensagem.

    urn:ietf:wg:oauth:2.0:oob
    Este valor indica que o servidor de autorização do Google deve retornar o código de autorização na barra de título do navegador. Esta opção é útil caso o cliente não possa conectar uma porta HTTP sem modificações significativas no cliente. Esta característica está presente em aplicativos do Windows.

    Caso seu aplicativo use este valor, será necessário determinar quando o navegador carregou uma resposta a partir do servidor de autorização. Em seguida, ele extrai o código de autorização do título da página aberta no navegador. Consulte a etapa 4 para instruções específicas para analisar o token a partir do título da página.

    Seu aplicativo também deverá fechar a janela do navegador caso você queira impedir que o usuário veja a página com o código de autorização. O mecanismo para fechar a janela varia de acordo com a plataforma.
    response_type Obrigatório. Determina se o endpoint do OAuth 2.0 do Google retorna um código de autorização. Defina o valor do parâmetro para code.
    scope Obrigatório. Uma lista de escopos com espaço delimitado que identifica os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores determinam quais permissões são listadas na página de consentimento que o Google exibe ao usuário.

    A YouTube Data API é compatível com os seguintes escopos:

    Alcances
    https://www.googleapis.com/auth/youtube Gerenciar sua conta do YouTube.
    https://www.googleapis.com/auth/youtube.readonly Visualizar sua conta do YouTube.
    https://www.googleapis.com/auth/youtube.upload Enviar e gerenciar seus vídeos do YouTube.
    https://www.googleapis.com/auth/youtubepartner-channel-audit Recuperar a parte auditDetails em um recurso channel.

    state Opcional. Uma string usada por seu aplicativo para manter o estado entre solicitar e redirecionar a resposta. O valor exato enviado é retornado como um par name=value no fragmento de hash (#) de redirect_uri depois que o usuário consentir ou negar a solicitação de acesso de seu aplicativo. Este parâmetro pode ser usado para diversas finalidades, como direcionar o usuário ao recurso correto em seu aplicativo, enviar nonces e diminuir a falsificação de solicitações de outros sites.

    A amostra de URL abaixo mostra o URI do servidor de autorização do Google que solicita permissão a um aplicativo para enviar solicitações ao YouTube Data API em nome do usuário. Os valores do parâmetro devem ter escape de URL apropriado.

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
      scope=https://www.googleapis.com/auth/youtube&
      response_type=code&
      access_type=offline
    
  3. Manipular resposta do Google

    Após o consentimento ou recusa do usuário em conceder acesso a seu aplicativo, o Google redireciona o usuário para o redirect_uri que você especificou na etapa 2 ou retorna a página para o navegador do usuário.

    • Se você definir o redirect_uri para http://localhost (ou algum caminho no servidor da web local), um dos dois cenários a seguir é válido:

      • Se o usuário concedeu acesso a seu aplicativo, o Google anexa um parâmetro code ao redirect_uri como mostrado no URL do exemplo abaixo. Seu valor especifica um código de autorização de uso único que você troca por um token de acesso, conforme descrito na etapa 5.

        http://localhost/oauth2callback?code=SINGLE_USE_CODE
      • Se o usuário se recusou a conceder acesso a seu aplicativo, o Google incluirá a mensagem de erro access_denied no fragmento hash do redirect_uri:

        http://localhost/oauth2callback#error=access_denied
    • Se você definir o redirect_uri para urn:ietf:wg:oauth:2.0:oob, o servidor de autorização do Google retorna uma página para o navegador semelhante à página mostrada abaixo. O aplicativo extrai o código de autorização do título da página.

      Para extrair o token, o aplicativo deve assumir que tudo que vem depois do último caractere de espaço no título da página é uma string de parâmetros no formato x=a&y=b. Seu código deve analisar os parâmetros dessa substring à procura de uma atribuição code= ou error= para indicar que a página contém a string final do título e o fluxo de login do fluxo está completo. Se o título da página atribuir um valor para o parâmetro code, esse valor será o token. No entanto, seu aplicativo não deve fazer suposições sobre o comprimento do token ou o número de parâmetros na string de parâmetros.

      Por exemplo, a captura de tela abaixo mostra uma página com os seguintes atributos:

      • Título da página: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • String de parâmetros: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • Token de autorização: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

  4. Substituição do código de autorização para tokens de acesso e atualização

    Supondo que o usuário tenha acesso a seu aplicativo, troque o código de autorização recebido na etapa 4 por um toque de atualização e um token de acesso. Envie uma solicitação POST para https://accounts.google.com/o/oauth2/token com os seguintes pares de valores-chave no corpo:

    Chaves
    code O código de autorização que o Google retornou para redirect_uri na etapa 4.
    client_id ID do cliente do OAuth 2.0 para seu aplicativo. Esse valor é exibido no Google APIs console.
    client_secret O segredo do cliente associado a seu ID do cliente. Esse valor é exibido no Google APIs console.
    redirect_uri redirect_uri registrada para seu ID do cliente.
    grant_type Defina esse valor como authorization_code.

    Veja um exemplo de solicitação abaixo:

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
    redirect_uri=http://localhost/oauth2callback&
    grant_type=authorization_code
    
  5. Processar resposta e armazenar tokens

    O Google responderá à sua solicitação POST retornando um objeto JSON com um token de acesso de curta duração e um token de atualização.

    {
      "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
    }
    

Chamar YouTube Data API

Depois de receber um token de acesso de um usuário, seu aplicativo pode usar esse token para enviar solicitações de API autorizadas em nome do usuário. A API suporta duas maneiras de especificar um token de acesso:

  1. Especificar o token de acesso como o valor do cabeçalho de solicitação HTTP Authorization: Bearer. Este é o método recomendado.

    GET /youtube/v3/channels?part=id&mine=true HTTP/1.1
    Host: www.googleapis.com
    Authorization: Bearer ACCESS_TOKEN
    ...
    

    Você pode testar isso usando cURL com o seguinte comando:

    curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true
    
  2. Especificar o token de acesso como o valor do parâmetro de consulta access_token:

    https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

    Você pode testar isso usando cURL com o seguinte comando:

    curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN
    

A API retorna um código de resposta HTTP 401 (Unauthorized) se você enviar uma solicitação para acessar um recurso protegido com um token de acesso vencido, falso, de escopo incorreto, ou inválido por qualquer outro motivo.

Se a API retornar um código de resposta HTTP 403, seu aplicativo não poderá ser registrado. Muitas APIs definem um limite de consulta de volume de 0 para aplicativos sem registro e retornam um código de resposta 403 quando o limite de consulta de volume é ultrapassado.

A seção a seguir explica como atualizar um token de acesso.

Atualização do token de acesso

Tokens de acesso expiram periodicamente e, quando isso acontece, precisam ser atualizados. Quando um token de acesso expira, ou a qualquer outro momento, seu aplicativo poderá usar um token de atualização para receber um novo token de acesso válido. Aplicativos da Web do lado do servidor, aplicativos instalados e dispositivos recebem tokens de atualização durante o processo de autorização.

Para atualizar um token de acesso, o aplicativo envia uma solicitação POST ao servidor de autorização do Google que especifica seu ID do cliente, a chave secreta do cliente e o token de atualização para o usuário. A solicitação também define como refresh_token o valor do parâmetro grant_type. O exemplo a seguir demonstra essa solicitação:

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

O servidor de autorização retorna um objeto JSON com um novo token de acesso:

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer"
}

A quantidade de tokens de atualização emitidos é limitada, variando de um determinado limite para a combinação cliente/usuário e outro limite por usuário em todos os clientes. Os tokens de atualização devem ser salvos em um dispositivo de armazenamento de longo prazo para serem usados enquanto forem válidos. Caso seu aplicativo exija muitos tokens de atualização, esse limite pode ser atingido, o que fará com que os tokens de atualização deixem de funcionar.

Revogação de token

Há duas formas para revogar um token de acesso:

  • Um usuário pode revogar o acesso dado a um aplicativo acessando o seguinte URL e revogando explicitamente o acesso:

    https://accounts.google.com/b/0/IssuedAuthSubTokens

    As etapas a seguir explicam como chegar a esta página:

    1. Clique na imagem do usuário no sandbar do Google e clique no link Conta ou navegue até a página Visão geral da conta da Conta do Google do usuário.
    2. Siga o link para a página de configurações de Segurança.
    3. Clique no botão para gerenciar o acesso a aplicativos conectados e sites que podem acessar e usar detalhes da Conta do Google do usuário.

  • Um aplicativo pode revogar programaticamente seu próprio acesso. Este tipo de revogação é importante nos casos em que um usuário cancela a inscrição ou remove um aplicativo, em que uma solicitação do API para remover as permissões concedidas ao aplicativo devem fazer parte do processo de remoção.

    Para revogar programaticamente um token, o aplicativo envia uma solicitação para https://accounts.google.com/o/oauth2/revoke e inclui o token como um parâmetro:

    curl https://accounts.google.com/o/oauth2/revoke?token={token}

    O token especificado pode ser um token de acesso ou um token 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 ocorrer corretamente, o código de status da resposta será 200. Se ocorrer algum erro, o código de status da resposta será 400 e a resposta também conterá um código de erro.

Bibliotecas de clientes

Login com o Google

Observação: se você planeja oferecer login com o recurso do Google, recomendamos que você use o Google+ Sign-in, que fornece o mecanismo de autenticação OAuth 2.0 juntamente com acesso adicional a recursos sociais do Google+.

Você pode usar as bibliotecas de clientes listadas abaixo para implementar o OAuth 2.0 em seu aplicativo. Recomendamos o uso de bibliotecas de clientes em vez de escrever seu próprio código. As bibliotecas de clientes padrão são importantes para a segurança de seus usuários e de seu aplicativo.

Você também pode seguir as instruções na seção Chamando o aplicativo YouTube Data API para modificar seu código para usar o token OAuth 2.0 de forma adequada.