OpenID Connect

As APIs OAuth 2.0 do Google podem ser usadas para autenticação e autorização. Este documento descreve a implementação do OAuth 2.0 para autenticação, que está em conformidade com a especificação OpenID Connect e tem a certificação 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 no Stack Overflow (em inglês), marque suas perguntas com "##99;google-oauth'.

Observação: se você quiser incluir um botão "quot;Fazer login com o Google" no seu site ou app, recomendamos usar o Google Identity Services, nossa biblioteca de cliente de login criada no protocolo OpenID Connect e que fornece tokens de ID formatados do OpenID Connect.

Configurar o OAuth 2.0

Antes que seu aplicativo possa usar o sistema de autenticação OAuth 2.0 do Google para o login do usuário, você deve configurar um projeto no Google API Console para receber credenciais do OAuth 2.0, definir um URI de redirecionamento e, como opção, 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 o faturamento, configurar a filtragem e realizar outras tarefas. Para saber mais, consulte a Ajuda Google API Console.

Receber credenciais do OAuth 2.0

Você precisa de credenciais do OAuth 2.0, como o ID do cliente 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 as respostas para as 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 os 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á lançando 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. Solicite 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 marca, como nome do produto, logotipo e um URL da página inicial. Você controla as informações de 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 verá quando uma combinação de escopos do OAuth 2.0 e do Google Drive estiver presente na solicitação. Essa caixa de diálogo genérica foi gerada usando o Playground do Google OAuth 2.0. Portanto, ela não inclui informações de marca que seriam definidas no API Console.

Como acessar o serviço

O Google e terceiros oferecem bibliotecas que podem ser usadas para cuidar de muitos detalhes de implementação da autenticação de usuários e do acesso às APIs do Google. Alguns exemplos são o Google Identity Services e as bibliotecas de cliente do Google, que estão disponíveis para várias plataformas.

Observação: devido às implicações de segurança para implementar corretamente a implementação, recomendamos que você aproveite uma biblioteca ou um serviço pré-gravado. A autenticação correta dos usuários é importante para a segurança deles. Usar códigos bem depurados criados por outras pessoas geralmente é uma prática recomendada. Para mais informações, consulte Bibliotecas de cliente.

Se você decidir não usar uma biblioteca, siga as instruções no restante deste documento, que descreve os fluxos de solicitação HTTP que servem como base para as bibliotecas disponíveis.

Autenticar o usuário

Autenticar o usuário envolve conseguir e receber um token de ID. Os tokens de ID são um recurso padronizado do OpenID Connect desenvolvido para compartilhar declarações de identidade na Internet.

As abordagens mais usadas para autenticar um usuário e conseguir um token de ID são chamadas de fluxo "server" e de "quot;implicit" O fluxo do servidor permite que o servidor de 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 (geralmente um app JavaScript em execução no navegador) precisa acessar as APIs diretamente em vez de usar o servidor de back-end.

Este documento descreve como executar o fluxo do servidor para autenticar o usuário. O fluxo implícito é muito mais complicado devido a riscos de segurança ao processar e usar tokens no lado do cliente. Se você precisar implementar um fluxo implícito, recomendamos usar o Google Identity Services.

Fluxo do servidor

Configure seu app no API Console para que ele possa usar esses protocolos e autenticar seus 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. Troque code por token de acesso e token de ID
5. Receber informações do usuário do token de ID
6. Autenticar o usuário

1. Criar um token de estado antifalsificação

É preciso proteger a segurança dos usuários, evitando ataques de falsificação de solicitações. A primeira etapa é criar um token de sessão exclusivo que mantém o estado entre seu app e o cliente do usuário. Mais tarde, você fará 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. Esses tokens costumam ser chamados de tokens de falsificação de solicitações entre sites (CSRF, na sigla em inglês).

Uma boa opção para um token de estado é uma string de 30 caracteres construídos usando um gerador de números aleatórios de alta qualidade. Outro é um hash gerado assinando 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 a geração de tokens de sessão exclusivos.

PHP

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

// 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 de cliente das 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 de cliente das 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 GET de HTTPS com os parâmetros de URI apropriados. Observe o uso de HTTPS em vez de HTTP em todas as etapas deste processo. Conexões HTTP são recusadas. Recupere o URI base do 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 você recebe 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. Leia 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 seu 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 ConsoleCredentials 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 único antifalsificação, bem como qualquer outra informação necessária para recuperar o contexto quando o usuário retornar ao aplicativo, por exemplo, o URL inicial. Leia mais em state.
• nonce é um valor aleatório gerado pelo app, que ativa a proteção de 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 informar 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 o 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 Cloud. Leia mais em hd.

