Clés de signature
Les clés de signature OIDC de Logto, également appelées "clés privées OIDC" et "clés de cookie OIDC", sont les clés utilisées pour signer les JWT (jetons d’accès (Access tokens) et jetons d’identifiant (ID tokens)) ainsi que les cookies de navigateur dans les sessions de connexion Logto. Ces clés de signature sont générées lors de l'initialisation de la base de données Logto (open-source) ou lors de la création d'un nouveau tenant (Cloud) et peuvent être gérées via le CLI (open-source), les Management APIs ou l'interface Console UI.
Par défaut, Logto utilise l'algorithme à courbe elliptique (EC) pour générer les signatures numériques. Cependant, étant donné que les utilisateurs doivent souvent vérifier les signatures JWT et que de nombreux anciens outils ne prennent pas en charge l'algorithme EC (ne supportant que RSA), nous avons implémenté la fonctionnalité de rotation des clés privées et permis aux utilisateurs de choisir l'algorithme de signature (y compris RSA et EC). Cela garantit la compatibilité avec les services utilisant des outils de vérification de signature obsolètes.
Théoriquement, les clés de signature ne devraient pas être divulguées et n'ont pas de date d'expiration, ce qui signifie qu'il n'est pas nécessaire de les faire tourner. Cependant, effectuer une rotation périodique de la clé de signature après une certaine période peut renforcer la sécurité.
Comment ça fonctionne ?
- Clé privée OIDC
Lors de l'initialisation d'une instance Logto, une paire de clé publique et clé privée est automatiquement générée et enregistrée dans le fournisseur OIDC sous-jacent. Ainsi, lorsque Logto émet un nouveau JWT (jeton d’accès ou jeton d’identifiant), le jeton est signé avec la clé privée. Pendant ce temps, toute application cliente qui reçoit un JWT peut utiliser la clé publique associée pour vérifier la signature du jeton, afin de s'assurer que le jeton n'a pas été altéré par un tiers. La clé privée est protégée sur le serveur Logto. La clé publique, comme son nom l'indique, est publique et accessible via l'interface
/oidc/jwksdu point de terminaison OIDC. Un algorithme de clé de signature peut être spécifié lors de la génération de la clé privée, et Logto utilise par défaut l'algorithme EC (Elliptic Curve). Les administrateurs peuvent changer l'algorithme par défaut en RSA (Rivest-Shamir-Adleman) en effectuant une rotation des clés privées. - Clé de cookie OIDC Lorsqu'un utilisateur initie un flux de connexion ou d'inscription, une "session OIDC" est créée sur le serveur, ainsi qu'un ensemble de cookies de navigateur. Avec ces cookies, le navigateur peut demander à l’Experience API Logto d’effectuer une série d’interactions au nom de l’utilisateur, telles que la connexion, l’inscription et la réinitialisation du mot de passe. Cependant, contrairement aux JWT, les cookies sont uniquement signés et vérifiés par le service OIDC Logto lui-même, des mesures de cryptographie asymétrique ne sont pas requises. Ainsi, nous n'avons pas de clés publiques associées pour les clés de signature de cookie, ni d'algorithmes de chiffrement asymétrique.
Rotation des clés de signature depuis la Console UI
Logto introduit une fonctionnalité de "Rotation des clés de signature", qui vous permet de créer une nouvelle clé privée OIDC et une clé de cookie dans votre tenant.
-
Accédez à Console > Paramètres du tenant > Configurations OIDC. À partir de là, vous pouvez gérer à la fois les clés privées OIDC et les clés de cookie OIDC.
-
Pour faire tourner la clé de signature, cliquez sur le bouton "Faire tourner les clés privées" ou "Faire tourner les clés de cookie". Lors de la rotation des clés privées, vous avez la possibilité de changer l'algorithme de signature.
-
Vous trouverez un tableau qui liste toutes les clés de signature utilisées. Pour les clés privées OIDC, vous pouvez supprimer la clé précédente, mais vous ne pouvez pas supprimer la clé actuelle ou la clé suivante. Pour les clés de cookie OIDC, vous pouvez supprimer la clé précédente, mais pas la clé actuelle.
Statut Description Suivante Ce statut est utilisé pour la rotation planifiée des clés privées OIDC. La clé a été créée, mais Logto ne l'utilisera pas pour signer de nouveaux JWT tant que la période de grâce n'est pas terminée et que la clé devient effective. Actuelle Cela indique que cette clé est actuellement utilisée par Logto pour signer les nouveaux JWT ou cookies émis. Précédente Il s'agit d'une clé qui était utilisée précédemment mais qui a été remplacée. Les JWT ou cookies existants signés avec cette clé restent valides jusqu'à leur expiration ou la suppression de la clé.
Veuillez noter que la rotation implique les trois actions suivantes :
- Création d'une nouvelle clé de signature : Pour les clés privées OIDC, Logto peut d'abord préparer la nouvelle clé en tant que "Suivante" afin que vos applications et APIs aient le temps de rafraîchir la clé publique depuis le point de terminaison
/oidc/jwksavant que la nouvelle clé ne soit utilisée pour la signature. - Rotation de la clé actuelle : Lorsque la rotation devient effective, la clé "Suivante" devient "Actuelle", et la clé "Actuelle" existante devient "Précédente". Les jetons signés avec la clé précédente resteront valides.
- Suppression de la plus ancienne clé précédente : Logto conserve au maximum une seule clé privée "Précédente". Si une clé privée précédente existe déjà lorsque la clé planifiée devient actuelle, l'ancienne clé précédente sera supprimée.
Pour Logto Cloud, la rotation des clés privées OIDC prend effet après une période de grâce de 4 heures. Pendant cette période, la nouvelle clé est préparée et exposée via JWKS avant que Logto ne commence à signer les nouveaux JWT avec celle-ci. Dans le tableau de la Console, la colonne Effective à indique quand une clé "Suivante" deviendra "Actuelle".
Pour les déploiements OSS auto-hébergés, la période de grâce par défaut pour la rotation des clés privées est de 0 secondes, ce qui signifie que la rotation est immédiate. Pour utiliser une rotation planifiée, définissez la variable d'environnement PRIVATE_KEY_ROTATION_GRACE_PERIOD sur le service Logto, ou passez une valeur explicite rotationGracePeriod dans le corps de la requête lors de l'appel à l'endpoint Management API POST /api/configs/oidc/private-keys/rotate.
Évitez de faire tourner les clés de signature à plusieurs reprises avant que la rotation en attente ne devienne effective, sauf si vous souhaitez intentionnellement remplacer la clé "Suivante" planifiée.
Supprimer trop tôt la seule clé "Précédente" peut invalider les JWT ou cookies existants qui ont été signés avec cette clé.
Ressources associées
Introduction aux algorithmes de signature EC et RSA dans les JWT