Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Pacote de segurança

Este guia descreve uma coleção de recursos que retornam indicadores de confiança adicionais sobre uma Conta do Google. Esses indicadores ajudam seu sistema de gerenciamento da conta a tomar decisões baseadas em risco durante a inscrição, a criação da conta e, mais tarde, sobre usuários recorrentes.

Configuração

Para receber declarações adicionais, seu app precisa ser publicado, verificado e ter os recursos do pacote de segurança ativados.

Para confirmar se o app foi publicado e verificado:

Abra o Google Auth Platform
Selecione ou crie o projeto do seu app
Clique em Público-alvo no menu
Confirme se o status de publicação é Em produção
Clique em Central de verificação no menu
Confirme se o status de verificação é Verificado.

Para saber mais, acesse a Central de Ajuda de verificação de apps OAuth.

Para ativar a declaração auth_time:

Abra o Google Auth Platform
Selecione ou crie o projeto do seu app
Clique em Configurações no menu
Em Configurações avançadas , selecione Declarações de idade da sessão para ativar auth_time.

Recursos compatíveis

Esta seção descreve os recursos individuais que compõem o pacote de segurança.

auth_time

A declaração auth_time é uma parte padrão do protocolo OpenID Connect que fornece informações sobre quando o usuário final foi autenticado mais recentemente com o Google. É um número JSON que representa o número de segundos decorridos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC) e é o horário em que o usuário foi autenticado pela última vez. Pense nisso como um carimbo de data/hora que indica o último evento de login do usuário na Conta do Google no dispositivo ou navegador atual. Essa declaração está incluída no token de ID, que é um token da Web JSON (JWT) que contém informações verificadas sobre a autenticação e o usuário.

A declaração auth_time é valiosa para seu aplicativo porque permite determinar há quanto tempo um usuário fez login ativamente em uma Conta do Google no dispositivo ou navegador que está usando. Isso pode ser particularmente importante para fins de segurança, como:

Tomar uma decisão informada sobre se o app deve emitir um desafio de autenticação adicional antes de realizar ações sensíveis do usuário, como excluir a conta, mudar as formas de contato da conta ou fazer um pagamento. O Google não oferece suporte a solicitações de reautenticação da Conta do Google.
Usar a atualização e a estabilidade da sessão da Conta do Google do usuário como um indicador de confiança. De modo geral, um valor auth_time recente é uma indicação de atualização, enquanto um valor mais antigo indica estabilidade.

Para apps da Web, a combinação do navegador e do sistema operacional do usuário constitui uma sessão depois que o usuário faz login na Conta do Google. De forma independente, seu site também mantém uma sessão de usuário separada. Um valor auth_time mais recente indica que o usuário fez login na Conta do Google recentemente. Muitas vezes, isso é uma indicação de um usuário ativo e engajado e pode ser interpretado como um indicador de menor risco.

Em plataformas móveis, como o Android, os usuários costumam fazer login diretamente no dispositivo usando métodos biométricos, como impressão digital ou escaneamento facial, e PIN ou padrão de desbloqueio específicos do dispositivo. Apps e plataformas para dispositivos móveis costumam usar esses métodos de autenticação baseados em plataforma em vez de criar uma nova sessão com o Google, resultando em logins infrequentes da Conta do Google e atualizações correspondentes para auth_time. Portanto, um valor auth_time recente pode sinalizar uma mudança em uma sessão de Conta do Google de longa duração e, portanto, um risco maior.

Os indicadores de confiança são um assunto complexo. Espera-se que auth_time seja usado com outros indicadores, como se a autenticação multifator (MFA) está ativada, o método de autenticação usado e a duração da sessão do usuário entre o aplicativo e a plataforma.

Solicitação de auth_time

O método específico usado para solicitar a declaração auth_time difere de acordo com a API usada. No entanto, todas as APIs incluem um parâmetro claims opcional para solicitar auth_time.

Protocolo OIDC

Ao usar a plataforma OAuth diretamente, solicite auth_time adicionando-o ao parâmetro de solicitação de declarações opcionais. Defina o valor do id_token campo do objeto JSON de declarações como {"auth_time":{"essential":true}}. Por exemplo,

https://accounts.google.com/o/oauth2/v2/auth?
response_type=id_token&
client_id=YOUR_CLIENT_ID&
scope=openid email profile&
redirect_uri=https://example.com/user-login&
nonce=123-456-7890&
claims={"id_token":{"auth_time":{"essential":true}}}

Consulte OpenID Connect para mais informações.

GIS para a Web

