OAuth 2.0 Flow: Client-side web apps

Este fluxo do OAuth 2.0 foi projetado para permitir que aplicativos da Web baseados em JavaScript enviassem solicitações de API do Google autorizadas. Esses aplicativos não podem manter o estado ao longo do tempo, o que significa que o aplicativo acessa a YouTube Data API enquanto o usuário está presente no aplicativo. Este fluxo assume que o aplicativo não pode armazenar informações confidenciais.

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. 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. Registre URIs de redirecionamento válidos para seu aplicativo no APIs Console.
    response_type Obrigatório. Determina se o endpoint do OAuth 2.0 do Google retorna um código de autorização. Aplicativos JavaScript precisam definir o valor dos parâmetros para token. Com isso, o Servidor de autorização do Google é instruído a retornar o token de acesso como um par name=value no fragmento de hash (#) do URI de redirecionamento retornado pelo servidor.
    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.

    approval_prompt Opcional. Este parâmetro indica se o usuário deve receber uma solicitação para conceder acesso da conta ao aplicativo sempre que tentar completar uma ação específica. O valor padrão é auto, indicando que o usuário precisa apenas conceder acesso na primeira vez que tentar acessar um recurso protegido.

    Defina o valor do parâmetro para force para direcionar o usuário a uma página de consentimento, mesmo que já tenha concedido acesso a seu aplicativo por um conjunto de escopos determinado.
    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.
    login_hint Opcional. Se seu aplicativo souber qual usuário está tentando autenticar, este parâmetro poderá ser usado para apresentar um hint ao Servidor de autenticação do Google. O servidor usa o hint para simplificar o fluxo de login preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de multilogin apropriada.

    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=token
    
  2. Manipular respostas do Google

    Após o consentimento ou a recusa do usuário de conceder acesso a seu aplicativo, o Google redirecionará o usuário para o redirect_uri que você especificou na etapa 1.

    • Se o usuário concedeu acesso a seu aplicativo, o Google adicionará um token de acesso de curta duração no fragmento hash do URI de redirecionamento, conforme mostrado no URI de amostra abaixo. A resposta também inclui os parâmetros expires_in e token_type. Esses parâmetros descrevem, respectivamente, a vida útil do token em segundos e o tipo de token que está sendo retornado. Por fim, a resposta inclui o parâmetro state se um parâmetro state foi incluído na solicitação original para o servidor de autorização.

      http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600

      Nota: o aplicativo também deve permitir que outros parâmetros sejam incluídos no fragmento hash da resposta. O parágrafo acima descreve o conjunto mínimo de pares de nome-valor retornados no redirect_uri.

      O código JavaScript em execução em sua página pode capturar o token de acesso do valor window.location.hash e armazenar o token em um cookie ou POST em um servidor.

    • 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
  3. Validar o token do usuário

    Caso o usuário tenha concedido acesso a seu aplicativo, você precisará validar explicitamente o token retornado no redirect_uri. Ao validar ou verificar o token, você garante que seu aplicativo não fique vulnerável a problemas no Confused Deputy.

    Para validar o token, envie uma solicitação para https://www.googleapis.com/oauth2/v1/tokeninfo e defina o token como o valor do parâmetro access_token. Esse URL aceita e retorna informações sobre o token, incluindo o aplicativo ao qual o token foi emitido, o usuário associado ao token, os escopos aos quais o usuário concedeu acesso e o prazo de expiração do token.

    O URL de exemplo abaixo demonstra para onde você enviaria uma solicitação de validação do token:

    https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=ACCESS_TOKEN
  4. Processar a resposta a validação do token

    Em resposta a uma solicitação de validação do token, o servidor de autorização do Google retorna um objeto JSON que descreve o token ou contém uma mensagem de erro.

    • Se o token for válido, o objeto JSON incluirá as seguintes propriedades:

      Campos
      audience O aplicativo que é o usuário pretendido do token de acesso.

      Importante: antes de usar o token, você precisa verificar se o valor desse campo coincide exatamente com seu Client ID no Google APIs console. Esta verificação garante que seu aplicativo não fique vulnerável a problemas no Confused Deputy.
      expires_in Quantos segundos ainda restam para o token tornar-se inválido.
      scope Uma lista de escopos delimitada por espaços aos quais o usuário concede acesso. A lista deve coincidir com os escopos especificados na solicitação de autorização na etapa 1.
      userid Este valor permite correlacionar informações do perfil de múltiplas APIs do Google. Ele só estará presente na resposta se você incluiu o escopo https://www.googleapis.com/auth/userinfo.profile em sua solicitação na etapa 1. O valor do campo é um identificador imutável para o usuário conectado que pode ser usado para criar e gerenciar as sessões de usuário em seu aplicativo.

      Veja um exemplo de resposta:

      {
        "audience":"8819981768.apps.googleusercontent.com",
        "user_id":"123456789",
        "scope":"https://www.googleapis.com/auth/youtube",
        "expires_in":436
      }
      
    • Se o token expirou, foi adulterado, ou teve suas permissões revogadas, o servidor de autorização do Google retornará uma mensagem de erro no objeto JSON. O erro surge como um erro 400 e um corpo JSON no formato mostrado abaixo.

      {"error":"invalid_token"}

      Estruturalmente, nenhuma informação adicional é fornecida como o motivo da falha.

      Nota: na prática, um erro 400 geralmente indica que o URL de solicitação de token de acesso foi mal formada, normalmente devido a um escape impróprio de URL.

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.