Este documento explica como implementar a autorização OAuth 2.0 para acessar as APIs do Google em um aplicativo da Web JavaScript. O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo a privacidade de nomes de usuários, senhas e outras informações. Por exemplo, um aplicativo pode usar o OAuth 2.0 para receber permissão dos usuários para armazenar arquivos no Google Drive.
Esse fluxo do OAuth 2.0 é chamado de fluxo de concessão implícita. Ele foi projetado para aplicativos que acessam APIs somente enquanto o usuário está presente no aplicativo. Esses apps não podem armazenar informações confidenciais.
Nesse fluxo, o app abre um URL do Google que usa parâmetros de consulta para identificar o app e o tipo de acesso à API que ele exige. Você pode abrir o URL na janela do navegador atual ou em um pop-up. O usuário pode se autenticar com o Google e conceder as permissões solicitadas. Em seguida, o Google redireciona o usuário de volta ao seu app. O redirecionamento inclui um token de acesso, que o app verifica e usa para fazer solicitações de API.
Biblioteca de cliente das APIs do Google e Serviços de identidade do Google
Se você usa a biblioteca de cliente das APIs do Google para JavaScript para fazer chamadas autorizadas ao Google, use a biblioteca JavaScript do Google Identity Services para processar o fluxo do OAuth 2.0. Consulte o modelo de token dos serviços de identidade do Google, que é baseado no fluxo de concessão implícita do OAuth 2.0.
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.
- O API Library lista todas as APIs disponíveis, agrupadas por família de produtos e popularidade. Se a API que você quer ativar não estiver visível na lista, use a pesquisa para encontrá-la ou clique em Ver tudo na família de produtos a que ela pertence.
- Selecione aquela que você quer habilitar e clique no botão Ativar.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
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 Credentials page.
- Clique em Criar credenciais > ID do cliente OAuth.
- Selecione o tipo de aplicativo Aplicativo da Web.
- Preencha o formulário. Os aplicativos que usam JavaScript para fazer solicitações autorizadas da API do Google precisam especificar origens JavaScript autorizadas. As origens identificam os domínios de onde o aplicativo pode enviar solicitações para o servidor OAuth 2.0. Essas origens precisam obedecer às regras de validação do Google.
Identificar escopos de acesso
Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao seu aplicativo. Portanto, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário.
Antes de começar a implementar a autorização do OAuth 2.0, recomendamos identificar os escopos que o app vai precisar de permissão para acessar.
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 de um usuário e realizar uma solicitação de API em nome dele. Seu aplicativo precisa ter esse consentimento antes de executar uma solicitação da API Google que exija autorização do usuário.
Etapa 1: redirecionar para o servidor OAuth 2.0 do Google
Para solicitar permissão para acessar os dados de um usuário, redirecione-o ao servidor OAuth 2.0 do Google.
Endpoints OAuth 2.0
Gere um URL para solicitar acesso ao endpoint OAuth 2.0 do Google em
https://accounts.google.com/o/oauth2/v2/auth. Esse endpoint pode ser acessado por HTTPS.
Conexões HTTP simples são recusadas.
O servidor de autorização do Google oferece suporte aos seguintes parâmetros de string de consulta para aplicativos de servidor da Web:
| Parâmetros | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Obrigatório
O ID do cliente do seu aplicativo. Esse valor está no API Console Credentials page. |
||||||
redirect_uri |
Obrigatório
Determina para onde o servidor da API redireciona o usuário depois que ele conclui o
fluxo de autorização. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados do
cliente OAuth 2.0, que você configurou no
API Console
Credentials pagedo cliente. Se esse valor não corresponder a um
URI de redirecionamento autorizado para o O esquema, o caso e o caractere de barra inclinada final |
||||||
response_type |
Obrigatório
Os aplicativos JavaScript precisam definir o valor do parâmetro como |
||||||
scope |
Obrigatório
Uma lista de escopos delimitada por espaços que identifica os recursos que o aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google mostra ao usuário. Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de conseguir o consentimento do usuário. Recomendamos que o aplicativo solicite acesso aos escopos de autorização no contexto sempre que possível. Ao solicitar acesso aos dados do usuário no contexto, por meio da autorização incremental, você ajuda os usuários a entender melhor por que o app precisa do acesso que está sendo solicitado. |
||||||
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 valores de uso único e reduzir a falsificação de solicitações entre sites. Como a |
||||||
include_granted_scopes |
Opcional
Permite que os aplicativos usem a autorização incremental para solicitar acesso a outros
escopos no contexto. Se você definir o valor desse parâmetro como |
||||||
enable_granular_consent |
Opcional
O valor padrão é Quando o Google ativar permissões granulares para um app, esse parâmetro não vai mais ter efeito. |
||||||
login_hint |
Opcional
Se o aplicativo souber qual usuário está tentando fazer a autenticação, 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 adequada. Defina o valor do parâmetro como um endereço de e-mail ou identificador |
||||||
prompt |
Opcional
Uma lista de solicitações delimitada por espaço e que diferencia maiúsculas de minúsculas para apresentar ao usuário. Se você não especificar esse parâmetro, o usuário vai receber uma solicitação apenas na primeira vez que o projeto solicitar acesso. Consulte Como solicitar o novo consentimento para mais informações. Os valores possíveis são:
|
||||||
Exemplo de redirecionamento para o servidor de autorização do Google
Um exemplo de URL é mostrado abaixo, com quebras de linha e espaços para facilitar a leitura.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Depois de criar o URL da solicitação, redirecione o usuário para ele.
Exemplo de código JavaScript
O snippet de JavaScript a seguir mostra como iniciar o fluxo de autorização em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. Como esse endpoint OAuth 2.0 não oferece suporte ao compartilhamento de recursos entre origens (CORS, na sigla em inglês), o snippet cria um formulário que abre a solicitação para esse endpoint.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
Etapa 2: o Google solicita o consentimento do usuário
Nesta etapa, o usuário decide se concede ou não o acesso solicitado ao seu app. Nesse estágio, o Google exibe uma janela de consentimento que mostra o nome do seu aplicativo e os serviços da API do Google que ele está solicitando permissão para acessar com as credenciais de autorização do usuário e um resumo dos escopos de acesso a serem concedidos. O usuário pode consentir em conceder acesso a um ou mais escopos solicitados pelo aplicativo ou recusar a solicitação.
O aplicativo não precisa fazer nada nessa etapa, porque ele aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na etapa a seguir.
Erros
As solicitações para o endpoint de autorização OAuth 2.0 do Google podem mostrar mensagens de erro para o usuário em vez dos fluxos de autenticação e autorização esperados. Confira abaixo os códigos de erro comuns e as soluções sugeridas.
admin_policy_enforced
A Conta do Google não consegue 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 Controle quais apps internos e de terceiros acessam os dados do Google Workspace para saber mais sobre como um administrador pode restringir o acesso a todos os escopos ou escopos sensíveis e restritos até que o acesso seja concedido explicitamente ao seu ID de cliente OAuth.
disallowed_useragent
O endpoint de autorização é exibido dentro de um user-agent incorporado não permitido pelas Políticas do OAuth 2.0 do Google.
Android
Os desenvolvedores do Android podem encontrar essa mensagem de erro ao abrir solicitações de autorização no
android.webkit.WebView.
Em vez disso, os desenvolvedores precisam usar bibliotecas do Android, como
Login do Google para Android ou
AppAuth para Android da OpenID Foundation.
Os desenvolvedores da Web podem encontrar esse erro quando um app Android abre um link da Web geral em um user-agent incorporado e um usuário navega até 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, que inclui os gerenciadores Android App Links ou o app de navegador padrão. A biblioteca Android Custom Tabs também é uma opção compatível.
iOS
Os desenvolvedores de iOS e macOS podem encontrar esse erro ao abrir solicitações de autorização no
WKWebView.
Os desenvolvedores devem usar bibliotecas do iOS, como
Login do Google para iOS ou a
AppAuth para iOS da OpenID Foundation.
Os desenvolvedores da Web podem encontrar esse erro quando um app para iOS ou macOS abre um link da Web geral em
um agente do usuário incorporado e um usuário navega até 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, que inclui gerenciadores
Universal Links
ou o app de navegador padrão. A
biblioteca SFSafariViewController
também é uma opção aceita.
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 organização do Google Cloud específica. Para mais informações sobre essa opção de configuração, consulte a seção Tipo de usuário no artigo de ajuda "Como configurar a tela de consentimento OAuth".
invalid_client
A origem da solicitação não está autorizada para esse cliente. Consulte
origin_mismatch.
invalid_grant
Ao usar a autorização incremental, o token pode ter expirado ou sido invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se esse erro continuar a aparecer, verifique se o aplicativo foi configurado corretamente e se você está usando os tokens e parâmetros corretos na solicitação. Caso contrário, a conta de usuário pode ter sido excluída ou desativada.
origin_mismatch
O esquema, o domínio e/ou a porta do JavaScript que originou a solicitação de autorização podem não corresponder a um URI de origem do JavaScript autorizado registrado para o ID do cliente OAuth. Confira as origens autorizadas do JavaScript no Google API Console Credentials page.
redirect_uri_mismatch
O redirect_uri transmitido na solicitação de autorização não corresponde a um URI de redirecionamento
autorizado para o ID do cliente OAuth. Revise os URIs de redirecionamento autorizados no
Google API Console Credentials page.
O esquema, o domínio e/ou a porta do JavaScript que originou a solicitação de autorização podem não corresponder a um URI de origem do JavaScript autorizado registrado para o ID do cliente OAuth. Revise as origens JavaScript autorizadas no Google API Console Credentials page.
O parâmetro redirect_uri pode se referir ao fluxo fora de banda (OOB) do OAuth que foi
descontinuado e não tem mais suporte. Consulte o
guia de migração para atualizar sua
integração.
invalid_request
Algo deu errado com a solicitação que você fez. Isso pode acontecer por vários motivos:
- A solicitação não foi formatada corretamente
- A solicitação não tinha parâmetros obrigatórios
- A solicitação usa um método de autorização não aceito pelo Google. Verifique se a integração OAuth usa um método recomendado
Etapa 3: processar a resposta do servidor OAuth 2.0
Endpoints OAuth 2.0
O servidor OAuth 2.0 envia uma resposta para o redirect_uri especificado na sua solicitação de token de acesso.
Se o usuário aprovar a solicitação, a resposta conterá um token de acesso. Se o usuário não aprovar a solicitação, a resposta conterá uma mensagem de erro. O token de acesso ou a mensagem de erro é retornado no fragmento de hash do URI de redirecionamento, conforme mostrado abaixo:
Uma resposta de token de acesso:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Além do parâmetro
access_token, a string de fragmento também contém o parâmetrotoken_type, que é sempre definido comoBearer, e o parâmetroexpires_in, que especifica o ciclo de vida do token em segundos. Se o parâmetrostatefoi especificado na solicitação de token de acesso, o valor dele também será incluído na resposta.- Uma resposta de erro:
https://oauth2.example.com/callback#error=access_denied
Exemplo de resposta do servidor OAuth 2.0
Para testar esse fluxo, clique no seguinte URL de exemplo, que solicita acesso de leitura somente para visualizar metadados de arquivos no Google Drive e acesso de leitura somente para conferir seus eventos do Google Agenda:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Depois de concluir o fluxo do OAuth 2.0, você será redirecionado para
http://localhost/oauth2callback. Esse URL vai gerar um erro 404 NOT FOUND, a menos que sua máquina local forneça um arquivo nesse endereço. A próxima etapa fornece mais detalhes sobre as informações retornadas no URI quando o usuário é redirecionado de volta para o aplicativo.
Etapa 4: verificar quais escopos os usuários concederam
Ao solicitar vários escopos de uma só vez, os usuários podem não conceder todos os escopos solicitados pelo app. O app precisa sempre verificar quais escopos foram concedidos pelo usuário e processar qualquer negação de escopos desativando os recursos relevantes. Consulte Como gerenciar permissões granulares para mais informações.
Endpoints OAuth 2.0
Para verificar se o usuário concedeu ao seu app acesso 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 sensíveis a maiúsculas e minúsculas delimitadas por espaço.
Por exemplo, a resposta de token de acesso de exemplo a seguir indica que o usuário concedeu ao seu app acesso às permissões de eventos da Agenda e de atividade do Drive somente 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" }
Como chamar APIs do Google
Endpoints OAuth 2.0
Depois que o aplicativo receber um token de acesso, ele 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 fazer isso, inclua
o token de acesso em uma solicitação para a API incluindo um parâmetro de consulta
access_token ou um valor Bearer de cabeçalho HTTP Authorization. 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 suas chamadas para as APIs do Google. Por exemplo, ao
chamar a API Drive Files.
Teste todas as APIs do Google e confira os escopos delas no OAuth 2.0 Playground.
Exemplos de GET HTTP
Uma chamada para o endpoint
drive.files (a API Drive Files) usando o cabeçalho HTTP
Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:
GET /drive/v2/files 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/drive/v2/files?access_token=access_token
Exemplos de curl
É possível testar esses comandos com o aplicativo de linha de comando curl. Confira 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
Ou, como alternativa, a opção de parâmetro de string de consulta:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Exemplo de código JavaScript
O snippet de código abaixo demonstra como usar o CORS (compartilhamento de recursos entre origens) para enviar uma solicitação a uma API do Google. Este exemplo não usa a biblioteca de cliente de APIs do Google para JavaScript. No entanto, mesmo que você não esteja usando a biblioteca de cliente, o guia de suporte a CORS na documentação dessa biblioteca provavelmente vai ajudar você a entender melhor essas solicitações.
Neste snippet de código, a variável access_token representa o token que você
recebeu para fazer solicitações de API em nome do usuário autorizado. O exemplo
completo demonstra como armazenar esse token no armazenamento local do navegador e recuperá-lo
ao fazer uma solicitação de API.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Exemplo completo
Endpoints OAuth 2.0
Este exemplo de código demonstra como concluir o fluxo do OAuth 2.0 em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. O código é para uma página HTML que mostra um botão para testar uma solicitação de API. Se você clicar no botão, o código vai verificar se a página armazenou um token de acesso à API no armazenamento local do navegador. Se sim, ele executa a solicitação de API. Caso contrário, ele inicia o fluxo do OAuth 2.0.
Para o fluxo OAuth 2.0, a página segue estas etapas:
- Ele direciona o usuário ao servidor OAuth 2.0 do Google, que solicita acesso aos escopos
https://www.googleapis.com/auth/drive.metadata.readonlyehttps://www.googleapis.com/auth/calendar.readonly. - Depois de conceder (ou negar) acesso a um ou mais escopos solicitados, o usuário é redirecionado para a página original, que analisa o token de acesso da string de identificador de fragmento.
- A página verifica quais escopos o usuário concedeu acesso ao aplicativo.
Se o usuário tiver concedido acesso aos escopos() solicitados, a página vai usar o token de acesso para fazer a solicitação de API de exemplo.
A solicitação da API chama o método
about.getda API Drive para recuperar informações sobre a conta do Google Drive do usuário autorizado.- Se a solicitação for executada com sucesso, a resposta da API será registrada no console de depuração do navegador.
É possível revogar o acesso ao app na página Permissões da sua Conta do Google. O app será listado como Demonstração do OAuth 2.0 para a API Google Docs.
Para executar esse código localmente, defina valores para as variáveis YOUR_CLIENT_ID e
YOUR_REDIRECT_URI que correspondem às suas
credenciais de autorização. A variável YOUR_REDIRECT_URI
precisa ser definida como o mesmo URL em que a página está sendo veiculada. O valor precisa corresponder exatamente a um dos
URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no
API Console Credentials page. Se
esse valor não corresponder a um URI autorizado, você vai receber um erro
redirect_uri_mismatch. Seu projeto também precisa ter
ativado a API apropriada para essa solicitação.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
// User authorized the request. Now, check which scopes were granted.
if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
// User authorized read-only Drive activity permission.
// Calling the APIs, etc.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
}
else {
// User didn't authorize read-only Drive activity permission.
// Update UX and application accordingly
console.log('User did not authorize read-only Drive activity permission.');
}
// Check if user authorized Calendar read permission.
if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
// User authorized Calendar read permission.
// Calling the APIs, etc.
console.log('User authorized Calendar read permission.');
}
else {
// User didn't authorize Calendar read permission.
// Update UX and application accordingly
console.log('User did not authorize Calendar read permission.');
}
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
'state': state,
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>Regras de validação de origem do JavaScript
O Google aplica as seguintes regras de validação às origens do JavaScript para ajudar os desenvolvedores a manter os aplicativos seguros. As origens do JavaScript precisam obedecer a essas regras. Consulte a seção 3 do RFC 3986 para conferir a definição de domínio, host e esquema, mencionada abaixo.
| Regras de validação | |
|---|---|
| Esquema |
As origens do JavaScript precisam usar o esquema HTTPS, não o HTTP simples. Os URIs do host local (incluindo URIs de endereço IP do host local) estão isentos dessa regra. |
| Host |
Os hosts não podem ser endereços IP brutos. Os endereços IP do localhost estão isentos dessa regra. |
| Domínio |
“googleusercontent.com”.goo.gl),
a menos que o domínio seja do app. |
| Userinfo |
As origens do JavaScript não podem conter o subcomponente userinfo. |
| Caminho |
As origens do JavaScript não podem conter o componente de caminho. |
| Consulta |
As origens do JavaScript não podem conter o componente de consulta. |
| Fragmentos |
As origens do JavaScript não podem conter o componente de fragmento. |
| Personagens |
As origens do JavaScript não podem conter determinados caracteres, incluindo:
|
Autorização incremental
No protocolo OAuth 2.0, o app solicita autorização para acessar recursos, que são identificados por escopos. É considerada uma prática recomendada de experiência do usuário solicitar a autorização de recursos quando você precisar deles. Para permitir essa prática, o servidor de autorização do Google oferece suporte à autorização incremental. Esse recurso permite solicitar escopos conforme necessário e, se o usuário conceder permissão para o novo escopo, ele retornará um código de autorização que pode ser trocado por um token contendo todos os escopos que o usuário concedeu ao projeto.
Por exemplo, um app que permite que as pessoas samplem faixas de música e criem mixagens pode precisar de poucos recursos no momento do login, talvez nada além do nome da pessoa que está fazendo login. No entanto, salvar uma mixagem completa exige acesso ao Google Drive. A maioria das pessoas acharia natural se o acesso ao Google Drive fosse solicitado apenas quando o app realmente precisasse dele.
Nesse caso, no momento do login, o app pode solicitar os escopos openid e
profile para realizar o login básico e, mais tarde, solicitar o
escopo https://www.googleapis.com/auth/drive.file no momento da primeira solicitação para salvar uma
combinação.
As regras a seguir se aplicam a um token de acesso recebido de uma autorização incremental:
- O token pode ser usado para acessar recursos correspondentes a qualquer um dos escopos incluídos na nova autorização combinada.
- Quando você usa o token de atualização para a autorização combinada para conseguir um token de acesso, o token de acesso representa a autorização combinada e pode ser usado para qualquer um dos valores de
scopeincluídos na resposta. - A autorização combinada inclui todos os escopos que o usuário concedeu ao projeto da API, mesmo que as concessões tenham sido solicitadas por clientes diferentes. Por exemplo, se um usuário conceder acesso a um escopo usando o cliente para computador de um aplicativo e, em seguida, conceder outro escopo ao mesmo aplicativo por um cliente para dispositivos móveis, a autorização combinada vai incluir os dois escopos.
- Se você revogar um token que representa uma autorização combinada, o acesso a todos os escopos dessa autorização em nome do usuário associado será revogado simultaneamente.
Os exemplos de código abaixo mostram como adicionar escopos a um token de acesso. Essa abordagem permite que seu app evite gerenciar vários tokens de acesso.
Endpoints OAuth 2.0
Para adicionar escopos a um token de acesso existente, inclua o parâmetro include_granted_scopes
na solicitação para o servidor OAuth 2.0 do Google.
O snippet de código a seguir demonstra como fazer isso. O snippet pressupõe que você armazenou
os escopos para os quais seu token de acesso é válido no armazenamento local do navegador. O código do
exemplo completo armazena uma lista de escopos para os quais o token de acesso
é válido definindo a propriedade oauth2-test-params.scope no armazenamento local
do navegador.
O snippet compara os escopos para os quais o token de acesso é válido com o escopo que você quer usar
para uma consulta específica. Se o token de acesso não cobrir esse escopo, o fluxo do OAuth 2.0 será iniciado.
Aqui, a função oauth2SignIn é a mesma fornecida na
etapa 2 (e que será fornecida mais tarde no exemplo
completo).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
Revogar um token
Em alguns casos, o usuário pode querer revogar o acesso concedido a um app. Um usuário pode revogar o acesso acessando as Configurações da conta. Consulte a seção Remover acesso a sites ou apps do documento de suporte "Sites e apps de terceiros com acesso à sua conta" para mais informações.
Também é possível que um aplicativo revogue programaticamente 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.
Endpoints OAuth 2.0
Para revogar um token de forma programática, seu app 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, o código de status HTTP da resposta será
200. Para condições de erro, um código de status HTTP 400 é retornado com
um código de erro.
O snippet de JavaScript a seguir mostra como revogar um token em JavaScript sem usar a
biblioteca de cliente das APIs do Google para JavaScript. Como o endpoint OAuth 2.0 do Google para revogar
tokens não oferece suporte ao compartilhamento de recursos entre origens (CORS, na sigla em inglês), o código cria um formulário e o envia
para o endpoint em vez de usar o método XMLHttpRequest() para postar a
solicitação.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }
Como implementar a Proteção entre contas
Outra medida que você pode tomar 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 em notificações de eventos de segurança que fornecem informações ao seu app sobre mudanças importantes na conta do usuário. Em seguida, você pode usar as informações para tomar medidas dependendo de como você decide responder aos eventos.
Confira alguns exemplos de tipos de eventos enviados ao seu app pelo serviço de proteção entre contas do 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 Proteger contas de usuários 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.