OpenID Connect

O endpoint do OpenID Connect do Google é certificado pelo OpenID.

As APIs OAuth 2.0 do Google podem ser usadas para autenticação e autorização. Este documento descreve nossa implementação do OAuth 2.0 para autenticação, que está em conformidade com a especificação do OpenID Connect e tem a certificação do OpenID. A documentação encontrada em Como usar o OAuth 2.0 para acessar as APIs do Google também se aplica a esse serviço. Se você quiser conhecer esse protocolo de forma interativa, recomendamos o OAuth 2.0 Playground do Google. Para receber ajuda no Stack Overflow, marque suas perguntas com "google-oauth".

Como configurar o OAuth 2.0

Antes que seu aplicativo possa usar o sistema de autenticação OAuth 2.0 do Google para login do usuário, é necessário configurar um projeto no Console do Google Cloud para receber credenciais do OAuth 2.0, definir um URI de redirecionamento e, se quiser, personalizar as informações de branding que os usuários veem na tela de permissão do usuário. Também é possível usar o console do Cloud para criar uma conta de serviço, ativar o faturamento, configurar a filtragem e realizar outras tarefas. Para mais detalhes, consulte a Ajuda do console do Google Cloud.

Receber credenciais do OAuth 2.0

Você precisa de credenciais do OAuth 2.0, incluindo um ID do cliente e uma chave secreta do cliente, para autenticar usuários e ter acesso às APIs do Google.

Para ver o ID do cliente e a chave secreta do cliente de uma determinada credencial do OAuth 2.0, clique no seguinte texto: Selecionar credencial. Na janela que se abre, escolha o projeto e a credencial que você quer e clique em Visualizar.

Ou confira o ID do cliente e a chave secreta do cliente na página Clientes no Console do Cloud:

  1. Acesse a página Clientes.
  2. Clique no nome do cliente ou no ícone de edição (). O ID do cliente e a chave secreta estão na parte de cima da página.

Definir um URI de redirecionamento

O URI de redirecionamento definido no console do Cloud determina para onde o Google envia respostas às suas solicitações de autenticação.

Para criar, visualizar ou editar os URIs de redirecionamento de uma determinada credencial do OAuth 2.0, faça o seguinte:

  1. Acesse a página Clientes.
  2. Clique no cliente.
  3. Confira ou edite os URIs de redirecionamento.

Se não houver um cliente listado na página "Clientes", seu projeto não terá credenciais OAuth. Para criar um, clique em Criar cliente.

Personalizar a tela de permissão do usuário

Para os usuários, a experiência de autenticação do OAuth 2.0 inclui uma tela de permissão que descreve as informações que o usuário está liberando e os termos aplicáveis. Por exemplo, quando o usuário faz login, pode ser solicitado que ele conceda ao app acesso ao endereço de e-mail e às informações básicas da conta. Você solicita acesso a essas informações usando o parâmetro scope, que o app inclui na solicitação de autenticação. Também é possível usar escopos para solicitar acesso a outras APIs do Google.

A tela de consentimento do usuário também apresenta informações de branding, como o nome do produto, o logotipo e um URL da página inicial. Você controla as informações de branding no Console do Cloud.

Para ativar a tela de permissão do projeto:

  1. Abra a página Branding no Console do Google Cloud.
  2. Se for solicitado, selecione um projeto ou crie um novo.
  3. Preencha o formulário e clique em Salvar.

A caixa de diálogo de consentimento a seguir mostra o que um usuário veria quando uma combinação de escopos do OAuth 2.0 e do Google Drive estivesse presente na solicitação. Essa caixa de diálogo genérica foi gerada usando o OAuth 2.0 Playground do Google, por isso não inclui informações de marca que seriam definidas no Console do Cloud.

Exemplo de uma página de consentimento
Figura 1. Captura de tela da página de consentimento

Como acessar o serviço

O Google e terceiros fornecem bibliotecas que podem ser usadas para cuidar de muitos dos detalhes de implementação da autenticação de usuários e do acesso às APIs do Google. Os exemplos incluem os Serviços de Identificação do Google e as bibliotecas de cliente do Google, que estão disponíveis para várias plataformas.

Se você optar por não usar uma biblioteca, siga as instruções no restante deste documento, que descreve os fluxos de solicitação HTTP que estão na base das bibliotecas disponíveis.