Observação: somente os parâmetros mais usados estão listados acima. Para ver uma lista completa e mais detalhes sobre todos os parâmetros, consulte Parâmetros de URI de autenticação.

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

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=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Os usuários precisam dar consentimento se o app solicitar novas informações sobre eles ou se o aplicativo 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 da sessão criado na Etapa 1. Essa verificação de ida e volta ajuda a garantir que o usuário, 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

Faça o download da biblioteca de cliente das APIs do Google para PHP 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->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Faça o download da biblioteca de cliente das 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 de cliente das 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 code por tokens de acesso e 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 de ID. Seu servidor faz essa troca enviando uma solicitação POST de HTTPS. 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. Na discussão a seguir, pressupomos que o endpoint seja 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 obtido no API Console Credentials page, conforme descrito em Acessar credenciais do OAuth 2.0.
client_secret	A chave secreta do cliente que você recebe do API ConsoleCredentials page, conforme descrito em Receber credenciais do OAuth 2.0.
redirect_uri	Um URI de redirecionamento autorizado para o client_id especificado no Credentials page API Console, conforme descrito em Definir um URI de redirecionamento.
grant_type	Este 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 a essa 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 do usuário que foram assinadas digitalmente pelo Google.
scope	Os escopos de acesso concedidos por access_token expressos como uma lista de strings delimitadas por espaço e com diferenciação entre maiúsculas e minúsculas.
token_type	Identifica o tipo de token retornado. No momento, esse campo sempre tem o valor Bearer.
refresh_token	(opcional) Este campo só estará presente se o parâmetro access_type tiver sido definido como offline na solicitação de autenticação. Veja mais detalhes em Atualizar tokens.

Observação:há um limite para o número de tokens por conta de usuário do Google, e qualquer solicitação de autenticação acima desse limite pode invalidar um token de atualização pendente. Para detalhes, consulte Expiração do token.

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

Um token de ID é um JWT (JSON Web Token), ou seja, um objeto JSON codificado em Base64 assinado. Normalmente, é importante validar um token de ID antes de usá-lo. No entanto, como você está se comunicando diretamente com o Google por meio de um canal HTTPS sem intermediário e usando sua chave secreta do cliente para se autenticar no Google, pode ter certeza de que o token recebido é realmente do Google e válido. Caso seu servidor transmita 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 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 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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

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

Reivindicar	Fornecido	Descrição
aud	sempre	É o público-alvo deste token de ID. Precisa ser um dos IDs do cliente do OAuth 2.0 do seu aplicativo.
exp	sempre	O prazo de validade do token de ID (ou após) não pode ser aceito. Representado no horário Unix (segundos inteiros).
iat	sempre	A hora em que o token de código foi emitido. Representado no horário Unix (segundos inteiros).
iss	sempre	O identificador do emissor para a emissora 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, 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 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.
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 se proteger contra ataques de falsificação de solicitações entre sites, mas se você seguir a Etapa 1 e a Etapa 3, não é necessário verificar o token de acesso.
azp		É o client_id do apresentador autorizado. Essa reivindicação é necessária somente quando a parte que solicita o token de ID não é igual ao público-alvo do token de ID. Esse pode ser o caso do Google para apps híbridos em que um app da Web e um app Android têm um OAuth 2.0 client_id diferente, mas compartilham o mesmo projeto de APIs do Google.
email		O endereço de e-mail do usuário. Este valor pode não ser exclusivo do usuário e não é adequado para uso como chave primária. Fornecido apenas se o escopo incluir o valor do escopo email.
email_verified		Verdadeiro se o endereço de e-mail do usuário tiver sido verificado. Caso contrário, será falso.
family_name		Sobrenomes ou sobrenomes do usuário. Pode ser informado quando há uma declaração name.
given_name		O nome ou os nomes fornecidos pelo usuário. Pode ser informado quando há uma declaração name.
hd		O domínio associado à organização do Google Cloud do usuário. Fornecido apenas se o usuário pertencer a uma organização do Google Cloud.
locale		A localidade do usuário, representada por uma tag de idioma BCP 47. Pode ser informado quando uma declaração name estiver presente.
name		O nome completo do usuário, em formato de exibição. Podem ser fornecidos quando: O escopo da solicitação incluiu a string "profile" O token de ID é retornado de uma atualização de token. Quando declarações name estão presentes, você pode usá-las para atualizar os registros do usuário do seu app. Não há garantias de que essa reivindicação esteja presente.
nonce		O valor de nonce fornecido pelo app na solicitação de autenticação. Aplique a proteção contra ataques de repetição garantindo que ele seja apresentado apenas uma vez.
picture		O URL da foto do perfil do usuário. Podem ser fornecidos quando: O escopo da solicitação incluiu a string "profile" O token de ID é retornado de uma atualização de token. Quando declarações picture estão presentes, você pode usá-las para atualizar os registros do usuário do seu app. Não há garantias de que essa reivindicação esteja presente.
profile		O URL da página de perfil do usuário. Podem ser fornecidos quando: O escopo da solicitação incluiu a string "profile" O token de ID é retornado de uma atualização de token. Quando declarações profile estão presentes, você pode usá-las para atualizar os registros do usuário do seu app. Não há garantias de que essa reivindicação esteja presente.

