OAuth 2.0 para apps para computador

Neste documento, explicamos como os aplicativos para computador (como os que são executados no Windows, macOS ou Linux ou as ferramentas de interface de linha de comando (CLI)) usam os endpoints do 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 de usuário, 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 deles.

Os aplicativos para computador são instalados localmente na máquina do usuário (como software independente para computador, ferramentas de CLI para desenvolvedores, utilitários de sincronização em segundo plano ou scripts). Como esses apps são distribuídos para dispositivos individuais, presume-se que eles não possam manter secrets (são clientes públicos). Eles podem acessar as APIs do Google enquanto o usuário está interagindo ativamente com o app ou quando o app 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 para computador precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local (como um endereço IP de loopback) para processar as respostas do servidor de autorização do Google.

Bibliotecas e amostras

Recomendamos usar as bibliotecas de cliente da API do Google para sua linguagem de programação (por exemplo, Python, Java, Node.js, Go, .NET) ao implementar o OAuth 2.0 para aplicativos para computador. As bibliotecas de cliente processam a autorização do usuário e o gerenciamento de tokens, tornando a implementação mais simples e menos propensa a erros do que usar diretamente os endpoints HTTP/REST de nível inferior.

Para apps para dispositivos móveis, consulte os guias de autorização do Android e do iOS.

Para apps executados em dispositivos que não são compatíveis com 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 Login em TVs e dispositivos de entrada limitada.

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame as APIs do Google precisa ativá-las no Console de APIs.

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

1. Abra a biblioteca de APIs no Console de APIs do Google.
2. Se for solicitado, selecione um projeto ou crie um novo.
3. A biblioteca de APIs 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. Se necessário, ative o faturamento.
6. Se for solicitado, leia e aceite os Termos de Serviço da API.

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 o identifiquem 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. Acesse a página Clientes.
2. Clique em Criar cliente.
3. Selecione o tipo de aplicativo App para computador.
4. No campo Nome, insira um nome para o cliente OAuth. Esse nome é exibido na página Clientes do projeto para identificar o cliente.
5. Clique em Criar.

O ID do cliente e a chave secreta do cliente são gerados e exibidos no console do Google Cloud. Os apps para computador são clientes públicos e não podem manter a confidencialidade de secrets. Sempre use o Proof Key for Code Exchange (PKCE) ao solicitar códigos de autorização.

Identificar escopos de acesso

Os escopos permitem que o aplicativo solicite acesso apenas aos recursos necessários e que os usuários controlem o nível de acesso concedido ao aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de receber o consentimento do usuário.

Antes de começar a implementar a autorização do OAuth 2.0, recomendamos que você identifique os escopos que seu app 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 do usuário para realizar uma solicitação de API em nome dele. Seu aplicativo precisa ter esse consentimento antes de executar uma solicitação de API do Google que exija autorização do usuário.

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

O Google é compatível com o protocolo Proof Key for Code Exchange (PKCE) 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

Um 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 que seja impossível adivinhar o valor.

Criar o desafio de código

Há dois métodos para criar o desafio de código.

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

code_challenge = code_verifier

Etapa 2: enviar uma solicitação ao 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ó pode ser acessado por SSL e recusa conexões HTTP (não SSL).

O servidor de autorização aceita os seguintes parâmetros de string de consulta para aplicativos instalados:

Exemplos de URLs de autorização

As guias abaixo mostram exemplos de URLs de autorização 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, além do 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 pede o consentimento do usuário

Nesta etapa, o usuário decide se concede ao aplicativo o acesso solicitado. Nessa fase, o Google exibe uma janela de consentimento que mostra o nome do aplicativo e os serviços da API do Google que estão solicitando permissão de acesso 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.

Seu aplicativo não precisa fazer nada nesse estágio, pois ele aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na próxima etapa.

Etapa 4: processar a resposta do servidor OAuth 2.0

A maneira como o 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 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 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:

Embora o uso do DPoP seja opcional, ele é recomendado para aumentar a segurança. A segurança do DPoP depende da restrição da chave privada a um único dispositivo. Recomendamos armazená-la de forma que não possa ser copiada para fora do dispositivo, por exemplo, usando TPMs, Secure Enclaves ou outros keystores com suporte de hardware. Para usar a DPoP, seu aplicativo precisa gerar um novo JWT de prova de DPoP exclusivo para cada solicitação ao endpoint do token e adicioná-lo como um cabeçalho da solicitação HTTP.

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

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

Criar uma prova de DPoP

As etapas a seguir mostram como criar uma prova de DPoP usando o OpenSSL na linha de comando:

1. Gere um par de chaves EC P-256:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. Crie o cabeçalho DPoP:

   O cabeçalho precisa incluir as declarações typ, alg e jwk (chave pública). Os valores x e y são as coordenadas codificadas em Base64Url da sua chave pública EC. Codifique este JSON em Base64Url:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. Crie o payload de DPoP:

   O payload precisa incluir jti (um identificador exclusivo para a solicitação), htm (método HTTP, por exemplo, POST), htu (URI HTTP, por exemplo, https://oauth2.googleapis.com/token) e iat (emitido no momento). Se você recebeu um valor de uso único do servidor em um cabeçalho DPoP-Nonce na resposta a uma solicitação anterior, inclua esse valor em uma declaração nonce. A declaração nonce é opcional para trocas de código de autorização e usada apenas quando o cabeçalho DPoP-Nonce foi recebido anteriormente. Codifique este JSON em Base64Url:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   O valor de jti depende do tipo de troca:

   • Para trocas de código de autorização, o jti precisa ser o hash SHA256 codificado em Base64Url do código de autorização: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • Para trocas de token de atualização, o jti precisa ser um identificador exclusivo por solicitação: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. Assine a prova:

   Concatene o cabeçalho e o payload codificados com um ponto (.) e assine o resultado com sua chave privada usando o ES256. A JWS exige que a assinatura esteja em um formato bruto concatenado R | S (64 bytes para P-256). Se você usar o OpenSSL diretamente, será necessário converter a assinatura padrão codificada em DER ASN.1 para esse formato bruto.

Uma troca bem-sucedida é indicada por uma resposta 200 OK que contém os tokens. Se uma prova de DPoP válida for usada durante a troca, o token de atualização que o Google retornar será vinculado à sua chave por DPoP, mas os tokens de acesso não serão vinculados por DPoP. Os tokens de acesso vão manter o token_type de Bearer em vez de DPoP. Além disso, o Google retorna um cabeçalho HTTP DPoP-Nonce na resposta. O cliente precisa armazenar esse valor de uso único em cache e incluí-lo na declaração nonce da prova de DPoP em solicitações subsequentes (como ao trocar um token de atualização por um novo token de acesso ou ao chamar APIs protegidas por DPoP). Ao usar esse valor de uso único emitido antecipadamente, você pode evitar uma falha de ida e volta extra (use_dpop_nonce) na próxima solicitação.

As provas de DPoP precisam ser incluídas nas solicitações de troca de token feitas com tokens de atualização vinculados a DPoP.

Uma troca com falha ocorre se o cabeçalho DPoP estiver ausente quando esperado, for inválido ou se a prova usar uma chave diferente da vinculada ao token. Nesses casos, o servidor retorna um erro 400 Bad Request. Se a prova de DPoP tiver declarações htm ou htu incompatíveis, um iat expirado, um jti reutilizado ou uma assinatura inválida, o Google vai retornar um código do erro invalid_dpop_proof. Se um valor de uso único de DPoP for necessário, como durante uma troca de token de atualização, e a prova de DPoP não tiver uma declaração nonce ou o valor de uso único for inaceitável para o servidor (por exemplo, expirou, já foi usado ou está incorreto), o Google vai retornar um código de erro use_dpop_nonce com um cabeçalho HTTP DPoP-Nonce contendo um novo valor de uso único que pode ser usado em uma solicitação subsequente. Outras falhas podem retornar invalid_grant.

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 cabeçalhos de resposta e corpo bem-sucedidos quando o DPoP é usado:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "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árias permissões (escopos), os usuários podem não conceder ao app acesso a todas elas. Seu app precisa verificar quais escopos foram realmente concedidos e lidar de forma adequada com situações em que algumas permissões são negadas, normalmente desativando os recursos que dependem desses escopos negados.

No entanto, há exceções. Os apps do Google Workspace Enterprise com delegação de autoridade em todo o domínio ou marcados como Confiáveis ignoram a tela de permissão granular. Para esses apps, os usuários não vão ver a tela de permissão granular. Em vez disso, o app vai receber todos os escopos solicitados ou nenhum.

Para mais informações, consulte Como processar permissões granulares.

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

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

  {
    "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"
  }

Chamar APIs do Google

Depois que o aplicativo receber um token de acesso, você 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 isso, inclua o token de acesso em uma solicitação à API, incluindo um parâmetro de consulta access_token ou um valor de cabeçalho HTTP Authorization Bearer. 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 as chamadas para as APIs do Google (por exemplo, ao chamar a API Drive Files).

Você pode testar todas as APIs do Google e conferir os escopos delas no OAuth 2.0 Playground.

Exemplos de HTTP GET

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

Veja uma chamada para a mesma API para o 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. Veja 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

Atualizar um 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 pedir permissão ao usuário (inclusive quando ele não está presente) se você tiver solicitado acesso off-line aos escopos associados ao token.

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

Embora o uso do DPoP seja opcional, ele é recomendado para aumentar a segurança. Para usar o DPoP com um token de atualização, seu aplicativo precisa gerar um novo JWT de prova de DPoP exclusivo para cada solicitação ao endpoint do token. Essa prova precisa ser assinada com a mesma chave privada usada durante a troca inicial do código de autorização. O aplicativo adiciona a prova como um cabeçalho da solicitação HTTP.

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

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

Para usar o DPoP com um token de atualização, é necessário gerar um JWT de prova de DPoP novo e exclusivo para a solicitação. Consulte Criar uma prova de DPoP para instruções detalhadas sobre como gerar o par de chaves e criar o JWT.

Uma troca bem-sucedida é indicada por uma resposta 200 OK que contém um novo token de acesso. Quando o DPoP é usado, o token_type é Bearer. Uma resposta bem-sucedida confirma que a prova de DPoP para o token de atualização foi aceita. O Google também pode retornar um novo cabeçalho HTTP DPoP-Nonce na resposta. Se isso acontecer, seu cliente precisará armazenar em cache esse nonce e incluí-lo na declaração nonce da prova de DPoP em solicitações subsequentes.

Uma falha na troca ocorre se o cabeçalho DPoP estiver ausente, for inválido ou usar uma chave incorreta. Para detalhes sobre códigos de erro específicos do DPoP e como lidar com nonces, consulte Falha na troca.

O snippet a seguir mostra um exemplo de cabeçalhos de resposta e corpo bem-sucedidos quando o DPoP é usado:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "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 para o 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 usando-os enquanto forem válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos vão parar de funcionar.

Revogação de token

Em alguns casos, um usuário pode querer revogar o acesso concedido a um aplicativo. Para revogar o acesso, o usuário precisa acessar as Configurações da conta. Consulte a seção Remover o acesso de sites ou apps de terceiros com acesso à sua conta no documento de suporte para mais informações.

Também é possível que um aplicativo revogue de forma programática 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 maneira programática, seu aplicativo 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 um token de acesso ou um token de atualização. Se o token for de acesso e tiver um token de atualização correspondente, o token de atualização também será revogado.

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

Métodos de redirecionamento de apps

Proteger seus apps

Acesso baseado no horário

O acesso baseado em tempo permite que um usuário conceda ao app acesso aos dados dele por um período limitado para concluir uma ação. O acesso por tempo limitado está disponível em alguns produtos do Google durante o fluxo de consentimento, permitindo que os usuários concedam acesso por um período limitado. Um exemplo é a API Data Portability, que permite uma transferência única de dados.

Quando um usuário concede ao aplicativo acesso com base no tempo, o token de atualização expira após a duração especificada. Os tokens de atualização podem ser invalidados antes em circunstâncias específicas. Consulte estes casos para mais detalhes. O campo refresh_token_expires_in retornado na resposta da troca de código de autorização representa o tempo restante até que o token de atualização expire nesses casos.

Leitura adicional

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