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

<0x0 A visão geral resume os fluxos do OAuth 2.0 compatíveis com o Google, o que pode ajudar você a garantir que selecionou o fluxo certo para seu aplicativo.

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 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 e armazenar arquivos nos respectivos Google Drives.

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á no app ou quando o app está sendo executado 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 respostas do servidor de autorização do Google.

Bibliotecas e amostras

Para apps para dispositivos móveis, recomendamos usar a versão mais recente da biblioteca nativa dos Serviços de Identificação do Google para Android e da biblioteca nativa do Login do Google para iOS. Essas bibliotecas processam a autorização do usuário e são mais simples de implementar do que o protocolo de nível mais baixo descrito aqui.

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 Fazer login em TVs e dispositivos de entrada limitada.

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. A 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 cliente.
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 necessário.

Android

1. Selecione o tipo de aplicativo Android.
2. Insira um nome para o cliente OAuth. Esse nome é exibido no do projeto para identificar o cliente.
3. Insira o nome do pacote do seu app Android. Esse valor é definido no atributo package do elemento <manifest> no arquivo de manifesto do app.
4. Insira a impressão digital do certificado de assinatura SHA-1 da distribuição do app.
   • Se o app usar a assinatura de apps do Google Play, copie a impressão digital SHA-1 da página de assinatura de apps do Play Console.
   • Se você gerenciar seu próprio keystore e chaves de assinatura, use o utilitário keytool incluído no Java para imprimir informações de certificado em um formato legível para humanos. Copie o valor SHA1 na seção Certificate fingerprints da saída do keytool. Consulte Autenticar seu cliente na documentação das APIs do Google para Android para mais informações.
5. (Opcional) Verifique a propriedade do seu aplicativo Android.
6. Clique em Criar.

iOS

1. Selecione o tipo de aplicativo iOS.
2. Insira um nome para o cliente OAuth. Esse nome é exibido no do projeto para identificar o cliente.
3. Insira o identificador do pacote do seu app. O ID do pacote é o valor da chave CFBundleIdentifier no arquivo de recursos da lista de propriedades de informações do app (info.plist). O valor é mostrado com mais frequência nos painéis "General" ou "Signing & Capabilities" do editor de projetos do Xcode. O ID do pacote também é exibido na seção "Informações gerais" da página "Informações do app" no site App Store Connect da Apple.

   Confirme se você está usando o ID do pacote correto para seu app, já que não será possível mudá-lo se estiver usando o recurso App Check.

4. (Opcional)

   Insira o ID da App Store do app se ele estiver publicado na App Store da Apple. O ID da loja é uma string numérica incluída em todos os URLs da App Store da Apple.

   1. Abra o app Apple App Store no seu dispositivo iOS ou iPadOS.
   2. Procure seu app.
   3. Selecione o botão Compartilhar (símbolo de quadrado e seta para cima).
   4. Selecione Copiar link.
   5. Cole o link em um editor de texto. O ID da App Store é a parte final do URL.

      Exemplo: https://apps.apple.com/app/google/id284815942

5. (Opcional)

   Insira seu ID da equipe. Consulte Localizar o ID da equipe na documentação da conta de desenvolvedor da Apple para mais informações.

   Observação:o campo "ID da equipe" é obrigatório se você estiver ativando o App Check para seu cliente.
6. (Opcional)

   Ative o App Check para seu app iOS. Quando você ativa o App Check, o serviço App Attest da Apple é usado para verificar se as solicitações do OAuth 2.0 originadas do seu cliente OAuth são genuínas e vêm do seu app. Isso ajuda a reduzir o risco de representação de app. Saiba como ativar o App Check no seu app iOS.

7. Clique em Criar.

UWP

1. Selecione o tipo de aplicativo Plataforma Universal do Windows.
2. Insira um nome para o cliente OAuth. Esse nome é exibido no do projeto para identificar o cliente.
3. Insira o ID de 12 caracteres da Microsoft Store do seu app. Esse valor pode ser encontrado no Microsoft Partner Center na página Identidade do app na seção "Gerenciamento de apps".
4. Clique em Criar.