6. Autenticar o usuário

Depois de receber as informações do usuário do token de ID, consulte o banco de dados do usuário do seu app. Se o usuário já existir no banco de dados, você precisará iniciar 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 banco de dados do usuário, redirecione-o para o fluxo de inscrição de novo usuário. É possível registrar o usuário automaticamente com base nas informações recebidas do Google ou, no mínimo, preencher previamente alguns dos campos necessários no formulário de registro. Além das informações no token de ID, você pode receber informações adicionais do perfil do usuário nos endpoints do perfil.

Tópicos avançados

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

Acesso a outras APIs do Google

Uma das vantagens de usar 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 isso, inclua os outros escopos necessários na solicitação de autenticação enviada ao Google. Por exemplo, para adicionar a faixa etária do usuário à sua 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 consentimento. Com o token de acesso recebido do Google, é possível acessar todas as APIs relacionadas aos escopos de acesso solicitados e concedidos.

Observação: se o aplicativo solicitar muitos escopos, a tela de consentimento conterá muitas linhas de texto. Quanto mais escopos seu aplicativo solicitar, menor será a probabilidade de consentimento do usuário. Portanto, o aplicativo deve solicitar apenas os escopos necessários.

Tokens de atualização

Na sua solicitação de acesso à API, você pode solicitar um token de atualização a ser retornado durante a troca code. Um token de atualização fornece 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 solicitação de autenticação.

Considerações:

• Armazene o token de atualização de maneira segura e permanente, porque você só poderá receber um token de atualização na primeira vez que executar 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 deixam de funcionar.

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

Solicitação de novo consentimento

Você pode solicitar que o usuário autorize o app novamente. Para fazer isso, defina o parâmetro prompt como consent na sua solicitação de autenticação. Quando prompt=consent é 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 projeto de APIs do Google. Por esse motivo, só inclua prompt=consent 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 recebida do API Console Credentials page, conforme descrito em Acessar 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 básico de código de autorização, que exige um POST no endpoint para receber os tokens. Se o valor for token id_token ou id_token token, um fluxo implícito será iniciado, 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 que você definiu no API Console Credentials page (incluindo o esquema HTTP ou HTTPS, o caso, e '/' à direita, 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 incluirá 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ço. 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 é ida e volta no protocolo, ou seja, é 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 o valor redirect_uri pode ser adivinhado, usar um valor state pode aumentar a garantia de que uma conexão de entrada é resultado de uma solicitação de autenticação iniciada pelo seu aplicativo. 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 sejam 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 é 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 o 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 para autenticação e consentimento. Os valores a seguir são especificados e aceitos pelos servidores do Google, mas não afetam o comportamento: 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), você pode indicar que a IU de seleção de conta deve ser otimizada para contas nesse domínio. Para otimizar para contas da organização do Google Cloud em vez de apenas um domínio da organização do Google Cloud, defina um valor de um asterisco (*): hd=*. Não dependa dessa otimização da IU para controlar quem pode acessar seu aplicativo, porque as solicitações do lado do cliente podem ser modificadas. Confirme se o token de ID retornado tem um valor de declaração hd correspondente ao esperado (por exemplo, mycolledge.edu). Ao contrário do parâmetro de solicitação, a declaração hd de token de ID está contida em um token de segurança do Google para que o valor seja 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 seu app sabe qual usuário está tentando autenticar, esse parâmetro pode ser uma dica para o servidor de autenticação. A transmissão dessa dica suprime o seletor de contas e pré-preenche 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ço de valores de string que especifica se o servidor de autorização solicita ao usuário a reautenticação e o consentimento. 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 tiver sido autenticado e não tiver o consentimento pré-configurado 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 com várias contas no servidor de autorização pode escolher entre várias contas em que pode ter sessões atuais. Se nenhum valor for especificado e o usuário não tiver autorizado o acesso, uma tela de consentimento será exibida.

