Usar o modelo de código

A biblioteca Google Identity Services permite que os usuários solicitem um código de autorização do Google usando um fluxo de UX de pop-up ou redirecionamento baseado em navegador. Isso inicia um fluxo seguro do OAuth 2.0 e resulta em um token de acesso usado para chamar as 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 no 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 para o endpoint de token do Google.
• O Google valida o código de autorização, confirma que a solicitação foi originada da sua plataforma segura, emite tokens de acesso e atualização e os retorna chamando o endpoint de login hospedado pela sua plataforma.
• O endpoint de login recebe os tokens de acesso e de atualização, armazenando o token de atualização com segurança para uso posterior.

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

Pré-requisitos

Siga as etapas descritas em Configuração para configurar a tela de consentimento OAuth, receber 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 de redirecionamento

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

Para inicializar um cliente para:

• Redirecione o fluxo de 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 do cliente OAuth 2.0 que você configurou no API Console. Ele também precisa estar em conformidade com nossas regras de validação de URI de redirecionamento.

• Fluxo de UX de 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 à plataforma.

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

Proteção contra ataques CSRF

Para ajudar a evitar ataques de falsificação de solicitações entre sites (CSRF, na sigla em inglês), técnicas um pouco diferentes são usadas para os fluxos de UX do modo de redirecionamento e pop-up. No modo de redirecionamento, o parâmetro state do OAuth 2.0 é usado. Consulte a seção 10.12 do RFC6749 Falsificação de solicitação entre sites para saber mais sobre como gerar e validar o parâmetro state. Com o modo pop-up, você adiciona um cabeçalho HTTP personalizado às solicitações e, em seguida, confirma no servidor que ele corresponde ao valor e à origem esperados.

Escolha um modo de UX para conferir um snippet de código que mostra o código de autenticaçã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_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

Modo pop-up

Inicialize um cliente em que o navegador do usuário recebe um código de autenticação do Google e o envia ao servidor.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, 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);
  },
});

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 consinta em compartilhar escopos individuais antes de retornar um código de autorização para o endpoint de redirecionamento ou o gerenciador de callbacks.

Processamento do 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 gerenciador especificado por callback, em execução no navegador do usuário, encaminha o código de autorização para um endpoint hospedado pela plataforma.

No modo de redirecionamento, uma solicitação GET é enviada ao endpoint especificado por redirect_url, 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 atual.

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

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 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 para endpoints 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: anteriormente, POST era usado para solicitações. Atualize o gerenciador 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 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 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.

Só prossiga com a obtenção de tokens de atualização e acesso do Google se você tiver verificado a solicitação de código de autenticaçã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 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 acesso do guia Como usar o OAuth 2.0 para aplicativos de servidor da Web.

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.

Você também pode usar o RISC para proteger contas de usuários 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 do navegador do usuário, você precisa 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.