A biblioteca Fazer login com o Google para a Web tem duas APIs: HTML e JavaScript para solicitar declarações adicionais. Por exemplo, solicite auth_time usando a API JavaScript:

<html>
<body>
  <script src="https://accounts.google.com/gsi/client" async></script>
  <script>
    window.onload = function () {
      google.accounts.id.initialize({
        client_id: "YOUR_WEB_CLIENT_ID",
        callback: function(rsp) { console.log(rsp.credential); },
        essential_claims: "auth_time",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

Consulte Fazer login com o Google para a Web para mais informações.

GIS para Android

Um método setClaims e um objeto Claim são usados para solicitar auth_time.

Atualize as dependências de build para usar as versões mais recentes das bibliotecas androidx.credentials:credentials-play-services-auth e com.google.android.libraries.identity.googleid:googleid.

Instancie um objeto Claim do tipo auth_time, usando setClaims para adicioná-lo às opções de login:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setAutoSelectEnabled(true)
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setNonce("NONCE")
    .setClaims(ImmutableList.of(new Claim("auth_time", true)))
    .build()

Consulte Autenticar usuários com o Fazer login com o Google para mais informações.

iOS

O SDK de Fazer login com o Google para iOS adiciona um objeto authTimeClaime um parâmetro claims à classe GIDSignIn usada para solicitar auth_time opcionalmente.

Os apps que usam ASWebAuthenticationSession atualizam um contêiner de cookies compartilhado em todo o dispositivo. GIDSignIn usa esse método por padrão no iOS 12 ou mais recente e no macOS 12.16 ou mais recente. Nesse cenário, um usuário que faz login na Conta do Google é autenticado e a sessão é armazenada no contêiner de cookies compartilhado. Aqui, auth_time é a última autenticação do Google do usuário no dispositivo, não apenas no seu app.

SFSafariViewController, WKWebView e UIWebView operam em sandboxes isolados no seu app. Evite usá-los ao usar auth_time. Aqui, auth_time é o último login do usuário no próprio app. Como o valor é sempre recente, ele é menos significativo.

Para solicitar auth_time, atualize as dependências do GoogleSignIn para a versão mais recente e crie um objeto authTimeClaim, adicionando-o ao conjunto claims.

Swift

Adicione o conjunto de declarações ao método GIDSignIn.sharedInstance.signIn:

let authTimeClaim = GIDClaim.authTime()
let claims = Set([authTimeClaim])

// Start the sign-in process
GIDSignIn.sharedInstance.signIn(
  withPresenting: rootViewController,
  claims: claims
) { signInResult, error in
  guard let result = signInResult else {
    print("Error signing in: (error?.localizedDescription ?? "No error description")")
    return
  }
  // If sign in succeeded, display the app's main content View
  print("ID Token: (result.user.idToken?.tokenString ?? "No token")")
}

Objective-C

Adicione o conjunto de declarações ao método signInWithPresentingViewController:

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
NSSet *claims = [NSSet setWithObject:authTimeClaim];

// Include the claims set and start the sign-in process
[GIDSignIn.sharedInstance
  signInWithPresentingViewController:self
                                hint:nil
                              claims:claims
                          completion:^(GIDSignInResult * _Nullable signInResult,
                                      NSError * _Nullable error) {
                            // On success signInResult.user.idToken
                            // contains the requested claims.
                          }];

Consulte Integrar o Login do Google ao seu app iOS ou macOS para mais informações.

Resposta de auth_time

Quando a declaração auth_time é incluída na solicitação, ela aparece na resposta do payload do token de ID junto com outras declarações padrão, como iss (emissor), sub (assunto), aud (público-alvo) e exp (tempo de expiração). O valor da declaração auth_time é um número JSON que representa o número de segundos decorridos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC) até o momento em que a autenticação do usuário ocorreu pela última vez. Este é um exemplo de um token de ID decodificado que inclui a declaração auth_time:

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "alice@example.com",
  "email_verified": true,
  "nonce": "123-456-7890",
  "auth_time": 1748875426,
  "nbf": 1748880889,
  "name": "Elisa Beckett",
  "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1748881189,
  "exp": 1748884789,
  "jti": "8b5d7ce345787d5dbf14ce6e08a8f88ee8c9b5b1"
}

O token de ID também contém uma declaração iat (emitido em), que indica o horário em que o JWT foi emitido. Ao comparar as declarações iat e auth_time, é possível determinar o tempo decorrido desde a última autenticação do usuário em relação ao momento em que o token de ID específico foi criado. Por exemplo, se iat for 1748881189 e auth_time for 1748875426, a diferença será de 5763 segundos, o que representa 1 hora, 36 minutos e 3 segundos de tempo decorrido.