署名キーをローテーションする

POST /v1/signing-keys:rotate · 権限 signing-keys:write

自動スケジュールとは別に、今すぐ署名キーのローテーションを実行します。

フェデレーションキー

use では、環境のフェデレーションキーのいずれかを指定することもできます。指定可能なのは、saml_sp_signing および saml_sp_encryption（SP メタデータに公開される SAML サービスプロバイダーの署名用および暗号化用キー）、または oidc_rp_signing（エンタープライズ OIDC 接続の private_key_jwt キー。/sso/jwks.json で公開）です。これらのキーは常に RSA-3072 で、1年ごとに自動的にローテーションされます。新しい next キーは引き継ぎの30日前に公開され、古いキーは引き継ぎ後も30日間公開されたままです。

フェデレーションキーの場合、レスポンスのnext_kidはnullとなり、removed_kidsは空になります。また、revoke_sessions は許可されません。環境で SAML やprivate_key_jwt を一度も使用していない場合、ローテーション対象のキーが存在しないため、呼び出しは409 conflictで失敗します。

接続キー

SAML 接続には、環境のキーではなく専用の SP キーを設定できます。それらをローテーションするには、use: saml_sp_signing または saml_sp_encryption と併せて connection_id（conn_…）を追加します。モード、権限、ルールは同じですが、変更されるのはその接続のキーセットのみです。環境のキーと他の接続のキーはそのまま残り、connection.sp_certificate_rotation_started イベントはその接続に対してのみ送信されます。監査レコードの対象は環境として記録され、接続はmetadata.connection_id に記録されます。不明な接続、または別の環境の接続を指定すると、404 not_foundで失敗します。環境のキーを使用している接続を指定すると、409 connection_keys_not_dedicatedで失敗します（connection_id を指定せずに環境のキーをローテーションしてください）。connection_id を指定しない場合は、環境のキーセットがローテーションされます。

緊急モードでは、signing-keys:write に加えて、認証情報に明示的に付与された signing-keys:emergency 権限が必要です。この権限を持つ制限付きキーまたは M2M クライアントだけが呼び出せます。フルアクセスのシークレットキー（idp_sk_…）は、緊急モードでは403 insufficient_permissionsになります。

新しいトークン署名キーは、環境ポリシーのアルゴリズムを使用します（ポリシーを取得）。トークン署名キーのローテーションが成功すると、signing_key.rotated または signing_key.revoked Webhook イベントが送信されます。すべてのローテーションは管理監査レコードに記録されます。このエンドポイントは「キーとシークレットの発行」のレート制限ファミリーに属します。Idempotency-Key を送信してください。ネットワークエラーの後にリトライすると、2回ローテーションするのではなく、最初の結果が返されます。

リクエスト

JSON ボディ（未知のフィールドは400 unknown_fieldで拒否されます）:

フィールド 型 必須 説明
Idempotency-Key ヘッダー いいえ 推奨。A-Z a-z 0-9 _ - の 16〜64 文字。
mode 文字列 はい immediate または emergency。
use 文字列 いいえ ローテーションするキー。既定値はtoken_signing（アクセストークンおよび ID トークンの署名キー）です。フェデレーションキーはsaml_sp_signing、saml_sp_encryption、oidc_rp_signing です（フェデレーションキー を参照）。
revoke_sessions 真偽値 いいえ 緊急モードおよびtoken_signing のみ。すべてのセッションとリフレッシュトークンも取り消します。既定値はfalse。
revoke_next 真偽値 いいえ 緊急モードのみ。公開済みのnextキーも取り消します。既定値はfalse。
reason 文字列 緊急モード: はい 緊急モードのみ。印字可能な ASCII 文字 1〜512 文字（例: インシデント番号）。シークレットや個人データは含めないでください。
connection_id 文字列 いいえ saml_sp_signing およびsaml_sp_encryption のみ。専用の SP キーを持つ SAML 接続（conn_…）。環境のキーの代わりに、その接続のキーセットがローテーションされます（接続キー を参照）。

mode: immediate を指定した場合、revoke_sessions: true、revoke_next: true、または reason を送信すると422で失敗します（not_allowed）。connection_id をtoken_signing またはoidc_rp_signing と併用すると、同様に失敗します。

レスポンス

200 OK でローテーションの結果が返されます。activated_kid は今後署名を行うキーで、next_kid は新たに公開されたnextキーです（フェデレーションキーの場合はnull）。retired_kids は署名を停止したものの公開されたままのキーです（トークン署名キーは7日間、フェデレーションキーは30日間）。revoked_kids は緊急ローテーションによって JWKS から削除されたキーです。removed_kids は7日間の期間が終了して廃止されたキーで、同じ手順で JWKS から削除されています。

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

エラー

HTTP code 条件
400 unknown_field ボディに未知のフィールドが含まれています。
400 malformed_request ボディが有効な JSON ではない、または Idempotency-Key ヘッダーが不正であるか重複しています。
403 insufficient_permissions 認証情報にsigning-keys:writeがない、または明示的に付与されたsigning-keys:emergencyなしで緊急モードが要求されました。
404 not_found connection_id がこの環境の SAML 接続を指定していません。
409 connection_keys_not_dedicated connection_id が、環境の SP キーを使用している接続を指定しています。
409 next_key_too_young アルゴリズム変更が保留中で、next キーが7日以内に公開されている、または（フェデレーションキー、immediate）next キーが7日以内に公開されています。
409 conflict 環境に公開済みのnextキーがない、フェデレーションuse の有効なキーがない、または前のフェデレーションキーがまだ30日間の重複期間内にあります。
415 unsupported_media_type Content-Type がapplication/json ではありません。
422 validation_failed フィールドが欠落しているか無効です。ポインタはそのフィールドを示します（例: /reason）。
422 idempotency_key_reuse Idempotency-Key は、別のボディで既に使用されています。
501 not_implemented この操作は、このデプロイメントではまだ利用できません。
401 unauthenticated 認証情報が見つからない、無効、または取り消されています。
429 rate_limited レート制限を超えました。Retry-After 期間の後に再試行してください。
503 service_unavailable 依存先が一時的に利用できません。Retry-After 期間の後に再試行してください。

例

通常のローテーション:

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

SAML SP 署名キーの緊急ローテーション。公開済みのnextキーも取り消します:

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

1つの接続の専用 SAML SP 署名キーの緊急ローテーション:

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