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.

Sesiones

Una solicitud de autenticación de una aplicación devuelve un token de ID. Por ejemplo, cuando se presiona un botón de Acceder con Google, se devuelve un ID Token a la aplicación cliente o servidor de Android, iOS o Web que muestra el botón.

La autenticación para acceder a una Cuenta de Google es un evento distinto y separado. Los reclamos que se muestran en el token de ID representan este evento. Por ejemplo, la hora y los métodos de autenticación que se usaron para acceder a la Cuenta de Google.

Hay dos momentos de autenticación y dos sesiones de usuario:

• Sesión de usuario <-> Google: Se establece cuando un usuario accede a su Cuenta de Google. Google administra el ciclo de vida y la seguridad de esta sesión. Los reclamos auth_time y amr te brindan estadísticas sobre esta sesión.
• Usuario <-> Sesión de tu aplicación Se establece después de que el usuario accede a tu aplicación, a menudo con Acceder con Google. Tu aplicación administra esta sesión con las declaraciones para mejorar las decisiones de administración de la sesión y la cuenta.

Los usuarios suelen interactuar con los servicios de Google en varios dispositivos, como teléfonos, computadoras de escritorio, pantallas inteligentes o TVs. Acceder a cada plataforma o dispositivo establece una sesión distinta. En el caso de los accesos web, se establece una sesión entre el navegador específico y Google. Ten en cuenta que los modos de navegación privada y de incógnito crean sus propias sesiones aisladas y separadas. Por este motivo, una sola Cuenta de Google puede tener varias sesiones distintas activas simultáneamente en diferentes navegadores y dispositivos. Para obtener más detalles, consulta Revisa los dispositivos que tienen acceso a la cuenta.

Estado de la Cuenta de Google

Los eventos típicos del ciclo de vida de una Cuenta de Google son los siguientes:

• Una persona elige Crear una Cuenta de Google.
• Es posible que Google inhabilite la cuenta o que un usuario la reactive después de seguir los pasos que se indican en Cómo recuperar tu Cuenta de Google o de Gmail.
• Una persona puede decidir borrar su Cuenta de Google o, debido a la Política de Cuentas de Google Inactivas, Google puede borrar la cuenta.

Las funciones del paquete de seguridad que se describen en esta guía se aplican a las cuentas activas o inhabilitadas, pero no a los eventos de creación o eliminación de Cuentas de Google.

Google puede inhabilitar una cuenta en cualquier momento. Para conocer algunos de los motivos, consulta Se inhabilitó tu cuenta. Cuando esto ocurre, se finalizan todas las sesiones activas de Google y el servicio de Protección integral de la cuenta de Google envía un evento de RISC. Las cuentas inhabilitadas no pueden usar Acceder con Google, lo que significa que nunca se emite un token de ID y, por lo tanto, no se puede usar para supervisar las cuentas de usuario inhabilitadas.

Si bien recibir eventos de Protección integral de la cuenta (RISC) es opcional, estos eventos sirven como indicadores importantes para administrar la sesión entre el usuario y tu app, y si En Protege las cuentas de usuario con la Protección integral de la cuenta, se describen las instrucciones para implementar RISC y responder a los eventos.

Configuración

Para recibir reclamos adicionales, tu app debe estar publicada, verificada y tener habilitadas las funciones del paquete de seguridad. Primero, confirma que tu app esté publicada y verificada:

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

A continuación, habilita los reclamos adicionales:

1. Haz clic en Configuración en el menú.
2. En Configuración avanzada, selecciona una de las siguientes opciones:
   • Declaraciones de duración de la sesión para habilitar auth_time
   • Reclamaciones de seguridad de la autenticación para habilitar amr

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

Funciones admitidas

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

Referencias de métodos de autenticación

Authentication Methods References (amr) es un reclamo de OpenID Connect que describe los métodos utilizados durante el último evento de autenticación entre el usuario y Google.

De los posibles valores de IANA.AMR, Google admite los siguientes valores que indican lo siguiente:

• hwk se usó una llave de seguridad física
• mfa Se completó la autenticación de varios factores
• pwd se usó una contraseña
• swk se usó una llave de software, como una llave de acceso
• sms se usó un mensaje SMS para la verificación
• tel Se usó una llamada telefónica para la verificación

Uno o más de estos valores se devuelven como un array de strings en formato JSON dentro del reclamo amr del token de ID.

El reclamo amr se incluye en el token de ID solo cuando hay información disponible sobre el método de autenticación utilizado. Es posible que no esté presente incluso cuando se solicite.

Los propietarios de Cuentas de Google pueden optar por exigir la 2SV y elegir qué métodos de MFA usar. Cuando se habilita la Protección avanzada en una Cuenta de Google, se requiere un método de 2SV sólido, como las llaves de seguridad Titan (hwk) o la llave de acceso (swk). En ambas situaciones, el valor de mfa está presente cuando se usa más de un factor durante el acceso a la Cuenta de Google.

La presencia de mfa confirma que el evento de autenticación cumplió con los requisitos de Google para la autenticación de varios factores. Por ejemplo, una autenticación de la Cuenta de Google con una contraseña (pwd) y una llave de acceso (swk) genera este reclamo "amr": ["mfa", "pwd", "swk"].

Estos recursos tienen más información sobre la seguridad de la cuenta y la autenticación del usuario: Obtén la seguridad de cuenta más potente de Google con el Programa de Protección Avanzada, Accede con una llave de acceso en lugar de una contraseña y Usa una llave de seguridad para la verificación en 2 pasos.

Los administradores de Workspace controlan la política de autenticación para las cuentas administradas de Workspace y pueden requerir la MFA o el uso de llaves de seguridad. Consulta Descripción general de la administración de identidades de Google y Requisito de autenticación de varios factores para Google Cloud Protecciones y controles de acceso para obtener más información.

Fecha y hora de autenticación

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 fecha y 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 especialmente 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 las 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 inicios de sesión poco frecuentes en la Cuenta de Google y las actualizaciones correspondientes en 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.

Solicitudes

El método específico que se usa para solicitar los reclamos auth_time y amr difiere según la API que se use. Sin embargo, todas las APIs incluyen un parámetro opcional claims para solicitar auth_time y amr.

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 },
            "amr": {"essential":true}
          }
        }

<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, amr",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

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

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


// 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")")
}

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
GIDClaim *AMRClaim = [GIDClaim AMRClaim];
NSSet *claims = [NSSet setWithArray:@[authTimeClaim, AMRClaim]];


// 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.
                          }];

Respuestas

Cuando las reclamaciones auth_time o amr se incluyen en la solicitud, se devuelven 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).

Es probable que falten reclamos porque la app no está verificada o porque se inhabilitaron parámetros de configuración adicionales, que es la opción predeterminada. Sigue las instrucciones en Configuración para confirmar que el ID de cliente y la app en uso estén verificados y que se hayan habilitado los reclamos adicionales.

El valor del reclamo 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.

El valor del reclamo amr es un array de cadenas JSON que representa los métodos de autenticación utilizados durante el último evento de acceso a la Cuenta de Google.

Este es un ejemplo de un token de ID decodificado que incluye los reclamos auth_time y amr:

{
  "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,
  "amr": ["mfa", "pwd", "tel"],
  "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 token de ID también contiene un reclamo iat (emitido en), que indica la hora en que se emitió el JWT. Si comparas los reclamos 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.