Saltar al contenido principal

Claves de firma

Las claves de firma OIDC de Logto, también conocidas como "claves privadas OIDC" y "claves de cookies OIDC", son las claves de firma utilizadas para firmar JWTs (tokens de acceso (Access tokens) y tokens de ID (ID tokens)) y cookies del navegador en las sesiones de inicio de sesión (sign-in sessions) de Logto. Estas claves de firma se generan al inicializar la base de datos de Logto (código abierto) o al crear un nuevo tenant (Cloud) y pueden gestionarse a través de la CLI (código abierto), Management APIs o la interfaz de la Consola.

Por defecto, Logto utiliza el algoritmo de curva elíptica (EC) para generar firmas digitales. Sin embargo, considerando que los usuarios a menudo necesitan verificar firmas de JWT y muchas herramientas antiguas no admiten el algoritmo EC (solo admiten RSA), hemos implementado la funcionalidad para rotar claves privadas y permitir a los usuarios elegir el algoritmo de firma (incluyendo tanto RSA como EC). Esto garantiza la compatibilidad con servicios que utilizan herramientas de verificación de firmas obsoletas.

nota:

Teóricamente, las claves de firma no deberían filtrarse y no tienen tiempo de expiración, lo que significa que no es necesario rotarlas. Sin embargo, rotar periódicamente la clave de firma después de cierto tiempo puede mejorar la seguridad.

¿Cómo funciona?​

  • Clave privada OIDC Al inicializar una instancia de Logto, se genera automáticamente un par de clave pública y clave privada, que se registran en el proveedor OIDC subyacente. Así, cuando Logto emite un nuevo JWT (token de acceso o token de ID), el token se firma con la clave privada. Mientras tanto, cualquier aplicación cliente que reciba un JWT puede usar la clave pública emparejada para verificar la firma del token, con el fin de asegurar que el token no ha sido manipulado por terceros. La clave privada está protegida en el servidor de Logto. La clave pública, como su nombre indica, es pública para todos y puede accederse a través de la interfaz /oidc/jwks del endpoint OIDC. Se puede especificar un algoritmo de clave de firma al generar la clave privada, y Logto utiliza el algoritmo EC (Curva Elíptica) por defecto. Los usuarios administradores pueden cambiar el algoritmo predeterminado a RSA (Rivest-Shamir-Adleman) rotando las claves privadas.
  • Clave de cookie OIDC Cuando el usuario inicia un flujo de inicio de sesión o registro, se crea una "sesión OIDC" en el servidor, así como un conjunto de cookies en el navegador. Con estas cookies, el navegador puede solicitar a la Experience API de Logto realizar una serie de interacciones en nombre del usuario, como iniciar sesión, registrarse y restablecer la contraseña. Sin embargo, a diferencia de los JWTs, las cookies solo son firmadas y verificadas por el propio servicio OIDC de Logto, no se requieren medidas de criptografía asimétrica. Por lo tanto, no tenemos claves públicas emparejadas para las claves de firma de cookies, ni algoritmos de cifrado asimétrico.

Rotar claves de firma desde la Consola​

Logto introduce la función de "Rotación de claves de firma", que te permite crear una nueva clave privada OIDC y una clave de cookie en tu tenant.

  1. Navega a Consola > Configuración del tenant > Configuración OIDC. Desde allí, puedes gestionar tanto las claves privadas OIDC como las claves de cookies OIDC.

  2. Para rotar la clave de firma, haz clic en el botón "Rotar claves privadas" o "Rotar claves de cookies". Al rotar las claves privadas, tienes la opción de cambiar el algoritmo de firma.

  3. Encontrarás una tabla que enumera todas las claves de firma en uso. Para las claves privadas OIDC, puedes eliminar la clave anterior, pero no puedes eliminar la clave actual ni la siguiente. Para las claves de cookies OIDC, puedes eliminar la clave anterior, pero no puedes eliminar la clave actual.

    EstadoDescripción
    Siguiente (Next)Este estado se utiliza para la rotación escalonada de la clave privada OIDC. La clave ha sido creada, pero Logto no la usará para firmar nuevos JWTs hasta que finalice el período de gracia y la clave se vuelva efectiva.
    Actual (Current)Indica que esta clave está siendo utilizada actualmente por Logto para firmar los JWTs o cookies recién emitidos.
    Anterior (Previous)Se refiere a una clave que se usó previamente pero que ha sido rotada. Los JWTs o cookies existentes firmados con esta clave siguen siendo válidos hasta que expiren o la clave sea eliminada.

Recuerda que la rotación implica las siguientes tres acciones:

  1. Crear una nueva clave de firma: Para las claves privadas OIDC, Logto puede preparar la nueva clave como "Siguiente" primero para que tus aplicaciones y APIs tengan tiempo de actualizar la clave pública desde el endpoint /oidc/jwks antes de que la nueva clave se utilice para firmar.
  2. Rotar la clave actual: Cuando la rotación se hace efectiva, la clave "Siguiente" pasa a ser "Actual", y la clave "Actual" existente pasa a ser "Anterior". Los tokens firmados con la clave anterior seguirán siendo válidos.
  3. Eliminar la clave anterior más antigua: Logto mantiene como máximo una clave privada "Anterior". Si ya existe una clave privada anterior cuando la clave preparada pasa a ser actual, la clave anterior más antigua será eliminada.

Para Logto Cloud, la rotación de la clave privada OIDC entra en vigor después de un período de gracia de 4 horas. Durante este período, la nueva clave se prepara y se expone a través de JWKS antes de que Logto comience a firmar los JWTs recién emitidos con ella. En la tabla de la Consola, la columna Efectiva en muestra cuándo una clave "Siguiente" preparada pasará a ser "Actual".

Para implementaciones OSS autogestionadas, el período de gracia predeterminado para la rotación de la clave privada es de 0 segundos, lo que significa que la rotación es inmediata. Para usar la rotación escalonada, establece la variable de entorno PRIVATE_KEY_ROTATION_GRACE_PERIOD en el servicio Logto, o pasa un valor explícito de rotationGracePeriod en el cuerpo de la solicitud al llamar al endpoint de la Management API POST /api/configs/oidc/private-keys/rotate.

aviso:

Evita rotar las claves de firma repetidamente antes de que la rotación pendiente se haga efectiva, a menos que quieras reemplazar intencionalmente la clave "Siguiente" preparada.

Eliminar la única clave "Anterior" demasiado pronto puede invalidar los JWTs o cookies existentes que fueron firmados con esa clave.

Introducción a los algoritmos de firma EC y RSA en JWT