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 é certificada pelo 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, marque suas perguntas com "google-oauth".
Como configurar o OAuth 2.0
Antes que seu aplicativo possa usar o sistema de autenticação OAuth 2.0 do Google para fazer login do usuário, é preciso configurar um projeto no Google API Console para receber as 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 o API Console para criar uma conta de serviço, ativar o faturamento, configurar a filtragem e realizar outras tarefas. Para mais detalhes, consulte a Ajuda do Google API Console.
Receber credenciais do OAuth 2.0
É preciso ter credenciais do OAuth 2.0, incluindo ID e chave secreta do cliente, para autenticar usuários e ter acesso às APIs do Google.
To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.
Or, view your client ID and client secret from the Credentials page in API Console:
- Go to the Credentials page.
- Click the name of your credential or the pencil (create) icon. Your client ID and secret are at the top of the page.
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:
- Go to the Credentials page.
- Na seção IDs do cliente OAuth 2.0 da página, clique em uma credencial.
- 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, ele pode receber uma solicitação para dar 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 o nome do produto, logotipo e um URL de página inicial. Você controla as informações da marca na API Console.
Para ativar a tela de consentimento do seu projeto:
- Abra o Consent Screen page no Google API Console .
- If prompted, select a project, or create a new one.
- 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 OAuth 2.0 e escopos do Google Drive estiver presente na solicitação. Essa caixa de diálogo genérica foi gerada usando o Google OAuth 2.0 Playground. Portanto, ela não inclui informações de marca que seriam definidas no API Console.

