OAuth 2.0 Flow: Devices

Este fluxo do OAuth 2.0 é projetado para aplicativos que são executados em dispositivos com recursos limitados de entrada, tais como consoles de jogos ou câmeras de vídeo. Neste fluxo, o usuário interage com um aplicativo no dispositivo para obter uma URL e um código de dispositivo. Em seguida, o usuário muda para outro dispositivo, como um computador ou smartphone, que tem recursos de entrada mais ricos para autorizar o código do dispositivo.

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. Insira seu client_id e client_secret em seu aplicativo

    Você precisa registrar seu aplicativo com o Google e inserir em seu aplicativo o client ID e client secret criados durante o processo de registro. Ambos os valores são exibidos no Google APIs console.

  2. Solicite um código de dispositivo

    O dispositivo envia uma solicitação de POST ao servidor de autorização do Google em https://accounts.google.com/o/oauth2/device/code. A solicitação especifica os seguintes parâmetros:

    Parâmetros
    client_id Obrigatório. O ID do cliente do OAuth 2.0 para seu aplicativo.
    scope Obrigatório. A lista de escopos delimitada por espaços que identificam os recursos que seu aplicativo pode acessar em nome do usuário.

    O exemplo de solicitação a seguir mostra como recuperar um código de dispositivo:

    POST /o/oauth2/device/code HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    scope=https://www.googleapis.com/auth/youtube
    
  3. Manipule respostas do Google

    O Google responde sua solicitação, retornando um objeto JSON para seu dispositivo. O exemplo de resposta é exibido abaixo:

    {
      "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
      "user_code" : "a9xfwk9c",
      "verification_url" : "http://www.google.com/device",
      "expires_in" : "1800"
      "interval" : 5,
    }
    

    O aplicativo em seu dispositivo deve exibir o user_code e o verification_url para o usuário. Ele deve armazenar os valores device_code, expires_in e interval para uso na etapa 4.

  4. Comece a sondar o servidor de autorização do Google

    Seu aplicativo pode começar a sondar o servidor de autorização do Google usando o device_code retornado na resposta JSON na etapa 3. Para isso, o aplicativo envia uma solicitação POST para https://accounts.google.com/o/oauth2/token que especifica os seguintes pares de valores-chave:

    Chaves
    client_id O ID do cliente do OAuth 2.0 para seu aplicativo.
    client_secret O segredo do cliente associado a seu ID do cliente. Esse valor é exibido no Google APIs console.
    code O código do dispositivo obtido na etapa 3.
    grant_type Defina esse valor como http://oauth.net/grant_type/device/1.0.

    Um exemplo de solicitação de sondagem é mostrado abaixo. O interval retornado na resposta JSON na etapa 3 especifica a quantidade mínima de tempo (em segundos) que seu aplicativo deve aguardar entre as solicitações de sondagem.

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
    code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
    grant_type=http://oauth.net/grant_type/device/1.0
    

    Até que o usuário conclua as etapas 5 a 7, seu aplicativo receberá uma das seguintes respostas para cada solicitação de sondagem:

    • A resposta a seguir indica que o usuário ainda não concluiu as etapas para conceder acesso à API para o dispositivo:

      {
        "error" : "authorization_pending"
      }
      
    • A resposta a seguir indica que o aplicativo está enviando solicitações de sondagem com muita frequência:

      {
        "error" : "slow_down"
      }
      
  5. O usuário digita user_code em outro navegador

    O usuário abre um navegador em outro dispositivo, como um computador ou telefone celular, e navega até verification_url. O URL exibe uma página na qual o usuário pode digitar o user_code obtido na etapa 3.

    Nota: como o user_code faz distinção entre maiúsculas e minúsculas, o usuário precisa digitá-lo exatamente como ele aparece na resposta.

  6. O usuário efetua login na conta do Google

    Depois de digitar o user_code, o usuário deve efetuar login na Conta do Google que será usada para autorizar solicitações de YouTube Data API a partir de seu dispositivo (os usuários que já efetuaram login continuam diretamente na próxima etapa).

  7. Resposta do processo do servidor de sondagem para obter tokens

    Se o usuário conceder acesso a seu aplicativo, a próxima solicitação de sondagem que o dispositivo enviar retornará um objeto JSON que contém um token de acesso e um token de atualização.

    {
      "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
      "expires_in":3920,
      "token_type":"Bearer",
      "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
    }
    

    Importante: O aplicativo deve armazenar os dois valores.

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.