OAuth 2.0 para apps para dispositivos móveis e de computador

Este documento explica como os aplicativos instalados em dispositivos como smartphones, tablets e computadores usam os endpoints OAuth 2.0 do Google para autorizar o acesso às APIs do Google.

O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo a privacidade de nomes, senhas e outras informações. Por exemplo, um aplicativo pode usar o OAuth 2.0 para receber permissão dos usuários para armazenar arquivos no Google Drive.

Os apps instalados são distribuídos para dispositivos individuais, e presume-se que eles não podem manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está presente no app ou quando ele está em execução em segundo plano.

Esse fluxo de autorização é semelhante ao usado para aplicativos de servidor da Web. A principal diferença é que os apps instalados precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local para processar as respostas do servidor de autorização do Google.

Alternativas

Para apps para dispositivos móveis, é recomendável usar o recurso de login do Google para Android ou iOS. As bibliotecas de cliente do Login do Google processam a autenticação e a autorização do usuário e podem ser mais simples de implementar do que o protocolo de nível inferior descrito aqui.

Para apps executados em dispositivos que não oferecem suporte a um navegador do sistema ou que têm recursos de entrada limitados, como TVs, consoles de jogos, câmeras ou impressoras, consulte OAuth 2.0 para TVs e dispositivos ou Fazer login em TVs e dispositivos de entrada limitada.

Bibliotecas e amostras

Recomendamos as bibliotecas e os exemplos a seguir para ajudar a implementar o fluxo do OAuth 2.0 descrito neste documento:

• Biblioteca AppAuth para Android
• Biblioteca AppAuth para iOS
• OAuth para apps: exemplos do Windows

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame as APIs do Google precisa ativar essas APIs no API Console.

Para ativar uma API para um projeto, faça o seguinte:

1. Open the API Library no Google API Console.
2. If prompted, select a project, or create a new one.
3. O API Library lista todas as APIs disponíveis, agrupadas por família de produtos e popularidade. Se a API que você quer ativar não estiver visível na lista, use a pesquisa para encontrá-la ou clique em Ver tudo na família de produtos a que ela pertence.
4. Selecione aquela que você quer habilitar e clique no botão Ativar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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 seu projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou para esse projeto.

1. Go to the Credentials page.
2. Clique em Criar credenciais > ID do cliente OAuth.
3. As seções a seguir descrevem os tipos de cliente compatíveis com o servidor de autorização do Google. Escolha o tipo de cliente recomendado para seu aplicativo, nomeie o cliente OAuth e defina os outros campos do formulário conforme apropriado.

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao seu aplicativo. Portanto, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário.

Antes de começar a implementar a autorização do OAuth 2.0, recomendamos identificar os escopos que o app vai precisar de permissão para acessar.

O documento Escopos da API OAuth 2.0 contém uma lista completa de escopos que podem ser usados para acessar as APIs do Google.

Como conseguir tokens de acesso do OAuth 2.0

As etapas a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para receber o consentimento de um usuário e realizar uma solicitação de API em nome dele. Seu aplicativo precisa ter esse consentimento antes de executar uma solicitação da API Google que exija autorização do usuário.

Etapa 1: gerar um verificador de código e um desafio

O Google oferece suporte ao protocolo chave de prova para troca de código (PKCE, na sigla em inglês) para tornar o fluxo do app instalado mais seguro. Um verificador de código exclusivo é criado para cada solicitação de autorização, e o valor transformado, chamado de "code_challenge", é enviado ao servidor de autorização para receber o código de autorização.

Criar o verificador de código

