OpenID Connect

O ponto de extremidade OpenID Connect do Google é certificado por OpenID.

As APIs OAuth 2.0 do Google podem ser usadas para autenticação e autorização. Este documento descreve nossa implementação OAuth 2.0 para autenticação, que está em conformidade com a especificação OpenID Connect e é certificada por OpenID . A documentação encontrada em Usando OAuth 2.0 para acessar APIs do Google também se aplica a este serviço. Se você deseja explorar este protocolo interativamente, recomendamos o Google OAuth 2.0 Playground . Para obter ajuda no Stack Overflow , marque suas perguntas com 'google-oauth'.

Configurando OAuth 2.0

Antes que seu aplicativo possa usar o sistema de autenticação OAuth 2.0 do Google para login de usuário, você deve configurar um projeto no Google API Console para obter credenciais OAuth 2.0, definir um URI de redirecionamento e (opcionalmente) personalizar as informações de marca que seus usuários veem no usuário tela de consentimento. Você também pode usar o API Console para criar uma conta de serviço, habilitar o faturamento, configurar a filtragem e realizar outras tarefas. Para obter mais detalhes, consulte a Ajuda Google API Console .

Obtenha credenciais OAuth 2.0

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

要查看给定OAuth 2.0凭据的客户端ID和客户端密钥,请单击以下文本: 选择凭据 。在打开的窗口中,选择您的项目和所需的凭证,然后单击“ 查看”

或者,从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥:

  1. Go to the Credentials page.
  2. 单击您的凭证名称或铅笔( )图标。您的客户ID和密码位于页面顶部。

Defina um URI de redirecionamento

O URI de redirecionamento que você definiu em API Console determina para onde o Google envia respostas às suas solicitações de autenticação .

要创建,查看或编辑给定OAuth 2.0凭据的重定向URI,请执行以下操作:

  1. Go to the Credentials page.
  2. 在页面的OAuth 2.0客户端ID部分中,点击一个凭据。
  3. 查看或编辑重定向URI。

如果“凭据”页面上没有OAuth 2.0客户端ID部分,则您的项目没有OAuth凭据。要创建一个,点击创建凭证

Personalize a tela de consentimento do usuário

Para seus usuários, a experiência de autenticação OAuth 2.0 inclui uma tela de consentimento que descreve as informações que o usuário está liberando e os termos que se aplicam. Por exemplo, quando o usuário efetua login, ele pode ser solicitado a conceder ao seu aplicativo 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 de scope , que seu aplicativo inclui em sua solicitação de autenticação . Você também pode 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, logotipo e o URL da página inicial. Você controla as informações de marca no API Console.

要启用项目的同意屏幕:

  1. Consent Screen page中打开Google API Console 。
  2. If prompted, select a project, or create a new one.
  3. 填写表格,然后点击保存

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

Captura de tela da página de consentimento

Acessando o serviço

O Google e terceiros fornecem bibliotecas que você pode usar para cuidar de muitos dos detalhes de implementação de autenticação de usuários e obtenção de acesso às APIs do Google. Os exemplos incluem o Google Sign-In e as bibliotecas cliente do Google , que estão disponíveis para uma variedade de 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 de HTTP que sustentam as bibliotecas disponíveis.

Autenticar o usuário

Autenticar o usuário envolve obter 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 comumente usadas para autenticar um usuário e obter um token de ID são chamadas de fluxo de "servidor" e de fluxo "implícito". O fluxo do servidor permite que o servidor backend 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 aplicativo JavaScript em execução no navegador) precisa acessar APIs diretamente em vez de por meio de seu servidor back-end.

Este documento descreve como executar o fluxo do servidor para autenticar o usuário. O fluxo implícito é significativamente mais complicado devido aos riscos de segurança no manuseio e no uso de tokens no lado do cliente. Se você precisar implementar um fluxo implícito, é altamente recomendável usar o Google Sign-In .

Fluxo do servidor

