A biblioteca de Serviços de Identificação do Google permite que os usuários solicitem um código de autorização do Google usando um pop-up baseado em navegador ou o fluxo de UX de redirecionamento. 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 de botão, o proprietário da Conta do Google solicita um código de autorização.
- O Google responde enviando um código de autorização exclusivo para um callback no app JavaScript da Web 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 por usuário e de atualização usando uma solicitação para o endpoint do token do Google.
- O Google valida o código de autorização, confirma a solicitação originada da sua plataforma segura, emite tokens de acesso e de atualização e os retorna chamando o endpoint de login hospedado pela plataforma.
- O endpoint de login recebe os tokens de acesso e atualização, armazenando com segurança o token para uso posterior.
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
Para compartilhar um código de autenticação, use o fluxo de usuário no 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, compartilhando o código de autenticação como um parâmetro de URL. No modo pop-up, defina um gerenciador de callback JavaScript, que envia o código de autorização ao servidor. O modo pop-up 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:
Redirecione o fluxo de UX, defina
ux_mode
comoredirect
e o valor deredirect_uri
para 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 de APIs. Ele também precisa estar de acordo com nossas regras de validação do URI de redirecionamento.Fluxo de UX do pop-up, defina
ux_mode
comopopup
e o valor decallback
como o nome da função que você usará para enviar códigos de autorização à sua plataforma.
Prevenção de ataques CSRF
Para evitar ataques entre sites e solicitações de falsificação (CSRF, na sigla em inglês), técnicas ligeiramente diferentes são usadas para os fluxos de UX no modo de redirecionamento e pop-up. No modo de redirecionamento, o parâmetro state do OAuth 2.0 é usado. Consulte a seção RFC6749 10.12 Falsificação de solicitações entre sites (em inglês) 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 solicitações e, em seguida, no servidor confirma que ele corresponde ao valor e à origem esperados.
Escolha um modo de UX para visualizar 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 o 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 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 fluxo de código do OAuth 2.0
Chame o método requestCode()
do cliente de código para acionar o fluxo de usuários:
<button onclick="client.requestCode();">Authorize with Google</button>
Isso 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 o endpoint de redirecionamento ou para o 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 servidor de back-end.
No 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.
No 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 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 o endpoint atual para aceitar solicitações
GET
e parâmetros de URL. Anteriormente, era usada uma solicitaçãoPUT
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 do 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 |
prompt | Caixa de diálogo de consentimento do usuário |
escopo | Lista separada por espaço de um ou mais escopos OAuth2 a serem autorizados |
state | 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 do Google OAuth 2.0, uma solicitação POST
é usada.
Exemplo de solicitação POST
contendo 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
Validação do pedido
No seu servidor, faça o seguinte para evitar ataques CSRF.
Confira 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.
Continue com os tokens de atualização e acesso do Google somente se tiver verificado primeiro a solicitação do 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 autorização para receber e atualizar os tokens do Google para fazer chamadas de API.
Siga as instruções da Etapa 5: trocar código de autorização para tokens de acesso e atualização do guia Como usar o OAuth 2.0 para aplicativos de servidor da Web.
Como 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ário 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 as APIs do Google diretamente do navegador do usuário,
implemente 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 das 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 as APIs do Google.