Este documento explica como os aplicativos instalados em dispositivos como telefones, tablets e usam os endpoints OAuth 2.0 do Google para autorizar o acesso a a API de dados do YouTube.
O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo nomes de usuário, senhas e outras informações privadas. Por exemplo, um aplicativo pode usar OAuth 2.0 para obter permissões para recuperar dados do YouTube de um canal.
Os apps instalados são distribuídos para dispositivos individuais, e presume-se que eles e não pode manter segredos. Eles podem acessar as APIs do Google enquanto o usuário está no aplicativo ou quando que o app esteja 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 do servidor de autorização do Google.
Alternativas
Em apps para dispositivos móveis, use o Login do Google para Android ou No iOS. Login do Google as bibliotecas de cliente lidam com autenticação e autorização do usuário e podem ser mais simples 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 entrada limitada recursos, 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 descritos neste documento:
- Biblioteca AppAuth para Android
- Biblioteca AppAuth para iOS
- OAuth para apps: Windows Amostras
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:
- Open the API Library no Google API Console.
- If prompted, select a project, or create a new one.
- 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 deve ter credenciais de autorização que identificam 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 nesse projeto.
- Go to the Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth.
- As seções abaixo descrevem os tipos de clientes e os métodos de redirecionamento que o Google servidor de autorização compatível. Escolha o tipo de cliente recomendado para sua o aplicativo, nomeie seu cliente OAuth e defina os outros campos do formulário como apropriados.
Android
- Selecione o tipo de aplicativo Android.
- Digite um nome para o cliente OAuth. Esse nome é exibido no arquivo Credentials page para identificar o cliente.
- Insira o nome do pacote do seu app Android. Esse valor é definido no arquivo
Atributo
package
do elemento<manifest>
no arquivo de manifesto do app. - Insira a impressão digital do certificado de assinatura SHA-1 da distribuição do app.
- Caso seu app use assinatura de apps do Google Play, copie o SHA-1 impressão digital na 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
incluído com Java para imprimir informações de certificado em um formato legível. Copie o
SHA1
na seçãoCertificate fingerprints
do keytool. Consulte Como autenticar seu cliente no Documentação de APIs do Google para Android para mais informações.
- (Opcional) Verificar a propriedade do dispositivo Android para o aplicativo.
- Clique em Criar.
iOS
- Selecione o tipo de aplicativo iOS.
- Digite um nome para o cliente OAuth. Esse nome é exibido no arquivo Credentials page para identificar o cliente.
- Insira o identificador do pacote do seu app. O ID do pacote é o valor do atributo CFBundleIdentifier no arquivo de recursos da lista de propriedades de informações do app (info.plist). O valor é exibido com mais frequência no painel Geral ou no painel Recursos do Editor do projeto do Xcode. O ID do pacote também é exibido na seção "Informações gerais" do na página "Informações do app" em Site do App Store Connect da Apple.
- (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 Apple App Store.
- Abra o App App Store da Apple no seu dispositivo iOS ou iPadOS.
- Procure seu app.
- Selecione o botão "Compartilhar" (símbolo de seta para cima e quadrado).
- 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.
- Clique em Criar.
UWP
- Selecione o tipo de aplicativo da Plataforma Universal do Windows.
- Digite um nome para o cliente OAuth. Esse nome é exibido no arquivo Credentials page para identificar o cliente.
- Insira o ID da Microsoft Store de 12 caracteres do seu app. É possível encontrar esse valor em Central de parceiros da Microsoft no(a) Identidade do app na seção "Gerenciamento de aplicativos".
- 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.
. Alternativa ao uso de esquemas de URI personalizados no AndroidUse o SDK do Login do Google para Android que fornece a resposta de OAuth 2.0 diretamente para seu aplicativo, 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, precisará conclua as ações abaixo para migrar totalmente para o uso do Login do Google recomendado para SDK do Android:
- Atualize seu código para usar o SDK do Login do Google.
- Desative 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:
-
Atualize seu código para usar o SDK do Login do Google para Android:
-
Examine seu código para identificar onde você está
enviar uma solicitação ao servidor OAuth 2.0 do Google; se estiver usando um esquema personalizado, sua solicitação será semelhante a esta:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
é o URI de redirecionamento do esquema personalizado no do exemplo acima. Consulte a Definição do parâmetroredirect_uri
para mais detalhes sobre o formato do valor do esquema de URI personalizado. -
Anote os parâmetros de solicitação
scope
eclient_id
, que você precisa configurar o SDK do Login do Google. -
Siga o
Comece a integrar o Login do Google no seu app Android
instruções para configurar o SDK. Você pode pular
Receba a etapa do ID do cliente OAuth 2.0 do seu servidor de back-end como você faria para reutilizar
o
client_id
recuperado na etapa anterior. -
Siga o
Como ativar o acesso à API do lado do servidor
instruções. Isso inclui as seguintes etapas:
-
Use o método
getServerAuthCode
para recuperar um código de autenticação do escopos para os quais você está solicitando permissão. - Envie o código de autenticação ao back-end do seu app para trocá-lo por um acesso e atualizar com base no token correto anterior.
- Use o token de acesso recuperado para fazer chamadas às APIs do Google em nome do usuário.
-
Use o método
-
Examine seu código para identificar onde você está
enviar uma solicitação ao servidor OAuth 2.0 do Google; se estiver usando um esquema personalizado, sua solicitação será semelhante a esta:
-
Desative o suporte a esquemas personalizados no Console de APIs do Google:
- Acesse sua Credenciais do OAuth 2.0 e selecione seu cliente Android.
- Navegue até a seção Configurações avançadas, desmarque a opção caixa de seleção Ativar esquema de URI personalizado e em Salvar no desativar o suporte a esquemas de URI personalizados.
Como ativar o esquema de URI personalizado
Se a alternativa recomendada não funcionar para você, ative os esquemas de URI personalizados para seu Android seguindo as instruções abaixo:- Acesse sua lista de credenciais do OAuth 2.0 e selecione seu cliente Android.
- Navegue até a seção Configurações avançadas, marque a opção caixa de seleção Ativar esquema de URI personalizado e em Salvar para ativar suporte a esquemas de URI personalizados.
Use o API Chrome Identity que fornece a resposta de 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
Para concluir o processo de verificação, use sua conta de desenvolvedor do Google Play caso você tenha um e seu app esteja registrado na Google Play Console: O seguinte requisitos para uma verificação bem-sucedida:
- Você precisa ter um aplicativo registrado no Google Play Console com as mesmas nome de pacote e impressão digital do certificado de assinatura SHA-1 como o cliente OAuth do Android que você está para concluir a verificação.
- É necessário ter permissão de administrador para o aplicativo 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 ícone Verificar propriedade para concluir o processo de verificação.
Se a verificação for concluída, uma notificação será exibida do processo de verificação. 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 na 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ê deve 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 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 aplicativo do cliente da extensão do Google Chrome, clique em o botão Verificar propriedade para concluir o processo de verificação.
Observação:aguarde alguns minutos antes de concluir o processo de verificação. concedendo acesso à sua conta.
Se a verificação for concluída, uma notificação será exibida do processo de verificação. 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 O mesmo ID de item do cliente OAuth da extensão do Chrome para o qual você está fazendo a verificação.
- É preciso ser o editor individual do app, ou seja, você precisa ser o editor individual. do aplicativo 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 a lista de editores de grupo, verifique se a associação 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)
Para receber o código de autorização usando esse URL, seu aplicativo deve estar ouvindo no servidor da Web local. Isso é possível em muitas plataformas, mas não em todas. No entanto, se sua plataforma suporte, esse é o mecanismo recomendado para obter o código de autorização.
Quando seu aplicativo recebe a resposta de autorização, para melhor usabilidade, ele deve responder da seguinte forma: exibição de 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. |
Copiar/colar manualmente
Identificar escopos de acesso
Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários permitindo que os usuários controlem a quantidade de acesso que eles concedem ao aplicativo. Portanto, há pode ser 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 precisa de permissão para acessar.
A API YouTube Data v3 utiliza os seguintes escopos:
瞄准镜 | |
---|---|
https://www.googleapis.com/auth/youtube | 管理您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | 查看包含以下信息的列表:当前活跃的频道会员、其当前级别以及其成为会员的时间 |
https://www.googleapis.com/auth/youtube.force-ssl | 查看、修改以及永久删除您的 YouTube 视频、评分、评论和字幕 |
https://www.googleapis.com/auth/youtube.readonly | 查看您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.upload | 管理您的 YouTube 视频 |
https://www.googleapis.com/auth/youtubepartner | 查看和管理您在 YouTube 上的资源和关联内容 |
https://www.googleapis.com/auth/youtubepartner-channel-audit | 查看您的 YouTube 频道中关于 YouTube 合作伙伴试演的隐私信息 |
O documento Escopos da API OAuth 2.0 contém um lista de escopos que você pode usar para acessar as APIs do Google.
Como receber 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 para executar uma solicitação de API em nome dele. Seu aplicativo precisa ter consentimento antes de executar uma solicitação de API do Google que exija a autorização do usuário.
Etapa 1: gerar um verificador de código e um desafio
O Google aceita a chave de prova para troca de código (PKCE) para tornar o fluxo de apps instalados mais seguro. Um verificador de código exclusivo é criado para cada solicitação de autorização, e seu valor transformado, 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 a função
caracteres [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", com tamanho mínimo de 43 caracteres
e tamanho 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 código.
verificador.
|
simples | O desafio do código tem o mesmo valor do verificador de código gerado acima.
|
Etapa 2: enviar uma solicitação ao servidor OAuth 2.0 do Google
Para obter 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 suporta os seguintes parâmetros de string de consulta para aplicativos:
Parâmetros | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente do aplicativo. É possível encontrar esse valor API Console Credentials page. |
||||||||||||||||
redirect_uri |
Obrigatório
Determina como o servidor de autorização do Google envia uma resposta para seu app. Existem várias opções de redirecionamento disponíveis para os apps instalados, e você credenciais de autorização com um método de redirecionamento específico em mente. O valor deve corresponder exatamente a um dos URIs de redirecionamento autorizados para o OAuth 2.0
que você configurou no arquivo
API Console
Credentials page. Se esse valor não corresponder a um
URI autorizado, o erro A tabela abaixo mostra o valor 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
Um delimitado por espaço lista de escopos que identificam os recursos que seu aplicativo pode acessar na em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário. Os escopos permitem que o aplicativo solicite acesso apenas aos recursos necessários além de permitir que os usuários controlem a quantidade de acesso que eles concedem aos seus para o aplicativo. Desse modo, 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:
O documento Escopos da API OAuth 2.0 oferece uma lista completa de escopos que podem ser usados para acessar as APIs do Google. |
||||||||||||||||
code_challenge |
Recomendado
Especifica um |
||||||||||||||||
code_challenge_method |
Recomendado
Especifica qual método foi usado para codificar um |
||||||||||||||||
state |
Recomendado
Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre suas
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 Esse parâmetro pode ser usado para várias finalidades, como direcionar o usuário para o
o recurso correto no aplicativo, enviando valores de uso único e reduzindo solicitações entre sites.
falsificação. Como seu |
||||||||||||||||
login_hint |
Opcional
Caso seu aplicativo saiba 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 selecionar a sessão de login múltiplo apropriada. 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 exemplos de URLs de autorização para as diferentes opções de URI de redirecionamento.
Cada URL solicita acesso a um escopo que permite que recupere a propriedade dados do YouTube.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
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.force-ssl& 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.force-ssl& 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 concede o acesso solicitado ao seu aplicativo. Neste etapa, o Google exibe uma janela de consentimento com o nome do seu aplicativo e a API do Google serviços que está solicitando permissão de acesso com as credenciais de autorização do usuário. um resumo dos escopos de acesso a serem concedidos. A o usuário poderá então consentir em conceder acesso a um ou mais escopos solicitados por seu aplicativo ou recusar a solicitação.
O aplicativo não precisa fazer nada nessa etapa, já que aguarda a resposta Servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada em próxima etapa.
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. Códigos de erro comuns e sugestões resoluções estão listadas abaixo.
admin_policy_enforced
A Conta do Google não pode autorizar um ou mais escopos solicitados devido às políticas de administrador do Google Workspace. Consulte o artigo de ajuda para admins do Google Workspace Controle quais aplicativos de terceiros apps internos acessam dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os escopos ou informações escopos 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 pelo Políticas do OAuth 2.0.
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 devem usar bibliotecas Android, como
Login do Google para Android ou do OpenID Foundation
AppAuth para Android.
Os desenvolvedores Web podem encontrar esse erro quando um app Android abre um link geral da Web em uma user agent incorporado e um usuário navegar até o endpoint de autorização OAuth 2.0 do Google seu site. Os desenvolvedores devem permitir que links gerais sejam abertos no gerenciador de links padrão do do Google, o que inclui Links do app Android ou o app de navegador padrão. A Guias personalizadas do Android também é uma opção com suporte.
iOS
Os desenvolvedores de iOS e macOS podem encontrar esse erro ao abrir solicitações de autorização no
WKWebView
Em vez disso, os desenvolvedores devem usar bibliotecas iOS como
Login do Google para iOS ou do OpenID Foundation
AppAuth para iOS.
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 navegar até o endpoint de autorização do OAuth 2.0 do Google
seu site. Os desenvolvedores devem permitir que links gerais sejam abertos no gerenciador de links padrão do
do Google, o que inclui
Links universais
ou o app de navegador padrão. A
SFSafariViewController
também é uma opção com suporte.
org_internal
O ID do cliente OAuth da solicitação faz parte de um projeto que limita o acesso às Contas do Google em um específicas Organização do Google Cloud. Para mais informações sobre essa opção de configuração, consulte a 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
é inválido ou está ausente. Assegure-se de que
O parâmetro code_challenge
está definido corretamente.
Ao atualizar um token de acesso, ele pode ter expirado ou invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se você estiver continuando encontrar esse erro, verifique se o aplicativo foi configurado corretamente e se você está usando os tokens e parâmetros corretos em sua solicitação. Caso contrário, a conta de usuário pode ter tenha 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 para o ID do cliente OAuth. Revise os URIs de redirecionamento autorizados na
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) que tem
foi descontinuada e não tem mais suporte. Consulte a
guia de migração para atualizar seu
integração total.
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 o OAuth usa um método de integração recomendado
- Um esquema personalizado é usado para o URI de redirecionamento : se for exibida a mensagem de erro O esquema de URI personalizado não é compatível com os apps do Chrome ou com o esquema de URI personalizado não está ativado para seu cliente Android, isso significa que você está usando um URI personalizado que não é compatível com os aplicativos do Google Chrome e fica desativado por padrão no Android Saiba mais sobre o esquema de URI personalizado alternativas
Etapa 4: gerenciar a resposta do servidor OAuth 2.0
A maneira pela qual seu aplicativo recebe a resposta de autorização depende da
esquema de URI de redirecionamento usado. Independentemente do esquema, o
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 a seu aplicativo, você pode trocar o código de autorização por um de acesso e um token de atualização, conforme descrito na próxima etapa.
Etapa 5: trocar o código de autorização para atualização e acesso tokens
Para trocar um código de autorização por um token de acesso, chame o método
https://oauth2.googleapis.com/token
e defina os seguintes parâmetros:
Campos | |
---|---|
client_id |
O ID do cliente extraído 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 Etapa 1. |
grant_type |
Conforme definido no OAuth 2.0
especificação, 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 conjunto
client_id |
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 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ó é retornada se sua solicitação inclui 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 a
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é o usuário revoga 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 : |
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" }
Como chamar APIs do Google
Depois que o aplicativo obtém um token de acesso, você pode usá-lo para fazer chamadas a um serviço
em nome de um determinado
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 uma consulta access_token
ou um valor Bearer
do cabeçalho HTTP Authorization
. Quando possível,
o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ser visíveis nos registros do servidor. Na maioria
casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google (por exemplo, quando
chamando a API de transmissão do YouTube ao vivo).
A API de transmissão do YouTube ao vivo não é compatível com o fluxo da conta de serviço. Como não há
não há maneira de vincular uma conta de serviço a uma conta do YouTube, tenta autorizar solicitações com este
vai gerar um erro NoLinkedYouTubeAccount
.
Você pode experimentar todas as APIs do Google e visualizar seus escopos em OAuth 2.0 Playground.
Exemplos GET HTTP
Uma chamada ao
liveBroadcasts.list
endpoint (a API de transmissão do YouTube ao vivo) usando o protocolo HTTP Authorization: Bearer
pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Esta é uma chamada para a mesma API para o usuário autenticado com o access_token
parâmetro da string de consulta:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Exemplos de curl
É possível testar esses comandos com o aplicativo de linha de comando curl
. Este é um
exemplo que usa a opção de cabeçalho HTTP (preferencial):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Ou, alternativamente, a opção do parâmetro da string de consulta:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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. Você podem atualizar um token de acesso sem solicitar a permissão do usuário (inclusive quando o usuário é ausente) se você solicitou acesso off-line aos escopos associados ao token.
Para atualizar um token de acesso, o aplicativo envia um HTTPS POST
solicitação 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 é aplicável a solicitações de clientes registrados como
Android, iOS ou Chrome.)
|
grant_type |
Conforme
definidas no
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 retorna um objeto JSON que contém um novo token de acesso. O snippet a seguir mostra um exemplo 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 outra por usuário em todos os clientes. Salvar tokens de atualização no armazenamento a longo prazo e continuarão a usá-los enquanto permanecerem válidos. Se o seu aplicativo solicitar muitos tokens de atualização, poderá atingir esses limites; nesse caso, tokens de atualização mais antigos vão parar 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 acessando Configurações da conta. Consulte a Remover seção de acesso a sites ou apps da lista Sites de terceiros e apps com acesso à sua conta documento de suporte 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 uma aplicativo ou os recursos de API exigidos por um aplicativo tiverem mudado significativamente. Em outras palavras, do processo de remoção pode incluir uma solicitação de API para garantir que as permissões anteriores concedidas ao aplicativo são removidas.
Para revogar programaticamente um token, 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 o token for de acesso e tiver um token de atualização correspondente, o token de atualização também será revogado.
Se a revogação for processada com sucesso, o código de status HTTP da resposta será
200
: Para condições de erro, um código de status HTTP 400
é retornado junto
com um código de erro.
Leitura adicional
A prática recomendada atual da IETF OAuth 2.0 para Apps nativos é muitas das práticas recomendadas documentadas aqui.
Como implementar a Proteção entre contas
Uma etapa adicional que você deve tomar para proteger as informações está implementando o usando o serviço de proteção entre contas do Google. Esse serviço permite que você inscrever-se em notificações de ocorrências de segurança, que fornecem informações ao aplicativo sobre grandes mudanças na conta de usuário. Você pode então usar as informações para tomar medidas dependendo como você decide responder aos eventos.
Alguns exemplos dos tipos de evento enviados ao seu app pelo serviço de Proteção entre contas do Google são:
-
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 Proteger contas de usuário com a página "Proteção entre contas" para mais informações sobre como implementar a Proteção entre contas e para conferir a lista completa de eventos disponíveis.