Certifique-se de configurar seu aplicativo no API Console para habilitá-lo a usar esses protocolos e autenticar seus usuários. Quando um usuário tenta fazer login no Google, você precisa:

  1. Crie um token de estado anti-falsificação
  2. Envie uma solicitação de autenticação ao Google
  3. Confirme o token de estado anti-falsificação
  4. code troca para token de acesso e token de ID
  5. Obtenha as informações do usuário a partir do token de ID
  6. Autenticar o usuário

1. Crie um token de estado anti-falsificação

Você deve proteger a segurança de seus usuários, evitando ataques de falsificação de solicitação. A primeira etapa é criar um token de sessão exclusivo que mantém o estado entre seu aplicativo e o cliente do usuário. Posteriormente, você combina este token de sessão exclusivo com a resposta de autenticação retornada pelo serviço Google OAuth Login 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 ).

Uma boa escolha 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. Outro é um hash gerado assinando algumas das variáveis ​​de estado da sessão com uma chave que é mantida em segredo em seu back-end.

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

PHP

Você deve fazer download da biblioteca cliente de APIs do Google para PHP para usar este exemplo.

// 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

Você deve baixar a biblioteca cliente de APIs do Google para Java para usar este exemplo.

// 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);

Pitão

Você deve fazer download da biblioteca 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. Envie 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 deste processo; Conexões HTTP são recusadas. Você deve recuperar o URI de base do documento de descoberta usando o valor de metadados authorization_endpoint . A discussão a seguir assume que o URI básico é https://accounts.google.com/o/oauth2/v2/auth .

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

  • client_id , que você obtém em API Console Credentials page.
  • response_type , que em uma solicitação de fluxo de código de autorização básica deve ser code . (Leia mais em response_type .)
  • scope , que em uma solicitação básica deve ser um openid email . (Leia mais no scope .)
  • redirect_uri deve ser o endpoint HTTP em seu servidor que receberá a resposta do Google. O valor deve corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou em API Console Credentials page. Se este valor não corresponder a um URI autorizado, a solicitação falhará com um erro redirect_uri_mismatch .
  • state deve incluir o valor do token de sessão exclusivo anti-falsificação, bem como qualquer outra informação necessária para recuperar o contexto quando o usuário retornar ao seu aplicativo, por exemplo, a URL inicial. (Leia mais no state .)
  • nonce é um valor aleatório gerado por seu aplicativo que permite a proteção de reprodução, quando presente.
  • login_hint pode ser o endereço de e-mail do usuário ou a sub string, que é equivalente ao do usuário do Google ID. Se você não fornecer um login_hint e o usuário estiver conectado no momento, a tela de consentimento incluirá uma solicitação de aprovação para liberar o endereço de e-mail do usuário para o seu aplicativo. (Leia mais em login_hint .)
  • Use o parâmetro hd para otimizar o fluxo do OpenID Connect para usuários de um determinado domínio do G Suite. (Leia mais em hd .)

Aqui está um exemplo de URI de autenticação OpenID Connect completo, 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 são obrigados a dar consentimento se seu aplicativo solicitar novas informações sobre eles ou se seu aplicativo solicitar acesso à conta que eles não tenham aprovado anteriormente.

3. Confirme o token de estado anti-falsificação

A resposta é enviada para o redirect_uri que você especificou 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ê deve confirmar se o state recebido do Google corresponde ao token de sessão que você criou na Etapa 1 . Essa verificação completa ajuda a garantir que o usuário, e não um script malicioso, esteja 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

Você deve fazer download da biblioteca cliente de APIs do Google para PHP para usar este exemplo.

// 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

Você deve baixar a biblioteca cliente de APIs do Google para Java para usar este exemplo.

// 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.");
}

Pitão

Você deve fazer download da biblioteca 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. code troca para token de acesso e token de ID

