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:
- Open the API Library no Google API Console.
- If prompted, select a project, or create a new one.
- 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.
- Selecione aquela que você quer habilitar e clique no botão Ativar.
- If prompted, enable billing.
- 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.
- Go to the Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth.
- 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.
Android
- Selecione o tipo de aplicativo Android.
- Insira um nome para o cliente OAuth. Esse nome aparece no Credentials page do seu projeto para identificar o cliente.
- Insira o nome do pacote do app Android. Esse valor é definido no
atributo
packagedo elemento<manifest>no arquivo de manifesto do app. - 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 do certificado em um formato legível por humanos. Copie o valor
SHA1na seçãoCertificate fingerprintsda saída da keytool. Consulte Como autenticar seu cliente na documentação das APIs do Google para Android para mais informações.
- (Opcional) Verifique a propriedade do seu aplicativo Android.
- Clique em Criar.
iOS
- Selecione o tipo de aplicativo iOS.
- Insira um nome para o cliente OAuth. Esse nome aparece no Credentials page do seu projeto para identificar o cliente.
- Insira o identificador do pacote do app. O ID do pacote é o valor da chave
CFBundleIdentifier
no arquivo de recurso da lista de propriedades de informações do app (info.plist). O valor
é mais comumente exibido no painel "Geral" ou no painel "Assinatura e recursos" do
editor de projeto do Xcode. O ID do pacote também aparece na seção "Informações gerais" da
página "Informações do app" do
site da Apple App Store Connect.
Confirme se você está usando o ID de pacote correto para o app, já que não será possível alterá-lo se você estiver usando o recurso App Check.
- (Opcional)
Insira o ID da App Store do app, se ele for 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.
- Abra o app Apple App Store no seu dispositivo iOS ou iPadOS.
- Procure seu app.
- Selecione o botão "Compartilhar" (quadrado e seta para cima).
- Selecione Copiar link.
- 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
- (Opcional)
Insira o 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 "Team ID" é obrigatório se você estiver ativando o App Check para seu cliente. - (Opcional)
Ative o App Check no seu app iOS. Quando você ativa o App Check, o serviço App Attest da Apple é usado para verificar se as solicitações 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 falsificação de apps. Saiba como ativar o App Check no seu app iOS.
- Clique em Criar.
UWP
- Selecione o tipo de aplicativo Plataforma Universal do Windows.
- Insira um nome para o cliente OAuth. Esse nome aparece no Credentials page do seu projeto para identificar o cliente.
- Insira o ID de 12 caracteres da Microsoft Store do seu app. Esse valor pode ser encontrado na Central de parceiros da Microsoft na página Identidade do app na seção "Gerenciamento de apps".
- 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. 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.
| Métodos de geração de desafios de código | |
|---|---|
| S256 (recomendado) | O desafio de código é o hash SHA256 codificado em Base64URL (sem padding) do verificador de
código.
|
| plain | O desafio de código tem o mesmo valor do verificador de código gerado acima.
|
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:
| Parâmetros | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente do seu aplicativo. Esse valor está no API Console Credentials page. |
||||||
redirect_uri |
Obrigatório
Determina como o servidor de autorização do Google envia uma resposta para o app. Há várias opções de redirecionamento disponíveis para apps instalados, e você terá configurado suas credenciais de autorização pensando em um método de redirecionamento específico. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados do cliente OAuth 2.0, que você configurou na
API Console
Credentials pagedo cliente. Se esse valor não corresponder a um
URI autorizado, você vai receber um erro A tabela abaixo mostra o valor adequado do parâmetro
|
||||||
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 |
||||||
scope |
Obrigatório
Uma lista de escopos delimitada por espaços que identifica os recursos que o aplicativo pode acessar em nome do usuário. Esses valores informam a 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 aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário. |
||||||
code_challenge |
Recomendado
Especifica uma |
||||||
code_challenge_method |
Recomendado
Especifica o método usado para codificar um |
||||||
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 É possível usar esse parâmetro para várias finalidades, como direcionar o usuário ao recurso correto no aplicativo, enviar valores de uso único e reduzir a falsificação de solicitações entre sites. Como a |
||||||
login_hint |
Opcional
Se o aplicativo souber qual usuário está tentando fazer a autenticação, 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 login múltiplo adequada. Defina o valor do parâmetro como um endereço de e-mail ou identificador |
||||||
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.
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 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.
Erros
As solicitações para o endpoint de autorização 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 soluções sugeridas.
admin_policy_enforced
A Conta do Google não consegue 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 Controle quais apps internos e de terceiros acessam os dados do Google Workspace para saber mais sobre como um administrador pode restringir o acesso a todos os escopos ou escopos sensíveis e restritos até que o acesso seja concedido explicitamente ao seu ID de cliente OAuth.
disallowed_useragent
O endpoint de autorização é exibido dentro de um user-agent incorporado não permitido pelas Políticas do OAuth 2.0 do Google.
Android
Os desenvolvedores do Android podem encontrar essa mensagem de erro ao abrir solicitações de autorização no
android.webkit.WebView.
Em vez disso, os desenvolvedores precisam usar bibliotecas do Android, como
Login do Google para Android ou
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 os gerenciadores Android App Links 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 no
WKWebView.
Os desenvolvedores devem usar bibliotecas do iOS, como
Login do Google para iOS ou a
AppAuth para iOS da OpenID Foundation.
Os desenvolvedores da Web podem encontrar esse erro quando um app para iOS ou macOS abre um link da Web geral em
um agente do usuário 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
Universal Links
ou o app de navegador padrão. A
biblioteca SFSafariViewController
também é uma opção aceita.
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 consentimento OAuth".
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 ter sido invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se esse erro continuar a aparecer, verifique se o aplicativo foi configurado corretamente e se você está usando os tokens e parâmetros corretos na 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 no
Google API Console Credentials page.
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 que você fez. Isso pode acontecer por vários motivos:
- A solicitação não foi formatada corretamente
- A solicitação não tinha parâmetros obrigatórios
- A solicitação usa um método de autorização não aceito pelo Google. Verifique se a integração OAuth usa um método recomendado
- Um esquema personalizado é usado para o URI de redirecionamento : se você receber 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 o cliente Android, 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 as 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 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:
| Campos | |
|---|---|
client_id |
O ID do cliente recebido do API Console Credentials page. |
client_secret |
A chave secreta do cliente recebida do API Console Credentials page. |
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
API Console
Credentials page para o
client_id fornecido. |
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:
| Campos | |
|---|---|
access_token |
O token que seu aplicativo envia para autorizar uma solicitação de API do Google. |
expires_in |
A vida útil restante 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
token da Web JSON (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. Os tokens de atualização são sempre retornados para aplicativos instalados. |
scope |
Os escopos de acesso concedidos pelo access_token são expressos como uma lista de
strings delimitadas por espaços e diferenciadas por maiúsculas e minúsculas. |
token_type |
O tipo de token retornado. No momento, o valor desse campo é sempre definido como
Bearer. |
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:
| Campos | |
|---|---|
client_id |
O ID do cliente recebido 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 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 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
Esquema de URI personalizado (Android, iOS, UWP)
Os esquemas de URI personalizados são uma forma de vinculação direta que usa um esquema definido de forma personalizada para abrir o app.
Alternativa para usar esquemas de URI personalizados no Android
Use o SDK do Login do Google para Android, que envia a resposta do OAuth 2.0 diretamente para o app, eliminando a necessidade de um URI de redirecionamento.
Como migrar para o SDK do Login do Google para Android
Se você usa um esquema personalizado para sua integração OAuth no Android, será necessário concluir as seguintes ações para migrar totalmente para o SDK de Login do Google para Android recomendado:
- Atualize o código para usar o SDK do Login do Google.
- Desative o suporte ao esquema personalizado no Console de APIs do Google.
Siga as etapas abaixo para migrar para o SDK do Google Sign-In para Android:
-
Atualize seu código para usar o SDK do Google Sign-In para Android:
-
Examine seu código para identificar onde você está
enviando uma solicitação para o servidor OAuth 2.0 do Google. Se você estiver usando um esquema personalizado, sua solicitação vai 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âmetroredirect_uripara mais detalhes sobre o formato do valor do esquema de URI personalizado. -
Anote os parâmetros de solicitação
scopeeclient_idque você precisa configurar no SDK do Login do Google. -
Siga as instruções de
Como integrar o Login do Google ao seu app Android
para configurar o SDK. Você pode pular a etapa
Receber o ID do cliente OAuth 2.0 do servidor de back-end, reutilizando
o
client_idque você extraiu na etapa anterior. -
Siga as instruções de
Como ativar o acesso de API no lado do servidor. Isso inclui as seguintes etapas:
-
Use o método
getServerAuthCodepara recuperar um código de autenticação para os escopos em que você está solicitando permissão. - Envie o código de autenticação ao back-end do app para trocar por um token de acesso e atualização.
- Use o token de acesso recuperado para fazer chamadas para as APIs do Google em nome do usuário.
-
Use o método
-
Examine seu código para identificar onde você está
enviando uma solicitação para o servidor OAuth 2.0 do Google. Se você estiver usando um esquema personalizado, sua solicitação vai ser semelhante a esta:
-
Desative o suporte ao esquema personalizado no Console de APIs do Google:
- Acesse a lista de credenciais do OAuth 2.0 e selecione o cliente Android.
- 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 ao esquema de URI personalizado.
Ativar esquema de URI personalizado
Se a alternativa recomendada não funcionar, ative esquemas de URI personalizados para seu cliente Android seguindo as instruções abaixo:- Acesse a lista de credenciais do OAuth 2.0 e selecione o cliente Android.
- 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 ao esquema de URI personalizado.
Alternativa para usar esquemas de URI personalizados em apps do Chrome
Use a API Chrome Identity, que envia a resposta do OAuth 2.0 diretamente para o app, eliminando a necessidade de um URI de redirecionamento.
Endereço IP de loopback (computador macOS, Linux ou Windows)
Para receber o código de autorização usando esse URL, seu aplicativo precisa estar em escuta no servidor da Web local. Isso é possível em muitas plataformas, mas não em todas. No entanto, se a plataforma oferecer suporte, esse é o mecanismo recomendado para conseguir o código de autorização.
Quando o app receber a resposta de autorização, para melhor usabilidade, ele precisará mostrar uma página HTML que instrua o usuário a fechar o navegador e retornar ao app.
| Uso recomendado | Apps para macOS, Linux e Windows (mas não para a Plataforma Universal do Windows) |
| Valores de formulário | Defina o tipo de aplicativo como App para computador. |
Cópia/colagem manual (descontinuado)
Proteger seus apps
Verificar a propriedade do app (Android, Chrome)
É possível verificar a propriedade do aplicativo para reduzir o risco de falsificação.
Android
Para concluir o processo de verificação, use sua conta de desenvolvedor do Google Play se você tiver uma e o app estiver registrado no Google Play Console. Os seguintes requisitos precisam ser atendidos para que a verificação seja 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 de verificação.
Se a verificação for bem-sucedida, uma notificação será exibida para confirmar o sucesso do processo de verificação. Caso contrário, uma solicitação de erro será exibida.
Para corrigir uma verificação com falha, tente o seguinte:
- Verifique se o app que você está verificando está registrado no Google Play Console.
- Confira 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. Os seguintes requisitos precisam ser atendidos para que a verificação seja bem-sucedida:
- Você precisa ter um item registrado no Painel de controle do desenvolvedor da Chrome Web Store com o mesmo ID de item do cliente OAuth da extensão do Chrome para a qual você está fazendo 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 a propriedade do app do cliente da extensão do Chrome, clique no botão Verificar propriedade para concluir o processo de verificação.
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 de verificação. Caso contrário, uma solicitação de erro será exibida.
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 de item do cliente OAuth da extensão do Chrome para a qual você está fazendo a verificação.
- Verifique se você é um editor do app, ou seja, se você é o editor individual do app ou um membro do editor do grupo do app. Saiba mais sobre o gerenciamento de acesso no Painel de controle do desenvolvedor da Chrome Web Store.
- Se você acabou de atualizar a lista de editores do grupo, verifique se a lista de membros do editor do grupo está sincronizada no Painel de controle do desenvolvedor da Chrome Web Store. Saiba mais sobre como sincronizar sua lista de membros do editor.
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 para os endpoints do Google OAuth 2.0 são originadas dos seus aplicativos autênticos. Isso ajuda a reduzir o risco de falsificação de apps.
Ativar o App Check para o 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 o cliente iOS.
- Não use um curinga no ID do pacote, porque ele pode ser resolvido em mais de um app. Isso significa que o ID do pacote não pode incluir o símbolo de asterisco (*).
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ê aplicar o App Check. As informações na página de monitoramento de métricas podem ajudar a determinar quando iniciar a aplicação.
Talvez você encontre erros relacionados ao recurso App Check ao ativar o recurso para seu app iOS. 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 ao cliente iOS
Ativar o App Check no seu app não bloqueia automaticamente as solicitações não reconhecidas. Para aplicar essa proteção, acesse a visualização de edição do cliente iOS. Lá, você vai encontrar as métricas do App Check à direita da página na seção Google Identity 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: 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 não autêntico que tenta se passar pelo seu app ou de ambientes emulados.
Para aplicar a verificação de apps, clique no botão ENFORCE e confirme sua escolha. Quando a aplicação estiver ativa, todas as solicitações não verificadas do 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 do seu cliente iOS
Remover a aplicação do App Check do seu app vai interromper a aplicação e vai permitir todas as solicitações do cliente para os endpoints do Google OAuth 2.0, incluindo solicitações não verificadas.
Para desativar a verificação de apps no seu cliente iOS, navegue até a visualização de edição do cliente iOS e clique no botão UNENFORCE e confirme sua escolha.
Observação: depois de desativar a verificação de app, pode levar até 15 minutos para que as mudanças entrem em vigor.
Desativar o App Check para o cliente iOS
Desativar o App Check no seu app vai interromper todo o monitoramento e aplicação do App Check. Considere desativar o App Check para continuar monitorando as métricas do cliente.
Para desativar o App Check no cliente iOS, navegue até a visualização de edição do cliente iOS e desative o botão de alternância Proteja seu cliente OAuth contra abusos com o Firebase App Check.
Observação: depois de desativar a verificação de app, pode levar até 15 minutos para que as mudanças entrem em vigor.
Leitura adicional
A prática recomendada atual do IETF OAuth 2.0 para apps nativos estabelece muitas das práticas recomendadas documentadas aqui.
Como implementar a Proteção entre contas
Outra medida que você pode tomar para proteger as contas dos usuários é implementar a proteção entre contas usando o serviço de proteção entre contas do Google. Esse serviço permite que você se inscreva em notificações de eventos de segurança que fornecem informações ao seu app sobre mudanças importantes na conta do usuário. Em seguida, você pode usar as informações para tomar medidas dependendo de como você decide responder aos eventos.
Confira alguns exemplos de 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ários 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.