Como usar o modelo de token

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.

        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );
        

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );
        

          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.

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
          

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

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);
  });