今回の Azure SDK documentation update でまず確認すべき点は、Azure Key Vault の SecurityDomain SDK が新しいフォルダー構成で再生成され、既定の API バージョンが 2025-07-01 に更新されたことです。対象は主に Python の azure-keyvault-securitydomain を使って、Azure Key Vault Managed HSM のセキュリティドメイン取得・復元・転送キー取得を自動化している管理者や開発者です。公式PRでは、SecurityDomain SDK向けの新機能追加はなく、自動生成SDKの再生成とAPIバージョン更新が中心と説明されています。(GitHub)
実務上の結論はシンプルです。Managed HSM のセキュリティドメイン操作を本番運用している場合は、依存パッケージの更新前に APIバージョン固定の有無、Error モデルへの依存、内部Mixinや自動生成コードへの依存、セキュリティドメインの保管・権限設計 を確認してください。通常のキー・シークレット・証明書操作だけで SecurityDomain SDK を使っていない環境では、直接の影響は限定的です。
Azure SDKのSecurityDomain SDK更新で何が変わったのか
今回の更新は、Azure Key Vault Managed HSM の「Security Domain」操作に関する SDK 再生成です。Security Domain は Managed HSM を利用するために必要な暗号化された blob で、HSMバックアップ、ユーザー資格情報、署名キー、Managed HSM固有のデータ暗号化キーなどを含みます。Microsoft Learn では、Security Domain が失われるとディザスターリカバリーができず、キーが永続的に失われる可能性があると説明されています。(Microsoft Learn)
今回のポイントを整理すると、次のとおりです。
| 変更点 | 内容 | 実務上の確認ポイント |
|---|---|---|
| APIバージョン更新 | 2025-07-01 がサポートされ、既定値として扱われる | 明示的に api_version="7.5" を指定しているコードがないか確認する |
| SDK再生成 | TypeSpec由来の新しい構成で自動生成コードが更新 | 自動生成ファイル、内部クラス、テストの差分に依存していないか確認する |
| モデル名変更 | 内部クラス Error が KeyVaultErrorError に変更 | azure.keyvault.securitydomain.models.Error を直接importしていないか確認する |
| 操作Mixinの内部化 | SecurityDomainClientOperationsMixin が _SecurityDomainClientOperationsMixin 側へ整理 | SDK内部クラスを継承・モックしているテストを確認する |
| ストリーム処理まわりの差分 | decompress の扱いやエラー逆シリアライズ処理に差分 | カスタムトランスポート、録画テスト、レスポンスモックを確認する |
PRのCHANGELOG差分では、2025-07-01 APIのサポート追加、Error から KeyVaultErrorError へのリネーム、Key Vault API version 2025-07-01 の既定化が記載されています。(GitHub)
これは脆弱性修正ではなく、Security Domain操作のSDK更新
「SecurityDomain」という名前から、緊急のセキュリティパッチのように見えるかもしれません。しかし、今回の公式説明では SecurityDomain SDK に新機能は含まれないとされています。つまり、直ちに脆弱性対応として全環境へ急ぎ適用する更新というより、Managed HSM のセキュリティドメイン操作を行う自動化コードの互換性確認が必要なSDK更新 と捉えるのが適切です。(GitHub)
ただし、Security Domain は Managed HSM の復旧や所有権に関わる重要な情報です。更新の性質が「SDK再生成」であっても、影響範囲の確認を省略してよいわけではありません。特に、HSMのアクティブ化、DR環境への復元、セキュリティドメインの再ダウンロードを運用手順に組み込んでいる組織では、更新前に検証環境で一連の操作を確認してください。
影響を受ける環境と受けにくい環境
影響を受けやすいのは、Azure SDK for Python の azure-keyvault-securitydomain を使っている環境です。Microsoft Learn のPython向けドキュメントでは、SecurityDomainClient により Managed HSM のセキュリティドメインのダウンロード、アップロード、転送キー取得を行えると説明されています。(Microsoft Learn)
| 環境・利用状況 | 影響度 | 理由 |
|---|---|---|
SecurityDomainClient で begin_download を使っている | 高 | Managed HSMのアクティブ化やSecurity Domain取得に関係する |
begin_upload でDR復元を自動化している | 高 | 復元処理、転送キー、ポーリング結果に影響する可能性がある |
get_transfer_key を使っている | 中〜高 | Security Domainアップロード前の暗号化処理に関係する |
| SDK内部クラスや生成コードを直接importしている | 高 | Error リネームやMixin内部化の影響を受けやすい |
| 通常の Key Vault Secrets/Keys/Certificates のみ利用 | 低 | SecurityDomain SDKを使っていなければ直接影響は小さい |
| Azure CLIだけでSecurity Domainを操作している | 低〜中 | Python SDK更新の直接影響は小さいが、APIバージョンや運用手順は確認対象 |
ここで重要なのは、「Key Vaultを使っているか」ではなく「Managed HSM の Security Domain SDK を使っているか」です。通常のシークレット取得やキー作成だけのアプリケーションなら、今回の更新が直接の改修理由になるとは限りません。
管理者が確認すべきセキュリティと権限のポイント
Security Domainの保管ルールを再確認する
Security Domain は Managed HSM の復旧に必要な中核情報です。Microsoft Learn では、Security Domain とRSA秘密鍵を安全かつ分離された場所に保管する必要があり、これらを失うとディザスターリカバリーに支障が出ると説明されています。(Microsoft Learn)
更新対応のタイミングで、次の点を棚卸ししてください。
| 確認項目 | 判断基準 |
|---|---|
| Security Domainファイルの保管場所 | 暗号化されたオフラインストレージ、物理的に分離された保管場所を使っているか |
| RSA秘密鍵の管理 | 1人がクォーラムを満たす数の秘密鍵を保持できない設計になっているか |
| 所有者の台帳 | 誰がどの鍵を保持しているか、引き継ぎ履歴が残っているか |
| 復旧テスト | 復旧手順がドキュメントだけでなく、検証環境で確認されているか |
| 退職・異動時の対応 | クォーラム構成や保管担当者を見直すプロセスがあるか |
特に失敗しやすいのは、SDK更新の検証でSecurity Domainファイルを一時的に作業端末へ置いたままにするケースです。検証用であっても、保管ポリシーから外れた場所に置かないようにしてください。
Managed HSMの権限を最小化する
Security Domain操作には、通常のキー操作とは別の権限が関係します。Microsoft Learn のManaged HSMロール定義には、Security Domainのダウンロード、ダウンロード状態確認、アップロード、アップロード状態確認、転送キー取得に対応するデータアクションが列挙されています。(Microsoft Learn)
確認すべき代表的な権限は次のとおりです。
| 操作 | 関連するデータアクション |
|---|---|
| Security Domainのダウンロード | Microsoft.KeyVault/managedHsm/securitydomain/download/action |
| ダウンロード状態の確認 | Microsoft.KeyVault/managedHsm/securitydomain/download/read |
| Security Domainのアップロード | Microsoft.KeyVault/managedHsm/securitydomain/upload/action |
| アップロード状態の確認 | Microsoft.KeyVault/managedHsm/securitydomain/upload/read |
| 転送キー取得 | Microsoft.KeyVault/managedHsm/securitydomain/transferkey/read |
本番環境では、Managed HSM Administrator のような強い権限を常時付与するのではなく、必要な作業時間だけ有効化する設計が望まれます。公式ドキュメントでも、Managed HSM Administrator は高権限ロールであり、Security Domain関連操作の通知・アラートやPIMの利用が推奨されています。(Microsoft Learn)
開発者が確認すべき実装・移行ポイント
APIバージョンを暗黙に任せているか、明示しているかを確認する
今回の更新では、SecurityDomain SDKの既定APIバージョンが 2025-07-01 に変わります。PRの差分では、従来 7.5 だった既定値が 2025-07-01 に更新されている箇所が複数確認できます。(GitHub)
まず、コードベース全体で次のような指定を検索してください。
grep -R "api_version" .
grep -R "7.5" .
grep -R "7.6" .
grep -R "SecurityDomainClient" .明示的に古いAPIバージョンを指定している場合は、意図して固定しているのか、過去のサンプルをそのまま使っているだけなのかを判断します。特別な理由がなければ、検証環境で 2025-07-01 を使う形に寄せるのが自然です。
from azure.identity import DefaultAzureCredential
from azure.keyvault.securitydomain import SecurityDomainClient
credential = DefaultAzureCredential()
client = SecurityDomainClient(
vault_url="https://<your-hsm-name>.managedhsm.azure.net",
credential=credential,
api_version="2025-07-01",
)本番でいきなり既定値任せに変更するのではなく、まずステージング環境で明示的に 2025-07-01 を指定して、ダウンロード、アップロード、転送キー取得、エラー時のログ出力を確認してください。
Error モデルを直接使っていないか確認する
今回の差分で見落としやすいのが、内部クラス Error から KeyVaultErrorError へのリネームです。CHANGELOG上は内部クラスの変更として扱われていますが、テストコードや独自の例外処理で直接importしている場合は壊れる可能性があります。(GitHub)
確認すべきコード例は次のようなものです。
from azure.keyvault.securitydomain.models import Errorこのようなコードがある場合、まず本当にSDK内部モデルへ依存する必要があるかを見直してください。多くのアプリケーションでは、具体的な内部エラーモデルではなく、azure.core.exceptions.HttpResponseError などの上位例外を捕捉し、ステータスコード、エラーコード、メッセージをログ化する設計のほうが保守しやすくなります。
SDK内部のMixinや自動生成コードに依存していないか確認する
PRのレビュー概要では、操作Mixinの名前変更、_failsafe_deserialize の引数変更、ストリーム処理での decompress 扱い、自動生成コードの型表現変更などが示されています。(GitHub)
通常の利用では、これらの内部差分を意識する必要はあまりありません。しかし、次のような実装をしている場合は注意が必要です。
| 実装パターン | リスク |
|---|---|
_operations 配下のクラスを直接importしている | 内部クラス名変更でimportエラーになる |
| 自動生成メソッドを直接モックしている | メソッド引数や戻り値の扱いが変わりテストが落ちる |
| レスポンスJSONを前提にエラー処理を書いている | エラー逆シリアライズ処理の変更で想定と違うログになる |
stream=True でレスポンスを扱っている | iter_bytes / iter_raw の扱いを確認する必要がある |
| SDK生成物のファイルパスをCIで参照している | 新しいフォルダー構成でパスが変わる可能性がある |
「動いているから大丈夫」と判断せず、特にテストダブルやモックを使っている箇所を重点的に確認してください。SDKの内部実装を前提にしたテストは、今回のような再生成で壊れやすいポイントです。
管理者・開発者向けの検証手順
更新対応は、次の順で進めると失敗しにくくなります。
| 手順 | 作業内容 | 完了条件 |
|---|---|---|
| 依存関係の棚卸し | azure-keyvault-securitydomain の利用有無とバージョンを確認 | 本番・検証・CIの依存バージョンが把握できている |
| コード検索 | SecurityDomainClient、api_version、Error、_operations を検索 | 直接影響を受ける箇所が一覧化されている |
| 権限確認 | Managed HSMのSecurity Domain関連データアクションを確認 | 必要最小限のロール設計になっている |
| 検証環境で更新 | パッケージ更新後、2025-07-01 で操作を実行 | ダウンロード、アップロード、転送キー取得が成功する |
| エラー系テスト | 不正権限、存在しないHSM、失敗レスポンスを確認 | 例外処理とログが期待どおり |
| 運用手順の更新 | Runbook、DR手順、保管台帳を修正 | 作業者が同じ手順で再現できる |
| 本番展開 | 段階的に更新し、監視を強化 | エラー率、認証失敗、Security Domain操作ログに異常がない |
依存パッケージの確認には、次のようなコマンドが使えます。
python -m pip show azure-keyvault-securitydomain
python -m pip freeze | grep azure-keyvault-securitydomainCI/CDでは、requirements.txt や pyproject.toml でバージョン範囲を広く指定している場合に注意が必要です。たとえば azure-keyvault-securitydomain>=1.0.0b1 のように指定していると、将来の更新を自動で取り込む可能性があります。Managed HSMの復旧に関わる処理では、意図しない自動更新を避けるため、検証済みバージョンへ固定し、更新時は手動で検証する運用が安全です。
REST API利用者が確認すべき点
SDKではなくREST APIを直接呼び出している場合も、api-version=2025-07-01 の扱いを確認してください。Microsoft Learn のREST APIリファレンスでは、HSM Security Domain のダウンロード操作は POST {vaultBaseUrl}/securitydomain/download?api-version=2025-07-01 として記載されています。(Microsoft Learn)
REST API利用者は、次の点を確認します。
| 確認項目 | 内容 |
|---|---|
| エンドポイント | Managed HSMのURLを使っているか |
| APIバージョン | 2025-07-01 を指定した検証が済んでいるか |
| 認証スコープ | https://vault.azure.net/.default を使った認証が成立するか |
| リクエスト本文 | 証明書情報とクォーラム指定が手順どおりか |
| 非同期処理 | Azure-AsyncOperation と Retry-After を正しく扱っているか |
| エラー処理 | Key Vault Error形式を想定してログ・再試行を設計しているか |
Security Domainのダウンロードは、Managed HSMをアクティブ化する操作にも関係します。Azure CLIのクイックスタートでは、Managed HSMのアクティブ化にはSecurity Domainのダウンロードが必要で、少なくとも3つ、最大10個のRSAキーペアとクォーラム指定が必要と説明されています。(Microsoft Learn)
展開時に失敗しやすいポイント
本番だけ古いAPIバージョン固定が残っている
開発環境では既定値で動くのに、本番だけ環境変数や設定ファイルで 7.5 を指定しているケースがあります。APIバージョンはコードだけでなく、Terraform、Ansible、GitHub Actions、Azure DevOpsの変数、Kubernetes Secret、App Service設定にも残りがちです。
SDK内部をモックしたテストが壊れる
今回のような自動生成SDKの更新では、公開APIではなく内部構造に依存したテストが壊れやすくなります。テストが壊れた場合は、単にモックを修正するのではなく、「SDK内部ではなく公開メソッドの入出力をテストできないか」を見直してください。
Security Domainファイルを検証環境に置きっぱなしにする
検証中にSecurity DomainファイルやRSA秘密鍵をローカル端末、共有フォルダー、CIログ、チケット添付に残すのは危険です。ファイル名に <hsm-name>-SD.json のような分かりやすい名前を使う場合は、保管場所と削除手順までRunbookに明記してください。
パッケージ公開タイミングとGitHubマージを混同する
GitHubのPRがマージされても、利用中の環境に即座に反映されるとは限りません。実際の影響は、PyPIなどのパッケージ配布、依存解決、CI/CDの更新タイミングで決まります。更新確認では「PRがマージされたか」だけでなく、「自分の環境でどのパッケージ版がインストールされているか」を必ず確認してください。
今回の更新を受けて取るべき行動
SecurityDomain SDKを使っている場合、最初にやるべきことは大きな改修ではなく、影響範囲の切り分けです。次の順で進めてください。
azure-keyvault-securitydomainを使っているサービス、バッチ、Runbook、CIジョブを洗い出す。api_version、Error、SecurityDomainClientOperationsMixin、_operationsへの依存を検索する。- 検証環境で
2025-07-01を使い、ダウンロード・アップロード・転送キー取得・エラー処理を確認する。 - Managed HSMのSecurity Domain操作権限、PIM、アラート、保管台帳を見直す。
- 問題がなければ、依存バージョンを固定して段階的に本番展開する。
今回のAzure SDK更新は、SecurityDomain SDKに新機能を追加するものではなく、APIバージョン 2025-07-01 と新しい生成構成へ揃えるための変更です。だからこそ、表面的なリリース確認だけで終わらせず、Managed HSMの復旧に関わるコード、権限、保管手順まで合わせて点検する価値があります。特に本番環境では、「SDKを更新して終わり」ではなく、「復旧できる状態を維持できているか」を基準に判断してください。
コメント