Para apps UWP, o esquema de URI personalizado não pode ter mais de 39 caracteres.

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. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de obter 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.

Observação:a autorização incremental não é compatível com apps instalados ou dispositivos.

O documento Escopos da API OAuth 2.0 contém uma lista completa de escopos que você pode usar para acessar as APIs do Google.

Se o aplicativo público usar escopos que permitem o acesso a determinados dados do usuário, ele precisará concluir um processo de verificação. Se você vir app não verificado na tela ao testar o aplicativo, envie uma solicitação de verificação para remover essa mensagem. Saiba mais sobre apps não verificados e encontre respostas para perguntas frequentes sobre a verificação de apps na Central de Ajuda.

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 obter o consentimento de um usuário para fazer 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 e um desafio de código

O Google é compatível com o protocolo Chave de prova para troca de código (PKCE) para tornar o fluxo de apps instalados mais seguro. Um verificador de código exclusivo é criado para cada solicitação de autorização, e o valor transformado dele, chamado "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 máximo de 128 caracteres.

O verificador de código precisa ter entropia suficiente para tornar a adivinhação do valor impraticável.

Criar o desafio de programação

Dois métodos de criação do desafio de código são aceitos.

Métodos de geração de desafio de código
S256 (recomendado)	O desafio de código é o hash SHA256 codificado em Base64URL (sem padding) do verificador de código. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain	O desafio de código tem o mesmo valor do verificador de código gerado acima. 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ões ativas, autentica o usuário e obtém o consentimento dele. O endpoint só pode ser acessado por SSL e recusa conexões HTTP (não SSL).

O servidor de autorização é compatível com os seguintes parâmetros de string de consulta para aplicativos instalados:

