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 Analytics ou à API YouTube Reporting.
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 e recuperar os dados do YouTube Analytics de um canal.
Os apps instalados são distribuídos para dispositivos individuais, e presume-se que eles não podem manter segredos. Elas podem acessar as APIs do Google enquanto o usuário está no app ou quando o app está sendo executado em segundo plano.
Esse fluxo de autorização é semelhante ao usado para aplicativos de servidor da Web. A principal diferença é que os apps instalados precisam abrir o navegador do sistema e fornecer um URI de redirecionamento local para processar respostas do servidor de autorização do Google.
Bibliotecas e amostras
Para apps iOS, recomendamos usar a versão mais recente do SDK para iOS do Google Sign-In. 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 oferecem suporte a um navegador do sistema ou que têm recursos de entrada limitados, como TVs, consoles de jogos, câmeras ou impressoras, consulte OAuth 2.0 para TVs e dispositivos ou Login em TVs e dispositivos de entrada limitada.
Pré-requisitos
Ativar as APIs do projeto
Qualquer aplicativo que chame as APIs do Google precisa ativar essas APIs no API Console.
Para ativar uma API para um projeto, faça o seguinte:
- Open the API Library no Google API Console.
- If prompted, select a project, or create a new one.
- Use a página "Biblioteca" para encontrar e ativar a API YouTube Analytics e a API YouTube Reporting. Muitos aplicativos que recuperam dados do YouTube Analytics também interagem com 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 identifiquem o aplicativo para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para seu projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou para esse projeto.
- Go to the Clients page.
- Clique em Criar cliente.
- As seções a seguir descrevem os tipos de clientes compatíveis com o servidor de autorização do Google. Escolha o tipo de cliente recomendado para seu aplicativo, nomeie o cliente OAuth e defina os outros campos do formulário conforme necessário.
iOS
- Selecione o tipo de aplicativo iOS.
- Insira um nome para o cliente OAuth. Esse nome é exibido no Clients page 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 recursos da lista de propriedades de informações do app (info.plist). O valor é mostrado com mais frequência nos painéis "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 App Store Connect da Apple.
Confirme se você está usando o ID do pacote correto para seu app, já que não será possível mudar isso se você estiver usando o recurso App Check.
- (Opcional)
Insira o ID da App Store do app 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 seu 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 representação de app. Saiba como ativar o App Check no seu app iOS.
- Clique em Criar.
UWP
- Selecione o tipo de aplicativo Plataforma Universal do Windows.
- Insira um nome para o cliente OAuth. Esse nome é exibido no Clients page do projeto para identificar o cliente.
- Insira o ID de 12 caracteres da Microsoft Store do seu app. Esse valor pode ser encontrado no Microsoft Partner Center na página Identidade do app na seção "Gerenciamento de apps".
- Clique em Criar.
Para aplicativos UWP, o URI de redirecionamento é formado usando o Identificador de Segurança do Pacote (SID) exclusivo do seu aplicativo. Você pode encontrar o Package SID do seu aplicativo no arquivo Package.appxmanifest dentro do seu projeto do Visual Studio.
Ao criar seu ID do cliente no console do Google Cloud, você deve especificar o URI de redirecionamento no seguinte formato, usando o valor em minúsculas do seu Package SID:
ms-app://YOUR_APP_PACKAGE_SID
Para aplicativos UWP, o esquema URI personalizado não pode ter mais de 39 caracteres, conforme especificado emDocumentação da Microsoft.
Identificar escopos de acesso
Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permitem aos usuários controlar o nível de acesso que concedem ao seu aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de obter o consentimento do usuário.
Antes de começar a implementar a autorização OAuth 2.0, recomendamos que você identifique os escopos aos quais seu aplicativo precisará de permissão de acesso.
A API do YouTube Analytics utiliza os seguintes escopos:
| Escopo | Descrição |
|---|---|
https://www. |
Gerenciar sua conta do YouTube |
https://www. |
Visualize sua conta do YouTube |
https://www. |
Ver e gerenciar seus ativos e conteúdos associados no YouTube |
https://www. |
Ver relatórios monetários e não monetários do YouTube Analytics sobre seu conteúdo do YouTube |
https://www. |
Visualize os relatórios do YouTube Analytics para seu conteúdo no YouTube |
A API de denúncias do YouTube usa os seguintes escopos:
| Escopo | Descrição |
|---|---|
https://www. |
Ver relatórios monetários e não monetários do YouTube Analytics sobre seu conteúdo do YouTube |
https://www. |
Visualize os relatórios do YouTube Analytics para seu conteúdo no YouTube |
O documento Escopos da API OAuth 2.0 contém uma lista completa de escopos que você pode usar para acessar as APIs do Google.
Obtenção de tokens de acesso OAuth 2.0
Os passos a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para obter o consentimento do usuário para realizar uma solicitação de API em nome dele. Seu aplicativo precisa dessa autorização antes de poder executar uma solicitação à API do Google que requer autorização do usuário.
Etapa 1: Gere 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 aplicativos 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 obter o código de autorização.
Crie o verificador de código
Um code_verifier é uma string criptográfica aleatória de alta entropia usando os caracteres não reservados [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", com um comprimento mínimo de 43 caracteres e um comprimento máximo de 128 caracteres.
O verificador de código deve ter entropia suficiente para tornar impraticável a tentativa de adivinhar o valor.
Desafio de criação de código
São suportados dois métodos para criar o desafio de código.
| Métodos de geração de desafios de código | |
|---|---|
| S256 (recomendado) | O desafio de código consiste no hash SHA256 codificado em Base64URL (sem preenchimento) do verificador de código.
|
| plain | O desafio de código é o mesmo valor do verificador de 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ões ativas,
autentica o usuário e obtém o consentimento dele. O endpoint só pode ser acessado por SSL e rejeita conexões HTTP (não SSL).
O servidor de autorização é compatível com os seguintes parâmetros de string de consulta para aplicativos instalados:
| Parâmetros | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente do seu aplicativo. Esse valor está no Cloud Console Clients page. |
||||||||||||||||||
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 no
Cloud Console
Clients pagedo cliente. Se esse valor não corresponder a um
URI autorizado, você vai receber um erro A tabela 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
Uma lista delimitada por espaços de escopos que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam à tela de consentimento que o Google mostra ao usuário. Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permitem aos usuários controlar o nível de acesso que concedem ao seu 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 Analytics usa os seguintes escopos:
A API de denúncias do YouTube usa os seguintes escopos:
O documento Escopos da API OAuth 2.0 oferece uma lista completa de escopos que você pode usar 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 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 seu 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 utiliza a dica para simplificar o fluxo de login, seja preenchendo previamente o campo de e-mail no formulário de inscrição ou selecionando a sessão de login múltiplo apropriada. Defina o valor do parâmetro para um endereço de e-mail ou identificador |
||||||||||||||||||
Exemplos de URLs de autorização
As abas 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 relatórios do YouTube Analytics 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 obrigatórios response_type e client_id, bem como o parâmetro opcional state. Cada URL contém quebras de linha e espaços para facilitar a leitura.
Esquema de URI personalizado
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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%2Fyt-analytics.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 concede ou não o acesso solicitado ao seu aplicativo. Nessa etapa, o Google exibe uma janela de consentimento que mostra o nome do seu aplicativo e os serviços da API do Google aos quais está solicitando permissão de acesso com as credenciais de autorização do usuário, além de um resumo dos escopos de acesso a serem concedidos. O usuário pode então consentir em conceder acesso a um ou mais escopos solicitados pelo seu aplicativo ou recusar a solicitação.
Seu aplicativo não precisa fazer nada nesta etapa, pois está aguardando a resposta do servidor OAuth 2.0 do Google, que indicará se o acesso foi concedido. Essa resposta é explicada na etapa seguinte.
Erros
As solicitações ao endpoint de autorização OAuth 2.0 do Google podem exibir mensagens de erro para o usuário em vez dos fluxos de autenticação e autorização esperados. Os códigos de erro comuns e as soluçõ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 do administrador do Google Workspace Controlar quais apps de terceiros e internos acessam os dados do Google Workspace para obter 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 seu ID de cliente OAuth.
disallowed_useragent
O endpoint de autorização é exibido dentro de um user-agent incorporado, o que é proibido pelo Google.Políticas do OAuth 2.0 .
Os desenvolvedores de iOS e macOS podem encontrar esse erro ao abrir solicitações de autorização emWKWebView.
Os desenvolvedores devem usar bibliotecas do iOS, como o Google Sign-In para iOS ou o AppAuth para iOS da OpenID Foundation.
Os desenvolvedores web podem encontrar esse erro quando um aplicativo iOS ou macOS abre um link web genérico em um user-agent incorporado e um usuário navega até o endpoint de autorização OAuth 2.0 do Google a partir do seu site. Os desenvolvedores devem permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui ambosLinks universais manipuladores ou o aplicativo de navegador padrão. OSFSafariViewController A biblioteca também é uma opção suportada.
org_internal
O ID do cliente OAuth na solicitação faz parte de um projeto que limita o acesso a contas do Google em uma região específica. Organização do Google Cloud . Para obter mais informações sobre esta opção de configuração, consulte a seção Tipo de usuário no artigo de ajuda Configurando sua tela de consentimento OAuth.
deleted_client
O cliente OAuth usado para fazer a solicitação foi excluído. A exclusão pode acontecer manualmente ou automaticamente 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 será inválido ou estará ausente. Verifique se o parâmetro
code_challenge está definido corretamente.
Ao atualizar um token de acesso, ele pode ter expirado ou sido invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se o erro persistir, verifique se o aplicativo foi configurado corretamente e se você está usando os tokens e parâmetros certos na sua 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 em
Google Cloud Console
Clients page.
O redirect_uri transmitido pode ser inválido para o tipo de cliente.
O parâmetro redirect_uri pode se referir ao fluxo fora de banda (OOB) do OAuth, que foi
descontinuado e não é mais compatível. Consulte o
guia de migração para atualizar sua
integração.
invalid_request
Algo deu errado com a solicitação. Isso pode acontecer por vários motivos:
- A solicitação não estava formatada corretamente
- A solicitação não tinha os parâmetros obrigatórios
- A solicitação usa um método de autorização não compatível com o Google. Verificar se a integração do OAuth usa um método recomendado
- Um esquema personalizado incompatível foi usado para o URI de redirecionamento. Se você receber a mensagem de erro O esquema de URI personalizado não é compatível com apps Android ou Chrome, saiba mais sobre alternativas ao esquema de URI personalizado.
Etapa 4: processar a resposta do servidor OAuth 2.0
A maneira como seu aplicativo recebe a resposta de autorização depende do esquema de URI de redirecionamento que ele usa. Independente do esquema, a
resposta vai conter um código de autorização (code) ou um erro
(error). Por exemplo, error=access_denied indica que o usuário
recusou a solicitação.
Se o usuário conceder acesso ao seu aplicativo, você poderá trocar o código de autorização por um token de acesso e um token de atualização, conforme descrito na próxima etapa.
Etapa 5: Trocar o código de autorização pelos 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 do Cloud Console Clients page. |
client_secret |
Opcional
O segredo do cliente obtido de Cloud Console Clients page. |
code |
O código de autorização retornado da solicitação inicial. |
code_verifier |
O verificador de código que você criou emPasso 1. |
grant_type |
Conforme definido na especificação OAuth 2.0, o valor deste campo deve ser definido como authorization_code. |
redirect_uri |
Um dos URIs de redirecionamento listados para o seu projeto no Cloud Console
Clients page para o client_id fornecido. |
O trecho 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& 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:
O trecho a seguir mostra um exemplo de resposta:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Etapa 6: Verifique quais escopos foram concedidos aos usuários.
Ao solicitarmúltiplos Em relação às permissões (escopos), os usuários podem não conceder ao seu aplicativo acesso a todas elas. Seu aplicativo deve verificar quais escopos foram efetivamente concedidos e lidar adequadamente com situações em que algumas permissões são negadas, geralmente desativando os recursos que dependem desses escopos negados.
No entanto, existem exceções. Aplicativos do Google Workspace Enterprise comdelegação de autoridade em todo o domínio ou aplicativos marcados comoConfiável , ignore a tela de consentimento de permissões detalhadas. Para esses aplicativos, os usuários não verão a tela de consentimento com permissões detalhadas. Em vez disso, seu aplicativo receberá todos os escopos solicitados ou nenhum.
Para obter informações mais detalhadas, consulte Como lidar com permissões granulares.
Para verificar se o usuário concedeu acesso ao seu aplicativo a um escopo específico, examine o campo scope na resposta do token de acesso. Os escopos de acesso concedidos pelo access_token, expressos como uma lista de strings separadas por espaços e que diferenciam maiúsculas de minúsculas.
Por exemplo, a seguinte resposta de token de acesso indica que o usuário concedeu ao seu aplicativo acesso somente leitura às permissões de atividade do Drive e eventos do Calendário:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Chamar APIs do Google
Depois que seu aplicativo obtiver um token de acesso, você poderá usá-lo para fazer chamadas a uma API do Google em nome de uma determinada conta de usuário, desde que o(s) escopo(s) de acesso exigido(s) pela API tenham 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 de cabeçalho HTTP Authorization Bearer. Quando possível, o cabeçalho HTTP é preferível, pois as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca cliente para configurar suas chamadas às APIs do Google (por exemplo, quandoChamando a API do YouTube Analytics ).
A API YouTube Analytics não é compatível com o fluxo de conta de serviço. A API de Relatórios do YouTube oferece suporte apenas a contas de serviço para proprietários de conteúdo do YouTube que possuem e gerenciam vários canais, como gravadoras e estúdios de cinema.
Você pode testar todas as APIs do Google e conferir os escopos delas no OAuth 2.0 Playground.
Exemplos de HTTP GET
Um apelo ao
reports.query endpoint (a API do YouTube Analytics) usando oAuthorization: Bearer O cabeçalho HTTP pode ter a seguinte aparência. É necessário especificar seu próprio token de acesso:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Esta é uma chamada para a mesma API do usuário autenticado usando o parâmetro de string de consulta access_token:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Exemplos de curl
Você pode testar esses comandos com o aplicativo de linha de comando curl. Aqui está um exemplo que utiliza a opção de cabeçalho HTTP (preferencial):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Ou, alternativamente, a opção de parâmetro de string de consulta:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Atualizar um token de acesso
Os tokens de acesso expiram periodicamente e tornam-se credenciais inválidas para uma solicitação de API relacionada. É possível atualizar um token de acesso sem solicitar a permissão do usuário (inclusive quando ele não está presente) se você solicitou acesso off-line aos escopos associados ao token.
Para atualizar um token de acesso, seu aplicativo envia uma solicitação HTTPS POST para o servidor de autorização do Google (https://oauth2.googleapis.com/token) que inclui os seguintes parâmetros:
| Campos | |
|---|---|
client_id |
O ID do cliente obtido de API Console. |
client_secret |
Opcional
O segredo do cliente obtido de API Console.
O |
grant_type |
Comodefinido na especificação OAuth 2.0 , o valor deste campo deve ser definido comorefresh_token. |
refresh_token |
O token de atualização retornado da troca de código de autorização. |
O trecho 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& refresh_token=refresh_token& grant_type=refresh_token
Enquanto o usuário não revogar o acesso concedido ao aplicativo, o servidor de token vai retornar um objeto JSON que contém um novo token de acesso. O snippet a seguir mostra um exemplo de resposta:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
Há limites 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 em 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, e 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. Um usuário pode revogar o acesso acessando Configurações da conta. Consulte a seção Remover o acesso de sites ou apps do documento de suporte Sites e apps de terceiros com acesso à sua conta para mais informações.
Também é possível que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante quando um usuário cancela a inscrição, remove um aplicativo ou os recursos da API exigidos por um app mudaram significativamente. Em outras palavras, parte do processo de remoção pode incluir uma solicitação de API para garantir que as permissões concedidas anteriormente ao aplicativo sejam removidas.
Para revogar um token de forma programática, seu 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 de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, ele também será revogado.
Se a revogação for processada com sucesso, o código de status HTTP da resposta será
200. Em condições de erro, um código de status HTTP 400 é retornado junto
com um código de erro.
Métodos de redirecionamento de apps
Esquema de URI personalizado
Os esquemas de URI personalizados são uma forma de deep linking que utiliza um esquema definido pelo usuário para abrir seu aplicativo.
Alternativa ao uso de esquemas de URI personalizados em aplicativos do Chrome
Use a API Chrome Identity que envia a resposta do OAuth 2.0 diretamente para seu app, eliminando a necessidade de um URI de redirecionamento.
Endereço IP de loopback (macOS, Linux, computador Windows)
Para receber o código de autorização usando este URL, seu aplicativo deve estar em execução no servidor web local. Isso é possível em muitas plataformas, mas não em todas. No entanto, se a sua plataforma o suportar, este é o mecanismo recomendado para obter o código de autorização.
Quando seu aplicativo receber a resposta de autorização, para melhor usabilidade, ele deverá exibir uma página HTML que instrua o usuário a fechar o navegador e retornar ao aplicativo.
| Uso recomendado | Aplicativos para macOS, Linux e Windows (exceto para a Plataforma Universal do Windows). |
| Valores do formulário | Defina o tipo de aplicativo como Aplicativo de desktop. |
Copiar/colar manualmente (Obsoleto)
Proteja seus aplicativos
Verifique a propriedade do aplicativo no Chrome.
Você pode verificar a propriedade do seu aplicativo para reduzir o risco de falsificação de identidade.
Para concluir o processo de verificação, você deverá usar sua conta de desenvolvedor da Chrome Web Store. Os seguintes requisitos devem ser atendidos para que a verificação seja bem-sucedida:
- Você deve ter um item registrado no Painel do desenvolvedor da Chrome Web Store com o mesmo ID de item que o cliente OAuth da extensão do Chrome para o qual você está concluindo a verificação.
- Você precisa ser um editor do item na Chrome Web Store. Saiba mais sobre gerenciamento de acesso no Painel do Desenvolvedor da Chrome Web Store.
Na seção Verificar propriedade do aplicativo do cliente da extensão do Chrome, clique no botão Verificar propriedade para concluir o processo de verificação.
Nota: Aguarde alguns minutos antes de concluir o processo de verificação após 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, será exibida uma mensagem de erro.
Para corrigir uma falha na verificação, tente o seguinte:
- Certifique-se de que haja um item registrado no Painel do Desenvolvedor da Chrome Web Store com o mesmo ID do item que o cliente OAuth da extensão do Chrome para o qual você está concluindo a verificação.
- Certifique-se de ser um editor do aplicativo, ou seja, você deve ser o editor individual do aplicativo ou um membro do grupo de editores do aplicativo. Saiba mais sobre gerenciamento de acesso no Painel 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 do Desenvolvedor da Chrome Web Store. Saiba mais sobre como sincronizar sua lista de membros do publisher.
Verificação de aplicativo (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 Google OAuth 2.0 se originam de seus aplicativos autênticos. Isso ajuda a reduzir o risco de representação indevida de apps.
Ative a verificação de aplicativos para seu cliente iOS.
Os seguintes requisitos precisam ser atendidos para ativar o App Check no seu cliente iOS:- Você precisa especificar um ID de equipe para seu cliente iOS.
- Você não deve usar um caractere curinga no seu ID de pacote, pois ele pode ser resolvido para mais de um aplicativo. Isso significa que o ID do pacote não deve incluir o símbolo de asterisco (*).
Após ativar a Verificação de Aplicativos, você começará a ver as métricas relacionadas às solicitações OAuth do seu cliente na tela de edição do cliente OAuth. As solicitações de fontes não verificadas não serão bloqueadas até que você aplique o App Check. As informações na página de monitoramento de métricas podem ajudá-lo a determinar quando iniciar a aplicação das regras.
Ao ativar o App Check para seu app iOS, talvez você veja erros relacionados a esse recurso. Para corrigir esses erros, tente o seguinte:
- Verifique se o ID do pacote e o ID da equipe especificados são válidos.
- Verifique se você não está usando um caractere curinga para o ID do pacote.
Aplicar o App Check para seu cliente iOS
Ativar o App Check para seu app não bloqueia automaticamente solicitações não reconhecidas. Para aplicar essa proteção, acesse a visualização de edição do seu cliente iOS. Lá, você vai encontrar as métricas do App Check à direita da página, na seção Identidade do Google para iOS. As métricas incluem as seguintes informações:- Número de solicitações verificadas: solicitações com um token do App Check válido. Depois de ativar a aplicação do App Check, apenas as solicitações nessa categoria serão bem-sucedidas.
- Número de solicitações não verificadas: solicitações de cliente possivelmente desatualizadas: solicitações sem um token do App Check. Essas solicitações podem ser de uma versão mais antiga do app que não inclui uma implementação do App Check.
- Número de solicitações não verificadas: 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 forçar a verificação do aplicativo, clique no botão ENFORCE e confirme sua escolha. Assim que a aplicação das regras estiver ativa, todas as solicitações não verificadas do seu cliente serão rejeitadas.
Nota: depois de ativar a aplicação, pode demorar até 15 minutos para que as alterações entrem em vigor.
Desative a verificação de aplicativos para seu cliente iOS
Desativar a verificação de aplicativos impedirá que seu aplicativo pare de funcionar.fiscalização e permitirá todas as solicitações do seu cliente para os endpoints do Google OAuth 2.0, incluindo solicitações não verificadas.
Para desativar a verificação de aplicativos para seu cliente iOS, navegue até a tela de edição do cliente iOS, clique no botão DESATIVAR e confirme sua escolha.
Nota: após desativar a verificação de aplicativos, pode levar até 15 minutos para que as alterações entrem em vigor.
Desative a verificação de aplicativos para seu cliente iOS.
Desativar a verificação de aplicativos para seu aplicativo interromperá todo o monitoramento do App Check efiscalização. Considere unenforcing App Check em vez disso, para que você possa continuar monitorando as métricas do seu cliente.
Para desativar a verificação de aplicativos para seu cliente iOS, navegue até a visualização de edição do cliente iOS e desative o botão de alternância Proteja seu cliente OAuth contra abusos com a verificação de aplicativos do Firebase.
Nota: após desativar a verificação de aplicativos, pode levar até 15 minutos para que as alterações entrem em vigor.
Acesso baseado em tempo
O acesso baseado em tempo permite que um usuário conceda ao seu aplicativo acesso aos seus dados por um período limitado para concluir uma ação. O acesso baseado em tempo está disponível em alguns produtos do Google durante o processo de consentimento, aos usuários a opção de conceder acesso por um período limitado. Um exemplo é a API de Portabilidade de Dados que permite uma transferência única de dados.
Quando um usuário concede acesso temporário ao seu aplicativo, o token de atualização expira após o período especificado. Observe que os tokens de atualização podem ser invalidados mais cedo em circunstâncias específicas; veja estes casos para detalhes. O campo refresh_token_expires_in retornado na resposta de troca de código de autorização representa o tempo restante até que o token de atualização expire nesses casos.
Leitura adicional
A IETF Best Current Practice OAuth 2.0 for Native Apps estabelece muitas das melhores práticas documentadas aqui.
Implementar proteção entre contas
Uma medida adicional que você deve tomar para proteger as contas de seus usuários é implementar a Proteção entre Contas, utilizando o serviço de Proteção entre Contas do Google. Este serviço permite que você se inscreva para receber notificações de eventos de segurança, que fornecem informações ao seu aplicativo sobre alterações importantes na conta do usuário. Você poderá então usar as informações para tomar medidas dependendo de como decidir reagir aos acontecimentos.
Alguns exemplos dos tipos de eventos enviados ao seu aplicativo 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 proteção entre contas para obter mais informações sobre como implementar a proteção entre contas e para a lista completa de eventos disponíveis.