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 do OpenID Connect e tem a certificação do OpenID. A documentação encontrada em Como usar o OAuth 2.0 para acessar as APIs do Google também se aplica a esse serviço. Se você quiser explorar esse protocolo de forma interativa, recomendamos o Google OAuth 2.0 Playground. Para receber ajuda no Stack Overflow, marque suas perguntas com "google-oauth".

Observação:para incluir um botão "Fazer login com o Google" no seu site, use o Google Identity Services, nossa biblioteca de cliente de login criada com base no protocolo OpenID Connect. Essa biblioteca oferece tokens de ID formatados do OpenID Connect. Os apps Android nativos precisam usar a API Credential Manager para implementar o fluxo de "Fazer login com o Google".

Configurar o OAuth 2.0

Antes que seu aplicativo possa usar o sistema de autenticação OAuth 2.0 do Google para login do usuário, você precisa configurar um projeto no para receber as 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. Também é possível usar o para criar uma conta de serviço, ativar o faturamento, configurar a filtragem e fazer outras tarefas. Para mais detalhes, consulte a ajuda .

Receber credenciais do OAuth 2.0

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

Definir um URI de redirecionamento

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

Personalizar a tela de consentimento do usuário

Para os 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 aplicáveis. Por exemplo, quando o usuário faz login, ele pode ser solicitado a conceder ao app acesso ao endereço de e-mail e às informações básicas da conta. Você solicita acesso a essas informações usando o parâmetro scope, que o app inclui na solicitação de autenticação. Também é possível usar escopos para solicitar acesso a outras APIs do Google.

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

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 estiver presente na solicitação. Essa caixa de diálogo genérica foi gerada usando o Google OAuth 2.0 Playground, então ela não inclui informações de marca que seriam definidas no .

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. Exemplos incluem os Serviços de identidade do Google 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 da correção da implementação, recomendamos que você use uma biblioteca ou um serviço predefinido. A autenticação adequada dos usuários é importante para a segurança deles e sua, e o uso de códigos bem depurados escritos por outras pessoas é geralmente uma prática recomendada. Para mais informações, consulte Bibliotecas de cliente.

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

Autenticar o usuário

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

As abordagens mais usadas 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 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 (normalmente um app JavaScript executado no navegador) precisa acessar 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 aos riscos de segurança no processamento e 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 o app no para permitir que ele use esses protocolos e autentique os usuários. Quando um usuário tentar fazer login com o Google, você precisará fazer o seguinte:

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

1. Criar um token de estado antifraude

Você precisa proteger a segurança dos seus usuários impedindo ataques de falsificação de solicitações. A primeira etapa é criar um token de sessão exclusivo que mantenha o estado entre o app e o cliente do usuário. Depois, você vai corresponder esse token de sessão exclusivo à 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 malicioso. Esses tokens são frequentemente 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 cerca de 30 caracteres construída usando um gerador de números aleatórios de alta qualidade. Outro é um hash gerado ao assinar algumas das suas variáveis de estado de sessão com uma chave que é mantida em segredo no back-end.

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

PHP

Faça o download da biblioteca de 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

Faça o download da biblioteca de 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);

Python

É necessário fazer o download da biblioteca de cliente de APIs do Google para Python para usar este exemplo.

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

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

A próxima etapa é formar uma solicitação GET HTTPS com os parâmetros de URI apropriados. Use HTTPS em vez de HTTP em todas as etapas do processo. As conexões HTTP são recusadas. É necessário extrair 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 seja https://accounts.google.com/o/oauth2/v2/auth.

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

• client_id, que você recebe do .
• 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. (Saiba mais em scope.)
• redirect_uri precisa ser o endpoint HTTP no seu servidor que vai receber a resposta do Google. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados do cliente OAuth 2.0, que você configurou no . 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 antifraude, bem como qualquer outra informação necessária para recuperar o contexto quando o usuário retornar ao seu aplicativo, por exemplo, o URL inicial. (Saiba mais em state.)
• nonce é um valor aleatório gerado pelo app que ativa a proteção contra repetição quando presente.
• login_hint pode ser o endereço de e-mail do usuário ou a string sub, que é equivalente ao ID do Google do usuário. Se você não fornecer um login_hint e o usuário estiver conectado, a tela de consentimento vai 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 Workspace ou do Cloud. Saiba mais em hd.

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

