A biblioteca JavaScript google.accounts.oauth2
ajuda a solicitar o consentimento
do usuário e a receber um token de acesso para trabalhar com os dados do usuário. Ela é baseada no fluxo de concessão implícita do OAuth 2.0 e foi projetada para permitir que você chame as APIs do Google diretamente usando REST e CORS ou use nossa biblioteca de cliente de APIs do Google para JavaScript (também conhecida como gapi.client
) e tenha acesso simples e flexível às nossas APIs mais complexas.
Antes de acessar dados protegidos do usuário em um navegador, os usuários do seu site acionam o seletor de conta, o login e os processos de consentimento do Google baseados na Web e, por último, os servidores OAuth do Google emitem e retornam um token de acesso para seu app da Web.
No modelo de autorização baseado em token, não é necessário armazenar tokens de atualização por usuário no servidor de back-end.
É recomendável seguir a abordagem descrita aqui, em vez das técnicas abordadas no antigo guia OAuth 2.0 para aplicativos da Web do lado do cliente.
Configuração
Encontre ou crie um ID do cliente seguindo as etapas descritas no guia Acessar o ID do cliente da API do Google. Em seguida, adicione a biblioteca de cliente às páginas do site que chamarão as APIs do Google. Por fim, inicialize o cliente do token. Normalmente, isso é feito no gerenciador onload
da biblioteca de cliente.
Inicializar um cliente de token
Chame initTokenClient()
para inicializar um novo cliente de token com o ID do cliente do seu app da Web. Se preferir, inclua uma lista de um ou mais escopos que o usuário precisa acessar:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
Acionar o fluxo de tokens do OAuth 2.0
Use o método requestAccessToken()
para acionar o fluxo de UX do token e receber um
token de acesso. O Google solicita que o usuário:
- Escolha a conta.
- fizer login na Conta do Google, caso ainda não tenha feito.
- dê consentimento para que seu app da Web acesse cada escopo solicitado.
Um gesto do usuário aciona o fluxo de tokens: <button onclick="client.requestAccessToken();">Authorize me</button>
Em seguida, o Google retorna um TokenResponse
contendo um token de acesso e uma lista de
escopos a que o usuário concedeu acesso ou um erro ao gerenciador de callbacks.
Os usuários podem fechar o seletor de conta ou as janelas de login. Nesse caso, sua função de callback não será invocada.
Como lidar com o consentimento
O design e a experiência do usuário do app só devem ser implementados após uma revisão completa das políticas do OAuth 2.0 do Google. Essas políticas abrangem o trabalho com vários escopos, quando e como lidar com o consentimento do usuário e muito mais.
A autorização incremental é uma metodologia de criação de políticas e apps usada para solicitar acesso a recursos usando escopos somente conforme necessário, e não antecipadamente e de uma só vez. Os usuários podem aprovar ou rejeitar o compartilhamento de recursos individuais solicitados pelo app. Isso é conhecido como permissões granulares.
Durante esse processo, o Google solicita o consentimento do usuário, listando individualmente cada escopo solicitado, os usuários selecionam os recursos a serem compartilhados com o app e, por fim, o Google invoca sua função de callback para retornar um token de acesso e escopos aprovados pelo usuário. Em seguida, o app processa com segurança os vários resultados diferentes possíveis com permissões granulares.
Autorização incremental
Nos apps da Web, os dois cenários de alto nível a seguir demonstram autorização incremental usando:
- Um app Ajax de uma única página, geralmente usando
XMLHttpRequest
com acesso dinâmico a recursos. - Ter várias páginas da Web, e os recursos são separados e gerenciados por página.
Esses dois cenários são apresentados para ilustrar considerações e metodologias de design, mas não são recomendações abrangentes sobre como criar o consentimento no app. Apps reais podem usar uma variação ou combinação dessas técnicas.
Ajax
Adicione suporte à autorização incremental ao app fazendo várias chamadas
para requestAccessToken()
e usando o parâmetro scope
do objeto OverridableTokenClientConfig
para solicitar escopos individuais no momento em que eles forem necessários e
somente quando necessário. Neste exemplo, os recursos serão solicitados e ficarão visíveis
somente depois que um gesto do usuário expandir uma seção de conteúdo recolhida.
Aplicativo Ajax |
---|
Inicialize o cliente do token no carregamento da página:
const client = google.accounts.oauth2.initTokenClient({ client_id: 'YOUR_GOOGLE_CLIENT_ID', callback: "onTokenResponse", });Solicite o consentimento e receba os tokens de acesso por meio de gestos do usuário. Clique em "+" para abrir: Documentos para lerMostrar documentos recentes client.requestAccessToken( overrideConfig = ({ scope = 'https://www.googleapis.com/auth/documents.readonly' }) ); Próximos eventosMostrar informações da agenda client.requestAccessToken( overrideConfig = ({ scope = 'https://www.googleapis.com/auth/calendar.readonly' }) ); Carrossel de fotosExibir fotos client.requestAccessToken( overrideConfig = ({ scope = 'https://www.googleapis.com/auth/photoslibrary.readonly' }) ); |
Cada chamada para requestAccessToken
aciona um momento de consentimento do usuário. Seu app terá
acesso apenas aos recursos exigidos pela seção que o usuário escolher
expandir, limitando o compartilhamento de recursos pela escolha do usuário.
Várias páginas da Web
Ao projetar para autorização incremental, várias páginas são usadas para solicitar apenas os escopos necessários para carregar uma página, reduzindo a complexidade e a necessidade de fazer várias chamadas para receber o consentimento do usuário e recuperar um token de acesso.
App com várias páginas | ||||||||
---|---|---|---|---|---|---|---|---|
|
Cada página solicita o escopo necessário e recebe um token de acesso chamando
initTokenClient()
e requestAccessToken()
no tempo de carregamento. Nesse cenário, páginas da Web individuais são usadas para separar claramente a funcionalidade e os recursos do usuário por escopo. Em uma situação real, páginas individuais podem solicitar
vários escopos relacionados.
Permissões granulares
As permissões granulares são tratadas da mesma maneira em todos os cenários. Depois que requestAccessToken()
invocar sua função de callback e um token de acesso for retornado, verifique se o usuário aprovou os escopos solicitados usando hasGrantedAllScopes()
ou hasGrantedAnyScope()
. Exemplo:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly \
https://www.googleapis.com/auth/documents.readonly \
https://www.googleapis.com/auth/photoslibrary.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
'https://www.googleapis.com/auth/photoslibrary.readonly')) {
// Look at pictures
...
}
if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
'https://www.googleapis.com/auth/calendar.readonly',
'https://www.googleapis.com/auth/documents.readonly')) {
// Meeting planning and review documents
...
}
}
},
});
Todas as concessões aceitas anteriormente de sessões ou solicitações anteriores também serão
incluídas na resposta. Um registro de consentimento do usuário é mantido por usuário e ID do cliente e persiste em várias chamadas para initTokenClient()
ou requestAccessToken()
. Por padrão, o consentimento do usuário só é necessário na primeira vez que ele acessa seu site e solicita um novo escopo, mas pode ser solicitado a cada carregamento de página usando prompt=consent
nos objetos de configuração do cliente de token.
Como trabalhar com tokens
No modelo de token, um token de acesso não é armazenado pelo SO nem pelo navegador. Em vez disso,
um novo token é recebido primeiro no tempo de carregamento da página ou, posteriormente, pelo acionamento de uma
chamada para requestAccessToken()
com um gesto do usuário, como o pressionamento de um botão.
Como usar REST e CORS com as APIs do Google
Um token de acesso pode ser usado para fazer solicitações autenticadas às APIs do Google usando REST e CORS. Isso permite que os usuários façam login, concedam consentimento, o Google emita um token de acesso e seu site funcione com os dados do usuário.
Neste exemplo, mostramos os próximos eventos da agenda dos usuários que fizeram login usando o
token de acesso retornado por tokenRequest()
:
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();
Consulte Como usar o CORS para acessar as APIs do Google para saber mais.
A próxima seção aborda como se integrar facilmente a APIs mais complexas.
Como trabalhar com a biblioteca JavaScript das APIs do Google
O cliente de token funciona com a biblioteca de cliente das APIs do Google para JavaScript. Consulte o snippet de código abaixo.
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
gapi.client.setApiKey('YOUR_API_KEY');
gapi.client.load('calendar', 'v3', listUpcomingEvents);
}
},
});
function listUpcomingEvents() {
gapi.client.calendar.events.list(...);
}
Expiração do token
Por padrão, os tokens de acesso têm um ciclo de vida curto. Se o token de acesso expirar
antes do fim da sessão do usuário, consiga um novo token chamando
requestAccessToken()
de um evento acionado pelo usuário, como o pressionamento de um botão.
Uso de um token de acesso para revogar o consentimento
Chame o método google.accounts.oauth2.revoke
para remover o consentimento do usuário e o acesso aos recursos de todos os escopos concedidos ao app. É necessário um token de acesso válido para revogar essa permissão:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});