# CMEK鍵の障害検知と復旧を三層で設計する方法

> external_key.failedはKMSが鍵を拒否してから30分以内に届くが、届かない場合もある。Claudeの顧客管理鍵の障害を取りこぼさず検知し復旧する設計を解説する。

- Canonical: https://kuucorp.com/blog/claude-cmek-external-key-webhook-failure-detection-recovery-design/
- Date: 2026-11-22
- Last modified: 2026-11-22
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
顧客管理鍵（CMEK）でClaudeのデータを保護すると、KMS側で鍵を無効化した瞬間に、Claudeを使う全ワークスペースが止まり得ます。鍵の無効化は運用ミスでも起きるため、止まったことに最初に気づく仕組みが統制の要件になります。2026年11月16日、組織webhookに `external_key.failed` と `external_key.recovered` が追加されました。この記事は、イベントを軸にした検知と復旧の設計を、取りこぼしを前提にまとめます。

## external_key.failedはどんな条件で届くのか

> KMSが鍵の利用を拒否し続けるとfailedが届き、復旧するとrecoveredが届きます。到達は最大30分遅れます。

トリガーは、鍵の無効化や、Anthropicへのアクセス権の取り消しなど、KMSによる**実際の拒否**です。テストイベントはありません。ペイロードは `data.id`（`ekey_` で始まる鍵ID）と `organization_id` のみで、ワークスペースは含まれません。1つの鍵を複数のワークスペースが使えるためです。

到達時間の目安は、各ワークスペースが毎分1回程度Messages APIを呼ぶ場合で次のとおりです。トラフィックが少ないほど遅くなります。

- `external_key.failed`: 鍵の無効化から30分以内。到着時点でリクエストが成功することもあります
- `external_key.recovered`: 鍵が復旧してから約30分後

## webhookだけで検知してはいけない理由は何か

> イベントは取りこぼし得ます。鍵を使うリクエストがなければ検知されず、KMS障害は拒否に数えられません。

公式ドキュメントが挙げる取りこぼしの条件は、次のとおりです。

1. 鍵を使うリクエストがない（拒否が観測されない）
2. KMSの障害やタイムアウト（拒否ではないため両イベントとも出ない）
3. 複数組織で同時に鍵が失敗した場合（Anthropicまたはクラウド側が原因の可能性があり、イベントもメールも出ない）
4. Default Workspaceの鍵が失敗し、エンドポイントの値を暗号化している場合（自身のfailedを含む全イベントが止まる）

配信自体も、再送は数分で打ち切られ、失敗したイベントは破棄されます。連続失敗や3xx応答でエンドポイントが自動で無効化されても、通知はありません。結果として `failed` が2回続く、`failed` なしの `recovered` が届く、といった順序の乱れも起こります。受信側は冪等にし、`webhook-id` で重複排除してください。

## 検知と復旧の設計はどう組むべきか

> 三層で組みます。webhookは速報、cmek_keyエラーは実害の検知、定期validateが最終防衛線です。

**第1層: webhook受信。** 署名（Standard Webhooks の `webhook-id` / `webhook-timestamp` / `webhook-signature`）を検証し、5秒以内に2xxを返します。重い処理はキューに回します。

**第2層: APIエラーの監視。** 次の3つのエラーコードを別個にアラート化します。

- `cmek_key_disabled`（400）: 鍵の無効化
- `cmek_key_network_blocked`: ネットワークによるアクセス遮断
- `cmek_key_unreachable`（503）: KMSに到達できない。再試行可能

**第3層: 定期照合。** 1日1回など、鍵一覧を取得して各鍵をvalidateします。エンドポイントの `state` が `enabled` かも併せて確認します。

イベントを受けた後の標準手順は次のとおりです。

```text
POST /v1/organizations/external_keys/{id}/validate
  → status=failure : error の指示に従う / CMEKトラブルシュートを参照
  → status=success : 鍵を使う全ワークスペースで Messages API を1回送る
```

validateは1ワークスペース分の暗号化・復号の往復しか試さず、最大30秒待ちます。AWSでワークスペース単位にキーポリシーを絞っている場合、validateが成功しても他のワークスペースは拒否され得ます。したがって、`external_key_id` で一致するワークスペースを列挙し、個別に疎通確認します。無効化の反映には最大1時間かかるため、成功した場合は `failed` の1時間後に再確認が必要です。復旧後は `recovered` を待たず、同じ確認を繰り返します。

## 運用上の落とし穴と統制の要点は何か

> 鍵の削除は取り消せず復元もできません。無効化は再有効化で戻せますが、失敗中のリクエストは再試行されません。

- **削除と無効化の区別:** KMSで鍵を削除・削除予約・鍵素材を破棄すると、データは復元できません。無効化なら再有効化で戻ります。この差を、KMSの権限設計（削除権限の分離、削除予約期間の確保）に反映します
- **Default Workspaceの依存:** 鍵がDefault Workspaceに使われると、エンドポイントの `name`、`description`、署名シークレットが鍵に依存します。障害中は配信が失敗し、イベントは後から送られません。警報の経路をClaude外の監視基盤にも持たせます
- **変更の不可逆性:** ワークスペースに一度attachした鍵は、外すことも差し替えることもできません。鍵の `provider_config` も、参照後は実質変更できません。鍵の変更は、新しいワークスペースを作って移行します
- **削除の制約:** 鍵のレコードは、アーカイブ済みを含むどのワークスペースも使っていない場合に限り削除できます
- **スコープ:** 受信用の認証情報には、Admin APIキー、または `org:admin` スコープのトークンを使います。最小権限で分離し、鍵はシークレット管理基盤で保管します

大規模な組織では、鍵のライフサイクルと障害対応のRunbookを、クラウド基盤チーム・セキュリティチームと合同で整備することが成功条件になります。AI変革全体の統制設計は [RDE](https://kuucorp.com/services/rde/) で伴走しています。関連する設計は[Claudeのデータ保持とFable 5.2移行](/blog/claude-fable-5-2-migration-covered-model-retention-enterprise/)と[組織webhookの受信設計](/blog/claude-org-webhook-enforcement-receiver-reconcile-smb/)も参照してください。

## 参考

- [Organization webhooks（Claude Platform Docs）](https://platform.claude.com/docs/en/manage-claude/organization-webhooks)
- [What happens when you rotate, disable, or delete your encryption key](https://platform.claude.com/docs/en/manage-claude/cmek-key-lifecycle)
- [External Keys API リファレンス](https://platform.claude.com/docs/en/api/admin/external_keys)
- [Claude Platform リリースノート](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

CMEKの障害は、webhookだけでは確実に検知できません。webhookを速報、`cmek_key_*` エラーを実害の検知、定期validateを最終防衛線とする三層で組むと、取りこぼしの穴を塞げます。鍵の運用統制や検知基盤の設計で迷う場合は、[Kuu株式会社のRDE](https://kuucorp.com/services/rde/)にご相談ください。
