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

<

A visão geral resume os fluxos do OAuth 2.0 compatíveis com o Google, o que pode ajudar a garantir que você 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 à API YouTube Data.

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 a permissão de envio de vídeos ao canal do YouTube de um usuário.

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 lidar com as respostas do servidor de autorização do Google.

Alternativas

Em apps para dispositivos móveis, recomendamos usar o Login do Google para Android ou 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 que não são compatíveis com um navegador do sistema ou que têm recursos de entrada limitados, como TVs, consoles de jogos, câmeras ou impressoras, consulte OAuth 2.0 para TVs e dispositivos ou Login em TVs e dispositivos de entrada limitada.

Bibliotecas e amostras

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

• Biblioteca AppAuth para Android
• Biblioteca AppAuth para iOS
• OAuth para apps: exemplos para Windows (em inglês)

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame 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 em Google API Console.
2. If prompted, select a project, or create a new one.
3. Use a página Biblioteca para encontrar e ativar a API YouTube Data. Encontre e ative outras APIs que seu aplicativo vai usar.

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 o projeto. Seus aplicativos podem usar as credenciais para acessar as APIs ativadas para o 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 clientes e os métodos de redirecionamento aceitos pelo servidor de autorização do Google. Escolha o tipo de cliente recomendado para seu aplicativo, dê um nome ao 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. 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 usa 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 chaves de assinatura, use o utilitário keytool do Java para imprimir informações de certificado em um formato legível por humanos. Copie o valor SHA1 na seção Certificate fingerprints da saída do 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 app 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. 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). Geralmente, o valor é exibido no painel General ou no painel Signing & Capabilities do editor de projeto do Xcode. O ID do pacote também é exibido na seção "Informações gerais" da página "Informações do app" do aplicativo no site da App Store Connect da Apple.
4. (Opcional)

   Insira o ID da App Store se o app 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 seta para cima e quadrado).
   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 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 da 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 da Microsoft Store de 12 caracteres 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 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)

Esquemas de URI personalizados são uma forma de link direto que usa um esquema personalizado para abrir seu app.

Importante:os esquemas de URI personalizados não têm mais suporte em novos apps do Chrome e são desativados por padrão em novos clientes Android devido ao risco de falsificação de identidade.

Alternativa ao uso de 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 a integração do OAuth no Android, precisa concluir as ações abaixo para migrar totalmente para o SDK recomendado do Login do Google para Android:

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

Observação:conclua e implante as atualizações de código (considerando o tempo de adoção da sua base de usuários ou de 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.

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. Analise o código para identificar onde você está enviando uma solicitação para o 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 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.
      Observação:se você estiver usando uma biblioteca de terceiros, analise o arquivo de configuração da biblioteca para encontrar essas informações.
   3. Siga as instruções Começar a integrar o Login do Google no seu app Android para configurar o SDK. Você pode pular a etapa Acessar o ID do cliente OAuth 2.0 do servidor de back-end porque reutilizaria o client_id recuperado na etapa anterior.
   4. Siga as instruções para Ativar o acesso à API do lado do servidor. Isso inclui as seguintes etapas:
      1. Use o método getServerAuthCode para recuperar um código de autorização dos escopos para os quais 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. Use o token de acesso recuperado para fazer chamadas às APIs do Google em nome do usuário.
      Observação:se o aplicativo não precisar de acesso off-line, siga estas instruções para solicitar acesso à API do lado do cliente.
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.

Como ativar o esquema de URI personalizado

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

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, 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 fornece a resposta do OAuth 2.0 diretamente para seu aplicativo, eliminando a necessidade de um URI de redirecionamento.

Verificar a propriedade do aplicativo (Android, Chrome)

Verifique a propriedade do seu aplicativo para reduzir o risco de falsificação de identidade.

Android

Observação:no momento, a verificação de propriedade de apps Android só está disponível para apps do Google Play.

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

• É necessário ter um aplicativo 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 para que você está concluindo a verificação.
• É necessário 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, um prompt de erro será exibido.

Para corrigir uma verificação com falha, 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, use sua conta de desenvolvedor da Chrome Web Store. Os seguintes requisitos precisam ser atendidos para que a verificação seja bem-sucedida:

• É preciso 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 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. Caso contrário, um prompt de erro será exibido.

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 o qual você está concluindo a verificação.
• É preciso ser um editor do aplicativo, ou seja, você precisa ser o editor individual dele ou um membro do editor em grupo do aplicativo. 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 essa lista 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, Windows desktop)

Importante:a opção de redirecionamento de endereço IP de loopback foi 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 é 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 retornar ao app.