Uma code_verifier é uma string aleatória criptográfica de alta entropia que usa os caracteres não reservados [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", com um comprimento mínimo de 43 caracteres e um comprimento máximo de 128 caracteres.

O verificador de código precisa ter entropia suficiente para tornar impraticável adivinhar o valor.

Criar o desafio de código

Há suporte para dois métodos de criação do desafio de código.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Etapa 2: enviar uma solicitação para o servidor OAuth 2.0 do Google

Para receber a autorização do usuário, envie uma solicitação ao servidor de autorização do Google em https://accounts.google.com/o/oauth2/v2/auth. Esse endpoint processa a pesquisa de sessão ativa, autentica o usuário e recebe o consentimento dele. O endpoint só é acessível por SSL e recusa conexões HTTP (não SSL).

O servidor de autorização oferece suporte aos seguintes parâmetros de string de consulta para aplicativos instalados:

Exemplos de URLs de autorização

As guias abaixo mostram URLs de autorização de exemplo para as diferentes opções de URI de redirecionamento.

Os URLs são idênticos, exceto pelo valor do parâmetro redirect_uri. Os URLs também contêm os parâmetros obrigatórios response_type e client_id, bem como o parâmetro opcional state. Cada URL contém quebras de linha e espaços para facilitar a leitura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Etapa 3: o Google solicita consentimento ao usuário

Nesta etapa, o usuário decide se concede ou não o acesso solicitado ao seu app. Nesse estágio, o Google exibe uma janela de consentimento que mostra o nome do seu aplicativo e os serviços da API do Google que ele está solicitando permissão para acessar com as credenciais de autorização do usuário e um resumo dos escopos de acesso a serem concedidos. O usuário pode consentir em conceder acesso a um ou mais escopos solicitados pelo aplicativo ou recusar a solicitação.

O aplicativo não precisa fazer nada nessa etapa, porque ele aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na etapa a seguir.

Etapa 4: processar a resposta do servidor OAuth 2.0

A maneira como seu aplicativo recebe a resposta de autorização depende do esquema de URI de redirecionamento usado. Independentemente do esquema, a resposta vai conter um código de autorização (code) ou um erro (error). Por exemplo, error=access_denied indica que o usuário recusou a solicitação.

Se o usuário conceder acesso ao seu aplicativo, você poderá trocar o código de autorização por um token de acesso e um token de atualização, conforme descrito na próxima etapa.

Etapa 5: trocar o código de autorização por tokens de atualização e de acesso

Para trocar um código de autorização por um token de acesso, chame o endpoint https://oauth2.googleapis.com/token e defina os seguintes parâmetros:

O snippet a seguir mostra uma solicitação de exemplo:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

O Google responde a essa solicitação retornando um objeto JSON que contém um token de acesso de curta duração e um token de atualização.

A resposta contém os seguintes campos:

O snippet a seguir mostra um exemplo de resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Etapa 6: verificar quais escopos os usuários concederam

Ao solicitar vários escopos de uma só vez, os usuários podem não conceder todos os escopos solicitados pelo app. O app precisa sempre verificar quais escopos foram concedidos pelo usuário e processar qualquer negação de escopos desativando os recursos relevantes. Consulte Como gerenciar permissões granulares para mais informações.

Para verificar se o usuário concedeu ao seu app acesso a um escopo específico, examine o campo scope na resposta do token de acesso. Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings sensíveis a maiúsculas e minúsculas delimitadas por espaço.

Por exemplo, a resposta de token de acesso de exemplo a seguir indica que o usuário concedeu ao seu app acesso às permissões de eventos da Agenda e de atividade do Drive somente leitura:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Como chamar APIs do Google

Depois que o aplicativo receber um token de acesso, ele poderá usá-lo para fazer chamadas para 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 para a API incluindo um parâmetro de consulta access_token ou um valor Bearer de cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, é possível usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google. Por exemplo, ao chamar a API Drive Files.

Teste todas as APIs do Google e confira os escopos delas no OAuth 2.0 Playground.

Exemplos de GET HTTP

Uma chamada para o endpoint drive.files (a API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta é uma chamada para a mesma API do usuário autenticado usando o parâmetro de string de consulta access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Exemplos de curl

É possível testar esses comandos com o aplicativo de linha de comando curl. Confira um exemplo que usa a opção de cabeçalho HTTP (preferencial):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Ou, como alternativa, a opção de parâmetro de string de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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 solicitar a permissão do usuário (inclusive quando o usuário não está presente) se você solicitou acesso off-line aos escopos associados ao token.

Para atualizar um token de acesso, o aplicativo envia uma solicitação POST HTTPS ao servidor de autorização do Google (https://oauth2.googleapis.com/token) que inclui os seguintes parâmetros:

O snippet a seguir mostra uma solicitação de exemplo:

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

Enquanto o usuário não tiver revogado o acesso concedido ao aplicativo, o servidor de tokens vai 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 https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Há limites no 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 os tokens de atualização no armazenamento de longo prazo e continue a usá-los enquanto eles permanecerem válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá encontrar esses limites. Nesse caso, os tokens de atualização mais antigos vão deixar de funcionar.

Revogar um token

Em alguns casos, o usuário pode querer revogar o acesso concedido a um app. Um usuário pode revogar o acesso acessando 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 que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante em casos em que um usuário cancela a inscrição, remove um aplicativo ou 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, seu app 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 de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, ele também será revogado.

Se a revogação for processada, 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.

Métodos de redirecionamento de apps

Proteger seus apps

Leitura adicional

A prática recomendada atual do IETF OAuth 2.0 para apps nativos estabelece muitas das práticas recomendadas documentadas aqui.