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

Observação 2 Observação Observação Observação Observação Observação Observação Observação 2 Observação Observação 2 Observação 2 Observação Observação 2 Observação Observação: Observação 2 Observação 2 Observação Observação: Observação Observação 2 Observação Observação Observação Observação 2 Observação 2 Observação 2 Observação Observação: Observação sobre o processo

Este documento explica como os aplicativos instalados em dispositivos como smartphones, tablets e computadores usam 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 conseguir permissão dos usuários para armazenar arquivos no Google Drive deles.

Os apps instalados são distribuídos para dispositivos individuais, e presume-se que esses apps não possam manter secrets. 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 as respostas do servidor de autorização do Google.

Alternativas

No caso de apps para dispositivos móveis, use o Login do Google no Android ou no iOS. As bibliotecas de cliente do Login do Google lidam com 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 sem suporte a um navegador do sistema ou com 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 limitados.

Bibliotecas e amostras

Recomendamos as seguintes bibliotecas e amostras para ajudar você a implementar o fluxo do OAuth 2.0 descrito neste documento:

Pré-requisitos

Ativar as APIs do projeto

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

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

  1. Open the API Library no arquivo Google API Console.
  2. If prompted, select a project, or create a new one.
  3. 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. Os aplicativos podem usar as credenciais para acessar as APIs ativadas para esse projeto.

  1. Go to the Credentials page.
  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. As seções abaixo descrevem os tipos de cliente e os métodos de redirecionamento 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
  1. Selecione o tipo de aplicativo Android.
  2. Digite um nome para o cliente OAuth. Esse nome é exibido no Credentials page do projeto para identificar o cliente.
  3. Digite o nome do pacote do seu app Android. Esse valor é definido no atributo package do elemento <manifest> no arquivo de manifesto do app.
  4. Digite a impressão digital do certificado de assinatura SHA-1 da distribuição do app.
    • Caso seu app use 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ê gerencia seu próprio keystore e suas chaves de assinatura, use o utilitário keytool incluído no Java para imprimir as informações do certificado em um formato legível. Copie o valor SHA1 na seção Certificate fingerprints da saída keytool. Para mais informações, consulte Como autenticar seu cliente na documentação das APIs do Google para Android.
  5. (Opcional) Verifique a propriedade do seu aplicativo para Android.
  6. Clique em Criar.
iOS
  1. Selecione o tipo de aplicativo iOS.
  2. Digite um nome para o cliente OAuth. Esse nome é exibido no Credentials page do projeto para identificar o cliente.
  3. Digite o identificador do pacote do seu app. Esse ID é o valor da chave CFBundleIdentifier no arquivo de recursos da lista de propriedades de informações do seu app (info.plist). O valor é exibido com mais frequência no painel "General" ou no painel "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 da App Store Connect da Apple.
  4. (Opcional)

    Insira o ID da App Store do seu aplicativo se ele tiver sido 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 Copy 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 o ID da equipe. Para mais informações, consulte Localizar o ID da equipe na documentação da conta de desenvolvedor da Apple.

  6. Clique em Criar.
UWP
  1. Selecione o tipo de aplicativo Plataforma Universal do Windows.
  2. Digite um nome para o cliente OAuth. Esse nome é exibido no Credentials page do projeto para identificar o cliente.
  3. Insira o ID de 12 caracteres da Microsoft Store do seu app. É possível encontrar esse valor na Central de parceiros da Microsoft na página Identidade do app na seção "Gerenciamento de aplicativos".
  4. Clique em Criar.

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

Esquema de URI personalizado (Android, iOS, UWP)

Os esquemas de URI personalizados são uma forma de links diretos que usam um esquema personalizado para abrir seu app.

Alternativa ao uso de esquemas de URI personalizados no Android

Use o SDK do Login do Google para Android, que entrega a resposta OAuth 2.0 diretamente ao seu 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, é necessário concluir as ações abaixo para migrar totalmente e começar a usar o SDK recomendado do Login do Google para Android:

  1. Atualize seu código para usar o SDK do Login do Google.
  2. Desativar o suporte a esquemas personalizados no Console de APIs do Google.

Siga as etapas abaixo para migrar para o SDK do Login do Google para Android:

  1. Atualize seu código para usar o SDK do Login do Google para Android:
    1. Examine seu código para identificar para onde você está enviando uma solicitação para o servidor OAuth 2.0 do Google. Se estiver usando um esquema personalizado, sua solicitação vai ficar assim: 
        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 de 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 necessários para configurar o SDK do Login do Google.
    3. Siga as instruções em Começar a integrar o Login do Google no seu app Android para configurar o SDK. Pule a etapa Receber o ID do cliente do OAuth 2.0 do servidor de back-end, porque você reutilizaria o client_id recuperado na etapa anterior.
    4. Siga as instruções para ativar o acesso à API no lado do servidor. Isso inclui as seguintes etapas:
      1. Use o método getServerAuthCode para recuperar um código de autenticação para os escopos em que você está solicitando permissão.
      2. Envie o código de autenticação ao back-end do seu app para trocá-lo por um token de acesso e atualização.
      3. Usar o token de acesso recuperado para fazer chamadas às APIs do Google em nome do usuário.
  2. Desative o suporte a esquemas personalizados no Console de APIs do Google:
    1. Acesse a lista de credenciais do OAuth 2.0 e selecione o 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 ao esquema de URI personalizado.
