Esta página foi traduzida pela API Cloud Translation.

Pacote de segurança

Este guia descreve um conjunto de recursos que retornam outros indicadores de confiança sobre uma Conta do Google. Esses indicadores de confiança 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 mais reivindicações, 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 a Google Auth Platform.
Selecionar ou criar o projeto do 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 da verificação é Verificado.

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

Para ativar a declaração auth_time:

Abra a Google Auth Platform.
Selecionar ou criar o projeto do 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 fez a autenticação mais recente 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 momento em que o usuário fez a última autenticação. É 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 JSON Web Token (JWT) com 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 é importante principalmente para fins de segurança, como:

Tomar uma decisão informada sobre se o app deve emitir um desafio adicional de autenticação de aumento antes de realizar ações sensíveis do usuário como excluir a conta, mudar os métodos de contato da conta ou fazer um pagamento. O Google não oferece suporte a solicitações de reautenticação da Conta do Google.
Usando a atualização e a estabilidade da sessão da Conta do Google do usuário como um indicador de confiança. Em geral, um valor auth_time recente indica 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 maneira 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 indica um usuário ativo e engajado e pode ser interpretado como um sinal de menor risco.

Em plataformas móveis, como o Android, os usuários geralmente fazem login diretamente no dispositivo usando métodos biométricos, como impressão digital ou reconhecimento facial, e desbloqueios específicos do dispositivo com PIN ou padrão. Apps e plataformas móveis geralmente usam esses métodos de autenticação baseados em plataforma em vez de criar uma nova sessão com o Google, o que resulta em logins pouco frequentes na Conta do Google e atualizações correspondentes em auth_time. Portanto, um valor auth_time recente pode sinalizar uma mudança em uma sessão da Conta do Google de longa duração e, portanto, um risco maior.

Os indicadores de confiança são um assunto complexo. auth_time deve ser 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 seu aplicativo e sua plataforma.

Solicitação auth_time

O método específico usado para solicitar a declaração auth_time varia de acordo com a API usada. No entanto, todas as APIs incluem um parâmetro opcional claims 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 campo id_token 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 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 adicionar as 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 recurso Fazer login com o Google para mais informações.

Resposta 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 (prazo de validade). 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 (emitida 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 5.763 segundos, o que representa 1 hora, 36 minutos e 3 segundos de tempo decorrido.