Parâmetros
client_id	Obrigatório O ID do cliente do seu aplicativo. Esse valor está no .
redirect_uri	Obrigatório Determina como o servidor de autorização do Google envia uma resposta ao seu app. Há várias opções de redirecionamento disponíveis para apps instalados, e você terá configurado suas credenciais de autorização com um método de redirecionamento específico em mente. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no do cliente. Se esse valor não corresponder a um URI autorizado, você vai receber um erro redirect_uri_mismatch. A tabela abaixo mostra o valor de parâmetro redirect_uri adequado para cada método: Valores redirect_uri Esquema de URI personalizado com.example.app:redirect_uri_path ou com.googleusercontent.apps.123:redirect_uri_path com.example.app é a notação DNS inversa de um domínio sob seu controle. O esquema personalizado precisa conter um período para ser válido. com.googleusercontent.apps.123 é a notação DNS reversa do ID do cliente. redirect_uri_path é um componente de caminho opcional, como /oauth2redirect. O caminho precisa começar com uma única barra, que é diferente dos URLs HTTP comuns. Observação : os esquemas de URI personalizados não são mais compatíveis com apps do Chrome e são desativados por padrão no Android. Saiba mais sobre alternativas de esquemas personalizados para apps Android e Chrome. Endereço IP de loopback http://127.0.0.1:port ou http://[::1]:port Consulte sua plataforma para o endereço IP de loopback relevante e inicie um listener HTTP em uma porta aleatória disponível. Substitua port pelo número da porta em que o app está escutando. A opção de redirecionamento de endereço IP de loopback em apps para dispositivos móveis foi DESCONTINUADA.
response_type	Obrigatório Determina se o endpoint do Google OAuth 2.0 retorna um código de autorização. Defina o valor do parâmetro como code para aplicativos instalados.
scope	Obrigatório Uma lista delimitada por espaços de escopos que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam à tela de consentimento que o Google mostra ao usuário. 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. Assim, há uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário.
code_challenge	Recomendado Especifica um code_verifier codificado que será usado como um desafio do lado do servidor durante a troca de código de autorização. Consulte a seção criar um desafio de código acima para mais informações.
code_challenge_method	Recomendado Especifica qual método foi usado para codificar um code_verifier que será usado durante a troca de código de autorização. Esse parâmetro precisa ser usado com o parâmetro code_challenge descrito acima. O valor de code_challenge_method assume o padrão plain se não estiver presente na solicitação que inclui um code_challenge. Os únicos valores aceitos para esse parâmetro são S256 ou plain.
state	Recomendado Especifica qualquer valor de string que o aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização. O servidor retorna o valor exato que você envia como um par name=value no identificador de fragmento de URL (#) do redirect_uri depois que o usuário consente ou nega a solicitação de acesso do seu aplicativo. É possível usar esse parâmetro para várias finalidades, como direcionar o usuário ao recurso correto no aplicativo, enviar nonces e reduzir a falsificação de solicitações entre sites. Como seu redirect_uri pode ser adivinhado, usar um valor state aumenta a garantia de que uma conexão recebida é resultado de uma solicitação de autenticação. Se você gerar uma string aleatória ou codificar o hash de um cookie ou outro valor que capture o estado do cliente, poderá validar a resposta para garantir ainda mais que a solicitação e a resposta se originaram no mesmo navegador, oferecendo proteção contra ataques como falsificação de solicitação entre sites. Consulte a documentação do OpenID Connect para ver um exemplo de como criar e confirmar um token state. Importante:o cliente OAuth precisa evitar CSRF, conforme indicado na especificação do OAuth2 . Uma maneira de fazer isso é usar o parâmetro state para manter o estado entre sua solicitação de autorização e a resposta do servidor de autorização.
login_hint	Opcional Se o aplicativo souber qual usuário está tentando se autenticar, ele poderá usar esse parâmetro para fornecer uma dica ao servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login, preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de vários logins apropriada. Defina o valor do parâmetro como um endereço de e-mail ou um identificador sub, que é equivalente ao ID do Google do usuário.

Observação:a autorização incremental com apps instalados não é compatível porque o cliente não pode manter o client_secret confidencial.

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.

Esquema de URI personalizado

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

Endereço IP de loopback

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 etapa, 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.

Nesta etapa, o aplicativo não precisa fazer nada, já que aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na próxima etapa.

Erros

As solicitações ao endpoint de autorização do OAuth 2.0 do Google podem mostrar mensagens de erro para o usuário em vez dos fluxos de autenticação e autorização esperados. Confira abaixo os códigos de erro comuns e as resoluções sugeridas.

admin_policy_enforced

A Conta do Google não pode autorizar um ou mais escopos solicitados devido às políticas do administrador do Google Workspace. Consulte o artigo de ajuda do administrador do Google Workspace Controlar quais apps internos e de terceiros acessam os dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os escopos ou a escopos sensíveis e restritos até que o acesso seja concedido explicitamente ao ID do cliente OAuth.

disallowed_useragent

O endpoint de autorização é mostrado em um user agent incorporado proibido pelas políticas do OAuth 2.0 do Google.

Android

Os desenvolvedores Android podem encontrar essa mensagem de erro ao abrir solicitações de autorização em android.webkit.WebView. Em vez disso, os desenvolvedores precisam usar bibliotecas do Android, como o Google Sign-In para Android ou o AppAuth para Android da OpenID Foundation.

Os desenvolvedores da Web podem encontrar esse erro quando um app Android abre um link da Web geral em um user agent incorporado e um usuário navega até o endpoint de autorização do OAuth 2.0 do Google no seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui gerenciadores de links de apps Android ou o app de navegador padrão. A biblioteca Android Custom Tabs também é uma opção compatível.

iOS

Os desenvolvedores de iOS e macOS podem encontrar esse erro ao abrir solicitações de autorização em WKWebView. Em vez disso, os desenvolvedores precisam usar bibliotecas do iOS, como o Google Sign-In para iOS ou o AppAuth para iOS da OpenID Foundation.

Os desenvolvedores da Web podem encontrar esse erro quando um app iOS ou macOS abre um link da Web geral em um user agent incorporado e um usuário navega até o endpoint de autorização do OAuth 2.0 do Google no seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui gerenciadores de links universais ou o app de navegador padrão. A biblioteca SFSafariViewController também é uma opção compatível.

org_internal

O ID do cliente OAuth na solicitação faz parte de um projeto que limita o acesso a Contas do Google em uma organização do Google Cloud específica. Para mais informações sobre essa opção de configuração, consulte a seção Tipo de usuário no artigo de ajuda "Como configurar a tela de permissão OAuth".

deleted_client

O cliente OAuth usado para fazer a solicitação foi excluído. A exclusão pode acontecer manualmente ou automaticamente no caso de clientes não utilizados . Os clientes excluídos podem ser restaurados em até 30 dias após a exclusão. Saiba mais .

invalid_grant

Se você estiver usando um verificador de código e desafio, o parâmetro code_callenge será inválido ou estará ausente. Verifique se o parâmetro code_challenge está definido corretamente.

Ao atualizar um token de acesso, ele pode ter expirado ou sido invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se o erro persistir, verifique se o aplicativo foi configurado corretamente e se você está usando os tokens e parâmetros certos na sua solicitação. Caso contrário, a conta de usuário pode ter sido excluída ou desativada.

redirect_uri_mismatch

O redirect_uri transmitido na solicitação de autorização não corresponde a um URI de redirecionamento autorizado para o ID do cliente OAuth. Revise os URIs de redirecionamento autorizados em .

O redirect_uri transmitido pode ser inválido para o tipo de cliente.

O parâmetro redirect_uri pode se referir ao fluxo fora de banda (OOB) do OAuth, que foi descontinuado e não tem mais suporte. Consulte o guia de migração para atualizar sua integração.

invalid_request

Algo deu errado com a solicitação. Isso pode acontecer por vários motivos:

• A solicitação não estava formatada corretamente
• A solicitação não tinha os parâmetros obrigatórios
• A solicitação usa um método de autorização não compatível com o Google. Verifique se a integração do OAuth usa um método recomendado.
• Um esquema personalizado é usado para o URI de redirecionamento : se você vir a mensagem de erro O esquema de URI personalizado não é compatível com apps do Chrome ou O esquema de URI personalizado não está ativado para seu cliente Android, isso significa que você está usando um esquema de URI personalizado que não é compatível com apps do Chrome e está desativado por padrão no Android. Saiba mais sobre alternativas de esquema de URI personalizado

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 que ele usa. Independente 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:

Campos
client_id	O ID do cliente obtido do .
client_secret	A chave secreta do cliente obtida do .
code	O código de autorização retornado da solicitação inicial.
code_verifier	O verificador de código que você criou na Etapa 1.
grant_type	Conforme definido na especificação do OAuth 2.0, o valor desse campo precisa ser definido como authorization_code.
redirect_uri	Um dos URIs de redirecionamento listados para seu projeto no para o client_idespecificado.

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

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:

Campos
access_token	O token que seu aplicativo envia para autorizar uma solicitação de API do Google.
expires_in	O tempo restante de vida útil do token de acesso em segundos.
id_token	Observação:essa propriedade só será retornada se a solicitação incluir um escopo de identidade, como openid, profile ou email. O valor é um JSON Web Token (JWT) que contém informações de identidade assinadas digitalmente sobre o usuário.
refresh_token	Um token que pode ser usado para receber um novo token de acesso. Os tokens de atualização são válidos até que o usuário revogue o acesso ou o token de atualização expire. Os tokens de atualização são sempre retornados para aplicativos instalados.
refresh_token_expires_in	A vida útil restante do token de atualização em segundos. Esse valor só é definido quando o usuário concede acesso com base em tempo.
scope	Os escopos de acesso concedidos pelo access_token, expressos como uma lista de strings delimitadas por espaço e sensíveis a maiúsculas e minúsculas.
token_type	O tipo de token retornado. No momento, o valor desse campo é sempre definido como Bearer.

Importante:seu aplicativo precisa armazenar os dois tokens em um local seguro e de longa duração que possa ser acessado entre diferentes invocações do aplicativo. O token de atualização permite que seu aplicativo receba um novo token de acesso se o que você tem expirar. Assim, se o aplicativo perder o token de atualização, o usuário precisará repetir o fluxo de consentimento do OAuth 2.0 para que o aplicativo possa receber um novo token de atualização.

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

Observação:seu aplicativo precisa ignorar todos os campos não reconhecidos incluídos na resposta.

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 concedidos e processar corretamente situações em que algumas permissões são negadas, geralmente 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 de acesso granular. Para esses apps, os usuários não vão ver a tela de permissão granular. Em vez disso, seu 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 acesso a um escopo específico ao seu aplicativo, examine o campo scope na resposta do token de acesso. Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaço e sensíveis a maiúsculas e minúsculas.

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 atividade do Drive e eventos da agenda 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á ser usado para fazer chamadas a 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 à 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 suas chamadas às 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 (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 ele não está presente) se você solicitou 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:

Campos
client_id	O ID do cliente obtido do API Console.
client_secret	A chave secreta do cliente obtida do API Console. O client_secret não é aplicável a solicitações de clientes registrados como aplicativos Android, iOS ou Chrome.
grant_type	Conforme definido na especificação do OAuth 2.0, o valor desse campo precisa ser definido como refresh_token.
refresh_token	O token de atualização retornado da troca de código de autorização.

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Enquanto o usuário não revogar o acesso concedido ao aplicativo, o servidor de token 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 para o número de tokens de atualização que serão emitidos: um limite por combinação cliente/usuário e outro por usuário em todos os clientes. Salve os tokens de atualização em 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, e 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. Um usuário pode revogar o acesso nas Configurações da conta. Consulte a seção Remover o acesso de 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 quando um usuário cancela a inscrição, remove um aplicativo ou os recursos da API necessários para 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 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 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 com sucesso, o código de status HTTP da resposta será 200. Em condições de erro, um código de status HTTP 400 é retornado junto com um código de erro.

Observação:após uma resposta de revogação bem-sucedida, pode levar algum tempo até que a revogação tenha efeito total.

Métodos de redirecionamento de apps

Esquema de URI personalizado (Android, iOS, UWP)

Os esquemas de URI personalizados são uma forma de link direto que usa um esquema definido pelo usuário para abrir seu app.

Importante:os esquemas de URI personalizados não são mais compatíveis com novos apps Chrome e são desativados por padrão em novos clientes Android devido ao risco de falsificação de apps.

Alternativa ao uso de esquemas de URI personalizados no Android

Use a alternativa recomendada, que envia a resposta do OAuth 2.0 diretamente para seu app, eliminando a necessidade de um URI de redirecionamento.

Como migrar para a biblioteca do Android dos Serviços de Identificação do Google

Se você usa um esquema personalizado para sua integração do OAuth no Android, é necessário concluir as seguintes ações para migrar totalmente para o uso da biblioteca de serviços de identidade do Google para Android recomendada:

1. Atualize seu código para usar a biblioteca do Google Identity Services para Android.
2. Desative o suporte para esquema personalizado no console do Google Cloud.

Observação:conclua e implante as atualizações de código (considerando o tempo de adoção em toda a base de usuários ou dispositivos mais antigos) antes de desativar o suporte a esquemas personalizados no console de APIs do Google para evitar que os usuários recebam uma mensagem de erro invalid_request ao tentar usar o app.

As etapas a seguir detalham como migrar para a biblioteca do Android dos Serviços de Identificação do Google:

1. Atualize seu código para usar a biblioteca do Android dos Serviços de Identificação do Google:
   1. Examine seu código para identificar onde você está enviando uma solicitação ao servidor OAuth 2.0 do Google. Se estiver usando um esquema personalizado, sua solicitação será semelhante a esta:

        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        

      com.example.app:/oauth2redirect é o URI de redirecionamento do esquema personalizado no exemplo acima. Consulte a definição do parâmetro redirect_uri para mais detalhes sobre o formato do valor do esquema de URI personalizado.
   2. Anote os parâmetros de solicitação scope e client_id, que você precisará configurar no SDK de Login do Google.
      Observação:se você estiver usando uma biblioteca de terceiros, revise o arquivo de configuração dela para encontrar essas informações.
   3. Siga as instruções em Autorizar o acesso aos dados de usuários do Google para configurar o SDK. Você pode pular a etapa Configurar o projeto do Console do Google Cloud , já que vai reutilizar o client_id recuperado na etapa anterior.
   4. Siga as instruções para Solicitar permissões necessárias para ações do usuário. Isso inclui as seguintes etapas:
      1. Solicite permissões do usuário.
      2. Use o método getServerAuthCode para recuperar um código de autenticação dos escopos para os quais você está pedindo permissão.
      3. Envie o código de autenticação ao back-end do app para trocá-lo por um token de acesso e de atualização.
      4. Use o token de acesso recuperado para fazer chamadas às APIs do Google em nome do usuário.
      Observação:se o aplicativo exigir apenas escopos de autenticação, siga estas instruções para usar a biblioteca recomendada do Gerenciador de credenciais.
2. Desative o suporte para esquema personalizado no Console de APIs do Google:
   1. Acesse a lista de credenciais do OAuth 2.0 e selecione seu cliente Android.
   2. Navegue até a seção Configurações avançadas, desmarque a caixa de seleção Ativar esquema de URI personalizado e clique em Salvar para desativar o suporte a esquemas de URI personalizados.

Ativar esquema de URI personalizado

Se a alternativa recomendada não funcionar para você, siga as instruções abaixo para ativar esquemas de URI personalizados no seu cliente Android:

1. Acesse a lista de credenciais do OAuth 2.0 e selecione seu cliente Android.
2. Navegue até a seção Configurações avançadas, marque a caixa de seleção Ativar esquema de URI personalizado e clique em Salvar para ativar o suporte a esquemas de URI personalizados.

Alternativa ao uso de esquemas de URI personalizados em apps do Chrome

Use a API Chrome Identity que envia a resposta do OAuth 2.0 diretamente para seu app, eliminando a necessidade de um URI de redirecionamento.

Endereço IP de loopback (macOS, Linux, computador Windows)

Importante:a opção de redirecionamento de endereço IP de loopback está DESCONTINUADA para os tipos de cliente OAuth Android, app do Chrome e iOS. Consulte o guia de migração de endereços IP de loopback para instruções sobre como migrar para uma alternativa compatível.

Para receber o código de autorização usando esse URL, seu aplicativo precisa estar escutando no servidor da Web local. Isso é possível em muitas plataformas, mas não em todas. No entanto, se a plataforma for compatível, esse será o mecanismo recomendado para conseguir o código de autorização.

Quando o app recebe a resposta de autorização, para melhor usabilidade, ele precisa responder mostrando uma página HTML que instrui o usuário a fechar o navegador e voltar ao app.

Uso recomendado	Aplicativos para computador macOS, Linux e Windows (mas não Plataforma Universal do Windows)
Valores de formulário	Defina o tipo de aplicativo como App para computador.

Observação:consulte a definição do parâmetro redirect_uri para mais informações sobre o endereço IP de loopback. Também é possível usar localhost em vez do IP de loopback, mas essa configuração pode causar problemas com firewalls de clientes. A maioria dos firewalls permite a comunicação de loopback, mas nem todos.

Copiar e colar manualmente (descontinuado)

Importante:a opção de copiar e colar manualmente, também conhecida como um método de redirecionamento fora da banda (OOB), não é mais compatível. Consulte o guia de migração OOB para instruções sobre como migrar para uma alternativa segura.

Proteja seus apps

Verificar a propriedade do app (Android, Chrome)

É possível verificar a propriedade do aplicativo para reduzir o risco de representação indevida.

Android

Observação:a verificação de propriedade de apps Android está disponível apenas para apps do Google Play.

Para concluir o processo de verificação, use sua conta de desenvolvedor do Google Play se você tiver uma e seu app estiver registrado no Google Play Console. Os seguintes requisitos precisam ser atendidos para uma verificação bem-sucedida:

• Você precisa ter um aplicativo registrado no Google Play Console com o mesmo nome de pacote e impressão digital do certificado de assinatura SHA-1 do cliente OAuth do Android para o qual você está concluindo a verificação.
• Você precisa ter permissão de administrador para o app no Google Play Console. Saiba mais sobre o gerenciamento de acesso no Google Play Console.

Na seção Verificar propriedade do app do cliente Android, clique no botão Verificar propriedade para concluir o processo.

Se a verificação for bem-sucedida, uma notificação será exibida para confirmar o sucesso do processo. Caso contrário, uma mensagem de erro será mostrada.

Para corrigir uma verificação com falha, tente o seguinte:

• Verifique se o app que você está verificando está registrado no Google Play Console.
• Verifique se você tem permissão de administrador para o app no Google Play Console.

Chrome

Para concluir o processo de verificação, use sua conta de desenvolvedor da Chrome Web Store. Para que a verificação seja concluída, é necessário atender aos seguintes requisitos:

• Você precisa ter um item registrado no Painel de controle do desenvolvedor da Chrome Web Store com o mesmo ID do item do cliente OAuth da extensão do Chrome para o qual você está concluindo a verificação.
• Você precisa ser um editor do item da Chrome Web Store. Saiba mais sobre o gerenciamento de acesso no Painel de controle do desenvolvedor da Chrome Web Store.

Na seção Verificar propriedade do app do cliente da extensão do Chrome, clique no botão Verificar propriedade para concluir o processo.

Observação:aguarde alguns minutos antes de concluir o processo de verificação depois de conceder acesso à sua conta.

Se a verificação for bem-sucedida, uma notificação será exibida para confirmar o sucesso do processo. Caso contrário, uma mensagem de erro será mostrada.

Para corrigir uma verificação com falha, tente o seguinte:

• Verifique se há um item registrado no Painel de controle do desenvolvedor da Chrome Web Store com o mesmo ID do item do cliente OAuth da extensão do Chrome que você está verificando.
• Verifique se você é um editor do app, ou seja, se você é o editor individual ou um membro do grupo de editores do app. Saiba mais sobre o gerenciamento de acesso no Painel de controle do desenvolvedor da Chrome Web Store.
• Se você acabou de atualizar sua lista de editores de grupo, verifique se a lista de membros do grupo está sincronizada no Painel de controle do desenvolvedor da Chrome Web Store. Saiba mais sobre como sincronizar sua lista de membros do publisher.

App Check (somente iOS)

O recurso App Check ajuda a proteger seus aplicativos iOS contra uso não autorizado usando o serviço App Attest da Apple para verificar se as solicitações feitas aos endpoints OAuth 2.0 do Google são originadas dos seus aplicativos autênticos. Isso ajuda a reduzir o risco de representação indevida de apps.

Ativar o App Check para seu cliente iOS

Os requisitos a seguir precisam ser atendidos para ativar o App Check no seu cliente iOS:

• É necessário especificar um ID de equipe para seu cliente iOS.
• Não use um caractere curinga no ID do pacote, porque ele pode ser resolvido para mais de um app. Isso significa que o ID do pacote não pode incluir o símbolo de asterisco (*).

Aviso:quando o App Check está ativado, não é possível editar o ID do pacote do cliente OAuth sem criar um novo cliente. Antes de criar o cliente iOS ou ativar o App Check, verifique se você está usando o ID do pacote correto. A atualização do ID do pacote de um projeto atual pode resultar em uma experiência ruim para os usuários dos seus apps se você estiver usando o ID do pacote como um URI de redirecionamento.

Para ativar o App Check, ative o botão de alternância Proteja seu cliente OAuth contra abusos com o Firebase App Check na visualização de edição do seu cliente iOS.

Depois de ativar o App Check, você vai começar a ver métricas relacionadas a solicitações OAuth do seu cliente na visualização de edição do cliente OAuth. As solicitações de fontes não verificadas não serão bloqueadas até que você aplique o App Check. As informações na página de monitoramento de métricas podem ajudar você a determinar quando iniciar a aplicação.

Ao ativar o App Check para seu app iOS, você pode encontrar erros relacionados a esse recurso. Para corrigir esses erros, tente o seguinte:

• Verifique se o ID do pacote e o ID da equipe especificados são válidos.
• Verifique se você não está usando um caractere curinga para o ID do pacote.

Aplicar o App Check para seu cliente iOS

Ativar o App Check para seu app não bloqueia automaticamente solicitações não reconhecidas. Para aplicar essa proteção, acesse a visualização de edição do seu cliente iOS. Lá, você vai encontrar as métricas do App Check à direita da página, na seção Identidade do Google para iOS. As métricas incluem as seguintes informações:

• Número de solicitações verificadas: solicitações com um token válido do App Check. Depois de ativar a aplicação do App Check, apenas as solicitações nessa categoria serão bem-sucedidas.
• Número de solicitações não verificadas: solicitações de cliente possivelmente desatualizadas: solicitações sem um token do App Check. Essas solicitações podem ser de uma versão mais antiga do app que não inclui uma implementação do App Check.
• Número de solicitações não verificadas: solicitações de origem desconhecida: solicitações sem um token do App Check que não parecem ser do seu app.
• Número de solicitações não verificadas: solicitações inválidas: solicitações com um token inválido do App Check, que podem ser de um cliente fraudulento tentando se passar pelo seu app ou de ambientes emulados.

Analise essas métricas para entender como a aplicação do App Check vai afetar seus usuários.

Para aplicar o App Check, clique no botão APLICAR e confirme sua escolha. Depois que a aplicação estiver ativa, todas as solicitações não verificadas do seu cliente serão rejeitadas.

Observação: depois de ativar a aplicação, pode levar até 15 minutos para que as mudanças entrem em vigor.

Remover a aplicação do App Check para seu cliente iOS

Remover a aplicação do App Check no seu app vai interromper a aplicação obrigatória e permitir todas as solicitações do seu cliente para os endpoints do Google OAuth 2.0, incluindo solicitações não verificadas.

Para remover a aplicação do App Check no seu cliente iOS, acesse a visualização de edição do cliente iOS, clique no botão REMOVER A APLICAÇÃO e confirme sua escolha.

Observação: depois de desativar a aplicação do App Check, pode levar até 15 minutos para que as mudanças entrem em vigor.

Desativar o App Check para seu cliente iOS

Desativar o App Check no seu app interrompe todo o monitoramento e a aplicação do App Check. Considere não aplicar o App Check para continuar monitorando as métricas do seu cliente.

Para desativar o App Check no seu cliente iOS, acesse a visualização de edição do cliente e desative o botão de alternância Proteja seu cliente OAuth contra abusos com o Firebase App Check.

Observação: depois de desativar o App Check, as mudanças podem levar até 15 minutos para entrar em vigor.

Acesso com base no tempo

O acesso por 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, aos usuários a opção de conceder 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 acesso por tempo ao seu aplicativo, 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 de 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 do IETF OAuth 2.0 para apps nativos estabelece muitas das práticas recomendadas documentadas aqui.

Implementar a Proteção entre contas

Outra etapa para proteger as contas dos usuários é implementar a proteção entre contas usando o serviço de proteção entre contas do Google. Com esse serviço, você pode assinar notificações de eventos de segurança que fornecem informações ao seu aplicativo sobre mudanças importantes na conta do usuário. Depois, use as informações para tomar medidas dependendo de como você decide responder aos eventos.

Alguns exemplos dos tipos de eventos enviados ao seu app pelo Serviço de proteção entre contas do Google:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulte a página Proteger contas de usuário com a Proteção entre contas para mais informações sobre como implementar a Proteção entre contas e a lista completa de eventos disponíveis.