Autenticar o usuário

A autenticação do usuário envolve receber um token de ID e validá-lo. Os tokens de ID são um recurso padronizado do OpenID Connect projetado para uso no compartilhamento de declarações de identidade na Internet.

As abordagens mais usadas com frequência para autenticar um usuário e receber um token de ID são chamadas de fluxo de "servidor" e fluxo "implícito". O fluxo do servidor permite que o servidor de back-end de um aplicativo verifique a identidade da pessoa que está usando um navegador ou dispositivo móvel. O fluxo implícito é usado quando um aplicativo do lado do cliente (geralmente um app JavaScript em execução no navegador) precisa acessar APIs diretamente em vez de usar o servidor de back-end.

Neste documento, descrevemos como realizar o fluxo do servidor para autenticar o usuário. O fluxo implícito é muito mais complicado devido aos riscos de segurança no processamento e uso de tokens no lado do cliente. Se você precisar implementar um fluxo implícito, recomendamos usar os Serviços de Identificação do Google.

Fluxo do servidor

Configure seu app no Console do Cloud para que ele use esses protocolos e autentique os usuários. Quando um usuário tenta fazer login com o Google, você precisa:

  1. Criar um token de estado antifalsificação
  2. Enviar uma solicitação de autenticação ao Google
  3. Confirmar o token de estado antifalsificação
  4. Trocar code por token de acesso e token de ID
  5. Obter informações do usuário no token de ID
  6. Autenticar o usuário

1. Criar um token de estado antifalsificação

Você precisa proteger a segurança dos usuários impedindo ataques de falsificação de solicitações. A primeira etapa é criar um token de sessão exclusivo que mantenha o estado entre o app e o cliente do usuário. Depois, você faz a correspondência desse token de sessão exclusivo com a resposta de autenticação retornada pelo serviço de login do Google OAuth para verificar se o usuário está fazendo a solicitação, e não um invasor mal-intencionado. Esses tokens são frequentemente chamados de tokens de falsificação de solicitação entre sites (CSRF, na sigla em inglês).

Uma boa opção para um token de estado é uma string de cerca de 30 caracteres construída usando um gerador de números aleatórios de alta qualidade. Outra é um hash gerado pela assinatura de algumas das variáveis de estado da sessão com uma chave que é mantida em segredo no back-end.

O código a seguir demonstra como gerar tokens de sessão exclusivos.

PHP

Para usar este exemplo, faça o download da biblioteca de cliente das APIs do Google para PHP.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Para usar este exemplo, faça o download da biblioteca de cliente de APIs do Google para Java.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Faça o download da biblioteca de cliente de APIs do Google para Python para usar este exemplo.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Enviar uma solicitação de autenticação ao Google

A próxima etapa é formar uma solicitação HTTPS GET com os parâmetros de URI adequados. Observe o uso de HTTPS em vez de HTTP em todas as etapas desse processo. As conexões HTTP são recusadas. Recupere o URI de base do documento de descoberta usando o valor de metadados authorization_endpoint. A discussão a seguir pressupõe que o URI base seja https://accounts.google.com/o/oauth2/v2/auth.

Para uma solicitação básica, especifique os seguintes parâmetros:

  • client_id, que você recebe na página Clientes do console do Cloud.
  • response_type, que em uma solicitação básica de fluxo do código de autorização precisa ser code. (Leia mais em response_type.)
  • scope, que em uma solicitação básica precisa ser openid email. (Saiba mais em scope.)
  • redirect_uri precisa ser o endpoint HTTP no seu servidor que vai receber a resposta do Google. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou na página de credenciais do Console do Cloud. Se esse valor não corresponder a um URI autorizado, a solicitação vai falhar com um erro redirect_uri_mismatch.
  • state precisa incluir o valor do token de sessão exclusivo antifalsificação, além de outras informações necessárias para recuperar o contexto quando o usuário retornar ao aplicativo, como o URL inicial. (Saiba mais em state.)
  • nonce é um valor aleatório gerado pelo app que ativa a proteção contra repetição quando presente.
  • login_hint pode ser o endereço de e-mail do usuário ou a string sub, que é equivalente ao ID do Google do usuário. Se você não fornecer um login_hint e o usuário estiver conectado, a tela de permissão vai incluir um pedido de aprovação para liberar o endereço de e-mail do usuário para seu app. Leia mais em login_hint.
  • Use o parâmetro hd para otimizar o fluxo do OpenID Connect para usuários de um domínio específico associado a uma organização do Google Workspace ou do Cloud (leia mais em hd).