Confira um exemplo de URI de autenticação do 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=[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 app solicitar acesso à conta que eles não aprovaram anteriormente.

3. Confirmar o token de estado antifraude

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, confirme 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, esteja fazendo a solicitação.

O código a seguir demonstra a confirmação dos tokens de sessão criados na etapa 1:

PHP

Faça o download da biblioteca de 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

Faça o download da biblioteca de 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.");
}

Python

É necessário fazer o download da biblioteca de cliente de APIs do Google para Python para usar este exemplo.

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

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

A resposta inclui um parâmetro code, um código de autorização único que o servidor pode trocar por um token de acesso e um token de ID. O servidor faz essa troca enviando uma solicitação POST HTTPS. A solicitação POST é enviada para o endpoint do token, que você precisa extrair do documento de descoberta usando o valor de metadados token_endpoint. A discussão a seguir pressupõe 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 que você recebe do , conforme descrito em Receber credenciais do OAuth 2.0.
client_secret	A chave secreta do cliente que você recebe do , conforme descrito em Receber credenciais do OAuth 2.0.
redirect_uri	Um URI de redirecionamento autorizado para o client_id especificado no , 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 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 sobre o usuário assinadas digitalmente pelo Google.
scope	Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaços e diferenciando maiúsculas de minúsculas.
token_type	Identifica o tipo de token retornado. No momento, esse campo sempre tem o valor Bearer.
refresh_token	(opcional) Esse campo só 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.

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 silenciosamente um token de atualização em aberto. Para mais detalhes, consulte Validade do token.

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

