Usar o modelo de código

A biblioteca do Google Identity Services permite que os usuários solicitem um código de autorização do Google usando um fluxo pop-up baseado em navegador ou redirecionamento de UX. 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 do usuário.

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

• Em um navegador, com um gesto como o clique de um 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 seu 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 acesso por usuário e atualizado os tokens usando uma solicitação para o endpoint de token do Google.
• O Google valida o código de autorização, confirma a solicitação originada da plataforma segura, emite tokens de acesso e atualização e retorna os tokens chamando o endpoint de login hospedado pela sua plataforma.
• O endpoint de login recebe os tokens de acesso e atualização, armazenando com segurança o token de atualização para uso posterior.

Importante:no servidor de back-end, troque um código de autorização para atualizar tokens e tokens de acesso chamando o endpoint do token do Google.

Inicializar um cliente de código

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

Modo de pop-up ou redirecionamento

Você pode escolher compartilhar um código de autenticação usando o fluxo de usuários Modo de 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, compartilhando 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 ao servidor. Esse modo pode ser usado para oferecer uma experiência do usuário perfeita, sem que os visitantes precisem sair do site.

Para inicializar um cliente para:

• Redirecionar o fluxo de UX, definir ux_mode como redirect e o valor de redirect_uri ao endpoint do código de autorização da plataforma. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0 que você configurou no Console de APIs. Ele também precisa estar em conformidade com nossas regras de validação do URI de redirecionamento.

• Fluxo de UX pop-up, definir ux_mode como popup e o valor de callback como o nome da função que você usará para enviar códigos de autorização para sua plataforma.

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

Prevenção de ataques de CSRF

Para ajudar a evitar ataques de falsificação de solicitação entre sites (CSRF, na sigla em inglês), são empregadas técnicas um pouco diferentes para os fluxos de UX do modo de redirecionamento e pop-up. O parâmetro state do OAuth 2.0 é usado no modo de redirecionamento. Consulte a seção 10.12 Falsificação de solicitações entre sites da RFC6749 para mais informações sobre como gerar e validar o parâmetro state. Com o modo pop-up, você adiciona um cabeçalho HTTP personalizado às suas solicitações e, em seguida, no seu servidor, confirma 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 autenticação e o processamento de CSRF:

Modo de redirecionamento

Inicialize um cliente em que o Google redirecione 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 de pop-up

Inicialize um cliente onde o navegador do usuário receba um código de autenticação do Google e o envie 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 fluxo de código 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 autorize o compartilhamento de escopos individuais antes de retornar um código de autorização ao endpoint de redirecionamento ou ao gerenciador 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 seu servidor de back-end.

Para o modo pop-up, o gerenciador especificado por callback, em execução no navegador do usuário, redireciona o código de autorização para um endpoint hospedado pela sua plataforma.

Para o modo de redirecionamento, uma solicitação GET é enviada para o endpoint especificado por redirect_url, compartilhando o código de autorização no parâmetro de código do URL. Para receber o código de autorização, siga estas etapas:

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

• Atualize o endpoint atual para aceitar GET solicitações e parâmetros de URL. Anteriormente, 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
usuário de autenticação	Solicitação de autenticação de login do usuário
código	Um código de autorização OAuth2 gerado pelo Google
alta definição‎‏‎‎‏‎	O domínio hospedado da conta de usuário
solicitação	Caixa de diálogo de consentimento do usuário
escopo	Lista separada por espaço de um ou mais escopos de 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

Uma solicitação POST é usada quando o fluxo do código de autorização é iniciado por bibliotecas JavaScript anteriores ou por chamadas diretas para endpoints do Google OAuth 2.0.

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 quiser continuar usando bibliotecas JS mais antigas ou chamar endpoints do Google OAuth 2.0 diretamente ao usar a biblioteca dos Serviços de identidade do Google.

Validação do pedido

No seu 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 os tokens de acesso e atualização do Google apenas se você tiver verificado primeiro a solicitação de código de autenticação.

Receber tokens de acesso e 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 para fazer chamadas de API.

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

Como gerenciar tokens

Sua plataforma armazena com segurança tokens de atualização. Exclua os tokens de atualização armazenados quando as contas de usuários 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 considerar o RISC para proteger contas de usuários com a Proteção entre contas.

Normalmente, sua plataforma de back-end chamará as APIs do Google usando um token de acesso. Se o app da Web também chamar diretamente as APIs do Google pelo navegador do usuário, implemente uma maneira de compartilhar o token de acesso com o aplicativo da Web, fazer isso está fora do escopo deste guia. Ao seguir essa abordagem e usar a biblioteca de cliente de APIs 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 APIs do Google.