İmzalama anahtarlarını yenileme

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

Otomatik takvimin dışında, hemen bir imzalama anahtarı yenilemesi çalıştırır.

• mode: immediate: Normal yenileme adımı hemen çalışır. Önceden yayımlanmış next anahtarı imzalamaya başlar, eski active anahtarı 7 gün boyunca retired olarak kalır ve yeni bir next anahtarı yayımlanır. next, etkin anahtardan farklı bir algoritma kullanıyorsa (algoritma değişikliği) ve 7 günden kısa süre önce yayımlanmışsa, çağrı 409 next_key_too_young hatasıyla başarısız olur.
• mode: emergency (anahtarın ele geçirildiğinden şüphelenilmesi): Eski active anahtarı iptal edilir ve JWKS'ten hemen çıkarılır; next etkin hale gelir ve yeni bir next üretilir. revoke_next: true ayrıca next anahtarını iptal eder ve yeni üretilmiş, hiç yayımlanmamış bir anahtarı etkinleştirir. revoke_sessions: true ayrıca ortamın tüm oturumlarını ve yenileme jetonu ailelerini iptal eder, böylece kullanıcılar yeniden giriş yapmak zorunda kalır. reason zorunludur.

Federasyon anahtarları

use ortamın federasyon anahtarlarından birini de belirtebilir: saml_sp_signing ve saml_sp_encryption (SP metadata'nızda yayımlanan SAML hizmet sağlayıcı imzalama ve şifreleme anahtarları) veya oidc_rp_signing (kurumsal OIDC bağlantılarının private_key_jwt anahtarı, /sso/jwks.json adresinde yayımlanır). Bu anahtarlar her zaman RSA-3072'dir ve kendiliğinden yılda bir kez yenilenir: yeni bir next anahtarı, devralmasından 30 gün önce yayımlanır ve eski anahtar devralmanın ardından 30 gün boyunca yayımlı kalır.

• mode: immediate, önceden yayımlanmış next anahtarını hemen etkinleştirir; eski anahtar 30 gün daha yayımlı kalır (retired_kids içinde görünür). Yayımlanmış bir next anahtarı yoksa çağrı 409 conflict hatasıyla başarısız olur; next anahtarı 7 günden kısa süre önce yayımlanmışsa 409 next_key_too_young hatasıyla başarısız olur.
• mode: emergency, etkin anahtarı metadata'dan veya JWKS'ten hemen kaldırır ve özel anahtarını yok eder (revoked_kids). Yayımlanmış next anahtarı etkin hale gelir; böyle bir anahtar yoksa veya revoke_next: true ile kullanılıyorsa, hiç yayımlanmamış yeni bir anahtar bu görevi üstlenir. Metadata'yı veya JWKS'i URL'sinden yükleyen kimlik sağlayıcılar değişikliği bir sonraki yenilemelerinde alır. Metadata'yı veya sertifikayı elle yüklediğiniz sağlayıcılar, yeni sertifikayı yükleyene kadar oturum açmaları reddeder; bu durum için etkilenen her bağlantı için bir connection.sp_certificate_rotation_started webhook olayı gönderilir.

Federasyon anahtarı için yanıttaki next_kid null değerini alır, removed_kids boş kalır ve revoke_sessions kullanılamaz. Ortam hiç SAML veya private_key_jwt kullanmadıysa yenilenecek anahtar yoktur ve çağrı 409 conflict hatasıyla başarısız olur.

Bağlantı anahtarları

Bir SAML bağlantısı, ortamın anahtarları yerine kendine özgü SP anahtarlarına sahip olabilir. Bunları yenilemek için connection_id (conn_…) değerini use: saml_sp_signing veya saml_sp_encryption ile ekleyin. Aynı modlar, izinler ve kurallar geçerlidir; ancak yalnızca o bağlantının anahtar kümesi değişir: ortamın anahtarları ve diğer bağlantıların anahtarları olduğu gibi kalır ve connection.sp_certificate_rotation_started olayı yalnızca o bağlantı için gönderilir. Denetim kaydı, hedef olarak ortamı, bağlantıyı ise metadata.connection_id alanında belirtir. Bilinmeyen bir bağlantı veya başka bir ortama ait bir bağlantı 404 not_found hatasıyla başarısız olur; ortamın anahtarlarını kullanan bir bağlantı 409 connection_keys_not_dedicated hatasıyla başarısız olur (ortamın anahtarlarını connection_id olmadan yenileyin). connection_id belirtilmezse ortamın anahtar kümesi yenilenir.

Acil durum modu, signing-keys:write dışında, kimlik bilgisinde açıkça verilmiş signing-keys:emergency iznini gerektirir: bu çağrıyı yalnızca kısıtlı bir anahtar veya bu izni taşıyan bir M2M istemcisi yapabilir. Tam erişimli bir gizli anahtar (idp_sk_…) acil durum modunda 403 insufficient_permissions alır.

Yeni jeton imzalama anahtarları, ortam politikasının algoritmasını kullanır (politikayı alın). Başarılı bir jeton imzalama anahtarı yenilemesi signing_key.rotated veya signing_key.revoked webhook olayını yayar; her yenileme bir yönetim denetim kaydı yazar. Bu uç nokta "anahtar ve gizli anahtar düzenleme" hız sınırı ailesine aittir. Bir Idempotency-Key başlığı gönderin: ağ hatasından sonra yapılan yeniden denemede, iki kez yenilemek yerine ilk sonuç döndürülür.

İstek

JSON gövdesi (bilinmeyen alanlar 400 unknown_field ile reddedilir):

mode: immediate ile revoke_sessions: true, revoke_next: true veya bir reason göndermek 422 hatasıyla başarısız olur (not_allowed). token_signing veya oidc_rp_signing ile birlikte bir connection_id de aynı şekilde başarısız olur.

Yanıt

200 OK, yenilemenin sonucunu içerir. activated_kid, bundan sonra imzalayan anahtardır; next_kid ise yeni yayımlanan next anahtarıdır (federasyon anahtarı için null). retired_kids, imzalamayı bırakmış ve yayımlı kalmaya devam eden anahtarlardır (jeton imzalama anahtarı için 7 gün, federasyon anahtarı için 30 gün); revoked_kids, acil durum yenilemesiyle JWKS'ten kaldırılan anahtarlardır; removed_kids ise 7 günlük süresi dolmuş ve aynı adımda JWKS'ten çıkmış emekli anahtarlardır.

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

Hatalar

Örnek

Normal yenileme:

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

signing-keys:write ve signing-keys:emergency iznini veren kısıtlı bir anahtarla acil durum yenilemesi:

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

Yayımlanmış next anahtarını da iptal eden, SAML SP imzalama anahtarının acil durum yenilemesi:

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

Bir bağlantının kendine özgü SAML SP imzalama anahtarının acil durum yenilemesi:

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