Este documento explica como as aplicações instaladas em dispositivos, como telemóveis, tablets e computadores, usam os endpoints OAuth 2.0 da Google para autorizar o acesso às APIs Google.
O OAuth 2.0 permite que os utilizadores partilhem dados específicos com uma aplicação, mantendo os respetivos nomes de utilizador, palavras-passe e outras informações privados. Por exemplo, uma aplicação pode usar o OAuth 2.0 para obter autorização dos utilizadores para armazenar ficheiros nos respetivos Google Drives.
As apps instaladas são distribuídas a dispositivos individuais e presume-se que estas apps não podem manter segredos. Podem aceder às APIs Google enquanto o utilizador está presente na app ou quando a app está a ser executada em segundo plano.
Este fluxo de autorização é semelhante ao usado para aplicações de servidor Web. A principal diferença é que as apps instaladas têm de abrir o navegador do sistema e fornecer um URI de redirecionamento local para processar as respostas do servidor de autorização da Google.
Bibliotecas e amostras
Para apps iOS, recomendamos que use a versão mais recente do SDK do iOS Iniciar sessão com o Google. O SDK processa a autorização do utilizador e é mais simples de implementar do que o protocolo de nível inferior descrito neste guia.
Para apps executadas em dispositivos que não suportam um navegador do sistema ou que têm capacidades de entrada limitadas, como TVs, consolas de jogos, câmaras ou impressoras, consulte o artigo OAuth 2.0 para TVs e dispositivos ou Início de sessão em TVs e dispositivos de entrada limitada.
Pré-requisitos
Ative APIs para o seu projeto
Qualquer aplicação que chame APIs Google tem de ativar essas APIs na Consola de APIs.
Para ativar uma API para o seu projeto:
- Abra a biblioteca de APIs na Google API Console.
- Se lhe for pedido, selecione um projeto ou crie um novo.
- A biblioteca de APIs apresenta todas as APIs disponíveis, agrupadas por família de produtos e popularidade. Se a API que quer ativar não estiver visível na lista, use a pesquisa para a encontrar ou clique em Ver tudo na família de produtos à qual pertence.
- Selecione a API que quer ativar e, de seguida, clique no botão Ativar.
- Se lhe for pedido, ative a faturação.
- Se lhe for pedido, leia e aceite os Termos de Utilização da API.
Crie credenciais de autorização
Qualquer aplicação que utilize o OAuth 2.0 para aceder às APIs Google tem de ter credenciais de autorização que identifiquem a aplicação no servidor OAuth 2.0 da Google. Os passos seguintes explicam como criar credenciais para o seu projeto. As suas aplicações podem, então, utilizar as credenciais para aceder às APIs que ativou para esse projeto.
- Aceda à página Clientes.
- Clique em Criar cliente.
- As secções seguintes descrevem os tipos de clientes suportados pelo servidor de autorização da Google. Escolha o tipo de cliente recomendado para a sua aplicação, atribua um nome ao cliente OAuth e defina os outros campos no formulário conforme adequado.
iOS
- Selecione o tipo de aplicação iOS.
- Introduza um nome para o cliente OAuth. Este nome é apresentado na página Clientes do seu projeto para identificar o cliente.
- Introduza o identificador do pacote da sua app. O ID do pacote é o valor da chave
CFBundleIdentifier
no ficheiro de recursos da lista de propriedades de informações da sua app (info.plist). O valor
é apresentado mais frequentemente no painel Geral ou no painel Assinatura e capacidades do
editor de projetos do Xcode. O ID do pacote também é apresentado na secção Informações gerais da página Informações da app para a app no site App Store Connect da Apple.
Confirme que está a usar o ID do pacote correto para a sua app, uma vez que não o pode alterar se estiver a usar a funcionalidade App Check.
- (Opcional)
Introduza o ID da App Store da sua app se esta estiver publicada 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 a app Apple App Store no seu dispositivo iOS ou iPadOS.
- Pesquise a sua app.
- Selecione o botão Partilhar (símbolo de quadrado e seta para cima).
- Selecione Copiar link.
- Cole o link num editor de texto. O ID da App Store é a parte final do URL.
Exemplo:
https://apps.apple.com/app/google/id284815942
- (Opcional)
Introduza o ID da equipa. Consulte a secção Localize o ID da equipa na documentação da conta de programador da Apple para mais informações.
Nota: o campo ID da equipa é obrigatório se estiver a ativar o App Check para o seu cliente. - (Opcional)
Ative o App Check para a sua app iOS. Quando ativa o App Check, o serviço App Attest da Apple é usado para verificar se os pedidos OAuth 2.0 originários do seu cliente OAuth são genuínos e provêm da sua app. Isto ajuda a reduzir o risco de roubo de identidade da app. Saiba como ativar o App Check para a sua app iOS.
- Clique em Criar.
UWP
- Selecione o tipo de aplicação Plataforma Universal do Windows.
- Introduza um nome para o cliente OAuth. Este nome é apresentado no seu projeto para identificar o cliente.
- Introduza o ID de 12 carateres da Microsoft Store da sua app. Pode encontrar este valor no Microsoft Partner Center na página Identidade da app na secção Gestão de apps.
- Clique em Criar.
Para apps UWP, o URI de redirecionamento é formado através do identificador de segurança do pacote (SID) exclusivo da sua aplicação. Pode encontrar o Package SID da sua app no ficheiro Package.appxmanifest no seu projeto do Visual Studio.
Quando cria o ID do cliente na Google Cloud Console, tem de especificar o URI de redirecionamento no seguinte formato, usando o valor em letras minúsculas do SID do pacote:
ms-app://YOUR_APP_PACKAGE_SID
Para apps UWP, o esquema de URI personalizado não pode ter mais de 39 carateres, conforme especificado na documentação da Microsoft.
Identifique âmbitos de acesso
Os âmbitos permitem que a sua aplicação solicite acesso apenas aos recursos de que necessita, ao mesmo tempo que permitem que os utilizadores controlem a quantidade de acesso que concedem à sua aplicação. Assim, pode existir uma relação inversa entre o número de âmbitos solicitados e a probabilidade de obter o consentimento do utilizador.
Antes de começar a implementar a autorização OAuth 2.0, recomendamos que identifique os âmbitos aos quais a sua app vai precisar de autorização para aceder.
O documento Âmbitos da API OAuth 2.0 contém uma lista completa dos âmbitos que pode usar para aceder às APIs Google.
Obter chaves de acesso OAuth 2.0
Os passos seguintes mostram como a sua aplicação interage com o servidor OAuth 2.0 da Google para obter o consentimento de um utilizador para realizar um pedido de API em nome do utilizador. A sua aplicação tem de ter esse consentimento antes de poder executar um pedido de API Google que exija a autorização do utilizador.
Passo 1: gere um verificador de código e um desafio
A Google suporta o protocolo Proof Key for Code Exchange (PKCE) para tornar o fluxo de apps instaladas mais seguro. É criado um verificador de código exclusivo para cada pedido de autorização, e o respetivo valor transformado, denominado "code_challenge", é enviado para o servidor de autorização para obter o código de autorização.
Crie o verificador de código
Um code_verifier é uma string aleatória criptográfica de alta entropia que usa os carateres não reservados [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", com um comprimento mínimo de 43 carateres e um comprimento máximo de 128 carateres.
O verificador de código deve ter entropia suficiente para tornar impraticável adivinhar o valor.
Crie o desafio de código
São suportados dois métodos de criação do desafio de código.
| Métodos de geração de desafios de código | |
|---|---|
| S256 (recomendado) | O desafio de código é o hash SHA256 codificado em Base64URL (sem preenchimento) do verificador de código.
|
| simples | O desafio do código é o mesmo valor que o verificador do código gerado acima.
|
Passo 2: envie um pedido para o servidor OAuth 2.0 da Google
Para obter a autorização do utilizador, envie um pedido para o servidor de autorização da Google em
https://accounts.google.com/o/oauth2/v2/auth. Este ponto final processa a procura de sessões ativas,
autentica o utilizador e obtém o consentimento do utilizador. O ponto final só é acessível através de SSL e
recusa ligações HTTP (não SSL).
O servidor de autorização suporta os seguintes parâmetros da string de consulta para aplicações instaladas:
| Parâmetros | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente da sua aplicação. Pode encontrar este valor na Cloud Console página Clientes. |
||||||
redirect_uri |
Obrigatório
Determina como o servidor de autorização da Google envia uma resposta à sua app. Existem várias opções de redirecionamento disponíveis para apps instaladas, e terá configurado as suas credenciais de autorização com um método de redirecionamento específico em mente. O valor tem de corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que configurou na página Clientes da Cloud Console do cliente. Se este valor não corresponder a um URI autorizado, recebe um erro A tabela mostra o valor do parâmetro
|
||||||
response_type |
Obrigatório
Determina se o ponto final do Google OAuth 2.0 devolve um código de autorização. Defina o valor do parâmetro como |
||||||
scope |
Obrigatório
Uma lista delimitada por espaços de âmbitos que identificam os recursos aos quais a sua aplicação pode aceder em nome do utilizador. Estes valores informam o ecrã de consentimento que a Google apresenta ao utilizador. Os âmbitos permitem que a sua aplicação peça acesso apenas aos recursos de que precisa, ao mesmo tempo que permitem aos utilizadores controlar a quantidade de acesso que concedem à sua aplicação. Assim, existe uma relação inversa entre o número de âmbitos pedidos e a probabilidade de obter o consentimento do utilizador. |
||||||
code_challenge |
Recomendado
Especifica um |
||||||
code_challenge_method |
Recomendado
Especifica o método usado para codificar um |
||||||
state |
Recomendado
Especifica qualquer valor de string que a sua aplicação use para manter o estado entre o seu pedido de autorização e a resposta do servidor de autorização.
O servidor devolve o valor exato que envia como um par Pode usar este parâmetro para vários fins, como direcionar o utilizador para o recurso correto na sua aplicação, enviar números únicos e mitigar a falsificação de pedidos entre sites. Uma vez que o seu |
||||||
login_hint |
Opcional
Se a sua aplicação souber que utilizador está a tentar autenticar, pode usar este parâmetro para fornecer uma sugestão ao servidor de autenticação Google. O servidor usa a sugestão para simplificar o fluxo de início de sessão, preenchendo previamente o campo de email no formulário de início de sessão ou selecionando a sessão de início de sessão múltiplo adequada. Defina o valor do parâmetro para um endereço de email ou um identificador |
||||||
Exemplos de URLs de autorização
Os separadores abaixo mostram exemplos de URLs de autorização para as diferentes opções de URI de redirecionamento.
Os URLs são idênticos, exceto no que diz respeito ao 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 URI personalizado
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Endereço IP de loopback
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Passo 3: a Google pede o consentimento ao utilizador
Neste passo, o utilizador decide se concede à sua aplicação o acesso pedido. Nesta fase, a Google apresenta uma janela de consentimento que mostra o nome da sua aplicação e os serviços da API Google aos quais está a pedir autorização de acesso com as credenciais de autorização do utilizador e um resumo dos âmbitos de acesso a conceder. O utilizador pode, então, consentir em conceder acesso a um ou mais âmbitos pedidos pela sua aplicação ou recusar o pedido.
A sua aplicação não tem de fazer nada nesta fase, pois aguarda a resposta do servidor OAuth 2.0 da Google a indicar se foi concedido acesso. Essa resposta é explicada no passo seguinte.
Erros
Os pedidos ao ponto final de autorização do OAuth 2.0 da Google podem apresentar mensagens de erro orientadas para o utilizador 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 Google não consegue autorizar um ou mais âmbitos pedidos devido às políticas do respetivo administrador do Google Workspace. Consulte o artigo de ajuda do administrador do Google Workspace Controle as apps internas e de terceiros que podem aceder aos dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os âmbitos ou âmbitos confidenciais e restritos até que o acesso seja explicitamente concedido ao seu ID do cliente OAuth.
disallowed_useragent
O ponto final de autorização é apresentado num agente do utilizador incorporado não permitido pelas Políticas de OAuth 2.0 da Google.
Os programadores de iOS e macOS podem encontrar este erro ao abrir pedidos de autorização em
WKWebView.
Em alternativa, os programadores devem usar bibliotecas iOS, como o
início de sessão Google para iOS ou o
AppAuth para iOS da OpenID Foundation.
Os programadores Web podem encontrar este erro quando uma app iOS ou macOS abre um link Web geral num agente do utilizador incorporado e um utilizador navega para o ponto final de autorização do OAuth 2.0 da Google a partir do seu site. Os programadores devem permitir que os links gerais sejam abertos no controlador de links predefinido do sistema operativo, que inclui controladores de Links universais ou a app de navegador predefinida. A biblioteca SFSafariViewController também é uma opção suportada.
org_internal
O ID de cliente OAuth no pedido faz parte de um projeto que limita o acesso a Contas Google numa organização do Google Cloud específica. Para mais informações acerca desta opção de configuração, consulte a secção Tipo de utilizador no artigo de ajuda Configurar o ecrã de consentimento de OAuth.
deleted_client
O cliente OAuth usado para fazer o pedido foi eliminado. A eliminação pode ocorrer manualmente ou automaticamente no caso de clientes não usados . Os clientes eliminados podem ser restaurados no prazo de 30 dias após a eliminação. Saiba mais .
invalid_grant
Se estiver a usar um
verificador de código e
um desafio, o parâmetro code_callenge é inválido ou está em falta. Certifique-se de que o parâmetro
code_challenge está definido corretamente.
Ao atualizar uma chave de acesso, a chave pode ter expirado ou sido invalidada. Autentique novamente o utilizador e peça o consentimento do utilizador para obter novos tokens. Se continuar a ver este erro, certifique-se de que a sua aplicação foi configurada corretamente e que está a usar os tokens e os parâmetros corretos no seu pedido. Caso contrário, a conta de utilizador pode ter sido eliminada ou desativada.
redirect_uri_mismatch
O redirect_uri transmitido no pedido de autorização não corresponde a um URI de redirecionamento autorizado para o ID do cliente OAuth. Reveja os URIs de redirecionamento autorizados na
página Clientes da Google Cloud Console.
O redirect_uri transmitido pode ser inválido para o tipo de cliente.
O parâmetro redirect_uri pode referir-se ao fluxo OAuth fora da banda (OOB) que foi descontinuado e já não é suportado. Consulte o guia de migração para atualizar a sua integração.
invalid_request
Algo correu mal com o pedido que fez. Isto pode dever-se a vários motivos:
- O pedido não foi formatado corretamente
- O pedido não tinha os parâmetros obrigatórios
- O pedido usa um método de autorização que a Google não suporta. Valide se a sua integração do OAuth usa um método de integração recomendado
- Foi usado um esquema personalizado não suportado para o URI de redirecionamento. Se vir a mensagem de erro O esquema de URI personalizado não é suportado em apps Android nem do Chrome, saiba mais sobre as alternativas ao esquema de URI personalizado.
Passo 4: processe a resposta do servidor OAuth 2.0
A forma como a sua aplicação recebe a resposta de autorização depende do
esquema de URI de redirecionamento que usa. Independentemente do esquema, a resposta contém um código de autorização (code) ou um erro (error). Por exemplo, error=access_denied indica que o utilizador recusou o pedido.
Se o utilizador conceder acesso à sua aplicação, pode trocar o código de autorização por uma chave de acesso e um símbolo de atualização, conforme descrito no passo seguinte.
Passo 5: troque o código de autorização por tokens de atualização e de acesso
Para trocar um código de autorização por um token de acesso, chame o ponto final https://oauth2.googleapis.com/token e defina os seguintes parâmetros:
| Campos | |
|---|---|
client_id |
O ID de cliente obtido na Cloud Console página Clientes. |
client_secret |
Opcional
O segredo do cliente obtido na página Clientes da Cloud Console. |
code |
O código de autorização devolvido pelo pedido inicial. |
code_verifier |
O verificador de código que criou no Passo 1. |
grant_type |
Conforme definido na especificação OAuth 2.0, o valor deste campo tem de ser definido como authorization_code. |
redirect_uri |
Um dos URIs de redirecionamento indicados para o seu projeto na
Cloud Console
página Clientes para o dado
client_id. |
Embora a utilização do DPoP seja opcional, é recomendada para aumentar a segurança. A segurança do DPoP baseia-se na restrição da chave privada a um único dispositivo. Recomendamos que a armazene de forma que não possa ser copiada para fora do dispositivo, por exemplo, através de TPMs, enclaves seguros ou outros keystores suplementares em hardware. Para usar o DPoP, a sua aplicação tem de gerar um JWT de prova DPoP novo e exclusivo para cada pedido ao ponto final do token e adicioná-lo como um cabeçalho do pedido HTTP.
| Cabeçalho | Obrigatória | Descrição |
|---|---|---|
DPoP |
Opcional | Uma prova DPoP é um JWT que prova a posse de uma chave privada. Este é um cabeçalho e não um parâmetro. Se forem fornecidos, os tokens devolvidos
estão associados a esta chave. Tem de ser gerada uma nova prova única para cada pedido e
tem de incluir reivindicações htm (método HTTP) e htu (URI HTTP) que
correspondam ao pedido. |
O fragmento seguinte mostra um pedido de exemplo:
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
Construa uma prova DPoP
Os passos seguintes mostram como criar uma prova DPoP através do OpenSSL a partir da linha de comandos:
- 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 tem de incluir as reivindicaçõ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 a carga útil DPoP:
A carga útil tem de incluir
jti(um identificador exclusivo para o pedido),htm(método HTTP, por exemplo,POST),htu(URI HTTP, por exemplo,https://oauth2.googleapis.com/token) eiat(hora de emissão). Se recebeu um nonce do servidor num cabeçalhoDPoP-Noncena resposta a um pedido anterior, tem de incluir esse valor de nonce numa reivindicaçãononce. A reivindicação nonce é opcional para trocas de códigos 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ódigos de autorização, o
jtitem de ser o hash SHA256 codificado em Base64Url do código de autorização:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Para trocas de tokens de atualização, o
jtitem de ser um identificador exclusivo por pedido:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- Para trocas de códigos de autorização, o
- Assine o comprovativo:
Concatene o cabeçalho e a carga útil codificados com um ponto (
.) e, em seguida, assine o resultado com a sua chave privada através do ES256. Tenha em atenção que o JWS requer que a assinatura esteja num formatoR | Sconcatenado não processado (64 bytes para P-256). Se usar o OpenSSL diretamente, tem de converter a assinatura predefinida com codificação DER ASN.1 para este formato não processado.
Uma troca bem-sucedida é indicada por uma resposta 200 OK
que contém os tokens. Se for usada uma prova de DPoP válida durante a troca, o token de atualização devolvido pela Google vai estar associado ao DPoP da sua chave, mas os tokens de acesso não vão estar associados ao DPoP. As chaves de acesso vão reter o token_type de
Bearer em vez de DPoP.
Além disso, o Google devolve um cabeçalho HTTP DPoP-Nonce na resposta.
O seu cliente tem de colocar em cache este nonce e incluí-lo na reivindicação nonce da prova DPoP
em pedidos subsequentes (como quando troca um token de atualização por um novo token de acesso ou quando
chama APIs protegidas por DPoP). Ao usar este nonce emitido antecipadamente, pode evitar uma falha de ida e volta adicional (use_dpop_nonce) no seu próximo pedido.
As provas de DPoP têm de ser incluídas para pedidos de troca de tokens feitos com tokens de atualização associados ao DPoP.
Uma troca falhada ocorre se o cabeçalho DPoP estiver em falta quando esperado, for inválido ou se a prova usar uma chave diferente da
associada ao token. Nestes casos, o servidor devolve um erro 400 Bad Request.
Se a prova DPoP tiver reivindicações htm ou htu em conflito, um iat expirado, um jti reutilizado ou uma assinatura inválida, a Google devolve um código de erro invalid_dpop_proof.
Se for necessário um nonce DPoP, como durante uma troca de tokens de atualização, e a prova DPoP não tiver uma reivindicação nonce, ou o valor nonce for inaceitável para o servidor (por exemplo, tiver expirado, já tiver sido usado ou estiver incorreto), a Google devolve um código de erro use_dpop_nonce juntamente com um cabeçalho HTTP DPoP-Nonce que contém um novo nonce que pode usar numa solicitação subsequente.
Outras falhas podem devolver invalid_grant.
A Google responde a este pedido devolvendo um objeto JSON que contém uma chave de acesso de curta duração e um símbolo de atualização.
A resposta contém os seguintes campos:
| Campos | |
|---|---|
access_token |
O token que a sua aplicação envia para autorizar um pedido de API Google. |
expires_in |
O tempo de vida restante do token de acesso em segundos. |
id_token |
Nota: esta propriedade só é devolvida se o seu pedido incluir um âmbito de identidade,
como openid, profile ou email. O valor é um
símbolo da Web JSON (JWT) que contém informações de identidade com assinatura digital sobre o
utilizador. |
refresh_token |
Um token que pode usar para obter um novo token de acesso. As chaves de atualização são válidas até o utilizador revogar o acesso ou a chave de atualização expirar. Se foi usado o DPoP, o token de atualização está associado à chave privada usada para assinar a prova DPoP. Tenha em atenção que os tokens de atualização são sempre devolvidos para aplicações instaladas. |
refresh_token_expires_in |
O tempo de vida restante do token de atualização em segundos. Este valor só é definido quando o utilizador concede acesso com base no tempo. |
scope |
Os âmbitos de acesso concedidos pelo access_token expressos como uma lista de
strings delimitadas por espaços e sensíveis a maiúsculas e minúsculas. |
token_type |
O tipo de token devolvido. Este valor é sempre Bearer, mesmo quando é usado o DPoP. |
O fragmento seguinte mostra um exemplo de cabeçalhos e corpo de resposta 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Passo 6: verifique os âmbitos que os utilizadores concederam
Quando pede várias autorizações (âmbitos), os utilizadores podem não conceder à sua app acesso a todas elas. A sua app tem de verificar que âmbitos foram efetivamente concedidos e processar corretamente as situações em que algumas autorizações são recusadas, normalmente desativando as funcionalidades que dependem desses âmbitos recusados.
No entanto, existem exceções. As apps do Google Workspace Enterprise com delegação de autoridade ao nível do domínio, ou apps marcadas como Fidedignas, ignoram o ecrã de consentimento de autorizações detalhadas. Para estas apps, os utilizadores não veem o ecrã de consentimento de autorizações detalhadas. Em alternativa, a sua app recebe todos os âmbitos pedidos ou nenhum.
Para informações mais detalhadas, consulte o artigo Como processar autorizações detalhadas.
Para verificar se o utilizador concedeu à sua aplicação acesso a um âmbito específico,
examine o campo scope na resposta do token de acesso. Os âmbitos de acesso concedidos pelo access_token expressos como uma lista de strings sensíveis a maiúsculas e minúsculas delimitadas por espaços.
Por exemplo, a seguinte resposta de token de acesso de exemplo indica que o utilizador concedeu à sua aplicação acesso às autorizações de atividade do Drive e eventos do Calendário só de leitura:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Chame as APIs Google
Depois de a sua aplicação obter um token de acesso, pode usar o token para fazer chamadas a uma API Google em nome de uma determinada conta de utilizador se os âmbitos de acesso exigidos pela API tiverem sido concedidos. Para tal, inclua a chave de acesso num pedido à 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 ser visíveis nos registos do servidor. Na maioria dos casos, pode usar uma biblioteca cliente para configurar as suas chamadas para as APIs Google (por exemplo, quando chama a API Google Drive Files).
Pode experimentar todas as APIs Google e ver os respetivos âmbitos no OAuth 2.0 Playground.
Exemplos de HTTP GET
Uma chamada para o ponto final
drive.files (a API Google Drive Files) com o cabeçalho HTTP Authorization: Bearer
pode ter o seguinte aspeto. Tenha em atenção que tem de especificar a sua própria chave de acesso:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Segue-se uma chamada à mesma API para o utilizador autenticado através do parâmetro de string de consulta access_token:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl exemplos
Pode testar estes comandos com a aplicação de linha de comandos curl. Segue-se um exemplo que usa a opção de cabeçalho HTTP (preferencial):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Em alternativa, a opção de parâmetro de string de consulta:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Atualize uma chave de acesso
Os tokens de acesso expiram periodicamente e tornam-se credenciais inválidas para um pedido de API relacionado. Pode atualizar uma chave de acesso sem pedir autorização ao utilizador (inclusive quando o utilizador não está presente) se tiver pedido acesso offline aos âmbitos associados à chave.
Para atualizar um token de acesso, a sua aplicação envia um pedido HTTPS POST
para o servidor de autorização da Google (https://oauth2.googleapis.com/token) que
inclui os seguintes parâmetros no corpo do pedido:
| Nome | Valor |
|---|---|
client_id |
O ID de cliente obtido na API Console. |
client_secret |
Opcional
O segredo do cliente obtido na API Console.
(O |
grant_type |
Conforme
definido na
especificação OAuth 2.0,
o valor deste campo tem de ser definido como refresh_token. |
refresh_token |
O token de atualização devolvido pela troca do código de autorização. |
Embora a utilização do DPoP seja opcional, é recomendada para maior segurança. Para usar o DPoP com um token de atualização, a sua aplicação tem de gerar um JWT de prova do DPoP novo e exclusivo para cada pedido ao ponto final do token. Esta prova tem de ser assinada com a mesma chave privada que foi usada durante a troca inicial do código de autorização. A sua aplicação adiciona a prova como um cabeçalho de pedido HTTP.
| Cabeçalho | Obrigatória | Descrição |
|---|---|---|
DPoP |
Opcional | Uma prova DPoP é um JWT que prova a posse de uma chave privada. Este é um cabeçalho e não um parâmetro. Se forem fornecidos, os tokens devolvidos
estão associados a esta chave. Tem de ser gerada uma nova prova única para cada pedido e
tem de incluir reivindicações htm (método HTTP) e htu (URI HTTP) que
correspondam ao pedido. |
O fragmento seguinte mostra um pedido de exemplo:
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, tem de gerar um novo JWT de prova DPoP exclusivo para o pedido. Consulte o artigo Crie uma prova DPoP para obter instruções passo a passo 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 DPoP para o token de atualização foi aceite. A Google também pode devolver um novo cabeçalho HTTP DPoP-Nonce na resposta. Se for devolvido, o seu cliente tem de colocar este nonce em cache e incluí-lo na reivindicação nonce da prova DPoP em pedidos subsequentes.
Uma troca falhada ocorre se o cabeçalho DPoP estiver em falta, for inválido ou usar uma chave incorreta. Para ver detalhes sobre códigos de erro DPoP específicos e processamento de números aleatórios, consulte o artigo Falha na troca.
O fragmento seguinte mostra um exemplo de cabeçalhos e corpo de resposta 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"
}Tenha em atenção que existem limites para o número de tokens de atualização que são emitidos: um limite por combinação de cliente/utilizador e outro por utilizador em todos os clientes. Deve guardar os tokens de atualização no armazenamento a longo prazo e continuar a usá-los enquanto permanecerem válidos. Se a sua aplicação pedir demasiados tokens de atualização, pode atingir estes limites, caso em que os tokens de atualização mais antigos deixam de funcionar.
Revogação de tokens
Em alguns casos, um utilizador pode querer revogar o acesso concedido a uma aplicação. Um utilizador pode revogar o acesso acedendo às Definições da conta. Consulte a secção Remover o acesso de sites ou apps do documento de apoio técnico Sites e apps de terceiros com acesso à sua conta para mais informações.
Também é possível que uma aplicação revogue programaticamente o acesso que lhe foi concedido. A revogação programática é importante em instâncias em que um utilizador anula a subscrição, remove uma aplicação ou os recursos da API exigidos por uma app foram significativamente alterados. Por outras palavras, parte do processo de remoção pode incluir um pedido de API para garantir que as autorizações concedidas anteriormente à aplicação são removidas.
Para revogar um token de forma programática, a sua aplicação faz um pedido a
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 um token de acesso e tiver um token de atualização correspondente, o token de atualização também é revogado.
Se a revogação for processada com êxito, o código de estado HTTP da resposta é
200. Para condições de erro, é devolvido um código de estado HTTP 400 juntamente com um código de erro.
Métodos de redirecionamento de apps
Esquema URI personalizado
Os esquemas de URI personalizados são uma forma de links diretos que usam um esquema definido personalizado para abrir a sua app.
Alternativa à utilização de esquemas de URI personalizados em apps Chrome
Use a API Chrome Identity que envia a resposta OAuth 2.0 diretamente para a sua app, eliminando a necessidade de um URI de redirecionamento.
Endereço IP loopback (macOS, Linux e computador Windows)
Para receber o código de autorização através deste URL, a sua aplicação tem de estar a ouvir no servidor Web local. Isto é possível em muitas, mas não em todas as plataformas. No entanto, se a sua plataforma o suportar, este é o mecanismo recomendado para obter o código de autorização.
Quando a sua app recebe a resposta de autorização, para uma melhor usabilidade, deve responder apresentando uma página HTML que instrui o utilizador a fechar o navegador e voltar à sua app.
| Utilização recomendada | Apps para computador macOS, Linux e Windows (mas não da Plataforma Universal do Windows) |
| Valores de formulário | Defina o tipo de aplicação como App para computador. |
Copiar/colar manual (descontinuado)
Proteja as suas apps
Valide a propriedade da app para o Chrome
Pode validar a propriedade da sua aplicação para reduzir o risco de roubo de identidade da app.
Para concluir o processo de validação, tem de usar a sua conta de programador da Web Store do Chrome. Tem de cumprir os seguintes requisitos para uma validação bem-sucedida:
- Tem de ter um item registado no Painel de controlo do programador da Web Store do Chrome com o mesmo ID do item que o cliente OAuth da extensão do Chrome para o qual está a concluir a validação.
- Tem de ser um publicador do item da Web Store do Chrome. Saiba mais acerca da gestão de acesso no Painel de controlo do programador da Web Store do Chrome.
Na secção Validar propriedade da app do cliente da extensão do Chrome, clique no botão Validar propriedade para concluir o processo de validação.
Nota: aguarde alguns minutos antes de concluir o processo de validação depois de conceder acesso à sua conta.
Se a validação for bem-sucedida, é apresentada uma notificação a confirmar o êxito do processo de validação. Caso contrário, é apresentada uma mensagem de erro.
Para corrigir uma validação com falha, experimente o seguinte:
- Certifique-se de que existe um item registado no Painel de controlo do programador da Web Store do Chrome com o mesmo ID do item que o cliente OAuth da extensão do Chrome para o qual está a concluir a validação.
- Certifique-se de que é um publicador da app, ou seja, tem de ser o publicador individual da app ou um membro do publicador de grupo da app. Saiba mais acerca da gestão de acesso no Painel de controlo do programador da Web Store do Chrome.
- Se acabou de atualizar a sua lista de publicadores do grupo, verifique se a lista de membros do grupo de publicadores está sincronizada no Painel de controlo do programador da Web Store do Chrome. Saiba mais sobre a sincronização da lista de membros do publicador.
App Check (apenas no iOS)
A funcionalidade App Check ajuda a proteger as suas aplicações iOS contra a utilização não autorizada através do serviço App Attest da Apple para verificar se os pedidos feitos aos pontos finais do Google OAuth 2.0 são provenientes das suas aplicações autênticas. Isto ajuda a reduzir o risco de roubo de identidade da app.
Ative o App Check para o seu cliente iOS
Têm de ser cumpridos os seguintes requisitos para ativar com êxito a verificação de apps para o seu cliente iOS:- Tem de especificar um ID de equipa para o seu cliente iOS.
- Não pode usar um caráter universal no ID do pacote, uma vez que pode ser resolvido para mais do que uma app. Isto significa que o ID do pacote não pode incluir o símbolo de asterisco (*).
Depois de ativar o App Check, começa a ver métricas relacionadas com pedidos OAuth do seu cliente na vista de edição do cliente OAuth. Os pedidos de origens não validadas não são bloqueados até aplicar a verificação de apps. As informações na página de monitorização de métricas podem ajudar a determinar quando iniciar a aplicação.
Pode ver erros relacionados com a funcionalidade App Check quando ativa o App Check para a sua app iOS. Para corrigir estes erros, experimente o seguinte:
- Verifique se o ID do pacote e o ID da equipa que especificou são válidos.
- Verifique se não está a usar um caráter universal para o ID do pacote.
Aplique a verificação de apps para o seu cliente iOS
A ativação do App Check para a sua app não bloqueia automaticamente os pedidos não reconhecidos. Para aplicar esta proteção, aceda à vista de edição do seu cliente iOS. Aí, verá as métricas do App Check à direita da página na secção Google Identity para iOS. As métricas incluem as seguintes informações:- Número de pedidos validados: pedidos que têm um token do App Check válido. Depois de ativar a aplicação da verificação de apps, apenas os pedidos nesta categoria vão ser bem-sucedidos.
- Número de pedidos não validados: pedidos de clientes provavelmente desatualizados: pedidos em falta de um token do App Check. Estes pedidos podem ser de uma versão mais antiga da sua app que não inclui uma implementação do App Check.
- Número de pedidos não validados: pedidos de origem desconhecida: pedidos sem um token do App Check que não parecem ser provenientes da sua app.
- Número de pedidos não validados: pedidos inválidos: pedidos com um token do App Check inválido, que podem ser de um cliente não autêntico a tentar roubar a identidade da sua app ou de ambientes emulados.
Para aplicar a verificação de apps, clique no botão ENFORCE e confirme a sua escolha. Quando a aplicação estiver ativa, todos os pedidos não validados do seu cliente são rejeitados.
Nota: depois de ativar a aplicação, as alterações podem demorar até 15 minutos a entrar em vigor.
Desative a aplicação do App Check para o seu cliente iOS
A não aplicação da verificação de apps para a sua app vai parar a aplicação e permitir todos os pedidos do seu cliente aos pontos finais do Google OAuth 2.0, incluindo pedidos não validados.
Para anular a aplicação do App Check ao seu cliente iOS, navegue para a vista de edição do cliente iOS e clique no botão ANULAR A APLICAÇÃO e confirme a sua escolha.
Nota: depois de desativar a aplicação App Check, as alterações podem demorar até 15 minutos a entrar em vigor.
Desative o App Check para o seu cliente iOS
A desativação da verificação de apps para a sua app interrompe toda a monitorização e a aplicação da verificação de apps. Considere não aplicar a verificação de apps para poder continuar a monitorizar as métricas do seu cliente.
Para desativar o App Check para o seu cliente iOS, navegue para a vista de edição do cliente iOS e desative o botão Proteja o seu cliente OAuth contra abuso com o Firebase App Check.
Nota: depois de desativar o App Check, as alterações podem demorar até 15 minutos a entrar em vigor.
Acesso com base na hora
O acesso baseado no tempo permite que um utilizador conceda à sua app acesso aos respetivos dados durante um período limitado para concluir uma ação. O acesso baseado no tempo está disponível em determinados produtos Google durante o fluxo de consentimento, o que dá aos utilizadores a opção de conceder acesso por um período limitado. Um exemplo é a API Data Portability, que permite uma transferência única de dados.
Quando um utilizador concede à sua aplicação acesso baseado no tempo, o token de atualização expira após a duração especificada. Tenha em atenção que os tokens de atualização podem ser invalidados mais cedo em circunstâncias específicas. Consulte estes casos para ver detalhes. O campo refresh_token_expires_in devolvido na resposta de troca do código de autorização representa o tempo restante até o token de atualização expirar nesses casos.
Leitura complementar
A prática atual mais recomendada da IETF OAuth 2.0 para apps nativas estabelece muitas das práticas recomendadas documentadas aqui.
Implemente a Proteção entre contas
Um passo adicional que deve dar para proteger as contas dos seus utilizadores é implementar a proteção entre contas através da utilização do serviço de proteção entre contas da Google. Este serviço permite-lhe subscrever notificações de eventos de segurança que fornecem informações à sua aplicação sobre alterações importantes à conta de utilizador. Em seguida, pode usar as informações para tomar medidas consoante a forma como decide responder aos eventos.
Seguem-se alguns exemplos dos tipos de eventos enviados para a sua app pelo serviço de proteção em várias contas da Google:
-
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 Proteja as contas de utilizador com a proteção entre contas para mais informações sobre como implementar a proteção entre contas e a lista completa de eventos disponíveis.