OpenID Connect

As APIs do 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 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 explorar esse protocolo de maneira interativa, recomendamos o Google OAuth 2.0 Playground. Para receber ajuda com o 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 de usuário, configure um projeto em Google API Console para receber credenciais do OAuth 2.0, definir um URI de redirecionamento e, opcionalmente, personalizar as informações de marca que os usuários veem na tela de consentimento do usuário. Também é possível usar API Console para criar uma conta de serviço, ativar faturamento, configurar filtros e realizar outras tarefas. Para ver mais detalhes, consulte a Ajuda doGoogle API Console.

Receber credenciais do OAuth 2.0

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

Para visualizar o ID do cliente e o segredo do cliente para uma determinada credencial do OAuth 2.0, clique no texto a seguir: Selecione credencial . Na janela que se abre, escolha seu projeto e a credencial desejada e clique em Exibir .

Ou visualize seu ID e segredo do cliente na página Credenciais em API Console :

  1. Go to the Credentials page.
  2. Clique no nome da sua credencial ou no ícone de lápis ( ). Seu ID e segredo do cliente estão na parte superior da página.

Definir um URI de redirecionamento

O URI de redirecionamento definido em API Console determina para onde o Google envia respostas para suas solicitações de autenticação.

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

  1. Go to the Credentials page.
  2. Na seção IDs do cliente OAuth 2.0 da página, clique em uma credencial.
  3. Exibir ou editar os URIs de redirecionamento.

Se não houver uma seção IDs de cliente OAuth 2.0 na página Credenciais, seu projeto não terá credenciais OAuth. Para criar uma, clique em Criar credenciais .

Personalizar a tela de consentimento do usuário

Para seus usuários, a experiência de autenticação do OAuth 2.0 inclui uma tela de consentimento que descreve as informações que o usuário está liberando e os termos aplicáveis. Por exemplo, ao fazer login, o usuário pode receber uma solicitação para conceder ao seu app acesso ao endereço de e-mail e informações básicas da conta. Para solicitar acesso a essas informações, use o parâmetro scope, que seu 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 marca, como o nome do produto, o logotipo e o URL da página inicial. Você controla as informações da marca no API Console.

Para ativar a tela de consentimento do seu projeto:

  1. Abra o Consent Screen page no Google API Console .
  2. If prompted, select a project, or create a new one.
  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 Google OAuth 2.0 Playground, por isso, não inclui informações de marca que seriam definidas em API Console.

Captura de tela da página de consentimento

Como acessar o serviço

O Google e terceiros oferecem 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 subjacentes às bibliotecas disponíveis.

Autenticar o usuário

Autenticar o usuário envolve conseguir um token de ID e validá-lo. Os tokens de ID são um recurso padronizado do OpenID Connect (em inglês) projetado para uso no compartilhamento de declarações de identidade na Internet.

As abordagens mais usadas para autenticar um usuário e receber um token de ID são chamadas de fluxo "servidor" e fluxo "implícito". O fluxo do servidor permite que o servidor back-end de um aplicativo verifique a identidade da pessoa usando um navegador ou dispositivo móvel. O fluxo implícito é usado quando um aplicativo do lado do cliente (normalmente um app JavaScript executado no navegador) precisa acessar as APIs diretamente, e não pelo servidor de back-end.

Este documento descreve como executar o fluxo de servidor para autenticar o usuário. O fluxo implícito é significativamente mais complicado devido aos riscos de segurança no processamento e no uso de tokens no lado do cliente. Se você precisar implementar um fluxo implícito, recomendamos o uso dos Serviços de identidade do Google.

Fluxo do servidor

Configure seu app no API Console para permitir 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 do estado antifalsificação
  4. Troque o code pelo token de acesso e pelo token de ID
  5. Coletar informações do usuário com o token de ID
  6. Autenticar o usuário

1. Criar um token de estado antifalsificação

Proteja 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 seu app e o cliente do usuário. Posteriormente, você faz a correspondência desse token de sessão exclusivo com a resposta de autenticação retornada pelo serviço de login do OAuth do Google para verificar se o usuário está fazendo a solicitação e não é um invasor malicioso. Esses tokens são geralmente chamados de tokens de falsificação de solicitações entre sites (CSRF, na sigla em inglês).

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

O código a seguir demonstra a geração de tokens de sessão exclusivos.

PHP

Para usar esta amostra, é necessário fazer o download da biblioteca cliente de 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

Faça o download da biblioteca cliente de APIs do Google para Java para usar esta amostra.

// 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 cliente de APIs do Google para Python para usar esta amostra.

