Usar o modelo de código

A biblioteca dos Serviços de identidade do Google permite que os usuários solicitem um código de autorização do Google usando um fluxo de UX de redirecionamento ou pop-up baseado em navegador. Isso inicia um fluxo seguro do OAuth 2.0 e resulta em um token de acesso usado para chamar APIs do Google em nome de um usuário.

Resumo do fluxo do código de autorização do OAuth 2.0:

• Em um navegador, com um gesto como um clique de botão, o proprietário da Conta do Google solicita um código de autorização do Google.
• O Google responde enviando um código de autorização exclusivo para um callback no app da Web JavaScript em execução no navegador do usuário ou invoca diretamente o endpoint do código de autorização usando um redirecionamento do navegador.
• Sua plataforma de back-end hospeda um endpoint de código de autorização e recebe o código. Após a validação, esse código é trocado por tokens de acesso e atualização por usuário usando uma solicitação ao endpoint de token do Google.
• O Google valida o código de autorização, confirma que a solicitação se originou da sua plataforma segura, emite tokens de acesso e de atualização e retorna os tokens chamando o endpoint de login hospedado pela sua plataforma.
• Seu endpoint de login recebe os tokens de acesso e de atualização, armazenando com segurança o token de atualização para uso posterior.

Ponto principal: no servidor de back-end, você troca um código de autorização por tokens de atualização e tokens de acesso chamando o endpoint de token do Google.

Pré-requisitos

Siga as etapas descritas em Configuração para configurar a tela de permissão OAuth, conseguir um ID do cliente e carregar a biblioteca de cliente.

Inicializar um cliente de código

O método google.accounts.oauth2.initCodeClient() inicializa um cliente de código.

Modo pop-up ou redirecionamento

É possível compartilhar um código de autorização usando o fluxo de usuário no modo Redirecionamento ou Pop-up. No modo de redirecionamento, você hospeda um endpoint de autorização OAuth2 no seu servidor, e o Google redireciona o user agent para esse endpoint, compartilhando o código de autenticação como um parâmetro de URL. No modo pop-up, você define um manipulador de callback JavaScript, que envia o código de autorização para seu servidor. O modo pop-up pode ser usado para oferecer uma experiência do usuário integrada sem que os visitantes precisem sair do seu site.

Para inicializar um cliente para:

• Redirecione o fluxo da UX, defina ux_mode como redirect e o valor de redirect_uri como o endpoint do código de autorização da sua plataforma. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0 configurado no console do Google Cloud. Ele também precisa estar de acordo com as regras de validação de URI de redirecionamento.

• Fluxo de UX do pop-up, defina ux_mode como popup e o valor de callback como o nome da função que você vai usar para enviar códigos de autorização à sua plataforma. O valor de redirect_uri é definido por padrão como a origem da página que chama initCodeClient. Esse valor é usado mais tarde no fluxo quando o código de autenticação é trocado por um token de acesso ou de atualização. Por exemplo, https://www.example.com/index.html chama initCodeClient e a origem: https://www.example.com é o valor de redirect_url.

Importante: para o melhor equilíbrio entre usabilidade e segurança, recomendamos usar o fluxo de UX do modo pop-up com o modelo de código de autorização.

Proteção contra ataques de CSRF

Para ajudar a evitar ataques de falsificação de solicitações entre sites (CSRF), técnicas ligeiramente diferentes são usadas nos fluxos de UX dos modos de redirecionamento e pop-up. No modo de redirecionamento, o parâmetro state do OAuth 2.0 é usado. Consulte a seção 10.12 da RFC6749 Cross-Site Request Forgery para mais informações sobre como gerar e validar o parâmetro state. No modo pop-up, você adiciona um cabeçalho HTTP personalizado às solicitações e, em seguida, confirma no servidor se ele corresponde ao valor e à origem esperados.

Escolha um modo de UX para ver um snippet de código que mostra o código de autorização e o processamento de CSRF:

Modo de redirecionamento

Inicialize um cliente em que o Google redireciona o navegador do usuário para seu endpoint de autenticação, compartilhando o código de autenticação como um parâmetro de URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Importante: um endpoint no servidor de back-end recebe e valida o código de autenticação, trocando-o por tokens de acesso e de atualização.

Modo pop-up

Inicialize um cliente em que o usuário inicia o fluxo de autorização em uma caixa de diálogo pop-up. Depois da autorização, o código é retornado pelo Google ao navegador do usuário usando uma função de callback. Uma solicitação POST do manipulador de callback JS entrega o código de autenticação a um endpoint no servidor de back-end, onde ele é primeiro verificado e depois o restante do fluxo OAuth é concluído.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Importante: um endpoint no servidor de back-end recebe e valida o código de autenticação, trocando-o por tokens de acesso e atualização.