Veja um exemplo de URI de autenticação completo do OpenID Connect, com quebras de linha e espaços para facilitar a leitura:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Os usuários precisam dar consentimento se o app solicitar novas informações sobre eles ou acesso à conta que não tenha sido aprovado anteriormente.

3. Confirmar o token de estado antifalsificação

A resposta é enviada para o redirect_uri que você especificou na solicitação. Todas as respostas são retornadas na string de consulta:

https://developers.google.com/oauthplayground?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

De acordo com a RFC 6749, os clientes PRECISAM ignorar parâmetros de resposta não reconhecidos. No servidor, confirme se o state recebido do Google corresponde ao token de sessão que você criou na Etapa 1. Essa verificação de ida e volta ajuda a confirmar que o usuário, e não um script malicioso, está fazendo a solicitação.

O código a seguir demonstra como confirmar os tokens de sessão criados na Etapa 1:

PHP

Para usar este exemplo, faça o download da biblioteca de cliente das APIs do Google para PHP.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Para usar este exemplo, faça o download da biblioteca de cliente de APIs do Google para Java.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Faça o download da biblioteca de cliente de APIs do Google para Python para usar este exemplo.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Trocar code por token de acesso e token de ID

A resposta inclui um parâmetro code, um código de autorização único que o servidor pode trocar por um token de acesso e um token de ID. Seu servidor faz essa troca enviando uma solicitação HTTPS POST. A solicitação POST é enviada ao endpoint do token, que precisa ser recuperado do documento de descoberta usando o valor de metadados token_endpoint. A discussão a seguir pressupõe que o endpoint é https://oauth2.googleapis.com/token. A solicitação precisa incluir os seguintes parâmetros no corpo POST:

Campos
code O código de autorização retornado da solicitação inicial.
client_id O ID do cliente que você recebe na página Clientes do console do Cloud, conforme descrito em Receber credenciais do OAuth 2.0.
client_secret A chave secreta do cliente que você recebe na página Clientes do console do Cloud, conforme descrito em Receber credenciais do OAuth 2.0.
redirect_uri Um URI de redirecionamento autorizado para o client_id especificado na página Clientes do console do Cloud, conforme descrito em Definir um URI de redirecionamento.
grant_type Esse campo precisa conter um valor de authorization_code, conforme definido na especificação do OAuth 2.0.

A solicitação real pode ser semelhante ao exemplo a seguir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//developers.google.com/oauthplayground&
grant_type=authorization_code

Uma resposta bem-sucedida a essa solicitação contém os seguintes campos em uma matriz JSON:

Campos
access_token Um token que pode ser enviado a uma API do Google.
expires_in A vida útil restante do token de acesso em segundos.
id_token Um JWT que contém informações de identidade sobre o usuário que é assinado digitalmente pelo Google.
scope Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaços que diferenciam maiúsculas de minúsculas.
token_type Identifica o tipo de token retornado. No momento, esse campo sempre tem o valor Bearer.
refresh_token (opcional)

Esse campo só vai estar presente se o parâmetro access_type tiver sido definido como offline na solicitação de autenticação. Para mais detalhes, consulte Tokens de atualização.

5. Receber informações do usuário do token de ID

Um token de ID é um JWT (JSON Web Token), ou seja, um objeto JSON codificado em Base64 assinado criptograficamente. Normalmente, é fundamental validar um token de ID antes de usá-lo. No entanto, como você está se comunicando diretamente com o Google por um canal HTTPS sem intermediários e usando sua chave secreta do cliente para se autenticar no Google, pode ter certeza de que o token recebido realmente vem do Google e é válido. Se o servidor transmitir o token de ID para outros componentes do app, é extremamente importante que eles validem o token antes de usá-lo.

Como a maioria das bibliotecas de API combina a validação com o trabalho de decodificar os valores codificados em base64url e analisar o JSON, você provavelmente vai acabar validando o token de qualquer maneira ao acessar as declarações no token de ID.

Um payload de token de ID