Um token de ID é um JWT (token da Web JSON), ou seja, um objeto JSON codificado em Base64 e assinado criptograficamente. Normalmente, é essencial validar um token de ID antes de usá-lo. No entanto, como você está se comunicando diretamente com o Google por um canal HTTPS sem intermediários e usando o segredo do cliente para se autenticar, pode ter certeza de que o token recebido realmente vem do Google e é válido. Se o servidor transmitir o token de ID para outros componentes do app, é extremamente importante que 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 decodificação dos valores codificados em base64url e analisa o JSON, provavelmente você vai validar o token de qualquer maneira ao acessar as reivindicaçõ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. Confira 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": "[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 desse token de ID. Precisa ser um dos IDs de cliente do OAuth 2.0 do seu aplicativo.
exp	sempre	Tempo de expiração a partir do qual o token de ID não pode ser aceito. Representado no formato de tempo Unix (segundos inteiros).
iat	sempre	A hora em que o token de ID foi emitido. Representado no formato de tempo Unix (segundos inteiros).
iss	sempre	O identificador do emissor da resposta. Sempre https://accounts.google.com ou accounts.google.com para tokens de ID do Google.
sub	sempre	Um identificador 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 diferentes momentos, mas o valor sub nunca é alterado. 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 do 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 para proteger contra ataques de falsificação de solicitações entre sites, mas, se você seguir Etapa 1 e Etapa 3, não será necessário verificar o token de acesso.
azp		O client_id do apresentador autorizado. Essa declaração é necessária apenas quando a parte que está solicitando o token de ID não é a mesma que o público-alvo do token de ID. Talvez este seja o caso de apps híbridos em que um aplicativo da Web e um app Android têm um client_id do OAuth 2.0 diferente, mas compartilham o mesmo projeto de APIs do Google.
email		O endereço de e-mail do usuário. Fornecido somente se você incluiu o escopo email na solicitação. O valor dessa declaração pode não ser exclusivo para essa conta e pode mudar com o tempo. Portanto, não use esse valor como o identificador principal para vincular ao seu registro de usuário. Também não é possível usar o domínio da declaração email para identificar usuários do Google Workspace ou das organizações do Cloud. Use a declaração hd.
email_verified		Verdadeiro se o endereço de e-mail do usuário foi verificado. Caso contrário, será falso.
family_name		Os sobrenomes do usuário. Pode ser fornecido quando uma reivindicação name estiver presente.
given_name		O nome ou os nomes próprios do usuário. Pode ser fornecido quando uma reivindicação name estiver presente.
hd		O domínio associado à organização do Google Workspace ou do Cloud do usuário. Fornecido somente se o usuário pertencer a uma organização do Google Cloud. Você precisa verificar essa reivindicação ao restringir o acesso a um recurso apenas para membros de determinados domínios. A ausência dessa declaração indica que a conta não pertence a um domínio hospedado pelo Google.
locale		O local do usuário, representado por uma tag de idioma BCP 47. Pode ser fornecido quando uma reivindicaçã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 incluiu a string "profile" O token de ID é retornado de uma atualização de token Quando as declarações name estão presentes, elas podem ser usadas para atualizar os registros de usuário do app. Não há garantia de que essa reivindicação vai estar presente.
nonce		O valor do nonce fornecido pelo seu app na solicitação de autenticação. Aplique 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. Pode ser fornecido quando: O escopo da solicitação incluiu a string "profile" O token de ID é retornado de uma atualização de token Quando as declarações picture estão presentes, elas podem ser usadas para atualizar os registros de usuário do app. Não há garantia de que essa reivindicação vai 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 "profile" O token de ID é retornado de uma atualização de token Quando as declarações profile estão presentes, elas podem ser usadas para atualizar os registros de usuário do app. Não há garantia de que essa reivindicação vai estar presente.

6. Autenticação do usuário

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

Temas 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 de autenticação e autorização.

Acesso a outras APIs do Google

Uma das vantagens do uso do OAuth 2.0 para autenticação é que seu aplicativo pode receber permissão para usar outras APIs do Google em nome do usuário (como YouTube, Google Drive, Agenda ou Contatos) ao mesmo tempo em que 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 faixa etária do usuário à solicitação de autenticação, transmita um parâmetro de escopo de openid email https://www.googleapis.com/auth/profile.agerange.read. O usuário é solicitado de 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.

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

Tokens de atualização

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

Considerações:

• Armazene o token de atualização de forma segura e permanente, porque você só pode 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á encontrar esses limites. Nesse caso, os tokens de atualização mais antigos vão parar de funcionar.

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

Solicitação de novo consentimento

É possível solicitar que o usuário reautorize seu app definindo o parâmetro prompt como consent na solicitação de autenticação. Quando prompt=consent é incluído, a tela de consentimento é mostrada sempre que o app solicita a autorização dos escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao projeto das APIs do Google. Por esse motivo, inclua prompt=consent somente 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 traz descrições mais completas dos parâmetros aceitos pela API de autenticação OAuth 2.0 do Google.

Parâmetro	Obrigatório	Descrição
client_id	(Obrigatório)	A string do ID do cliente que você recebe do , conforme descrito em Receber credenciais do OAuth 2.0.
nonce	(Obrigatório)	Um valor aleatório gerado pelo app que ativa a proteção contra repetição.
response_type	(Obrigatório)	Se o valor for code, será iniciado um fluxo básico de código de autorização, exigindo um POST para o endpoint de token para conseguir os tokens. Se o valor for token id_token ou id_token token, será iniciado 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 , incluindo o esquema HTTP ou HTTPS, a maiúscula/minúscula e o '/' final, se houver.
scope	(Obrigatório)	O parâmetro de escopo precisa começar com o valor openid e incluir o valor profile, o valor email ou ambos. Se o valor de escopo profile estiver presente, o token de ID poderá incluir (mas não é garantido) as declarações profile padrão do usuário. Se o valor do escopo email estiver presente, o token de ID vai incluir as declarações email e email_verified. Além desses escopos específicos do OpenID, o argumento de escopo também pode incluir outros valores de escopo. Todos os valores de escopo precisam ser separados por espaços. Por exemplo, se você quiser acesso por arquivo ao Google Drive de um usuário, o parâmetro de escopo pode ser openid profile email https://www.googleapis.com/auth/drive.file. Para informações sobre os escopos disponíveis, consulte Escopos do OAuth 2.0 para APIs do Google ou a documentação da API do Google que você quer usar.
state	(Opcional, mas altamente recomendado)	Uma string opaca que é transmitida no protocolo, ou seja, é retornada como um parâmetro de URI no fluxo básico e no identificador #fragment do URI no fluxo implícito. O state pode ser útil para correlacionar solicitações e respostas. Como o redirect_uri pode ser adivinhado, o uso de um valor state pode aumentar a garantia de que uma conexão de entrada é o resultado de uma solicitação de autenticação iniciada pelo app. Se você gerar uma string aleatória ou codificar o hash de algum status do cliente (por exemplo, um cookie) nesta variável state, poderá validar a resposta para garantir ainda mais que a solicitação e a resposta foram originadas no mesmo navegador. Isso oferece proteção contra ataques como a 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 vai 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 de interface do usuário de autenticação e consentimento. Os valores a seguir são especificados e aceitos pelos servidores do Google, mas não têm nenhum efeito no comportamento: page, popup, touch e wap.
hd	(Opcional)	Simplifique o processo de login para contas de uma organização do Google Cloud. Ao incluir o domínio da organização do Google Cloud (por exemplo, mycollege.edu), você pode indicar que a IU de seleção de contas precisa ser otimizada para contas nesse domínio. Para otimizar as contas de organização do Google Cloud em geral, em vez de apenas um domínio de organização do Google Cloud, defina um valor de asterisco (*): hd=*. Não confie nessa otimização da interface para controlar quem pode acessar seu app, porque as solicitações do lado do cliente podem ser modificadas. Valide se o token de ID retornado tem um valor de declaração hd que corresponde ao esperado (por exemplo, mycolledge.edu). Ao contrário do parâmetro de solicitação, a declaração hd do token de ID está contida em um token de segurança do Google, portanto, o valor pode ser confiável.
include_granted_scopes	(Opcional)	Se esse parâmetro for fornecido com o valor true e a solicitação de autorização for concedida, a autorização vai incluir todas as autorizações anteriores concedidas a essa combinação de usuário/aplicativo para outros escopos. Consulte Autorização incremental. Não é possível fazer a autorização incremental com o fluxo de 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 contas e preenche a caixa de e-mail no formulário de login ou seleciona a sessão correta (se o usuário estiver usando vários logins), 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 de valores de string delimitada por espaços que especifica se o servidor de autorização solicita ao usuário a reautorização e o 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 vai retornar um erro se o usuário ainda não tiver sido autenticado e não tiver configurado previamente 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 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 com várias contas no servidor de autorização selecione entre as várias contas em que ele pode ter sessões atuais. Se nenhum valor for especificado e o usuário não tiver autorizado o acesso anteriormente, uma tela de consentimento será mostrada.

Como validar um token de ID

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

Confira a seguir situações comuns em que você pode 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 de ID foi concedido.

Os tokens de ID são sensíveis e podem ser usados indevidamente se forem interceptados. É necessário garantir que esses tokens sejam tratados com segurança, transmitindo-os apenas por HTTPS e apenas por dados POST ou nos cabeçalhos de solicitação. Se você armazenar tokens de ID no servidor, também precisará armazená-los com segurança.

Uma das coisas que tornam os tokens de ID úteis é o fato de que eles podem ser transmitidos para 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 usá-lo como uma declaração de que o usuário foi autenticado, você precisa validá-lo.

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

1. Verifique se o token de ID foi 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 tempo de expiração (declaração exp) do token de ID não expirou.
5. Se você especificou um valor do parâmetro hd na solicitação, verifique se o token de ID tem uma reivindicaçã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 simples, então não vamos detalhar aqui.

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

O endpoint tokeninfo é útil para depuração, mas para fins de produção, extraia as chaves públicas do Google do endpoint de chaves e realize a validação localmente. É necessário extrair 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 estar sujeitas a erros intermitentes.

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

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

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

1. Para ser compatível com o OpenID, é necessário incluir os valores de escopo openid profile na 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 GET HTTPS para o endpoint de informações do usuário, que você precisa extrair 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 fornecer ou reter determinados campos. Por isso, talvez você não receba informações para todos os campos dos seus escopos de acesso autorizados.

O documento de descoberta

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

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

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

Para usar os serviços do OpenID Connect do Google, 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, em seguida, recupera os URIs de endpoint dele conforme necessário. Por exemplo, para autenticar um usuário, o código extrairia o valor de metadados authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth no exemplo abaixo) como o URI base para solicitações de autenticação enviadas ao Google.

Este é um exemplo de documento desse tipo. Os nomes de campo 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 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"
  ]
}

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

Bibliotecas de cliente

As bibliotecas de cliente a seguir simplificam a implementação do OAuth 2.0 com a integração a frameworks conhecidos:

• Biblioteca de cliente de APIs do Google para Java
• Biblioteca de cliente das APIs do Google para Python
• Biblioteca de cliente das 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
• Google Toolbox for Mac OAuth 2.0 Controllers

Conformidade com o 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 precisa interagir com esse serviço, exceto o objeto de solicitação do OpenID.