Como acessar o serviço
O Google e terceiros fornecem bibliotecas que podem ser usadas para cuidar de muitos dos detalhes de implementação da autenticação de usuários e do acesso a APIs do Google. Exemplos incluem o Google Identity Services e as bibliotecas de cliente do Google, que estão disponíveis para várias plataformas.
Se você optar por não usar uma biblioteca, siga as instruções no restante deste documento, que descreve os fluxos de solicitação HTTP que são usados nas bibliotecas disponíveis.
Autenticar o usuário
Autenticar o usuário envolve obter e validar um token de ID. Os tokens de ID são um recurso padronizado do OpenID Connect usado 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 "servidor" e "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 em execução no navegador) precisa acessar as APIs diretamente, em vez de usar o servidor de back-end.
Neste documento, descrevemos 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 no uso de tokens no lado do cliente. Se você precisar implementar um fluxo implícito, é altamente recomendável 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 fazer o seguinte:
- Criar um token de estado anti-falsificação
- Enviar uma solicitação de autenticação ao Google
- Confirmar o token de estado anti-falsificação
- Trocar
code
por token de acesso e de ID - Receber informações do usuário com o token de ID
- Autenticar o usuário
1. Criar um token de estado anti-falsificação
Você precisa proteger a segurança dos usuários, evitando ataques de falsificação de solicitação. A primeira etapa é criar um token de sessão exclusivo que contenha o estado entre seu app e o cliente do usuário. Posteriormente, você corresponderá esse 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ção entre sites (CSRF, na sigla em inglês).
Uma boa escolha para um token de estado é uma string de aproximadamente 30 caracteres usando um gerador de números aleatórios de alta qualidade. Outro é um hash gerado assinando algumas variáveis de estado da sua sessão com uma chave que é mantida em segredo no seu back-end.
O código a seguir demonstra a geração de tokens de sessão exclusivos.
PHP
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 HTTPS GET
com os parâmetros de URI apropriados.
Observe o uso de HTTPS em vez de HTTP em todas as etapas desse processo. As conexões HTTP são
recusadas. É necessário recuperar 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ê consegue em API Console Credentials page .response_type
, que em uma solicitação de fluxo de código de autorização básica precisa sercode
. Leia mais emresponse_type
.scope
, que em uma solicitação básica precisa seropenid email
. Leia mais emscope
.redirect_uri
precisa ser o endpoint HTTP no servidor que receberá a resposta do Google. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no API Console Credentials page. Se esse valor não corresponder a um URI autorizado, a solicitação falhará com um erroredirect_uri_mismatch
.state
precisa incluir o valor do token de sessão exclusivo anti-falsificação, bem como outras informações necessárias para recuperar o contexto quando o usuário retornar ao aplicativo, por exemplo, o URL inicial. Leia mais emstate
.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 stringsub
, que é equivalente ao ID do Google do usuário. Se você não informar umlogin_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 dele para o app. Saiba mais emlogin_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 emhd
.
Veja um exemplo de um URI de autenticação completo do OpenID Connect, com quebras de linha e espaços para facilitar a leitura:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//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 precisam dar consentimento caso seu app solicite novas informações sobre eles ou se o app solicitar acesso à conta que não foi aprovado anteriormente.
3. Confirmar token de estado anti-falsificação
A resposta é enviada ao 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 que 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, 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 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 token 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. O servidor faz essa troca enviando uma solicitação HTTPS POST
. A solicitação POST
é enviada para o endpoint do token,
que você precisa recuperar do documento de descoberta usando o
valor de metadados token_endpoint
. A discussão a seguir pressupõe que o endpoint é
https://oauth2.googleapis.com/token
. A solicitação precisa incluir os seguintes parâmetros no corpo POST
:
Campos | |
---|---|
code |
O código de autorização retornado da solicitação inicial. |
client_id |
O ID do cliente recebido de API Console Credentials page, conforme descrito em Receber credenciais do OAuth 2.0. |
client_secret |
A chave secreta do cliente recebida do API Console Credentials page, conforme descrito em Receber credenciais do OAuth 2.0. |
redirect_uri |
Um URI de redirecionamento autorizado para o client_id especificado no
API Console
Credentials page, conforme descrito em
Definir um URI de redirecionamento. |
grant_type |
Esse campo precisa conter um valor de authorization_code ,
conforme definido na especificação do OAuth 2.0. |
A solicitação real pode ser semelhante a este 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 para essa solicitação contém os seguintes campos em uma matriz JSON:
Campos | |
---|---|
access_token |
Um token que pode ser enviado a uma API do Google. |
expires_in |
O ciclo de vida restante do token de acesso em segundos. |
id_token |
Um JWT que contém informações de identidade do usuário que foi assinada digitalmente pelo Google. |
scope |
Os escopos de acesso concedidos pelo access_token expressos como uma lista de
strings delimitadas por espaços, que diferenciam maiúsculas de minúsculas. |
token_type |
Identifica o tipo de token retornado. Neste momento, esse campo sempre tem o valor Bearer .
|
refresh_token |
(opcional)
Esse campo só estará presente se o parâmetro
|
5. Conseguir 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 criptografia Base64. Normalmente, é essencial validar 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ários e usando sua chave secreta do cliente para se autenticar no Google, pode ter certeza de que o token recebido é realmente emitido pelo Google e válido. Se o servidor transmitir o token de ID para outros componentes do seu app, é extremamente importante que os outros componentes validem o token antes de usá-lo.
Como a maioria das bibliotecas de API combina a validação com o trabalho de decodificar os valores codificados em base64url e analisar o JSON dentro dele, você provavelmente vai validar o token mesmo assim ao acessar as declarações no token de ID.
Payload de um token de ID
Um token de ID é um objeto JSON que contém um conjunto de pares de nome/valor. Veja um exemplo formatado para legibilidade:
{ "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 código 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 de cliente do OAuth 2.0 do aplicativo. |
exp |
sempre | O prazo de validade do token de ID não pode ser posterior a esse. Representado no horário Unix (segundos inteiros). |
iat |
sempre | A hora em que o token de ID foi emitido. Representado no horário 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, 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ção entre sites, mas se você seguir a
Etapa 1 e a Etapa 3, não será
necessário verificar o token de acesso. |
|
azp |
É o client_id do apresentador autorizado. Essa reivindicação só é necessária quando
a parte que solicita o token de ID não é a mesma que o público-alvo dele. Isso
pode ser o caso do Google para apps híbridos em que um app da Web e o 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. Talvez esse valor não seja exclusivo para o usuário e não seja adequado
para uso como chave primária. Fornecido apenas se o escopo incluir o valor
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 uma
declaração name estiver presente. |
|
given_name |
O nome ou o nome de usuário Pode ser informado quando uma
declaração name estiver presente. |
|
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 está presente. |
|
name |
Nome completo do usuário em formato de exibição. Podem ser fornecidos quando:
Quando há declarações |
|
nonce |
O valor do nonce fornecido pelo app na solicitação de autenticação.
Aplique 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. Podem ser fornecidos quando:
Quando há declarações |
|
profile |
O URL da página de perfil do usuário. Podem ser fornecidos quando:
Quando há declarações |
6. Autenticar o usuário
Depois de receber as informações do usuário do token de ID, consulte o banco de dados de usuários do seu app. Se o usuário já existir no banco de dados, inicie uma sessão de aplicativo para ele se todos os requisitos de login forem atendidos pela resposta da API do Google.
Se o usuário não existir no banco de dados, redirecione-o para o fluxo de inscrição de novo. É possível registrar o usuário automaticamente com base nas informações recebidas do Google ou, no mínimo, preencher automaticamente muitos dos campos necessários no formulário de registro. Além das informações do token de ID, é possível acessar outras informações de perfil de usuário nos endpoints de perfil de usuário.
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 de autenticação e autorização.
Acesso a outras APIs do Google
Uma das vantagens de usar o OAuth 2.0 para autenticação é que seu aplicativo pode receber
permissão para usar outras APIs do Google em nome do usuário (como YouTube, Google Drive,
Agenda ou Contatos) ao mesmo tempo que você autentica o usuário. Para fazer isso, inclua os outros escopos necessários na solicitação de autenticação enviada ao Google. Por exemplo, para adicionar a idade do usuário à solicitação de autenticação, transmita um
parâmetro de escopo de
openid email https://www.googleapis.com/auth/profile.agerange.read
. O usuário receberá uma solicitação 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.
Tokens de atualização
Na sua solicitação de acesso à API, solicite 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
a offline
na
solicitação de autenticação.
Considerações:
- Armazene o token de atualização de maneira segura e permanente, porque só é possível receber um token de atualização na primeira vez que você executa o fluxo de troca de código.
- Há limites para o número de tokens de atualização emitidos: um limite por combinação cliente/usuário e outro por usuário em todos os clientes. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos vão deixar de funcionar.
Para mais informações, consulte Como atualizar um token de acesso (acesso off-line).
Solicitação de novo consentimento
Você pode solicitar que o usuário autorize o app novamente definindo o parâmetro
prompt
como consent
na
solicitação de autenticação. Quando prompt=consent
é incluído, a tela de consentimento é exibida sempre que seu app solicita autorização de escopos de acesso, mesmo que todos os escopos tenham sido concedidos anteriormente ao seu projeto de APIs do Google. Por isso, inclua prompt=consent
somente quando necessário.
Para mais informações sobre o parâmetro prompt
, consulte prompt
na tabela Parâmetros de URI de autenticação.
Parâmetros de URI de autenticação
Veja na tabela a seguir 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 extraída da API Console Credentials page, 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 , iniciará um
fluxo básico do código de autorização,
exigindo um POST para o endpoint de token. Se o valor for
token id_token ou id_token token , iniciará 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 que você definiu em API Console Credentials page , incluindo o esquema HTTP ou HTTPS, o caso e "/" no final. |
scope |
(obrigatório) | O parâmetro de escopo precisa começar com o valor Se o valor do escopo Se o valor do escopo Além desses escopos específicos do OpenID, seu argumento de escopo também pode incluir outros
valores de escopo. Todos os valores de escopo precisam ser separados por espaços. Por exemplo, para acesso
por arquivo ao Google Drive de um usuário, seu parâmetro de escopo pode ser
Para informações sobre os escopos disponíveis, consulte Escopos do OAuth 2.0 para APIs do Google ou a documentação da API que você quer usar. |
state |
(Opcional, mas altamente recomendado) | Uma string opaca que é retornada no protocolo. Ou seja, é retornada como um parâmetro de URI no fluxo básico e no identificador de URI O |
access_type |
(Opcional) | Os valores permitidos são offline e online . O efeito está documentado no 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 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 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 da conta precisa ser otimizada para contas nesse
domínio. Para otimizar as contas da organização do Google Cloud em geral, em vez de apenas um domínio da organização, defina um valor de asterisco ( Não confie nessa otimização de IU para controlar quem pode acessar o app, já que as solicitações do lado do
cliente podem ser modificadas. Valide se
o token de ID retornado tem um valor de declaração |
include_granted_scopes |
(Opcional) | Se o 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 do app instalado. |
login_hint |
(Opcional) | Quando o app sabe qual usuário está tentando autenticar, esse parâmetro pode ser uma dica para o servidor de autenticação. Transmitir essa dica suprime o
seletor de conta e preenche automaticamente a caixa de e-mail no formulário de login ou seleciona a sessão
correta (se o usuário estiver usando
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
solicitará ao usuário a reautenticação e o consentimento. Os valores possíveis são os seguintes:
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
É preciso 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êntico os tokens de ID recebidos dos apps cliente.
Veja 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 confidenciais e podem ser usados de forma indevida se interceptados. Você precisa garantir que esses tokens sejam processados com segurança pela transmissão somente por HTTPS e somente 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 coisa que torna os tokens de ID úteis é que eles podem ser transmitidos por diferentes componentes do seu app. Esses componentes podem usar um token de ID como um mecanismo de autenticação leve que autentica o app e o usuário. Mas, antes de usar as informações no token de ID ou depender delas como uma declaração de autenticação do usuário, é preciso fazer a validação.
A validação de um token de ID requer várias etapas:
- 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. - Verifique se o valor da declaração
iss
no token de ID é igual ahttps://accounts.google.com
ouaccounts.google.com
. - Verifique se o valor da declaração
aud
no token de ID é igual ao ID do cliente do seu app. - Verifique se o prazo de validade (reivindicação
exp
) do token de ID não passou. - Se você tiver especificado um valor de parâmetro hd na solicitação, verifique se
o token de ID tem uma declaração
hd
que corresponde a um domínio aceito associado a uma organização do Google Cloud.
As etapas de 2 a 5 envolvem somente comparações de strings e datas que são bastante simples. Por isso, não as detalharemos aqui.
A primeira etapa é mais complexa e envolve a verificação de assinaturas criptográficas. Para fins de
depuração, use o endpoint tokeninfo
do Google para comparar
o processamento local implementado no servidor ou dispositivo. Suponha que o valor do token de ID seja
XYZ123
. Depois, desfaça 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 no 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 das chaves do documento de descoberta usando o valor de metadados jwks_uri
. As solicitações para o endpoint de depuração podem ser
limitadas ou sujeitas a erros intermitentes.
Como o Google altera as próprias 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, realizar a validação local de maneira muito mais eficiente do que usar o endpoint tokeninfo
. Essa validação
exige a recuperação e análise de certificados e a realização das chamadas criptográficas apropriadas para
verificar a assinatura. Felizmente, há bibliotecas depuradas disponíveis em uma grande variedade
de linguagens para fazer isso (consulte jwt.io).
Como conseguir informações do perfil do usuário
Para ver mais informações sobre o 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:
Para ser compatível com o OpenID, é necessário 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 mais um valor de escopo de
email
. Para especificarprofile
eemail
, inclua o seguinte parâmetro no URI da solicitação de autenticação:scope=openid%20profile%20email
- Adicione seu token de acesso ao cabeçalho da autorização e faça uma solicitação
GET
HTTPS ao endpoint de informações do usuário, que você precisa recuperar do documento de descoberta usando o valor de metadadosuserinfo_endpoint
. A resposta do userinfo inclui informações sobre o usuário, conforme descrito emOpenID Connect Standard Claims
e o valor de metadadosclaims_supported
do documento de descoberta. Os usuários ou as organizações deles podem optar por fornecer ou reter alguns campos. Por isso, talvez você não receba informações sobre 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 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 com pares de chave-valor que fornecem detalhes sobre a configuração do provedor do OpenID Connect, incluindo os URIs dos endpoints de autorização, token, revogação, userinfo e chaves públicas. O documento de descoberta para o serviço OpenID Connect do Google pode ser recuperado de:
https://accounts.google.com/.well-known/openid-configuration
Para usar os serviços OpenID Connect do Google, codifique o URI do documento Discovery
(https://accounts.google.com/.well-known/openid-configuration
) no 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 para solicitações de autenticação enviadas ao Google.
Veja um exemplo desse documento. Os nomes dos campos são aqueles especificados em OpenID Connect Discovery 1.0. Consulte esses documentos para ver o significado deles. Os valores são apenas 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" ] }
Você pode evitar uma ida e volta HTTP armazenando em cache os valores do documento Discovery. Os cabeçalhos de armazenamento em cache HTTP padrão são usados e precisam 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 conhecidos:
- Biblioteca de cliente de APIs do Google para Java
- Biblioteca de clientes de APIs do Google para Python
- Biblioteca de clientes 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 Google Web Toolkit
- Controlador de ferramentas do Google para Mac 2.0 OAuth
Conformidade com OpenID Connect
O sistema de autenticação OAuth 2.0 do Google é compatível com os recursos obrigatórios da especificação OpenID Connect Core. Qualquer cliente projetado para funcionar com o OpenID Connect deve interoperar com esse serviço, exceto o objeto de solicitação OpenID.