# 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 apropriados. 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 no documento de descoberta usando o valor de metadados authorization_endpoint. A discussão a seguir pressupõe que o URI base é https://accounts.google.com/o/oauth2/v2/auth.

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

  • client_id, que é extraído do API Console Credentials page .
  • response_type, que, em uma solicitação de fluxo de código de autorização básica, precisa ser code. Saiba mais em response_type.
  • scope, que, em uma solicitação básica, precisa ser openid email. Leia mais em scope.
  • redirect_uri precisa ser o endpoint HTTP no servidor que 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 no API Console Credentials page. Se esse valor não corresponder a um URI autorizado, a solicitação falhará com um erro redirect_uri_mismatch.
  • state precisa incluir o valor do token de sessão exclusivo antifalsificação, bem como qualquer outra informação necessária para recuperar o contexto quando o usuário retorna ao aplicativo, por exemplo, o URL inicial. Leia mais em state.
  • nonce é um valor aleatório gerado pelo app que permite 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 consentimento incluirá uma solicitação de aprovação para liberar o endereço de e-mail do usuário para seu app. Saiba 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. Saiba mais em hd.

Veja um exemplo de URI completo de autenticação 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//oauth2.example.com/code&
 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 precisarão dar o consentimento se o app solicitar novas informações sobre eles ou se o app solicitar acesso à conta que não foi aprovado anteriormente.

3. Confirmar token de estado antifalsificação

A resposta é enviada para o redirect_uri especificado na solicitação. Todas as respostas são retornadas na string de consulta, conforme mostrado abaixo:

https://oauth2.example.com/code?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

No servidor, você precisa confirmar se o state recebido do Google corresponde ao token de sessão criado na Etapa 1. Essa verificação de ida e volta ajuda a garantir que o usuário, e não um script malicioso, está fazendo a solicitação.

O código a seguir demonstra a confirmação dos tokens de sessão que você criou na Etapa 1:

PHP

Para usar esta amostra, é necessário fazer o download da biblioteca cliente de 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

Faça o download da biblioteca cliente de APIs do Google para Java para usar esta amostra.

// 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 cliente de APIs do Google para Python para usar esta amostra.

# 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. Troque o code por um token de acesso e um de ID

A resposta inclui um parâmetro code, um código de autorização único que seu servidor pode trocar por um token de acesso e um de ID. O servidor faz essa troca enviando uma solicitação HTTPS POST. A solicitação POST é enviada para o endpoint do token, que você precisa recuperar 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 recebido de API Console Credentials page, conforme descrito em Receber credenciais do OAuth 2.0.
client_secret A chave secreta do cliente recebida de API Console Credentials page, conforme descrito em Receber credenciais do OAuth 2.0.
redirect_uri Um URI de redirecionamento autorizado para o client_id especificado em API Console Credentials page, 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//oauth2.example.com/code&
grant_type=authorization_code

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

Campos
access_token Um token que pode ser enviado para 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 com assinatura digital do Google.
scope Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaço e que diferenciam maiúsculas de minúsculas.
token_type Identifica o tipo de token retornado. No momento, este campo sempre tem o valor Bearer.
refresh_token (opcional)

Esse campo só 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 com o token de ID

Um token de ID é um JWT (JSON Web Token), ou seja, um objeto JSON codificado em Base64 e assinado criptograficamente. Normalmente, é fundamental validar um token de ID antes de usá-lo. Porém, como você se comunica diretamente com o Google por um canal HTTPS sem intermediário e usa a chave secreta do cliente para se autenticar ao 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 seu app, é extremamente importante que os outros componentes 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 validar o token mesmo assim ao acessar as declarações no token de ID.