A resposta inclui um parâmetro de code , um código de autorização único que seu 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 terminal de token, que você deve recuperar do documento de descoberta usando o valor de metadados token_endpoint . A discussão a seguir assume que o ponto de extremidade é https://oauth2.googleapis.com/token . A solicitação deve incluir os seguintes parâmetros no corpo do POST :

Campos
code O código de autorização que é retornado da solicitação inicial .
client_id O ID do cliente obtido em API Console Credentials page, conforme descrito em Obter credenciais do OAuth 2.0 .
client_secret O segredo do cliente obtido em API Console Credentials page, conforme descrito em Obter credenciais do OAuth 2.0 .
redirect_uri Um URI de redirecionamento autorizado para o client_id fornecido especificado em API Console Credentials page, conforme descrito em Definir um URI de redirecionamento .
grant_type Este campo deve conter um valor de authorization_code , conforme definido na especificação OAuth 2.0 .

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

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 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 assinadas digitalmente pelo Google.
scope Os escopos de acesso concedido pelo access_token expressos como uma lista de strings delimitadas por espaço e com distinção entre maiúsculas e minúsculas.
token_type Identifica o tipo de token retornado. Neste momento, este campo sempre tem o valor Bearer .
refresh_token (opcional)

Este campo estará presente apenas se o parâmetro access_type foi definido como offline na solicitação de autenticação . Para obter detalhes, consulte Atualizar tokens .

5. Obtenha as informações do usuário a partir do token de ID

Um token de identificação é um JWT (JSON Web Token), ou seja, um objeto JSON codificado em Base64 com assinatura criptográfica. Normalmente, é fundamental que você valide um token de ID antes de usá-lo, mas como você está se comunicando diretamente com o Google por meio de um canal HTTPS sem intermediário e usando o segredo do seu cliente para se autenticar no Google, pode ter certeza de que o token receber realmente vem do Google e é válido. Se o seu servidor passa o token de ID para outros componentes do seu aplicativo, é 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 por base64url e analisar o JSON dentro, você provavelmente terminará validando o token de qualquer maneira ao acessar as declarações no token de ID.

Carga útil de um token de identificação

Um token de ID é um objeto JSON que contém um conjunto de pares nome / valor. Aqui está 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 reivindicações ):

Afirmação Forneceu Descrição
aud sempre O público ao qual este token de ID se destina. Deve ser um dos IDs de cliente OAuth 2.0 de seu aplicativo.
exp sempre Tempo de expiração em ou após o qual o token de ID não deve ser aceito. Representado em tempo Unix (segundos inteiros).
iat sempre A hora em que o token de ID foi emitido. Representado em tempo 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 é alterado. Use sub em seu aplicativo como a chave de identificador exclusivo para o usuário. Comprimento máximo de 255 caracteres ASCII com distinção entre maiúsculas e 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 proteger contra ataques de falsificação de solicitação 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 está solicitando o token de ID não é a mesma que o público do token de ID. Esse pode ser o caso no Google para aplicativos híbridos em que um aplicativo da web e um aplicativo Android têm um client_id OAuth 2.0 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 para este usuário e não é adequado para uso como uma chave primária. Fornecido apenas se seu escopo incluiu o valor do escopo do email .
email_verified Verdadeiro se o endereço de e-mail do usuário foi verificado; caso contrário, false.
family_name O (s) sobrenome (s) ou último (s) nome (s) do usuário. Pode ser fornecido quando houver uma reivindicação de name .
given_name O (s) nome (s) ou o (s) primeiro (s) nome (s) do usuário. Pode ser fornecido quando houver uma reivindicação de name .
hd O domínio do G Suite hospedado do usuário. Fornecido apenas se o usuário pertencer a um domínio hospedado.
locale A localidade do usuário, representada por uma tag de idioma BCP 47 . Pode ser fornecido quando houver uma reivindicação de name .
name O nome completo do usuário, em uma forma exibível. Pode ser fornecido quando:
  • O escopo da solicitação incluiu a string "perfil"
  • O token de ID é retornado de uma atualização de token

