OAuth 2.0 Flow: Server-side web apps

Este fluxo OAuth 2.0 foi desenvolvido para aplicativos da Web com servidores que podem armazenar informações confidenciais e manter o estado. Esses aplicativos podem acessar o YouTube Data API enquanto o usuário está realmente usando o aplicativo ou após o usuário sair dele.

Este cenário começa quando um usuário tenta executar uma ação que requer autorização. O aplicativo redireciona o usuário a um URL do Google com os parâmetros de consulta que especificam o tipo de acesso de API exigido pelo aplicativo.

O Google lida com a autenticação e consentimento do usuário e retorna um código de autorização. O aplicativo usa esse código, além de seu client_id e client_secret, para receber um token de acesso, que pode ser usado para autorizar solicitações de API em nome do usuário. Nessa etapa, o aplicativo também pode solicitar um token de atualização para receber um novo token de acesso quando o token de acesso recebido antes expirar.

Important: You need to obtain authorization credentials in the Google API 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. 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.

    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.
    access_type Recomendação. Este parâmetro indica se seu aplicativo pode atualizar tokens de acesso quando o usuário não estiver presente no navegador. Os valores de parâmetro válidos são online e offline. Defina o valor deste parâmetro para offline para permitir que o aplicativo use tokens atualizados quando o usuário não estiver presente (este é o método de atualização de tokens de acesso descritas posteriormente neste documento).
    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=code&
      access_type=offline
    
  2. 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 ao redirect_uri que você especificou na etapa 1.

    • Se o usuário concedeu acesso a seu aplicativo, o Google anexa um parâmetro code a redirect_uri. Esse valor é um código de autorização temporário que você troca por um token de acesso, conforme descrito na etapa 4.

      http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf
    • 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. 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 3 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 3.
    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
    
  4. 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.