Validar um token de ID

Você precisa validar todos os tokens de ID no servidor, a menos que saiba que eles vieram diretamente do Google. Por exemplo, seu servidor precisa verificar como autênticos todos os tokens de ID que recebem dos seus apps clientes.

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

• Enviar 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 confidenciais e podem ser usados de forma indevida em caso de interceptação. Você precisa garantir que esses tokens sejam processados com segurança pela transmissão somente por HTTPS e somente por dados POST ou dentro de cabeçalhos de solicitação. Se você armazenar tokens de ID no seu servidor, também precisará armazená-los com segurança.

Os tokens de ID são úteis porque você pode transmiti-los em diferentes componentes do app. Esses componentes podem usar um token de ID como um mecanismo leve de autenticação que autentica o app e o usuário. Mas, antes de usar as informações no token de ID ou confiar nelas como uma declaração de que o usuário fez a autenticação, você precisa validá-las.

A validação de um token de código 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 hd parameter 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 somente comparações de strings e datas que são bastante simples. Portanto, não serão detalhadas aqui.

A primeira etapa é mais complexa e envolve a verificação de assinatura criptográfica. Para 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, remova a referência do 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 formato 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 realize a validação localmente. Recupere o URI de 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, você pode armazená-las em cache usando as diretivas de cache da resposta HTTP e, na grande maioria dos casos, executa a validação local de maneira muito mais eficiente do que usando o endpoint tokeninfo. Essa validação requer a recuperação e 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 uma grande variedade de linguagens para fazer isso (consulte jwt.io).

Como conseguir informações de perfil do usuário

Para ver mais informações de perfil sobre o usuário, use o token de acesso recebido pelo aplicativo 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 do 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 seu token de acesso ao cabeçalho de autorização e faça uma solicitação HTTPS GET ao endpoint de informações do usuário, que você precisa recuperar do documento de descoberta usando o valor de metadados userinfo_endpoint. A resposta do userinfo inclui informações sobre o usuário, conforme descrito em OpenID Connect Standard Claims e o valor de metadados claims_supported do documento Discovery. Os usuários ou as organizações deles podem escolher fornecer ou reter determinados campos. Por isso, talvez você não receba informações de todos os campos para os escopos de acesso autorizados.

Documento de descoberta

O protocolo OpenID Connect requer o uso de vários endpoints para autenticar usuários e para 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 JSON, encontrado em um local conhecido contendo 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:

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

Para usar os serviços de OpenID Connect do Google, codifique o URI do documento Discovery (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 URIs de endpoints dele 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 base das solicitações de autenticação enviadas ao Google.

Veja um exemplo desse documento. Os nomes dos campos são os especificados no OpenID Connect Discovery 1.0 (consulte esse documento para saber o significado deles). 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 evitar uma ida e volta no HTTP armazenando os valores do documento do Discovery em cache. Os cabeçalhos HTTP padrão são usados e devem ser respeitados.

Bibliotecas de cliente

As seguintes bibliotecas de cliente facilitam a implementação do OAuth 2.0 por meio da integração com frameworks conhecidas:

• Biblioteca de cliente de APIs do Google para Java
• Biblioteca de cliente de APIs do Google para Python
• Biblioteca de cliente de APIs do Google para .NET
• Biblioteca de cliente de APIs do Google para Ruby
• Biblioteca de cliente de APIs do Google para PHP
• Biblioteca OAuth 2.0 para o Google Web Toolkit
• Ferramentas do Google para controladores OAuth 2.0 do Mac

Compliance com o OpenID Connect

O sistema de autenticação OAuth 2.0 do Google aceita os recursos obrigatórios da especificação OpenID Connect Core. Qualquer cliente projetado para funcionar com o OpenID Connect precisa interoperar com esse serviço (exceto o objeto de solicitação OpenID).