Uso recomendado	Apps para computador macOS, Linux e Windows (mas não para a Plataforma Universal 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 no lugar do IP de loopback, mas essa configuração pode causar problemas com firewalls de clientes. A maioria dos firewalls, mas não todos, permite comunicação de loopback.

Copiar/colar manualmente

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

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 a quantidade de acesso que concedem ao aplicativo. Portanto, 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 o app precisará de permissão para acessar.

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

A API YouTube Data v3 utiliza os seguintes escopos:

Escopos
https://www.googleapis.com/auth/youtube	Gerenciar sua conta do YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creator	Ver uma lista dos membros ativos atuais do canal, do nível deles e de quando se tornaram membros
https://www.googleapis.com/auth/youtube.force-ssl	Ver, editar e excluir permanentemente vídeos, classificações, comentários e legendas do YouTube
https://www.googleapis.com/auth/youtube.readonly	Visualize sua conta do YouTube
https://www.googleapis.com/auth/youtube.upload	Gerenciar seus vídeos do YouTube
https://www.googleapis.com/auth/youtubepartner	Ver e gerenciar seus ativos e conteúdos associados no YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	Visualiza as informações particulares do seu canal que são relevantes para o processo de auditoria com um parceiro do YouTube

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.

Se o aplicativo público usa escopos que permitem o acesso a determinados dados do usuário, ele precisa concluir um processo de verificação. Se você vir um app não verificado na tela ao testar seu aplicativo, envie uma solicitação de verificação para removê-lo. Saiba mais sobre apps não verificados e veja respostas para as 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 do usuário e 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 de código e um desafio

O Google oferece suporte ao protocolo Proof Key for Code Exchange (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 criptográfica aleatória 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 deve ter entropia suficiente para que não seja possível adivinhar o valor.

Criar o desafio de código

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

Métodos de geração do 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 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 aceita os seguintes parâmetros de string de consulta para aplicativos instalados:

Parâmetros
client_id	Obrigatório O 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 para seu app. Há várias opções de redirecionamento disponíveis para apps instalados, e será necessário 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 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 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 barra, diferente dos URLs HTTP normais. Observação : os esquemas de URI personalizados não são mais compatíveis com os apps do Chrome e são desativados por padrão no Android. Saiba mais sobre alternativas de esquema personalizado para apps Android e Chrome. Endereço IP de loopback http://127.0.0.1:port ou http://[::1]:port Consulte sua plataforma para encontrar 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 real que o app detectar. O suporte à opção de redirecionamento de endereço IP de loopback em apps para dispositivos móveis está OBSOLETO.
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 exibe 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 a quantidade de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário. A API YouTube Data v3 utiliza os seguintes escopos: Escopos https://www.googleapis.com/auth/youtube Gerenciar sua conta do YouTube https://www.googleapis.com/auth/youtube.channel-memberships.creator Ver uma lista dos membros ativos atuais do canal, do nível deles e de quando se tornaram membros https://www.googleapis.com/auth/youtube.force-ssl Ver, editar e excluir permanentemente vídeos, classificações, comentários e legendas do YouTube https://www.googleapis.com/auth/youtube.readonly Visualize sua conta do YouTube https://www.googleapis.com/auth/youtube.upload Gerenciar seus vídeos do YouTube https://www.googleapis.com/auth/youtubepartner Ver e gerenciar seus ativos e conteúdos associados no YouTube https://www.googleapis.com/auth/youtubepartner-channel-audit Visualiza as informações particulares do seu canal que são relevantes para o processo de auditoria com um parceiro do YouTube O documento Escopos da API OAuth 2.0 apresenta uma lista completa dos escopos que podem ser usados para acessar as APIs do Google.
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 mais informações.
code_challenge_method	Recomendável Especifica o método usado para codificar um code_verifier que será usado durante a troca do código de autorização. Use esse parâmetro com o parâmetro code_challenge descrito acima. O valor de code_challenge_method será padronizado como 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 seu 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. Esse parâmetro 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, o uso de um valor state pode aumentar a garantia de que uma conexão de entrada é o 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, será possível validar a resposta para garantir também que a solicitação e a resposta tenham sido 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. Importante:o cliente OAuth precisa impedir o CSRF, conforme indicado na especificação OAuth2 . Uma maneira de fazer isso é usando o parâmetro state para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.
login_hint	Opcional Se o aplicativo sabe qual usuário está tentando autenticar, ele pode 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 vários logins apropriada. Defina o valor do parâmetro como um endereço de e-mail ou 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 a 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.

Cada URL solicita acesso a um escopo que permite visualizar a conta do YouTube do usuário.

Os URLs são idênticos, exceto pelo valor do parâmetro redirect_uri. Os URLs também contêm os parâmetros response_type e client_id obrigatórios, bem como o parâmetro state opcional. 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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. Nessa etapa, o Google exibe uma janela de consentimento que mostra o nome do seu aplicativo e dos serviços das APIs 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 então consentir com a concessão de acesso a um ou mais escopos solicitados pelo aplicativo ou recusar a solicitação.

Seu aplicativo não precisa fazer nada nesse estágio, já que 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 do OAuth 2.0 do Google podem exibir mensagens de erro voltadas ao usuário, em vez dos fluxos de autenticação e autorização esperados. Códigos de erro comuns e resoluções sugeridas estão listados abaixo.

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 para admins 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 confidenciais e restritos até que o acesso seja explicitamente concedido ao 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 Web podem encontrar esse erro quando um app Android abre um link geral da Web em um user agent incorporado e um usuário navega pelo site para o endpoint de autorização do OAuth 2.0 do Google. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, o que inclui os gerenciadores Links do app Android ou o app 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 Login do Google para iOS ou o AppAuth para iOS do OpenID Foundation.

Os desenvolvedores Web podem encontrar esse erro quando um app para iOS ou macOS abre um link geral da Web em um user agent incorporado e um usuário navega até o endpoint de autorização do OAuth 2.0 do Google pelo site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui os 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 às 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".

invalid_grant

Se você estiver usando um verificador de código e desafio, 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 sido invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se esse erro persistir, 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 OAuth fora de banda (OOB, na sigla em inglês) que foi descontinuado e não é mais compatível. Consulte o guia de migração para atualizar a integração.

invalid_request

Havia algo errado com a solicitação que você fez. Isso pode ocorrer por vários motivos:

• A solicitação não foi formatada corretamente
• Faltaram parâmetros obrigatórios na solicitação
• A solicitação usa um método de autorização incompatível com o Google. Verificar se a integração OAuth usa um método de integração 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 é ativado para seu 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 alternativas de esquemas de URI personalizados

Etapa 4: gerenciar a resposta do servidor OAuth 2.0

A maneira como seu app recebe a resposta de autorização depende do esquema do URI de redirecionamento usado. 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, será possível trocar o código de autorização por um token de acesso e um token de atualização, conforme descrito na próxima etapa.

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

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

Campos
client_id	O ID do cliente recebido 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 OAuth 2.0, o valor desse campo precisa ser definido como authorization_code.
redirect_uri	Um dos URIs de redirecionamento listados para o projeto em API Console Credentials page para o client_id especificado.

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	A vida útil restante do token de acesso em segundos.
id_token	Observação:essa propriedade só será retornada se sua 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. Observe que os tokens de atualização sempre são retornados para aplicativos instalados.
scope	Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaço e que diferenciam maiúsculas de minúsculas.
token_type	O tipo de token retornado. No momento, o valor desse campo é sempre definido como Bearer.

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

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/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Observação:é necessário que o aplicativo ignore todos os campos não reconhecidos incluídos na resposta.

Como chamar APIs do Google

Depois que o aplicativo recebe um token de acesso, é possível usá-lo 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 Bearer de cabeçalho HTTP Authorization. Recomendamos usar o cabeçalho HTTP sempre que possível, porque as strings de consulta costumam ficar visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca de cliente para configurar chamadas às APIs do Google (por exemplo, ao chamar a API YouTube Data).

A API YouTube Data é compatível apenas com contas de serviço de proprietários de conteúdo do YouTube que têm e gerenciam vários canais do YouTube, como gravadoras e estúdios de cinema.

É possível testar todas as APIs do Google e ver os escopos delas no OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada para o endpoint youtube.channels (a API YouTube Data) usando o cabeçalho HTTP Authorization: Bearer pode ter a seguinte aparência: É necessário especificar seu próprio token de acesso:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Veja abaixo uma chamada para a mesma API para o usuário autenticado com o parâmetro de string de consulta access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Exemplos com curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Ou, alternativamente, a opção do parâmetro da string de consulta:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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 pedir a permissão do usuário (mesmo quando ele não está presente) caso você tenha solicitado acesso off-line aos escopos associados ao token.

Para atualizar um token de acesso, o 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 recebido do 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 apps 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ódigos 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

Contanto que o usuário não tenha revogado o acesso concedido ao aplicativo, o servidor de token 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",
  "token_type": "Bearer"
}

Há limites para o número de tokens de atualização que serão emitidos: um limite por combinação de cliente/usuário e outro por usuário em todos os clientes. Salve esses tokens em um armazenamento de longo prazo e continue a usá-los enquanto permanecerem válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos deixarão de funcionar.

Revogação de um token

Em alguns casos, um usuário pode querer revogar o acesso concedido a um aplicativo. Um usuário pode revogar o acesso visitando 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 para um aplicativo revogar 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 quando 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, o aplicativo faz uma solicitação para https://oauth2.googleapis.com/revoke e inclui o token como um parâmetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

O token pode ser um token de acesso ou de atualização. Se for um token de acesso e tiver um token de atualização correspondente, este também será revogado.

Se a revogação for processada com sucesso, o código de status HTTP da resposta será 200. Para condições de erro, um código de status HTTP 400 é retornado com um código de erro.

Observação:depois de uma resposta de revogação bem-sucedida, pode levar algum tempo para que ela entre em vigor.

Leia mais

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