Um token de ID é um objeto JSON que contém um conjunto de pares de nome/valor. Veja um exemplo, formatado para facilitar a leitura:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Os tokens de ID do Google podem conter os seguintes campos (conhecidos como declarações):

Reivindicar Fornecido Descrição
aud sempre O público-alvo a que o token de ID se destina. Ele precisa ser um dos IDs do cliente OAuth 2.0 do seu aplicativo.
exp sempre O prazo de validade após o qual o token de ID não pode ser aceito. Representado no horário da época Unix (segundos inteiros).
iat sempre A hora em que o token de ID foi emitido. Representado no horário da época Unix (segundos inteiros).
iss sempre O identificador do emissor da resposta. Sempre https://accounts.google.com ou accounts.google.com para tokens de ID do Google.
sub sempre Um identificador do usuário, exclusivo entre todas as Contas do Google e nunca reutilizado. Uma Conta do Google pode ter vários endereços de e-mail em momentos diferentes, mas o valor de sub nunca é alterado. Use sub no aplicativo como a chave de identificador exclusivo do usuário. Comprimento máximo de 255 caracteres ASCII que diferenciam maiúsculas de minúsculas.
amr Uma matriz JSON de strings que identificam os métodos de autenticação usados para fazer login em uma Conta do Google. Se presente, inclui um ou mais destes possíveis valores [IANA.AMR]:
  • hwk uma chave de hardware foi usada
  • mfa A autenticação multifator foi concluída
  • pwd uma senha foi usada
  • sms uma mensagem SMS foi usada para verificação
  • swk uma chave de software, como uma chave de acesso, foi usada
  • tel uma ligação foi usada para verificação
Presente apenas quando a declaração amr está incluída na solicitação de autenticação e ativada nas configurações.
auth_time O horário em que a autenticação do usuário ocorreu, um número JSON que representa o número de segundos decorridos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC). Fornecido quando a declaração auth_time é incluída na solicitação de autenticação e ativada nas configurações.
at_hash Hash do token de acesso. Fornece validação de que o token de acesso está vinculado ao token de identidade. Se o token de ID for emitido com um valor access_token no fluxo do servidor, essa declaração será sempre incluída. Essa declaração pode ser usada como um mecanismo alternativo para proteger contra ataques de falsificação de solicitações entre sites, mas se você seguir as etapas 1 e 3, não será necessário verificar o token de acesso.
azp O client_id do apresentador autorizado. Essa declaração só é necessária quando a parte que solicita o token de ID não é a mesma que o público-alvo do token de ID. Isso pode acontecer no Google para apps híbridos em que um aplicativo da Web e um app Android têm um client_id do OAuth 2.0 diferente, mas compartilham o mesmo projeto de APIs do Google.
email O endereço de e-mail do usuário. Fornecido apenas se você incluiu o escopo email na solicitação. O valor dessa declaração pode não ser exclusivo para essa conta e pode mudar com o tempo. Portanto, não use esse valor como o identificador principal para vincular ao registro do usuário. Também não é possível usar o domínio da declaração email para identificar usuários do Google Workspace ou de organizações do Cloud. Use a declaração hd.
email_verified Verdadeiro se o endereço de e-mail do usuário foi verificado. Caso contrário, é falso.
family_name O sobrenome do usuário. Pode ser fornecido quando uma reivindicação name está presente.
given_name Os nomes do usuário. Pode ser fornecido quando uma reivindicação name está presente.
hd O domínio associado à organização do Google Workspace ou do Cloud do usuário. Fornecido apenas se o usuário pertencer a uma organização do Google Cloud. Verifique essa declaração ao restringir o acesso a um recurso apenas para membros de determinados domínios. A ausência dessa declaração indica que a conta não pertence a um domínio hospedado pelo Google.
locale A localidade do usuário, representada por uma tag de idioma BCP 47. Pode ser fornecido quando uma declaração name está presente.
name O nome completo do usuário, em um formato que pode ser exibido. Pode ser fornecido quando:
  • O escopo da solicitação incluiu a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando as declarações name estão presentes, é possível usá-las para atualizar os registros de usuário do app. Essa declaração nunca é garantida.