Quando as declarações de name estão presentes, você pode usá-los para atualizar os registros de usuário do seu aplicativo. Observe que essa reivindicação nunca tem a garantia de estar presente.

nonce O valor do nonce fornecido pelo seu aplicativo na solicitação de autenticação. Você deve reforçar a proteção contra ataques de repetição, garantindo que ela seja apresentada 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 "perfil"
  • O token de ID é retornado de uma atualização de token

Quando as reivindicações de picture estão presentes, você pode usá-las para atualizar os registros de usuário do seu aplicativo. Observe que essa reivindicação nunca tem a garantia de estar presente.

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

Quando as declarações de profile estão presentes, você pode usá-las para atualizar os registros de usuário do seu aplicativo. Observe que essa reivindicação nunca tem a garantia de estar presente.

6. Autentique o usuário

Depois de obter as informações do usuário do token de ID, você deve consultar o banco de dados do usuário do seu aplicativo. Se o usuário já existe em seu banco de dados, você deve iniciar uma sessão de aplicativo para esse usuário se todos os requisitos de login forem atendidos pela resposta da API do Google.

Se o usuário não existir em seu banco de dados de usuário, você deve redirecionar o usuário para seu fluxo de inscrição de novo usuário. Você pode registrar automaticamente o usuário com base nas informações que recebe do Google ou, pelo menos, pode preencher previamente muitos dos campos exigidos em seu formulário de registro. Além das informações no token de ID, você pode obter informações adicionais de perfil de usuário em nossos terminais de perfil de usuário.

Tópicos avançados

As seções a seguir descrevem a API do Google OAuth 2.0 em mais detalhes. Essas 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 OAuth 2.0 para autenticação é que seu aplicativo pode obter 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 de que precisa 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, passe um parâmetro de escopo do openid email https://www.googleapis.com/auth/profile.agerange.read . O usuário é solicitado de forma adequada na tela de consentimento . O token de acesso que você recebe de volta do Google permite que você acesse todas as APIs relacionadas aos escopos de acesso solicitados e concedidos.

Atualizar tokens

Em sua solicitação de acesso à API, você pode solicitar que um token de atualização seja retornado durante a troca de code . Um token de atualização fornece a seu aplicativo acesso contínuo às APIs do Google enquanto o usuário não está presente em seu aplicativo. Para solicitar um token de atualização, adicione definir o parâmetro access_type para offline em sua solicitação de autenticação .

Considerações:

  • Certifique-se de armazenar o token de atualização com segurança e permanentemente, porque você só pode obter um token de atualização na primeira vez que executar o fluxo de troca de código.
  • Existem limites para o número de tokens de atualização que são emitidos: um limite por combinação de cliente / usuário e outro por usuário em todos os clientes. Se o seu aplicativo solicitar muitos tokens de atualização, ele pode atingir esses limites e, nesse caso, os tokens de atualização mais antigos param de funcionar.

Para obter mais informações, consulte Atualizando um token de acesso (acesso offline) .

Você pode solicitar que o usuário autorize novamente seu aplicativo, definindo o parâmetro prompt para consent em sua solicitação de autenticação . Quando prompt=consent é incluído, a tela de consentimento é exibida sempre que seu aplicativo solicita autorização de escopos de acesso, mesmo se todos os escopos foram concedidos anteriormente ao seu projeto de APIs do Google. Por esse motivo, inclua prompt=consent apenas quando necessário.

Para obter mais informações sobre o parâmetro prompt , consulte prompt na tabela de 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 de ID do cliente obtida em API Console Credentials page, conforme descrito em Obter credenciais do OAuth 2.0 .
nonce (Obrigatório) Um valor aleatório gerado pelo seu aplicativo que ativa a proteção de reprodução.
response_type (Obrigatório) Se o valor for code , inicia um fluxo de código de autorização básico , exigindo um POST para o terminal do token para obter 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 URI #fragment
redirect_uri (Obrigatório) Determina para onde a resposta é enviada. O valor deste parâmetro deve corresponder exatamente a um dos valores de redirecionamento autorizados que você definiu em API Console Credentials page (incluindo o esquema HTTP ou HTTPS, caso e final '/', se houver).
scope (Obrigatório)

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

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

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

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