Ativar o esquema de URI personalizado
Se a alternativa recomendada não funcionar, ative os esquemas de URI personalizados para o cliente Android seguindo as instruções abaixo:
  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 ao esquema de URI personalizado.
Alternativa ao uso de esquemas de URI personalizados em apps do Chrome

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

Verificar a propriedade do aplicativo (Android, Chrome)

Você pode verificar a propriedade do seu aplicativo para reduzir o risco de falsificação de identidade.

Android

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

  • É preciso ter um app registrado no Google Play Console com o mesmo nome de pacote e impressão digital do certificado de assinatura SHA-1 que o cliente OAuth do Android em que você está concluindo a verificação.
  • Você precisa ter permissão de administrador do 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 processo. Caso contrário, um prompt de erro será exibido.

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

  • Confira se o app que você está verificando é 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, você pode usar sua conta de desenvolvedor da Chrome Web Store. Os seguintes requisitos precisam ser atendidos para uma verificação bem-sucedida:

  • Você precisa ter um item registrado no Painel do desenvolvedor da Chrome Web Store com o mesmo ID do item do cliente OAuth da extensão do Chrome em que 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 de 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 processo. Caso contrário, um prompt de erro será exibido.

Para corrigir uma falha na verificação, 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 que o cliente OAuth da extensão do Chrome para o qual você está concluindo a verificação.
  • Verifique se você é o editor do app, ou seja, você precisa ser o editor individual ou um membro do editor de 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 de grupo, verifique se ela está sincronizada no Painel de controle do desenvolvedor da Chrome Web Store. Saiba mais sobre como sincronizar sua lista de membros do editor.

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

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

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

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

Copiar/colar manualmente

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários e, ao mesmo tempo, permitem que os usuários controlem o nível de acesso que concedem ao 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 vai precisar de permissão de acesso.

O documento Escopos da API OAuth 2.0 contém uma lista completa dos 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 conseguir o consentimento de um usuário para executar 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 requer a autorização do usuário.

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

O Google oferece suporte ao protocolo Chave de prova para troca de código (PKCE, na sigla em inglês) 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, chamado "code_challenge", é enviado ao servidor de autorização para receber o código.

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 comprimento mínimo de 43 e máximo de 128 caracteres.

O verificador de código precisa ter entropia suficiente para não ser possível adivinhar o valor.

Criar o desafio do código

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

Métodos de geração de desafio de código
S256 (recomendado) O desafio do código é o hash SHA256 codificado em Base64URL (sem padding) do verificador de código.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
simples O desafio do 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ã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:

Parâmetros
client_id Obrigatório

ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials page.
redirect_uri Obrigatório

Determina como o servidor de autorização do Google envia uma resposta ao aplicativo. Há várias opções de redirecionamento disponíveis para os aplicativos instalados, e você precisará configurar as credenciais de autorização considerando um método de redirecionamento específico.

O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0 configurado no API Console Credentials pagedo cliente. Se esse valor não corresponder a um URI autorizado, você receberá um erro redirect_uri_mismatch.

A tabela abaixo mostra o valor do parâmetro redirect_uri apropriado 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 reversa de um domínio sob seu controle. O esquema personalizado deve conter um ponto 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. Observe que o caminho precisa começar com uma única barra, que é diferente dos URLs HTTP comuns.
Endereço IP de loopback http://127.0.0.1:port ou http://[::1]:port

Na sua plataforma, consulte o endereço IP de loopback relevante e inicie um listener HTTP em uma porta disponível aleatória. Substitua port pelo número real da porta em que seu app detecta.

A compatibilidade com a opção de redirecionamento do endereço IP de loopback em apps para dispositivos móveis está SUSPENSA.
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 de escopos delimitada por espaços que identificam os recursos que seu 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 e, ao mesmo tempo, permitem que os usuários controlem o nível de acesso que concedem ao 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 Recomendável

Especifica um code_verifier codificado que será usado como um desafio do lado do servidor durante a troca do código de autorização. Consulte a seção Criar desafio de código acima para saber mais.
code_challenge_method Recomendável

Especifica qual método foi usado para codificar um code_verifier que vai ser utilizado durante a troca do 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 será plain se não estiver presente na solicitação que inclui um code_challenge. Os únicos valores compatíveis com esse parâmetro são S256 ou plain.
state Recomendável

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 enviado como um par de 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 aplicativo.

Ele pode ser usado para várias finalidades, como direcionar o usuário para o recurso correto no aplicativo, enviar valores de uso único e mitigar a falsificação de solicitações entre sites. Como seu redirect_uri pode ser adivinhado, usar um valor state pode aumentar a garantia de que uma conexão de entrada seja 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, é possível validar a resposta para garantir que a solicitação e a resposta foram originadas no mesmo navegador, fornecendo proteção contra ataques, como falsificação de solicitações entre sites. Consulte a documentação do OpenID Connect para ver um exemplo de como criar e confirmar um token state.
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 automaticamente o campo de e-mail no formulário de login ou selecionando a sessão de login múltiplo 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.

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, bem como o parâmetro opcional state. Cada URL tem 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 o consentimento do usuário