nonce O valor do nonce fornecido pelo app na solicitação de autenticação. Para se proteger contra ataques de repetição, apresente esse valor apenas uma vez.
picture O URL da foto do perfil do usuário. Pode ser fornecido quando:
  • O escopo da solicitação incluiu a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando as declarações picture estão presentes, é possível usá-las para atualizar os registros de usuário do app. Essa declaração nunca é garantida.
profile O URL da página do perfil do usuário. Pode ser fornecido quando:
  • O escopo da solicitação incluiu a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando as declarações profile estão presentes, é possível usá-las para atualizar os registros de usuário do app. Essa declaração nunca é garantida.

6. Autenticar o usuário

Depois de receber as informações do usuário do token de ID, consulte o banco de dados de usuários do app. Se o usuário já existir no seu banco de dados, inicie uma sessão de aplicativo para ele se todos os requisitos de login forem atendidos pela resposta da API do Google.

Se o usuário não existir no seu banco de dados, redirecione-o para o fluxo de inscrição de novos usuários. Talvez seja possível registrar automaticamente o usuário com base nas informações recebidas do Google ou, pelo menos, pré-preencher muitos dos campos necessários no formulário de registro. Além das informações no token de ID, é possível receber mais informações do perfil de usuário nos nossos endpoints de perfil de usuário.

Tópicos avançados

As seções a seguir descrevem a API OAuth 2.0 do Google em mais detalhes. Estas informações são destinadas a desenvolvedores com requisitos avançados de autenticação e autorização.

Acesso a outras APIs do Google

Uma das vantagens de usar o OAuth 2.0 para autenticação é que seu aplicativo pode receber permissão para usar outras APIs do Google em nome do usuário (como YouTube, Google Drive, Agenda ou Contatos) ao mesmo tempo em que autentica o usuário. Para isso, inclua os outros escopos necessários na solicitação de autenticação que você envia ao Google. Por exemplo, para adicionar a faixa etária do usuário à solicitação de autenticação, transmita um parâmetro de escopo de openid email https://www.googleapis.com/auth/profile.agerange.read. O usuário recebe uma solicitação adequada na tela de permissão. O token de acesso que você recebe do Google permite que seu aplicativo acesse todas as APIs relacionadas aos escopos de acesso solicitados e concedidos.

Tokens de atualização

Na solicitação de acesso à API, é possível pedir que um token de atualização seja retornado durante a troca de code. Um token de atualização fornece ao app acesso contínuo às APIs do Google enquanto o usuário não está presente no aplicativo. Para solicitar um token de atualização, defina o parâmetro access_type como offline na sua solicitação de autenticação.

Considerações:

  • Armazene o token de atualização de forma segura e permanente, porque ele só pode ser recebido na primeira vez que você realizar o fluxo de troca de código.
  • Há limites para o número de tokens de atualização emitidos: um limite por combinação de cliente/usuário e outro por usuário em todos os clientes. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos vão parar de funcionar.

Para mais informações, consulte Como atualizar um token de acesso (acesso off-line).

Para pedir que o usuário autorize o app novamente, defina o parâmetro prompt como consent na solicitação de autenticação. Quando prompt=consent é incluído, a tela de permissão é exibida sempre que o app solicita autorização de escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao projeto das APIs do Google. Por esse motivo, inclua prompt=consent apenas quando necessário.

Para saber mais sobre o parâmetro prompt, consulte prompt na tabela Parâmetros de URI de autenticação.

Parâmetros de URI de autenticação

A tabela a seguir fornece descrições mais completas dos parâmetros aceitos pela API de autenticação OAuth 2.0 do Google.

Parâmetro Obrigatório Descrição
client_id (Obrigatório) A string do ID do cliente que você recebe na página Clientes do Console do Cloud, conforme descrito em Receber credenciais do OAuth 2.0.
nonce (Obrigatório) Um valor aleatório gerado pelo app que permite a proteção contra repetição.
response_type (Obrigatório) Se o valor for code, inicia um fluxo do código de autorização básico, exigindo um POST para o endpoint de token para receber os tokens. Se o valor for token id_token ou id_token token, inicia um fluxo implícito, exigindo o uso de JavaScript no URI de redirecionamento para recuperar tokens do identificador de URI #fragment.
redirect_uri (Obrigatório) Determina para onde a resposta é enviada. O valor desse parâmetro precisa corresponder exatamente a um dos valores de redirecionamento autorizados que você definiu na página "Clientes" do Console do Cloud (incluindo o esquema HTTP ou HTTPS, maiúsculas e minúsculas e a barra final, se houver).
scope (Obrigatório)