Para obter 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 deseja usar.

state (Opcional, mas altamente recomendado)

Uma string opaca que é rodada no protocolo; ou seja, ele é retornado como um parâmetro URI no fluxo Básico e no identificador URI #fragment 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 de state pode aumentar sua garantia de que uma conexão de entrada é o resultado de uma solicitação de autenticação iniciada por seu aplicativo. Se você gerar uma string aleatória ou codificar o hash de algum estado do cliente (por exemplo, um cookie) nesta variável de state , você pode validar a resposta para garantir adicionalmente que a solicitação e a resposta foram originadas no mesmo navegador. Isso fornece proteção contra ataques, como falsificação de solicitação entre sites.

access_type (Opcional) Os valores permitidos são offline e online . O efeito é documentado no Acesso offline ; se um token de acesso estiver sendo solicitado, o cliente não receberá um token de atualização, a menos que um valor 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 seguintes valores são especificados e aceitos pelos servidores do Google, mas não afetam seu comportamento: page , popup , touch e wap .
hd (Opcional)

O parâmetro hd (domínio hospedado) simplifica o processo de login para contas hospedadas do G Suite. Ao incluir o domínio do usuário do G Suite (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 do G Suite geralmente, em vez de apenas um domínio, defina o valor de um asterisco ( * ): hd=* .

Não confie nessa otimização da IU para controlar quem pode acessar seu aplicativo, pois as solicitações do lado do cliente podem ser modificadas. Certifique-se de validar se o token de ID retornado tem um valor de declaração hd que corresponde ao que você espera (por exemplo, mycolledge.edu ). Ao contrário do parâmetro de solicitação, a declaração hd token de ID está contida em um token de segurança do Google, portanto, o valor pode ser confiável.

include_granted_scopes (Opcional) Se este 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 .

Observe que você não pode fazer autorização incremental com o fluxo do aplicativo instalado.

login_hint (Opcional) Quando seu aplicativo sabe qual usuário está tentando autenticar, ele pode fornecer esse parâmetro como uma dica para o servidor de autenticação. Passar esta dica suprime o seletor de conta e preenche previamente 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 que ocorrem se seu aplicativo loga 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 sequência que especifica se o servidor de autorização solicita ao usuário uma reautenticação e consentimento. Os valores possíveis são:
  • none

    O servidor de autorização não exibe nenhuma tela de autenticação ou consentimento do usuário; ele retornará um erro se o usuário ainda não estiver autenticado e não tiver consentimento pré-configurado para os escopos solicitados. Você pode usar none para verificar a autenticação e / ou consentimento existente.

  • consent

    O servidor de autorização solicita o consentimento do usuário antes de retornar as 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 possui várias contas no servidor de autorização selecione entre as várias contas para as quais ele pode ter sessões atuais.

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

Validando um token de ID

Você precisa validar todos os tokens de ID em seu servidor, a menos que saiba que eles vieram diretamente do Google. Por exemplo, seu servidor deve verificar como autênticos todos os tokens de ID que recebe de seus aplicativos cliente.

A seguir estão situações comuns em que você pode enviar tokens de ID para o 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 confidenciais e podem ser mal utilizados se interceptados. Você deve garantir que esses tokens sejam tratados com segurança, transmitindo-os apenas por HTTPS e apenas por meio de dados POST ou dentro dos cabeçalhos de solicitação. Se você armazenar tokens de ID em seu servidor, também deverá armazená-los com segurança.

Uma coisa que torna os tokens de ID úteis é o fato de que você pode passá-los entre diferentes componentes do seu aplicativo. Esses componentes podem usar um token de ID como um mecanismo de autenticação leve, autenticando o aplicativo e o usuário. Mas antes de usar as informações no token de ID ou confiar nelas como uma afirmação de que o usuário foi autenticado, você deve validá-las.

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

  1. Verifique se o token de ID está devidamente assinado 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 de aud no token de ID é igual ao ID do cliente do seu aplicativo.
  4. Verifique se o tempo de expiração (declaração de 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 corresponda a um domínio aceito hospedado pelo G Suite.

As etapas 2 a 5 envolvem apenas comparações de strings e datas, que são bastante diretas, portanto, não as detalharemos aqui.

A primeira etapa é mais complexa e envolve a verificação de assinatura criptográfica. Para fins de depuração , você pode usar o ponto de extremidade tokeninfo do Google para comparar com o processamento local implementado em seu servidor ou dispositivo. Suponha que o valor do token de seu ID seja XYZ123 . Em seguida, você desreferencie o URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Se a assinatura do token for válida, a resposta seria a carga útil 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 do endpoint de chaves e execute a validação localmente. Você deve recuperar o URI das chaves do documento de descoberta usando o valor de metadados jwks_uri . As solicitações para o ponto de extremidade de depuração podem ser limitadas ou, de outra forma, sujeitas a erros intermitentes.

Como o Google altera suas chaves públicas raramente, você pode armazená-las em cache usando as diretivas de cache da resposta HTTP e, na grande maioria dos casos, realizar validação local com muito mais eficiência 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, existem bibliotecas bem depuradas disponíveis em uma ampla variedade de linguagens para fazer isso (consulte jwt.io ).

Obtenção de informações de perfil de usuário

Para obter informações adicionais de perfil sobre o usuário, você pode usar o token de acesso (que seu aplicativo recebe durante o fluxo de autenticação ) e o padrão OpenID Connect :

  1. Para ser compatível com OpenID, você deve incluir os valores de escopo do openid profile em sua solicitação de autenticação .

    Se quiser que o endereço de e-mail do usuário seja incluído, você pode especificar um valor de escopo adicional de email . Para especificar o profile e o e- email , você pode incluir o seguinte parâmetro em seu 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 HTTPS GET para o terminal userinfo, que você deve recuperar do documento de descoberta usando o valor de metadados userinfo_endpoint . A resposta 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 suas organizações podem optar por fornecer ou reter determinados campos, portanto, você pode não obter informações para todos os campos de seus escopos de acesso autorizados.

O documento de descoberta

O protocolo OpenID Connect requer o uso de vários terminais 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 contendo pares chave-valor que fornecem detalhes sobre a configuração do provedor OpenID Connect, incluindo os URIs da autorização , token, revogação, userinfo e endpoints de chaves públicas. O documento de descoberta do serviço OpenID Connect do Google pode ser obtido em:

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

Para usar os serviços OpenID Connect do Google, você deve codificar o URI do documento Discovery ( https://accounts.google.com/.well-known/openid-configuration ) em seu 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 de 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 para Google.

Aqui está um exemplo de tal documento; os nomes dos campos são aqueles especificados no OpenID Connect Discovery 1.0 (consulte esse documento para seus 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 evitar uma viagem de ida e volta de HTTP armazenando em cache os valores do documento de descoberta. Os cabeçalhos de cache HTTP padrão são usados ​​e devem ser respeitados.

Bibliotecas cliente

As seguintes bibliotecas cliente tornam a implementação do OAuth 2.0 mais simples, integrando-se a estruturas populares:

Conformidade com OpenID Connect

O sistema de autenticação OAuth 2.0 do Google oferece suporte aos recursos necessários da especificação OpenID Connect Core . Qualquer cliente projetado para funcionar com o OpenID Connect deve interoperar com este serviço (com exceção do objeto de solicitação OpenID ).