Este documento explica como os aplicativos instalados em dispositivos como smartphones, tablets e computadores usam os endpoints do 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 receber permissão para recuperar os dados do YouTube de um canal.
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á em execução em segundo plano.
Esse fluxo de autorização é semelhante ao usado para aplicativos de servidor da Web. A principal diferença é que os apps instalados precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local para processar as respostas do servidor de autorização do Google.
Bibliotecas e amostras
Para apps iOS, recomendamos usar a versão mais recente do SDK do Fazer Login com o Google para iOS. O SDK processa a autorização do usuário e é mais simples de implementar do que o protocolo de nível inferior descrito neste guia.
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.
Pré-requisitos
Ativar as APIs do projeto
Qualquer aplicativo que chame as APIs do Google precisa ativá-las no Console de APIs.
Para ativar uma API para um projeto, faça o seguinte:
- Abra a biblioteca de APIs no Console de APIs do Google.
- Se for solicitado, selecione um projeto ou crie um novo.
- Use a página "Biblioteca" para encontrar e ativar a API YouTube Data. Encontre outras APIs que seu aplicativo vai usar e ative-as também.
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 o identifiquem para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para seu projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou para esse projeto.
- Acesse a página Clientes.
- Clique em Criar cliente.
- As seções a seguir descrevem os tipos de cliente compatíveis com o servidor de autorização do Google. Escolha o tipo de cliente recomendado para seu aplicativo, nomeie o cliente OAuth e defina os outros campos no formulário conforme apropriado.
iOS
- Selecione iOS como o tipo de aplicativo.
- Insira um nome para o cliente OAuth. Esse nome é exibido na página Clientes do projeto para identificar o cliente.
- Insira o identificador do pacote do seu app. O ID do pacote é o valor da chave
CFBundleIdentifier
no arquivo de recurso da lista de propriedades de informações do app (info.plist). O valor
geralmente é exibido no painel "General" ou "Signing & Capabilities" do
editor de projetos do Xcode. O ID do pacote também é exibido na seção "Informações gerais" da
página "Informações do app" no
site do App Store Connect da Apple.
Confirme se você está usando o ID do pacote correto para seu app, porque não será possível mudá-lo se você estiver usando o recurso App Check.
- (Opcional)
Insira o ID do seu app na App Store se ele estiver publicado na App Store da Apple. O ID da loja é uma string numérica incluída em todos os URLs da App Store da Apple.
- Abra o app Apple App Store no seu dispositivo iOS ou iPadOS.
- Procure seu app.
- Selecione o botão "Compartilhar" (símbolo de quadrado e seta para cima).
- Selecione Copiar link.
- Cole o link em um editor de texto. O ID da App Store é a parte final do URL.
Exemplo:
https://apps.apple.com/app/google/id284815942
- (Opcional)
Insira o ID da equipe. Consulte Localizar o ID da equipe na documentação da conta de desenvolvedor da Apple para mais informações.
Observação:o campo "ID da equipe" é obrigatório se você estiver ativando o App Check para seu cliente. - (Opcional)
Ative o App Check no seu app iOS. Quando você ativa o App Check, o serviço App Attest da Apple é usado para verificar se as solicitações do OAuth 2.0 originadas do seu cliente OAuth são genuínas e vêm do seu app. Isso ajuda a reduzir o risco de falsificação de identidade do app. Saiba como ativar o App Check no seu app iOS.
- Clique em Criar.
Computador
- Selecione o tipo de aplicativo App para computador.
- No campo Nome, insira um nome para o cliente OAuth. Esse nome é exibido na página Clientes do projeto para identificar o cliente.
- Clique em Criar.
Identificar escopos de acesso
Os escopos permitem que o aplicativo solicite acesso apenas aos recursos necessários e que os usuários controlem o nível de acesso concedido ao aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de receber o consentimento do usuário.
Antes de começar a implementar a autorização do OAuth 2.0, recomendamos que você identifique os escopos que seu app precisará de permissão para acessar.
A API YouTube Data v3 usa os seguintes escopos:
| Escopo | Descrição |
|---|---|
https://www. |
Gerenciar sua conta do YouTube |
https://www. |
Ver uma lista dos membros ativos atuais do canal, do nível deles e de quando se tornaram membros |
https://www. |
Ver, editar e excluir permanentemente vídeos, classificações, comentários e legendas do YouTube |
https://www. |
Visualize sua conta do YouTube |
https://www. |
Gerenciar seus vídeos do YouTube |
https://www. |
Ver e gerenciar seus ativos e conteúdos associados no YouTube |
https://www. |
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 de escopos que podem ser usados para acessar as APIs do Google.
Como conseguir tokens de acesso do OAuth 2.0
As etapas a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para receber o consentimento do usuário para realizar 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 é compatível com o protocolo Proof Key for Code Exchange (PKCE) para tornar o fluxo do app instalado mais seguro. Um verificador de código exclusivo é criado para cada solicitação de autorização, e o valor transformado, chamado de "code_challenge", é enviado ao servidor de autorização para receber o código de autorização.
Criar o verificador de código
Um code_verifier é uma string aleatória criptográfica de alta entropia que usa os caracteres não reservados
[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", com um comprimento mínimo de 43 caracteres
e um comprimento máximo de 128 caracteres.
O verificador de código precisa ter entropia suficiente para que seja impossível adivinhar o valor.
Criar o desafio de código
Há dois métodos para criar o desafio de código.
| Métodos de geração de desafio de código | |
|---|---|
| S256 (recomendado) | O desafio de código é o hash SHA256 codificado em Base64URL (sem preenchimento) do verificador de
código.
|
| plain | O desafio do código é o mesmo valor do verificador do código gerado acima.
|
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
O ID do cliente do aplicativo. Esse valor pode ser encontrado na página Clientes do console do Cloud. |
||||||||||||||||
redirect_uri |
Obrigatório
Determina como o servidor de autorização do Google envia uma resposta ao seu app. Há várias opções de redirecionamento disponíveis para apps instalados, e você terá configurado suas credenciais de autorização com um método de redirecionamento específico em mente. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou na página Clientes do console do Cloud do cliente. Se esse valor não corresponder a um
URI autorizado, você vai receber um erro A tabela mostra o valor de parâmetro
|
||||||||||||||||
response_type |
Obrigatório
Determina se o endpoint do OAuth 2.0 do Google retorna um código de autorização. Defina o valor de parâmetro como |
||||||||||||||||
scope |
Obrigatório
Uma lista de escopos delimitada por espaços que identifica os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de permissão que o Google mostra 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 o nível de acesso concedido 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. A API YouTube Data v3 usa os seguintes escopos:
O documento Escopos da API OAuth 2.0 fornece 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 o aplicativo usa para manter o estado entre a
solicitação de autorização e a resposta do servidor de autorização.
O servidor retorna o valor exato que você envia como um par É possível usar esse parâmetro para várias finalidades, como direcionar o usuário ao
recurso correto no aplicativo, enviar nonces e reduzir a falsificação de solicitações
entre sites. Como seu |
||||||||||||||||
login_hint |
Opcional
Se o aplicativo souber qual usuário está tentando se autenticar, ele poderá usar esse parâmetro para fornecer uma dica ao servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login, preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de 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 recuperar os dados do usuário no YouTube.Os URLs são idênticos, exceto pelo valor do parâmetro redirect_uri. Os URLs
também contêm os parâmetros obrigatórios response_type e client_id, além do
parâmetro opcional state. Cada URL contém quebras de linha e espaços para
facilitar a leitura.
Esquema de URI personalizado
https://accounts.google.com/o/oauth2/v2/auth? scope=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 pede o consentimento do usuário
Nesta etapa, o usuário decide se concede ao aplicativo o acesso solicitado. Nessa fase, 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. O usuário pode consentir em conceder acesso a um ou mais escopos solicitados pelo aplicativo ou recusar a solicitação.
Seu aplicativo não precisa fazer nada nesse estágio, pois ele aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na próxima etapa.
Erros
As solicitações 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. Os códigos de erro comuns e as resoluções sugeridas são:
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 os apps internos e de terceiros com acesso aos dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os escopos ou aos escopos sensíveis e restritos até que o acesso seja explicitamente concedido ao ID do cliente OAuth.
disallowed_useragent
O endpoint de autorização é exibido em um user agent incorporado não permitido pelas políticas do OAuth 2.0 do Google.
Os desenvolvedores de iOS e macOS podem encontrar esse erro ao abrir solicitações de autorização no
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 web podem encontrar esse erro quando um app para 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 no
seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do
sistema operacional, o 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 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".
deleted_client
O cliente OAuth usado para fazer a solicitação foi excluído. A exclusão pode acontecer de forma manual ou automática no caso de clientes não utilizados . Os clientes excluídos podem ser restaurados em até 30 dias após a exclusão. Saiba mais .
invalid_grant
Se você estiver usando um
verificador de código e
desafio, o parâmetro code_callenge é 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 do usuário para obter novos tokens. Se o 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, é possível que a conta do usuário 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 autorizado para o ID do cliente OAuth. Revise os URIs de redirecionamento autorizados na
página Clientes
do console do Google Cloud.
O redirect_uri transmitido pode ser inválido para o tipo de cliente.
O parâmetro redirect_uri pode se referir ao fluxo fora de banda (OOB, na sigla em inglês) do OAuth, que foi
descontinuado e não é mais compatível. Consulte o
guia de migração para atualizar sua
integração.
invalid_request
Ocorreu um erro na sua solicitação. Isso pode acontecer 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 é aceito pelo Google. Verifique se a integração do OAuth usa um método de integração recomendado
- Um esquema personalizado incompatível foi usado para o URI de redirecionamento. Se aparecer a mensagem de erro O esquema de URI personalizado não é compatível com apps Android ou apps do Chrome, saiba mais sobre alternativas de esquema de URI personalizado.
Etapa 4: processar a resposta do servidor OAuth 2.0
A maneira como o aplicativo recebe a resposta de autorização depende do
esquema de URI de redirecionamento usado. Independentemente do esquema, a
resposta vai conter um código de autorização (code) ou um erro
(error). Por exemplo, error=access_denied indica que o usuário
recusou a solicitação.
Se o usuário conceder acesso ao aplicativo, você poderá trocar o código de autorização por um token de acesso e um token de atualização, conforme descrito na próxima etapa.
Etapa 5: trocar o código de autorização por tokens de atualização e acesso
Para trocar um código de autorização por um token de acesso, chame o
endpoint https://oauth2.googleapis.com/token e defina os seguintes parâmetros:
| Campos | |
|---|---|
client_id |
O ID do cliente obtido na página Clientes do console do Cloud. |
client_secret |
Opcional
A chave secreta do cliente obtida na página Clientes do console do Cloud. |
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 na
página Clientes do
Console do Cloud para o
client_id fornecido. |
Embora o uso do DPoP seja opcional, ele é recomendado para aumentar a segurança. A segurança do DPoP depende da restrição da chave privada a um único dispositivo. Recomendamos armazená-la de forma que não possa ser copiada para fora do dispositivo, por exemplo, usando TPMs, Secure Enclaves ou outros keystores com suporte de hardware. Para usar a DPoP, seu aplicativo precisa gerar um novo JWT de prova de DPoP exclusivo para cada solicitação ao endpoint do token e adicioná-lo como um cabeçalho da solicitação HTTP.
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
DPoP |
Opcional | Uma prova de DPoP é um JWT que comprova a
posse de uma chave privada. Este é um cabeçalho, não um parâmetro. Se fornecidos, os tokens retornados
serão vinculados a essa chave. Uma nova prova exclusiva precisa ser gerada para cada solicitação e
precisa incluir declarações htm (método HTTP) e htu (URI HTTP) que
correspondam à solicitaçã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 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Criar uma prova de DPoP
As etapas a seguir mostram como criar uma prova de DPoP usando o OpenSSL na linha de comando:
- Gere um par de chaves EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Crie o cabeçalho DPoP:
O cabeçalho precisa incluir as declarações
typ,algejwk(chave pública). Os valoresxeysão as coordenadas codificadas em Base64Url da sua chave pública EC. Codifique este JSON em Base64Url:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Crie o payload de DPoP:
O payload precisa incluir
jti(um identificador exclusivo para a solicitação),htm(método HTTP, por exemplo,POST),htu(URI HTTP, por exemplo,https://oauth2.googleapis.com/token) eiat(emitido no momento). Se você recebeu um valor de uso único do servidor em um cabeçalhoDPoP-Noncena resposta a uma solicitação anterior, inclua esse valor em uma declaraçãononce. A declaração nonce é opcional para trocas de código de autorização e usada apenas quando o cabeçalho DPoP-Nonce foi recebido anteriormente. Codifique este JSON em Base64Url:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }O valor de
jtidepende do tipo de troca:- Para trocas de código de autorização, o
jtiprecisa ser o hash SHA256 codificado em Base64Url do código de autorização:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Para trocas de token de atualização, o
jtiprecisa ser um identificador exclusivo por solicitação:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- Para trocas de código de autorização, o
- Assine a prova:
Concatene o cabeçalho e o payload codificados com um ponto (
.) e assine o resultado com sua chave privada usando o ES256. A JWS exige que a assinatura esteja em um formato bruto concatenadoR | S(64 bytes para P-256). Se você usar o OpenSSL diretamente, será necessário converter a assinatura padrão codificada em DER ASN.1 para esse formato bruto.
Uma troca bem-sucedida é indicada por uma resposta 200 OK
que contém os tokens. Se uma prova de DPoP válida for usada durante
a troca, o token de atualização que o Google retornar será vinculado à sua chave por DPoP, mas os tokens de acesso
não serão vinculados por DPoP. Os tokens de acesso vão manter o token_type de
Bearer em vez de DPoP.
Além disso, o Google retorna um cabeçalho HTTP DPoP-Nonce na resposta.
O cliente precisa armazenar esse valor de uso único em cache e incluí-lo na declaração nonce da prova de DPoP
em solicitações subsequentes (como ao trocar um token de atualização por um novo token de acesso ou ao
chamar APIs protegidas por DPoP). Ao usar esse valor de uso único emitido antecipadamente, você pode evitar uma falha de ida e volta
extra (use_dpop_nonce) na próxima solicitação.
As provas de DPoP precisam ser incluídas nas solicitações de troca de token feitas com tokens de atualização vinculados a DPoP.
Uma troca com falha ocorre se o cabeçalho DPoP estiver
ausente quando esperado, for inválido ou se a prova usar uma chave diferente da
vinculada ao token. Nesses casos, o servidor retorna um erro 400 Bad Request.
Se a prova de DPoP tiver declarações htm ou htu incompatíveis, um iat expirado, um jti reutilizado ou uma assinatura inválida, o Google vai retornar um código do erro invalid_dpop_proof.
Se um valor de uso único de DPoP for necessário, como durante uma troca de token de atualização, e a prova de DPoP não tiver uma declaração nonce ou o valor de uso único for inaceitável para o servidor (por exemplo, expirou, já foi usado ou está incorreto), o Google vai retornar um código de erro use_dpop_nonce com um cabeçalho HTTP DPoP-Nonce contendo um novo valor de uso único que pode ser usado em uma solicitação subsequente.
Outras falhas podem retornar invalid_grant.
O Google responde a essa solicitação retornando um objeto JSON que contém um token de acesso de curta duração e um token de atualização.
A resposta contém os seguintes campos:
| Campos | |
|---|---|
access_token |
O token que seu aplicativo envia para autorizar uma solicitação de API do Google. |
expires_in |
A vida útil restante do token de acesso em segundos. |
id_token |
Observação:essa propriedade só será retornada se a solicitação incluir um escopo de identidade,
como openid, profile ou email. O valor é um
JSON Web Token (JWT) que contém informações de identidade assinadas digitalmente sobre o
usuário. |
refresh_token |
Um token que pode ser usado para receber um novo token de acesso. Os tokens de atualização são válidos até que o usuário revogue o acesso ou o token de atualização expire. Se o DPoP foi usado, o token de atualização é vinculado à chave privada usada para assinar a prova do DPoP. Os tokens de atualização são sempre retornados para aplicativos instalados. |
refresh_token_expires_in |
A vida útil restante do token de atualização em segundos. Esse valor só é definido quando o usuário concede acesso com base no tempo. |
scope |
Os escopos de acesso concedidos pelo access_token expressos como uma lista de
strings que diferenciam maiúsculas de minúsculas e são delimitadas por espaços. |
token_type |
O tipo de token retornado. Esse valor é sempre Bearer, mesmo quando o DPoP é usado. |
O snippet a seguir mostra um exemplo de cabeçalhos de resposta e corpo bem-sucedidos quando o DPoP é usado:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Etapa 6: verificar quais escopos os usuários concederam
Ao solicitar várias permissões (escopos), os usuários podem não conceder ao app acesso a todas elas. Seu app precisa verificar quais escopos foram realmente concedidos e lidar de forma adequada com situações em que algumas permissões são negadas, normalmente desativando os recursos que dependem desses escopos negados.
No entanto, há exceções. Os apps do Google Workspace Enterprise com delegação de autoridade em todo o domínio ou marcados como Confiáveis ignoram a tela de permissão granular. Para esses apps, os usuários não vão ver a tela de permissão granular. Em vez disso, o app vai receber todos os escopos solicitados ou nenhum.
Para mais informações, consulte Como processar permissões granulares.
Para verificar se o usuário concedeu ao aplicativo acesso a um escopo específico,
examine o campo scope na resposta do token de acesso. Os escopos de acesso concedidos pelo
token de acesso expressos como uma lista de strings que diferenciam maiúsculas de minúsculas e são delimitadas por espaços.
Por exemplo, a resposta de token de acesso de amostra a seguir indica que o usuário concedeu ao seu aplicativo acesso às permissões de somente leitura de atividade do Drive e de eventos da agenda:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Chamar APIs do Google
Depois que o aplicativo receber um token de acesso, você poderá usá-lo para fazer chamadas para uma API do Google
em nome de uma determinada
conta de usuário, se os escopos de acesso exigidos pela API tiverem sido concedidos. Para isso, inclua
o token de acesso em uma solicitação à API, incluindo um parâmetro de consulta access_token
ou um valor de cabeçalho HTTP Authorization Bearer. Quando possível,
o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria
dos casos, é possível usar uma biblioteca de cliente para configurar as chamadas para as APIs do Google (por exemplo, ao
chamar a API YouTube Live Streaming).
A API YouTube Live Streaming não é compatível com o fluxo da conta de serviço. Como não
há como vincular uma conta de serviço a uma conta do YouTube, as tentativas de autorizar solicitações com esse
fluxo vão gerar um erro NoLinkedYouTubeAccount.
Você pode testar todas as APIs do Google e conferir os escopos delas no OAuth 2.0 Playground.
Exemplos de HTTP GET
Uma chamada para o endpoint
liveBroadcasts.list (API YouTube Live Streaming) usando o cabeçalho HTTP Authorization: Bearer
pode ser semelhante ao exemplo a seguir. É 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
Veja uma chamada para a mesma API para o usuário autenticado usando o parâmetro de string de consulta access_token:
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. 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/liveBroadcasts?part=id%2Csnippet&mine=true
Ou, como alternativa, a opção de parâmetro de string de consulta:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Atualizar um 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 permissão ao usuário (inclusive quando ele não está presente) se você tiver solicitado acesso off-line aos escopos associados ao token.
Para atualizar um token de acesso, seu aplicativo envia uma solicitação HTTPS POST
ao servidor de autorização do Google (https://oauth2.googleapis.com/token) que
inclui os seguintes parâmetros no corpo da solicitação:
| Nome | Valor |
|---|---|
client_id |
O ID do cliente recebido do Console de APIs. |
client_secret |
Opcional
A chave secreta do cliente recebida do Console de APIs.
O |
grant_type |
Conforme
definido na
especificação do OAuth 2.0,
o valor desse campo precisa ser definido como refresh_token. |
refresh_token |
O token de atualização retornado da troca de código de autorização. |
Embora o uso do DPoP seja opcional, ele é recomendado para aumentar a segurança. Para usar o DPoP com um token de atualização, seu aplicativo precisa gerar um novo JWT de prova de DPoP exclusivo para cada solicitação ao endpoint do token. Essa prova precisa ser assinada com a mesma chave privada usada durante a troca inicial do código de autorização. O aplicativo adiciona a prova como um cabeçalho da solicitação HTTP.
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
DPoP |
Opcional | Uma prova de DPoP é um JWT que comprova a
posse de uma chave privada. Este é um cabeçalho, não um parâmetro. Se fornecidos, os tokens retornados
serão vinculados a essa chave. Uma nova prova exclusiva precisa ser gerada para cada solicitação e
precisa incluir declarações htm (método HTTP) e htu (URI HTTP) que
correspondam à solicitaçã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 DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Para usar o DPoP com um token de atualização, é necessário gerar um JWT de prova de DPoP novo e exclusivo para a solicitação. Consulte Criar uma prova de DPoP para instruções detalhadas sobre como gerar o par de chaves e criar o JWT.
Uma troca bem-sucedida é indicada por uma resposta 200 OK
que contém um novo token de acesso. Quando o DPoP é usado, o
token_type é Bearer. Uma resposta bem-sucedida confirma
que a prova de DPoP para o token de atualização foi aceita. O Google também pode retornar um novo
cabeçalho HTTP DPoP-Nonce na resposta. Se isso acontecer, seu cliente precisará armazenar em cache esse
nonce e incluí-lo na declaração nonce da prova de DPoP em solicitações subsequentes.
Uma falha na troca ocorre se o cabeçalho DPoP estiver ausente, for inválido ou usar uma chave incorreta. Para detalhes sobre códigos de erro específicos do DPoP e como lidar com nonces, consulte Falha na troca.
O snippet a seguir mostra um exemplo de cabeçalhos de resposta e corpo bem-sucedidos quando o DPoP é usado:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Há limites para o número de tokens de atualização que serão emitidos: um limite por combinação de cliente/usuário e outro por usuário em todos os clientes. Salve os tokens de atualização no armazenamento de longo prazo e continue usando-os enquanto forem 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 vão parar de funcionar.
Revogação de token
Em alguns casos, um usuário pode querer revogar o acesso concedido a um aplicativo. Para revogar o acesso, o usuário precisa acessar as Configurações da conta. Consulte a seção Remover o acesso de sites ou apps de terceiros com acesso à sua conta no documento de suporte para mais informações.
Também é possível que um aplicativo revogue de forma programática o acesso concedido a ele. A revogação programática é importante em casos em que um usuário cancela a inscrição, remove um aplicativo ou os recursos da API exigidos por um app mudaram significativamente. Em outras palavras, parte do processo de remoção pode incluir uma solicitação de API para garantir que as permissões concedidas anteriormente ao aplicativo sejam removidas.
Para revogar um token de maneira programática, seu aplicativo faz uma solicitação para
https://oauth2.googleapis.com/revoke e inclui o token como um parâmetro:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}O token pode ser um token de acesso ou um token 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 com um código do erro.
Métodos de redirecionamento de apps
Esquema de URI personalizado
Os 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 em apps do Chrome
Use a API Chrome Identity, que envia a resposta do OAuth 2.0 diretamente para o app, eliminando a necessidade de um URI de redirecionamento.
Endereço IP de loopback (macOS, Linux, Windows para computador)
Para receber o código de autorização usando esse URL, seu aplicativo precisa estar detectando o 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 receber o código de autorização.
Quando o app recebe a resposta de autorização, para melhorar a usabilidade, ele precisa responder mostrando uma página HTML que instrui o usuário a fechar o navegador e voltar ao app.
| Uso recomendado | Apps para computador macOS, Linux e Windows |
| Valores do formulário | Defina o tipo de aplicativo como App para computador. |
Copiar/colar manual (descontinuado)
Proteger seus apps
Verificar a propriedade do app para o Chrome
É possível verificar a propriedade do aplicativo para reduzir o risco de falsificação de identidade.
Para concluir o processo de verificação, use 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 de controle do desenvolvedor da Chrome Web Store com o mesmo ID do item do cliente OAuth da extensão do Chrome que você está verificando.
- 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 de verificação. Caso contrário, uma mensagem de erro será mostrada.
Para corrigir uma verificação que falhou, tente o seguinte:
- Verifique se há um item registrado no Painel de controle do desenvolvedor da Chrome Web Store com o mesmo ID do cliente OAuth da extensão do Chrome que você está verificando.
- Verifique se você é um editor do app, ou seja, se é o editor individual ou um membro do grupo de editores do app. Saiba mais sobre o gerenciamento de acesso no Painel de controle do desenvolvedor da Chrome Web Store.
- Se você acabou de atualizar sua lista de editores de grupo, verifique se a lista de membros do grupo de editores está sincronizada no Painel de controle do desenvolvedor da Chrome Web Store. Saiba mais sobre como sincronizar sua lista de assinantes do publisher.
App Check (somente iOS)
O recurso App Check ajuda a proteger seus aplicativos iOS contra uso não autorizado usando o serviço App Attest da Apple para verificar se as solicitações feitas aos endpoints do OAuth 2.0 do Google são provenientes dos seus aplicativos autênticos. Isso ajuda a reduzir o risco de falsificação de identidade do app.
Ativar o App Check para seu cliente iOS
Os seguintes requisitos precisam ser atendidos para ativar o App Check no seu cliente iOS:- É necessário especificar um ID de equipe para o cliente iOS.
- Não use um caractere curinga no ID do pacote, porque ele pode ser resolvido para mais de um app. Isso significa que o ID do pacote não pode incluir o símbolo de asterisco (*).
Depois de ativar o App Check, você vai começar a ver métricas relacionadas às solicitações OAuth do seu cliente na visualização de edição do cliente OAuth. As solicitações de fontes não verificadas não serão bloqueadas até que você ative o App Check. As informações na página de monitoramento de métricas podem ajudar a determinar quando iniciar a aplicação.
Talvez você veja erros relacionados ao recurso App Check ao ativá-lo no seu app iOS. Para corrigir esses erros, tente o seguinte:
- Verifique se o ID do pacote e o ID da equipe que você especificou são válidos.
- Verifique se você não está usando um caractere curinga para o ID do pacote.
Aplicar o App Check ao cliente iOS
Ativar o App Check no seu app não bloqueia automaticamente solicitações não reconhecidas. Para aplicar essa proteção, acesse a visualização de edição do cliente iOS. Lá, você vai encontrar as métricas do App Check à direita da página, na seção Google Identity para iOS. As métricas incluem as seguintes informações:- Número de solicitações verificadas: solicitações que têm um token válido do App Check. Depois de ativar a aplicação do App Check, apenas as solicitações nessa categoria serão bem-sucedidas.
- Número de solicitações não verificadas: provavelmente solicitações de clientes desatualizadas: solicitações sem um token do App Check. Elas podem ser de uma versão mais antiga do seu app que não inclui uma implementação do App Check.
- Número de solicitações não verificadas: solicitações de origem desconhecida: solicitações sem um token do App Check que não parecem ser do seu app.
- Número de solicitações não verificadas: solicitações inválidas: solicitações com um token inválido do App Check, que podem ser de um cliente fraudulento tentando se passar pelo seu app ou de ambientes emulados.
Para aplicar o App Check, clique no botão ENFORCE e confirme sua escolha. Depois que a aplicação estiver ativa, todas as solicitações não verificadas do cliente serão rejeitadas.
Observação: depois de ativar a aplicação, pode levar até 15 minutos para que as mudanças entrem em vigor.
Remover a aplicação do App Check para seu cliente iOS
Remover a aplicação do App Check do seu app vai interromper a aplicação e permitir todas as solicitações do seu cliente para os endpoints do OAuth 2.0 do Google, incluindo solicitações não verificadas.
Para cancelar a aplicação do App Check no cliente iOS, acesse a visualização de edição do cliente iOS, clique no botão CANCELAR APLICAÇÃO e confirme sua escolha.
Observação: depois de desativar o App Check, pode levar até 15 minutos para que as mudanças entrem em vigor.
Desativar o App Check para seu cliente iOS
Desativar o App Check para seu app vai interromper todo o monitoramento e a aplicação do App Check. Considere desativar o App Check para continuar monitorando as métricas do cliente.
Para desativar o App Check no cliente iOS, acesse a visualização de edição do cliente iOS e desative o botão Proteja seu cliente OAuth contra abusos com o Firebase App Check.
Observação: depois de desativar o App Check, pode levar até 15 minutos para que as mudanças entrem em vigor.
Acesso baseado no horário
O acesso baseado em tempo permite que um usuário conceda ao app acesso aos dados dele por um período limitado para concluir uma ação. O acesso por tempo limitado está disponível em alguns produtos do Google durante o fluxo de consentimento, permitindo que os usuários concedam acesso por um período limitado. Um exemplo é a API Data Portability, que permite uma transferência única de dados.
Quando um usuário concede ao aplicativo acesso com base no tempo, o token de atualização expira após a
duração especificada. Os tokens de atualização podem ser invalidados antes em circunstâncias específicas. Consulte estes casos para mais detalhes. O campo refresh_token_expires_in retornado na resposta da troca de código de autorização representa o tempo restante até que o token de atualização expire nesses casos.
Leitura adicional
A prática recomendada atual da IETF OAuth 2.0 para apps nativos estabelece muitas das práticas recomendadas documentadas aqui.
Implementar a Proteção entre Contas
Outra etapa que você deve seguir para proteger as contas dos usuários é implementar a Proteção entre Contas usando o serviço de Proteção entre Contas do Google. Esse serviço permite que você se inscreva para receber notificações de ocorrências de segurança que fornecem informações ao seu aplicativo sobre mudanças importantes na conta do usuário. Em seguida, você pode usar as informações para entrar em ação, dependendo de como decidir responder aos eventos.
Alguns exemplos de 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 página Proteger contas de usuário com a Proteção entre Contas para saber como implementar a Proteção entre Contas e conferir a lista completa de eventos disponíveis.