Rotation des clés de signature

POST /v1/signing-keys:rotate · autorisation signing-keys:write

Lance une rotation de clé de signature immédiatement, en dehors du calendrier automatique.

• mode: immediate : l'étape de rotation régulière s'exécute aussitôt. La clé next préalablement publiée commence à signer, l'ancienne clé active reste retired pendant 7 jours et une nouvelle clé next est publiée. Si next utilise un algorithme différent de celui de la clé active (changement d'algorithme) et a été publiée il y a moins de 7 jours, l'appel échoue avec 409 next_key_too_young.
• mode: emergency (compromission présumée d'une clé) : l'ancienne clé active est révoquée et disparaît du JWKS immédiatement ; next devient active et une nouvelle clé next est générée. revoke_next: true révoque aussi next et active une clé fraîchement générée, qui n'a jamais été publiée. revoke_sessions: true révoque en outre toutes les sessions et toutes les familles de jetons d'actualisation de l'environnement, de sorte que les utilisateurs doivent se reconnecter. reason est obligatoire.

Clés de fédération

use peut aussi désigner une des clés de fédération de l'environnement : saml_sp_signing et saml_sp_encryption (les clés de signature et de chiffrement du fournisseur de service SAML, publiées dans vos métadonnées SP) ou oidc_rp_signing (la clé private_key_jwt des connexions OIDC d'entreprise, publiée à /sso/jwks.json). Ces clés sont toujours des RSA-3072 et tournent une fois par an automatiquement : une nouvelle clé next est publiée 30 jours avant de prendre le relais, et l'ancienne clé reste publiée pendant 30 jours après.

• mode: immediate rend active immédiatement la clé next préalablement publiée ; l'ancienne clé reste publiée 30 jours de plus (elle apparaît dans retired_kids). Sans clé next publiée, l'appel échoue avec 409 conflict ; si la clé next a été publiée il y a moins de 7 jours, il échoue avec 409 next_key_too_young.
• mode: emergency retire immédiatement la clé active des métadonnées ou du JWKS et détruit sa clé privée (revoked_kids). La clé next publiée devient active ; s'il n'y en a aucune, ou avec revoke_next: true, une nouvelle clé jamais publiée prend sa place. Les fournisseurs d'identité qui chargent vos métadonnées ou votre JWKS depuis leur URL prennent le changement en compte lors de leur prochaine actualisation. Les fournisseurs auxquels vous avez transmis les métadonnées ou le certificat à la main rejettent les connexions tant que vous n'avez pas téléversé le nouveau certificat ; dans ce cas, un événement webhook connection.sp_certificate_rotation_started est envoyé pour chaque connexion concernée.

Pour une clé de fédération, next_kid dans la réponse vaut null, removed_kids est vide et revoke_sessions n'est pas autorisé. Si l'environnement n'a jamais utilisé SAML ni private_key_jwt, il n'y a aucune clé à faire tourner et l'appel échoue avec 409 conflict.

Clés de connexion

Une connexion SAML peut avoir ses propres clés SP dédiées au lieu de celles de l'environnement. Pour les faire tourner, ajoutez connection_id (conn_…) avec use: saml_sp_signing ou saml_sp_encryption. Les mêmes modes, autorisations et règles s'appliquent, mais seul l'ensemble de clés de cette connexion change : les clés de l'environnement et celles des autres connexions restent inchangées, et l'événement connection.sp_certificate_rotation_started n'est envoyé que pour cette connexion. L'enregistrement d'audit désigne l'environnement comme cible et la connexion dans metadata.connection_id. Une connexion inconnue, ou appartenant à un autre environnement, échoue avec 404 not_found ; une connexion qui utilise les clés de l'environnement échoue avec 409 connection_keys_not_dedicated (faites tourner les clés de l'environnement sans connection_id). Sans connection_id, c'est l'ensemble de clés de l'environnement qui est renouvelé.

Le mode d'urgence exige, en plus de signing-keys:write, l'autorisation signing-keys:emergency accordée explicitement sur l'identifiant : seule une clé restreinte ou un client M2M portant cette autorisation peut l'appeler. Une clé secrète à accès complet (idp_sk_…) reçoit 403 insufficient_permissions en mode d'urgence.

Les nouvelles clés de signature des jetons utilisent l'algorithme défini par la politique de l'environnement (obtenir la politique). Une rotation réussie de la clé de signature des jetons émet l'événement webhook signing_key.rotated ou signing_key.revoked ; chaque rotation écrit un enregistrement d'audit de gestion. Ce point de terminaison appartient à la famille de limites de débit « émission de clés et de secrets ». Envoyez un Idempotency-Key : une nouvelle tentative après une erreur réseau renvoie alors le premier résultat au lieu de faire tourner la clé deux fois.

Requête

Corps JSON (les champs inconnus sont rejetés avec 400 unknown_field) :

Avec mode: immediate, l'envoi de revoke_sessions: true, revoke_next: true ou d'un reason échoue avec 422 (not_allowed). Un connection_id avec token_signing ou oidc_rp_signing échoue de la même manière.

Réponse

200 OK avec le résultat de la rotation. activated_kid est la clé qui signe désormais et next_kid la nouvelle clé next publiée (null pour une clé de fédération). retired_kids sont les clés qui ont cessé de signer et restent publiées (7 jours pour une clé de signature de jetons, 30 jours pour une clé de fédération) ; revoked_kids sont les clés retirées du JWKS par une rotation d'urgence ; removed_kids sont les clés retirées dont la fenêtre de 7 jours est échue et qui ont quitté le JWKS lors de la même étape.

{
  "mode": "immediate",
  "use": "token_signing",
  "activated_kid": "ypeBEsobvcr6wjGzmiPcTaeG7_gUfE5yuYB3ha_uSLs",
  "next_kid": "GKw-c0PwFokMUQ6T-TUmEWnZ4_VlQ2Qpgw-vCTT0-OQ",
  "retired_kids": ["PiPoFgA5WUoziU9lZOGxNIu9egCI1CxKy3PurtWcAJ0"],
  "revoked_kids": [],
  "removed_kids": ["Ln0sA6lQeuJl7PW1NWiFpTOTogKdJBOUmXJloaJa78Y"],
  "revoke_sessions": false
}

Erreurs

Exemple

Rotation régulière :

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"immediate"}'

Rotation d'urgence avec une clé restreinte qui accorde signing-keys:write et signing-keys:emergency :

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","revoke_sessions":true,"reason":"INC-2041 key exposure"}'

Rotation d'urgence de la clé de signature SP SAML, avec révocation aussi de la clé next publiée :

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","revoke_next":true,"reason":"INC-2042 SP key exposure"}'

Rotation d'urgence de la clé de signature SP SAML dédiée d'une connexion :

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","connection_id":"conn_01h2xcejqtf2nbrexx3vqjhp41","reason":"INC-2043 connection key exposure"}'