Paquete de seguridad

En esta guía, se describe un conjunto de funciones que devuelven indicadores de confianza adicionales sobre una Cuenta de Google. Estos indicadores de confianza ayudan a tu sistema de administración de cuentas a tomar decisiones basadas en el riesgo durante el registro, la creación de cuentas y, más adelante, para los usuarios recurrentes.

Configuración

Para recibir reclamos adicionales, tu app debe estar publicada, verificada y tener habilitadas las funciones del paquete de seguridad.

Para confirmar que tu app esté publicada y verificada, haz lo siguiente:

1. Abre Google Auth Platform
2. Selecciona o crea el proyecto de tu app
3. Haz clic en Público en el menú.
4. Confirma que el Estado de publicación sea En producción.
5. Haz clic en Centro de verificación en el menú.

6. Confirma que el Estado de verificación sea Verificado.

   Para obtener más información, visita el Centro de ayuda sobre la verificación de apps con OAuth.

Para habilitar el reclamo de auth_time, sigue estos pasos:

1. Abre Google Auth Platform
2. Selecciona o crea el proyecto de tu app
3. Haz clic en Configuración en el menú.
4. En Configuración avanzada, selecciona Declaraciones de antigüedad de la sesión para habilitar auth_time.

Funciones admitidas

En esta sección, se describen las funciones individuales que componen el paquete de seguridad.

auth_time

El reclamo auth_time es una parte estándar del protocolo OpenID Connect que proporciona información sobre cuándo se autenticó por última vez el usuario final con Google. Es un número JSON que representa la cantidad de segundos transcurridos desde la época Unix (1 de enero de 1970, 00:00:00 UTC) y es la hora en que el usuario se autenticó por última vez. Piensa en él como una marca de tiempo que indica el último evento de acceso del usuario a su Cuenta de Google desde el dispositivo o navegador actual. Este reclamo se incluye en el token de ID, que es un token web JSON (JWT) que contiene información verificada sobre la autenticación y el usuario.

El reclamo auth_time es valioso para tu aplicación porque te permite determinar qué tan recientemente un usuario accedió de forma activa a una Cuenta de Google en el dispositivo o navegador que está usando. Esto puede ser particularmente importante por motivos de seguridad, como los siguientes:

• Tomar una decisión fundamentada sobre si tu app debe emitir un desafío de autenticación adicional antes de realizar acciones sensibles del usuario, como borrar la cuenta, cambiar los métodos de contacto de la cuenta o realizar un pago Google no admite solicitudes de reautenticación de la Cuenta de Google.

• Usamos la actualización y la estabilidad de la sesión de la Cuenta de Google del usuario como indicador de confianza. En general, un valor de auth_time reciente es un indicador de actualidad, mientras que un valor más antiguo indica estabilidad.

En el caso de las apps web, la combinación del navegador y el sistema operativo del usuario constituye una sesión después de que el usuario accede a su Cuenta de Google. De forma independiente, tu sitio web también mantiene una sesión de usuario separada. Un valor de auth_time más reciente indica que el usuario accedió recientemente a su Cuenta de Google. A menudo, esto es un indicador de un usuario activo y participativo, y se puede interpretar como un indicador de menor riesgo.

En las plataformas para dispositivos móviles, como Android, los usuarios suelen acceder directamente a sus dispositivos con métodos biométricos, como el escaneo facial o de huellas dactilares, y con PIN o patrones de desbloqueo específicos del dispositivo. Las apps y plataformas para dispositivos móviles suelen usar estos métodos de autenticación basados en la plataforma en lugar de crear una sesión nueva con Google, lo que genera accesos poco frecuentes a la Cuenta de Google y las actualizaciones correspondientes a auth_time. Por lo tanto, un valor de auth_time reciente puede indicar un cambio en una sesión de la Cuenta de Google de larga duración y, por lo tanto, un mayor riesgo.

Los indicadores de confianza son un tema complejo. Se espera que auth_time se use junto con otros indicadores, como si la autenticación de varios factores (MFA) está habilitada, el método de autenticación que se usa y la duración de la sesión del usuario entre tu aplicación y tu plataforma.

Solicitud de auth_time

El método específico que se usa para solicitar el reclamo auth_time varía según la API que se use. Sin embargo, todas las APIs incluyen un parámetro opcional claims para solicitar auth_time.

Precaución: Actualización del 18/11/2025: Se detectó un problema conocido por el que se devuelve un valor de auth_time incorrecto cuando un solo dispositivo o navegador tiene varias sesiones de usuario activas. Las sesiones individuales no se ven afectadas.

Protocolo de OIDC

Cuando usas la plataforma de OAuth directamente, solicita auth_time agregándolo al parámetro de solicitud de reclamos opcionales. Establece el valor del campo id_token del objeto JSON de las declaraciones en {"auth_time":{"essential":true}}. Por ejemplo:

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

Nota: Se agregaron saltos de línea para facilitar la lectura. El valor real de la solicitud y el parámetro de reclamos es JSON codificado como URL.

Consulta OpenID Connect para obtener más información.

GIS para la Web

La biblioteca de Acceder con Google para la Web tiene dos APIs: HTML y JavaScript para solicitar declaraciones adicionales. Por ejemplo, solicita auth_time con la API de 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>

Consulta Acceder con Google para la Web para obtener más información.

GIS para Android

Se usan un método setClaims y un objeto Claim para solicitar auth_time.

Actualiza las dependencias de compilación para usar las versiones más recientes de las bibliotecas androidx.credentials:credentials-play-services-auth y com.google.android.libraries.identity.googleid:googleid.

Crea una instancia de un objeto Claim del tipo auth_time, usando setClaims para agregarle las opciones de acceso:

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

Consulta Cómo autenticar usuarios con Acceder con Google para obtener más información.

Respuesta de auth_time

Cuando se incluye la reclamación auth_time en la solicitud, aparece en la respuesta de la carga útil del token de ID junto con otras reclamaciones estándar, como iss (emisor), sub (asunto), aud (público) y exp (hora de vencimiento). El valor de la declaración auth_time es un número JSON que representa la cantidad de segundos transcurridos desde la época Unix (1 de enero de 1970, 00:00:00 UTC) hasta el momento en que se produjo la última autenticación del usuario. Este es un ejemplo de un token de ID decodificado que incluye el reclamo auth_time:

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "[e-mail]",
  "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"
}

El ID Token también contiene un reclamo iat (emitido en), que indica la hora en que se emitió el JWT. Si comparas los parámetros iat y auth_time, puedes determinar el tiempo transcurrido desde la última autenticación del usuario en relación con el momento en que se creó el token de ID específico. Por ejemplo, si iat es 1748881189 y auth_time es 1748875426, la diferencia es de 5, 763 segundos, lo que representa 1 hora, 36 minutos y 3 segundos de tiempo transcurrido.

Advertencia: Cuando implementes tu sistema de administración de cuentas, no debes usar el campo email en el token de ID como identificador único de un usuario. Siempre usa el campo sub, ya que es único para una Cuenta de Google, incluso si el usuario cambia su dirección de correo electrónico.