Acionar o fluxo de código do OAuth 2.0

Chame o método requestCode() do cliente de código para acionar o fluxo do usuário:

<button onclick="client.requestCode();">Authorize with Google</button>

Isso vai exigir que o usuário faça login em uma Conta do Google e concorde em compartilhar escopos individuais antes de retornar um código de autorização para seu endpoint de redirecionamento ou seu manipulador de callback.

Processamento de código de autenticação

O Google gera um código de autorização exclusivo por usuário, que você recebe e verifica no servidor de back-end.

No modo pop-up, o manipulador especificado por callback, executado no navegador do usuário, retransmite o código de autorização para um endpoint hospedado pela sua plataforma.

No modo de redirecionamento, uma solicitação GET é enviada ao endpoint especificado por redirect_uri, compartilhando o código de autorização no parâmetro code do URL. Para receber o código de autorização:

• Crie um novo endpoint de autorização se você não tiver uma implementação ou

• Atualize seu endpoint atual para aceitar solicitações GET e parâmetros de URL. Antes, era usada uma solicitação PUT com o valor do código de autorização no payload.

Endpoint de autorização

O endpoint do código de autorização precisa processar solicitações GET com estes parâmetros de string de consulta de URL:

Nome	Valor
authuser	Solicitação de autenticação de login do usuário
código	Um código de autorização OAuth2 gerado pelo Google
hd	O domínio hospedado da conta de usuário
prompt	Caixa de diálogo de consentimento do usuário
escopo	Lista separada por espaços de um ou mais escopos do OAuth2 a serem autorizados
estado	Variável de estado do CRSF.

Exemplo de solicitação GET com parâmetros de URL para um endpoint chamado auth-code e hospedado por example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Quando o fluxo do código de autorização é iniciado por bibliotecas JavaScript anteriores ou por chamadas diretas aos endpoints do OAuth 2.0 do Google, uma solicitação POST é usada.

Exemplo de solicitação POST que contém o código de autorização como um payload no corpo da solicitação HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Importante: antes, POST era usado para solicitações. Atualize seu manipulador para aceitar solicitações GET e POST ou considere hospedar dois endpoints diferentes se você planeja continuar usando bibliotecas JS mais antigas ou chamar diretamente os endpoints do Google OAuth 2.0 ao usar a biblioteca dos Serviços de identidade do Google.

Validação do pedido

No servidor, faça o seguinte para evitar ataques de CSRF.

Verifique o valor do parâmetro state para o modo de redirecionamento.

Confirme se o cabeçalho X-Requested-With: XmlHttpRequest está definido para o modo pop-up.

Em seguida, prossiga com a obtenção de tokens de atualização e de acesso do Google somente se você tiver verificado com sucesso a solicitação do código de autorização.

Receber tokens de acesso e de atualização

Depois que a plataforma de back-end receber um código de autorização do Google e verificar a solicitação, use o código de autenticação para receber tokens de acesso e de atualização do Google e fazer chamadas de API.

Siga as instruções a partir da Etapa 5: trocar o código de autorização por tokens de atualização e de acesso do guia Como usar o OAuth 2.0 para aplicativos de servidor da Web.

Observação: quando o modo pop-up é usado, o valor redirect_uri usado na etapa 5 e posteriormente é a origem da página de chamada. Por exemplo, https://www.example.com/index.html chama initCodeClient e a origem: https://www.example.com é o valor de redirect_url.

Gerenciar tokens

Sua plataforma armazena tokens de atualização com segurança. Exclua os tokens de atualização armazenados quando as contas de usuário forem removidas ou o consentimento do usuário for revogado por google.accounts.oauth2.revoke ou diretamente em https://myaccount.google.com/permissions.

Se quiser, use o RISC para proteger contas de usuário com a proteção entre contas.

Normalmente, a plataforma de back-end chama as APIs do Google usando um token de acesso. Se o app da Web também chamar diretamente as APIs do Google no navegador do usuário, você precisará implementar uma maneira de compartilhar o token de acesso com o aplicativo da Web. Isso está fora do escopo deste guia. Ao seguir essa abordagem e usar a biblioteca de cliente da API do Google para JavaScript, use gapi.client.SetToken() para armazenar temporariamente o token de acesso na memória do navegador e permitir que a biblioteca chame as APIs do Google.