O payload de um 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 esse token de ID se destina. Precisa ser um dos IDs do cliente OAuth 2.0 do seu aplicativo.
exp sempre Data de validade ou após a qual o token de ID não pode ser aceito. Representado no formato Unix (segundos inteiros).
iat sempre A hora em que o token de ID foi emitido. Representado no formato Unix (segundos inteiros).
iss sempre O identificador do emissor para o emissor da resposta. Sempre https://accounts.google.com ou accounts.google.com para tokens de ID do Google.
sub sempre Um identificador para o usuário, único entre todas as Contas do Google e nunca reutilizado. Uma Conta do Google pode ter vários endereços de e-mail em diferentes momentos, mas o valor sub nunca muda. Use sub no seu aplicativo como a chave de identificador exclusivo do usuário. Comprimento máximo de 255 caracteres ASCII, com diferenciação entre maiúsculas e minúsculas.
at_hash Hash de token de acesso. Fornece a 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 de proteção 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 desse token. Isso pode acontecer no Google com 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. Fornecidos apenas se você incluiu o escopo email na sua solicitação. O valor dessa declaração pode não ser exclusivo da conta e pode mudar ao longo do tempo. Por isso, não use esse valor como o identificador principal para vincular ao registro do usuário. Também não é possível confiar no domínio da declaração email para identificar usuários de organizações do Google Workspace ou do Cloud. Use a declaração hd.
email_verified Verdadeiro se o endereço de e-mail do usuário tiver sido verificado; caso contrário, será falso.
family_name O sobrenome ou o sobrenome do usuário. Pode ser fornecido quando uma declaração name estiver presente.
given_name O nome ou o nome do usuário. Pode ser fornecido quando uma declaração name estiver presente.
hd O domínio associado ao Google Workspace ou à organização 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 somente a 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 estiver presente.
name O nome completo do usuário em formato de exibição. Pode ser fornecido quando:
  • O escopo da solicitação incluía a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando há declarações name, é possível usá-las para atualizar os registros do usuário do app. Observe que não há garantia de que essa reivindicação estará presente.

nonce O valor do nonce fornecido pelo app na solicitação de autenticação. Para aplicar proteção contra ataques de repetição, certifique-se de que ele seja apresentado apenas uma vez.
picture O URL da foto do perfil do usuário. Pode ser fornecido quando:
  • O escopo da solicitação incluía a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando há declarações picture, é possível usá-las para atualizar os registros do usuário do app. Observe que não há garantia de que essa reivindicação estará presente.

profile O URL da página de perfil do usuário. Pode ser fornecido quando:
  • O escopo da solicitação incluía a string "profile"
  • O token de ID é retornado de uma atualização de token

Quando há declarações profile, é possível usá-las para atualizar os registros do usuário do app. Observe que não há garantia de que essa reivindicação estará presente.

6. Autenticar o usuário

Após receber as informações do usuário do token de ID, consulte o banco de dados de usuários do seu aplicativo. Se o usuário já existir no seu banco de dados, inicie uma sessão de aplicativo para esse usuário caso todos os requisitos de login sejam atendidos pela resposta da API do Google.

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

Temas avançados

As seções a seguir descrevem a API Google OAuth 2.0 em mais detalhes. Essas informações são destinadas a desenvolvedores com requisitos avançados relacionados à 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 que você autentica o usuário. Para fazer isso, inclua os outros escopos necessários na solicitação de autenticação que você envia ao Google. Por exemplo, para adicionar a idade 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 é solicitado da maneira adequada na tela de consentimento. O token de acesso recebido do Google permite acessar todas as APIs relacionadas aos escopos de acesso que você solicitou e recebeu.

Tokens de atualização

Na sua solicitação de acesso à API, é possível solicitar que um token de atualização seja retornado durante a troca 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, adicione 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 só é possível receber um token de atualização na primeira vez que executar o fluxo de troca de código.
  • Há limites no número de tokens de atualização emitidos: um limite por combinação 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 param de funcionar.

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

É possível solicitar que o usuário autorize o app novamente definindo o parâmetro prompt como consent na sua solicitação de autenticação. Quando prompt=consent está incluído, a tela de permissão é exibida sempre que seu app solicita autorização de escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao seu projeto de APIs do Google. Por esse motivo, inclua prompt=consent somente quando necessário.

Para mais informações 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 oferece 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 recebida de API Console Credentials page, 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 de código de autorização básico, que exige um POST para o endpoint do token 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 #fragment do URI.
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 definidos no API Console Credentials page (incluindo o esquema HTTP ou HTTPS, maiúsculas e minúsculas e "/", se houver).
scope (obrigatório)

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

Se o valor de escopo profile estiver presente, o token de ID poderá incluir as declarações profile padrão do usuário, mas não há garantia de que ele o fará.

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

Além desses escopos específicos do OpenID, seu 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, seu parâmetro de escopo poderá 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 que você quer usar.

state Opcional, mas altamente recomendado

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

O state pode ser útil para correlacionar solicitações e respostas. Como seu redirect_uri pode ser adivinhado, o uso de um valor state pode aumentar a garantia de que uma conexão de entrada seja 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, será possível validar a resposta para garantir que a solicitação e a resposta foram originadas no mesmo navegador. Isso oferece proteção 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.
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 afetam o comportamento deles: page, popup, touch e wap.
hd (Opcional)