O parâmetro de escopo precisa começar com o valor openid e incluir o valor profile, o valor email ou ambos.

Se o valor do escopo profile estiver presente, o token de ID poderá (mas não é garantido) incluir as declarações profile padrão do usuário.

Se o valor do escopo email estiver presente, o token de ID vai incluir as declarações email e email_verified.

Além desses escopos específicos do OpenID, o argumento de escopo também pode incluir outros valores de escopo. Todos os valores de escopo precisam ser separados por espaços. Por exemplo, se você quiser acesso por arquivo ao Google Drive de um usuário, o parâmetro de escopo pode ser openid profile email https://www.googleapis.com/auth/drive.file.

Para informações sobre os escopos disponíveis, consulte Escopos do OAuth 2.0 para APIs do Google ou a documentação da API do Google que você quer usar.
state (Opcional, mas altamente recomendado)

Uma string opaca que é enviada e recebida no protocolo. Ou seja, ela é retornada como um parâmetro de URI no fluxo básico e no identificador de URI #fragment no fluxo implícito.

O state pode ser útil para correlacionar solicitações e respostas. Como seu redirect_uri pode ser adivinhado, usar um valor state pode aumentar sua garantia de que uma conexão de entrada é o resultado de uma solicitação de autenticação iniciada pelo seu app. Se você gerar uma string aleatória ou codificar o hash de algum estado do cliente (por exemplo, um cookie) nessa variável state, poderá validar a resposta para verificar se a solicitação e a resposta se originaram no mesmo navegador. Isso protege contra ataques como falsificação de solicitações entre sites.
access_type (Opcional) Os valores permitidos são offline e online. O efeito está documentado em Acesso off-line. Se um token de acesso estiver sendo solicitado, o cliente não receberá um token de atualização, a menos que um valor de offline seja especificado.
claims (Opcional) O parâmetro de declarações é usado para especificar um ou mais campos opcionais a serem incluídos no endpoint userinfo ou nos tipos de resposta do token de ID da solicitação de autenticação. O valor é um objeto JSON que contém o tipo de resposta e as declarações solicitadas. As seguintes solicitações de declaração são aceitas pelos servidores do Google:
Solicitações de reivindicação
amr Solicite o método usado quando o usuário foi autenticado pela última vez. Para retornar amr como um campo na resposta do token de ID, inclua o parâmetro de solicitação claims: claims={"id_token":{"amr":{"essential":true}}} Precisa ser ativado nas configurações.
auth_time Solicite o horário em que o usuário foi autenticado pela última vez. Para retornar auth_time como um campo na resposta do token de ID, inclua o parâmetro de solicitação claims: claims={"id_token":{"auth_time":{"essential":true}}} Precisa ser ativado nas configurações.
display (Opcional) Um valor de string ASCII para especificar como o servidor de autorização exibe as páginas da interface do usuário de autenticação e consentimento. Os valores a seguir são especificados e aceitos pelos servidores do Google, mas não têm efeito no comportamento do fluxo do protocolo: page, popup, touch e wap.
hd (Opcional)

Simplifique o processo de login para contas de uma organização do Google Cloud. Ao incluir o domínio da organização do Google Cloud (por exemplo, mycollege.edu), é possível indicar que a interface de seleção de conta precisa ser otimizada para contas nesse domínio. Para otimizar as contas de organização do Google Cloud em geral, em vez de apenas um domínio de organização do Google Cloud, defina um valor de asterisco (*): hd=*.

Não use essa otimização de IU para controlar quem pode acessar seu app, já que as solicitações do lado do cliente podem ser modificadas. Valide se o token de ID retornado tem um valor de declaração hd que corresponde ao esperado (por exemplo, mycolledge.edu). Ao contrário do parâmetro de solicitação, a declaração hd do token de ID está contida em um token de segurança do Google, então o valor é confiável.
include_granted_scopes (Opcional) Se esse parâmetro for fornecido com o valor true e a solicitação de autorização for concedida, a autorização vai incluir todas as autorizações anteriores concedidas a essa combinação de usuário/aplicativo para outros escopos. Consulte Autorização incremental.