Nesta etapa, o usuário decide se quer conceder o acesso solicitado ao seu aplicativo. Nesse estágio, 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. Assim, o usuário poderá conceder acesso a um ou mais escopos solicitados pelo seu aplicativo ou recusar a solicitação.

Seu aplicativo não precisa fazer nada nesta etapa, já que aguarda a resposta do servidor OAuth 2.0 do Google indicando se o acesso foi concedido. Essa resposta é explicada na etapa a seguir.

Erros

As solicitações para o endpoint de autorização do OAuth 2.0 do Google podem exibir mensagens de erro voltadas para o usuário, em vez dos fluxos de autenticação e autorização esperados. Confira abaixo códigos de erro comuns e 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 aos escopos confidenciais e restritos até que o acesso seja explicitamente concedido ao seu ID do 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 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 o Login do Google 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 acessa 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 Links do app Android ou o app do navegador padrão. A biblioteca Guias personalizadas do Android também é uma opção compatível.

iOS

Os desenvolvedores 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 Login do Google 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 acessa o endpoint de autorização do OAuth 2.0 do Google do seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui os gerenciadores Links universais ou o app do 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 específica do Google Cloud. 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".

invalid_grant

Se você estiver usando um verificador e desafio de código, o parâmetro code_callenge será inválido ou está 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 você continuar vendo esse erro, verifique se o aplicativo foi configurado corretamente e se estão usando os tokens e parâmetros corretos na solicitação. Caso contrário, a conta do 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 é referente ao fluxo de OAuth fora de banda (OOB, na sigla em inglês) que foi descontinuado e não tem mais suporte. Consulte o guia de migração para atualizar sua integração.

invalid_request

Havia algo errado com o pedido que você fez. Isso pode ocorrer por vários motivos:

  • A solicitação não foi formatada corretamente
  • A solicitação não tinha os parâmetros obrigatórios
  • A solicitação usa um método de autorização que não é compatível com o Google. Verificar 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 Custom URI scheme is not supported on Chrome apps ou Custom URI scheme not enabled for your Android client, isso significa que você está usando um esquema de URI personalizado incompatível com apps do Chrome e que está desativado por padrão no Android. Saiba mais sobre alternativas de esquemas de URI personalizado

Etapa 4: lidar com a resposta do servidor OAuth 2.0

A maneira como seu aplicativo recebe a resposta de autorização depende do esquema do URI de redirecionamento que ele usa. Seja qual for o esquema, a resposta 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, troque 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 para 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:

Campos
client_id O ID do cliente extraído de API Console Credentials page.
client_secret A chave secreta do cliente recebida de 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 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 da API do Google.
expires_in A vida útil restante do token de acesso em segundos.
id_token Observação:essa propriedade só vai 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. Os tokens de atualização são sempre retornados para aplicativos instalados.
scope Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaço que diferenciam maiúsculas de 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",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Chamada de APIs do Google

Depois que o aplicativo recebe um token de acesso, é possível usá-lo para fazer chamadas para uma API do Google em nome de uma determinada conta de usuário, se o escopo de acesso exigido pela API tiver sido concedido. 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. Sempre que possível, recomendamos usar o cabeçalho HTTP, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para APIs do Google (por exemplo, ao chamar a API Drive Files).

É possível testar todas as APIs do Google e ver 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 ter a seguinte aparência. Observe que é 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 a seguir uma chamada para a mesma API feita pelo 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

Teste 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 da 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) caso tenha solicitado acesso off-line aos escopos associados ao token.

Para atualizar um token de acesso, seu 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 extraído de API Console.
client_secret A chave secreta do cliente recebida de API Console. O client_secret não se aplica 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 do 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

Se o usuário não tiver revogado o acesso concedido ao aplicativo, o servidor de token retornará um objeto JSON com 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",
  "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 um armazenamento de longo prazo e continue a usá-los enquanto permanecerem válidos. Se o aplicativo solicita muitos tokens de atualização, ele pode atingir esses limites. Nesse caso, os tokens de atualização mais antigos deixarão de funcionar.

Revogar um token

Em alguns casos, o usuário pode querer revogar o acesso dado a um aplicativo. Um usuário pode revogar o acesso acessando Configurações da conta. Para mais informações, consulte a seção Remover o acesso ao site ou app do documento de suporte de sites e apps de terceiros com acesso à sua conta.

Também é possível que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante nos casos em que um usuário cancela a inscrição, remove um aplicativo ou os recursos da API exigidos por um app são alterados de maneira significativa. 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 app sejam removidas.

Para revogar um token de forma programática, o aplicativo faz uma solicitação a https://oauth2.googleapis.com/revoke e o inclui 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 for um token de acesso e tiver um token de atualização correspondente, ele também será revogado.

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

Leitura complementar

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