Simplifique o processo de login de 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 da conta precisa ser otimizada para contas nesse domínio. Para otimizar para contas de organização do Google Cloud em geral em vez de apenas um domínio de organização do Google Cloud, defina o valor de um asterisco (*): hd=*.

Não confie nessa otimização de interface para controlar quem pode acessar seu app, já que as solicitações do lado do cliente podem ser modificadas. validate 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 do token de ID hd está contida em um token de segurança do Google, por isso 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 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 autorização incremental com o fluxo de apps instalados.

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. A transmissão dessa 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 login múltiplo), o que pode ajudar a evitar problemas caso o app faça 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 de valores de string delimitados por espaço que especifica se o servidor de autorização solicita a reautenticação e o consentimento do usuário. Os valores possíveis são:
  • none

    O servidor de autorização não exibe telas de autenticação ou de consentimento do usuário. Ele retornará um erro se o usuário ainda não estiver autenticado e não tiver pré-configurado o consentimento para os escopos solicitados. Use none para verificar a autenticação e/ou o consentimento atuais.

  • 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. Assim, um usuário que tem várias contas no servidor de autorização pode selecionar entre as contas em que pode ter sessões atuais.

Se nenhum valor for especificado e o usuário não tiver autorizado o acesso anteriormente, uma tela de consentimento será exibida.

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, seu servidor precisa verificar a autenticidade de todos os tokens de ID recebidos dos apps clientes.

Confira a seguir situações comuns em que é possível enviar tokens de ID para o servidor:

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

Os tokens de ID são sensíveis e podem ser usados de forma indevida se forem interceptados. Garanta que esses tokens sejam processados com segurança, transmitindo-os somente por HTTPS e somente por dados POST ou em cabeçalhos de solicitação. Se você armazenar tokens de ID no servidor, também precisará armazená-los com segurança.

Algo que torna os tokens de ID úteis é o fato de que eles podem ser transmitidos em diferentes componentes do app. Esses componentes podem usar um token de ID como um mecanismo de autenticação leve para autenticar o app e o usuário. No entanto, antes de usar as informações no token de ID ou confiar nelas como uma declaração de que o usuário foi autenticado, é necessário validá-las.

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 prazo de validade (reivindicação exp) do token de ID não passou.
  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 2 a 5 envolvem apenas comparações de string e data, que são bastante diretas e não serão detalhadas 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 servidor ou dispositivo. Suponha que o valor do seu 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 em seu formulário 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 execute a validação localmente. Recupere o URI das chaves do documento de descoberta usando o valor de metadados jwks_uri. As solicitações para o endpoint de depuração podem ser limitadas ou sujeitas a erros intermitentes.

Como o Google altera 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 com muito mais eficiência do que usando o endpoint tokeninfo. Essa validação requer a recuperação e a análise de certificados e a realização das chamadas criptográficas apropriadas para verificar a assinatura. Felizmente, há bibliotecas bem depuradas, disponíveis em diversas linguagens, para fazer isso. Consulte jwt.io.

Coletar informações do perfil do usuário

Para mais informações de perfil do 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, você precisa incluir 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 email. Para especificar profile e email, inclua o seguinte parâmetro no URI de solicitação de autenticação:

    scope=openid%20profile%20email
  2. Adicione seu token de acesso ao cabeçalho de autorização e faça uma solicitação GET HTTPS ao endpoint userinfo, que você precisa recuperar 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 o 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. Dessa forma, talvez você não receba informações de todos os campos dos escopos de acesso autorizados.

O documento de descoberta

O protocolo OpenID Connect requer 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, userinfo e chaves públicas. O documento de descoberta do serviço OpenID Connect do Google pode ser recuperado de:

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

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

Veja um exemplo desse documento. Os nomes dos campos são aqueles especificados no OpenID Connect Discovery 1.0 (consulte o documento para ver os significados). Os valores são meramente ilustrativos e podem mudar, embora sejam copiados de uma versão recente do documento real do Google Discovery:

{
  "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"
  ]
}

Você pode conseguir evitar os ciclos de ida e volta HTTP armazenando em cache os valores do documento de descoberta. Os cabeçalhos HTTP padrão de armazenamento em cache são usados e devem ser respeitados.

Bibliotecas de cliente

As seguintes bibliotecas de cliente tornam a implementação do OAuth 2.0 mais simples por meio da integração com frameworks conhecidos:

Compliance com o OpenID Connect

O sistema de autenticação OAuth 2.0 do Google é compatível com os recursos obrigatórios da especificação OpenID Connect Core. Qualquer cliente projetado para trabalhar com o OpenID Connect precisa interoperar com esse serviço (com exceção do objeto de solicitação do OpenID).