Não é possível fazer a autorização incremental com o fluxo de app instalado.
login_hint (Opcional) Quando o app sabe qual usuário está tentando autenticar, ele pode fornecer esse parâmetro como uma dica para o servidor de autenticação. Transmitir essa dica suprime o seletor de conta e preenche automaticamente a caixa de e-mail no formulário de login ou seleciona a sessão adequada (se o usuário estiver usando o login múltiplo), o que pode ajudar a evitar problemas que ocorrem se o app fizer login na conta de usuário errada. O valor pode ser um endereço de e-mail ou a string sub, que é equivalente ao ID do Google do usuário.
prompt (Opcional) Uma lista delimitada por espaços de valores de string que especifica se o servidor de autorização solicita que o usuário faça uma nova autenticação e dê consentimento. Os valores possíveis são:
  • none

    O servidor de autorização não mostra telas de autenticação ou de consentimento do usuário. Ele vai retornar um erro se o usuário ainda não estiver autenticado e não tiver configurado previamente o consentimento para os escopos solicitados. Use none para verificar se há autenticação e/ou consentimento.

  • consent

    O servidor de autorização solicita o consentimento do usuário antes de retornar informações ao cliente.

  • select_account

    O servidor de autorização solicita que o usuário selecione uma conta de usuário. Isso permite que um usuário que tenha várias contas no servidor de autorização selecione entre as várias contas em que ele pode ter sessões atuais.

Se nenhum valor for especificado e o usuário não tiver autorizado o acesso anteriormente, uma tela de permissão será mostrada.
hl (Opcional) Uma tag de idioma BCP 47 usada para especificar o idioma de exibição das telas de login, seletor de conta e consentimento. Se esse parâmetro não for fornecido, o idioma padrão será o da Conta do Google ou das configurações do navegador do usuário. Por exemplo, para solicitar a interface em inglês britânico, defina o parâmetro como en-GB.

Como validar um token de ID

É necessário validar todos os tokens de ID no seu servidor, a menos que você saiba que eles vieram diretamente do Google. Por exemplo, o servidor precisa verificar se os tokens de ID recebidos dos apps cliente são autênticos.

Veja a seguir situações comuns em que você pode enviar tokens de ID para seu servidor:

  • Envio de tokens de ID com solicitações que precisam ser autenticadas. Os tokens de ID informam o usuário específico que está fazendo a solicitação e para qual cliente esse token de ID foi concedido.

Os tokens de ID são sensíveis e podem ser usados de forma indevida se forem interceptados. É preciso garantir que esses tokens sejam processados de maneira segura, transmitindo-os apenas por HTTPS e usando apenas dados POST ou em cabeçalhos da solicitação. Se você armazenar tokens de ID no servidor, faça isso de forma segura.

Uma coisa que torna os tokens de ID úteis é o fato de que você pode transmiti-los por diferentes componentes do app. Esses componentes podem usar um token de ID como um mecanismo de autenticação leve que autentica o app e o usuário. No entanto, antes de usar as informações no token de ID ou confiar nele como uma declaração de que o usuário foi autenticado, é necessário validá-lo.

A validação de um token de ID requer várias etapas:

  1. Verifique se o token de ID está assinado corretamente pelo emissor. Os tokens emitidos pelo Google são assinados usando um dos certificados encontrados no URI especificado no valor de metadados jwks_uri do documento de descoberta.
  2. Verifique se o valor da declaração iss no token de ID é igual a https://accounts.google.com ou accounts.google.com.
  3. Verifique se o valor da declaração aud no token de ID é igual ao ID do cliente do seu app.
  4. Verifique se o expiry time (declaração exp) do token de ID não expirou.
  5. Se você especificou um valor de parâmetro hd na solicitação, verifique se o token de ID tem uma declaração hd que corresponde a um domínio aceito associado a uma organização do Google Cloud.

As etapas de 2 a 5 envolvem apenas comparações de strings e datas, que são bastante simples. Por isso, não vamos detalhá-las aqui.

A primeira etapa é mais complexa e envolve a verificação da assinatura criptográfica. Para fins de depuração, use o endpoint tokeninfo do Google para comparar com o processamento local implementado no seu servidor ou dispositivo. Suponha que o valor do token de ID seja XYZ123. Em seguida, você desreferenciaria o URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Se a assinatura do token for válida, a resposta será o payload do JWT na forma de objeto JSON decodificado.

O endpoint tokeninfo é útil para depuração, mas, para fins de produção, recupere as chaves públicas do Google no endpoint de chaves e faça a validação localmente. Recupere o URI das chaves no documento de descoberta usando o valor de metadados jwks_uri. As solicitações para o endpoint de depuração podem ser limitadas ou estar sujeitas a erros intermitentes.

Como o Google muda as chaves públicas com pouca frequência, é possível armazená-las em cache usando as diretivas de cache da resposta HTTP e, na grande maioria dos casos, realizar a validação local de maneira muito mais eficiente do que usando o endpoint tokeninfo. Essa validação requer a recuperação e a análise de certificados, além de fazer as chamadas criptográficas apropriadas para verificar a assinatura. Felizmente, há bibliotecas bem depuradas disponíveis em uma ampla variedade de linguagens para fazer isso (consulte jwt.io).

Como receber informações do perfil do usuário

Para receber mais informações de perfil sobre o usuário, use o token de acesso (que seu aplicativo recebe durante o fluxo de autenticação) e o padrão OpenID Connect:

  1. Para estar em conformidade com o OpenID, inclua os valores de escopo openid profile na sua solicitação de autenticação.

    Se você quiser que o endereço de e-mail do usuário seja incluído, especifique um valor de escopo adicional de email. Para especificar profile e email, inclua o seguinte parâmetro no URI da solicitação de autenticação:

    scope=openid%20profile%20email
  2. Adicione o token de acesso ao cabeçalho de autorização e faça uma solicitação HTTPS GET ao endpoint userinfo, que deve ser recuperado do documento de descoberta usando o valor de metadados userinfo_endpoint. A resposta de userinfo inclui informações sobre o usuário, conforme descrito em OpenID Connect Standard Claims e no valor de metadados claims_supported do documento de descoberta. Os usuários ou as organizações deles podem optar por fornecer ou reter determinados campos. Portanto, talvez você não receba informações de todos os campos para seus escopos de acesso autorizados.

O documento de descoberta

O protocolo OpenID Connect exige o uso de vários endpoints para autenticar usuários e solicitar recursos, incluindo tokens, informações do usuário e chaves públicas.

Para simplificar as implementações e aumentar a flexibilidade, o OpenID Connect permite o uso de um "documento de descoberta", um documento JSON encontrado em um local conhecido que contém pares de chave-valor que fornecem detalhes sobre a configuração do provedor do OpenID Connect, incluindo os URIs dos endpoints de autorização, token, revogação, informações do usuário e chaves públicas. O documento de descoberta do serviço OpenID Connect do Google pode ser recuperado em:

https://accounts.google.com/.well-known/openid-configuration

Para usar os serviços do OpenID Connect do Google, codifique o URI do documento de descoberta (https://accounts.google.com/.well-known/openid-configuration) no aplicativo. Seu aplicativo busca o documento, aplica regras de armazenamento em cache na resposta e, em seguida, recupera URIs de endpoint dele, conforme necessário. Por exemplo, para autenticar um usuário, seu código recuperaria o valor de metadados authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth no exemplo abaixo) como o URI base para solicitações de autenticação enviadas ao Google.

Veja um exemplo de um documento desse tipo. Os nomes dos campos são os especificados em OpenID Connect Discovery 1.0 (consulte esse documento para saber os significados). Os valores são puramente ilustrativos e podem mudar, embora sejam copiados de uma versão recente do documento de descoberta do Google:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

É possível evitar uma ida e volta de HTTP armazenando em cache os valores do documento de descoberta. Os cabeçalhos de armazenamento em cache HTTP padrão são usados e precisam ser respeitados.

Bibliotecas de cliente

As bibliotecas de cliente a seguir simplificam a implementação do OAuth 2.0 ao se integrarem a frameworks conhecidos:

Conformidade com o OpenID Connect

O sistema de autenticação OAuth 2.0 do Google é compatível com os recursos necessários da especificação OpenID Connect Core. Qualquer cliente projetado para funcionar com o OpenID Connect deve interoperar com esse serviço (exceto o objeto de solicitação do OpenID).