Azure REST API documentation update の「[Key Vault] Removed basic setup from SecurityDomain SDK」は、Key Vault のREST APIエンドポイントやリクエスト形式が変わる告知ではありません。結論から言うと、今回の変更は Key Vault Managed HSM の SecurityDomain SDK生成設定から、Python向けの basic-setup-py 設定を削除するSDK構成の整理です。REST APIを直接呼び出している管理者・開発者への影響は限定的ですが、Azure REST API specsからPython SDKを再生成しているチーム、CI/CDでSDKパッケージングを検証しているチームは確認が必要です。対象PRでは、specification/keyvault/data-plane/SecurityDomain/tspconfig.yaml の1行削除が行われ、API仕様そのものは変更しないSDK設定変更として説明されています。(GitHub)
今回のAzure REST API documentation updateで何が変わったのか
今回の更新は、Azure REST API specsリポジトリのPR「[Key Vault] Removed basic setup from SecurityDomain SDK」によるものです。PRはKey VaultのSecurityDomain SDKに関する設定変更で、tspconfig.yaml から "basic-setup-py": true が削除されています。PR本文では、SecurityDomain SDKはすでに pyproject.toml を使用しているため、basic setupを削除すると説明されています。(GitHub)
| 確認項目 | 内容 |
|---|---|
| 対象サービス | Azure Key Vault Managed HSM / SecurityDomain |
| 対象領域 | Azure REST API specs内のSDK生成設定 |
| 変更ファイル | specification/keyvault/data-plane/SecurityDomain/tspconfig.yaml |
| 削除された設定 | "basic-setup-py": true |
| API仕様変更 | PR上はSDK構成のみの変更として扱われている |
| 主な影響 | Python SDK生成、パッケージング、CI/CD検証 |
ここで重要なのは、REST APIの廃止やエンドポイント変更ではないという点です。Key Vault Managed HSMのSecurity Domain REST APIには、Download、Download Pending、Transfer Key、Upload、Upload Pendingといった操作があり、Microsoft LearnのREST APIリファレンスではAPI Version 2025-07-01 として整理されています。(Microsoft Learn)
「basic setup削除」はREST API利用者に影響するのか
REST APIを直接呼び出している利用者にとって、今回の変更による影響は基本的に小さいと考えられます。理由は、変更対象がOpenAPI/TypeSpecのAPI仕様ではなく、SDK生成に関する tspconfig.yaml のPython設定だからです。
たとえば、以下のような使い方をしている場合、今回の更新だけを理由にREST APIの呼び出しコードを変更する必要は通常ありません。
| 利用形態 | 影響度 | 確認すべきこと |
|---|---|---|
| REST APIをHTTPクライアントから直接呼び出している | 低 | api-version、エンドポイント、認可設定が既存通り動くか |
azure-keyvault-securitydomain をpipで利用している | 低〜中 | 使用中バージョン、メソッド呼び出し、テスト結果 |
| Azure REST API specsからSDKを再生成している | 中 | pyproject.toml前提のビルドにCIが対応しているか |
独自テンプレートで basic-setup-py を参照している | 中〜高 | 自動生成・検証スクリプトの修正 |
| Managed HSMのSecurity Domain運用手順を管理している | 低 | RBAC、クォーラム、秘密鍵保管手順の再確認 |
一方で、SDK生成パイプラインを持つ開発組織では注意が必要です。basic-setup-py がなくなることで、生成後の成果物を setup.py 前提で扱っている独自スクリプトが失敗する可能性があります。現在の azure-keyvault-securitydomain のSDKリポジトリ側には pyproject.toml があり、build-system や project 情報が定義されています。(GitHub)
SecurityDomain SDKとは何か
SecurityDomain SDKは、Azure Key Vault Managed HSMのセキュリティドメインを扱うためのPythonクライアントライブラリです。Microsoft Learnでは、SecurityDomainClient によりManaged HSMのSecurity Domainをダウンロード、アップロード、転送キー取得できると説明されています。(Microsoft Learn)
Security Domainは、Managed HSMを運用するうえで非常に重要なデータです。Microsoftのドキュメントでは、Managed HSMを動作させるにはSecurity Domainが必要であり、これはHSMバックアップ、ユーザー資格情報、署名キー、Managed HSM固有のデータ暗号化キーなどを含む暗号化されたblobファイルと説明されています。(Microsoft Learn)
つまり、今回の更新は「Key Vaultの通常のシークレット操作」ではなく、Managed HSMのセキュリティドメイン管理に関係するSDK生成設定の変更です。通常のKey Vaultシークレット、キー、証明書の取得・更新処理とは切り分けて考える必要があります。
管理者が確認すべきポイント
管理者がまず確認すべきなのは、今回の更新を「緊急のREST API移行」と誤解しないことです。REST API仕様変更ではなくSDK構成変更であるため、既存のManaged HSM運用手順を慌てて変更する必要はありません。
ただし、Security DomainはManaged HSMの災害復旧や所有権管理に直結します。変更の影響が限定的でも、運用面では以下を点検しておく価値があります。
| 確認項目 | 判断基準 | よくある失敗 |
|---|---|---|
| Managed HSM local RBAC | Security Domain操作に必要なデータプレーン権限があるか | Azure RBACだけ付与して満足してしまう |
| 管理者ロール | Managed HSM Administratorなど高権限ロールの利用が最小限か | 常時付与のまま放置する |
| クォーラム管理 | 複数人管理、保管場所、引き継ぎ記録があるか | 1人が復旧に必要な鍵を実質的に独占する |
| 監査・アラート | Security Domain関連操作を検知できるか | ダウンロードや状態確認を監査対象にしていない |
| DR手順 | Security Domain復元手順を机上だけでなく検証しているか | 災害時に鍵や担当者が揃わない |
Managed HSMでは、制御プレーンとデータプレーンのアクセス制御が分かれています。Microsoft Learnでは、制御プレーンはAzure RBAC、データプレーンはManaged HSM local RBACで認可され、Security Domainのダウンロードやアップロードはデータプレーン側の操作として説明されています。(Microsoft Learn)
開発者が確認すべきポイント
開発者、とくにSDK生成やAzure REST API specsを参照するチームは、今回の変更を「ビルド・生成・配布の確認」として扱うのが現実的です。
まず、リポジトリ内で以下を検索します。
grep -R "basic-setup-py" .
grep -R "azure-keyvault-securitydomain" .
grep -R "SecurityDomainClient" .
grep -R "setup.py" .
grep -R "pyproject.toml" .確認すべき観点は次のとおりです。
| 確認対象 | 見るべきポイント |
|---|---|
| SDK生成スクリプト | basic-setup-py を前提にしていないか |
| パッケージビルド | pyproject.toml ベースでビルドできるか |
| CI/CD | setup.py の存在チェックで失敗しないか |
| テスト | SecurityDomainClient の主要操作が通るか |
| 依存関係 | azure-core、azure-identity、Pythonバージョンの制約に問題がないか |
| ドキュメント | 社内手順に古いビルド方法が残っていないか |
azure-keyvault-securitydomain のPyPIページでは、パッケージは azure-keyvault-securitydomain として公開され、インストール例は python -m pip install azure-keyvault-securitydomain azure-identity とされています。SecurityDomainClientを使うには、Managed HSM、Vault URL、資格情報オブジェクトが必要です。(PyPI)
変更後のSDK生成・展開で注意すべきこと
今回の変更で失敗しやすいのは、REST APIの動作確認ではなく、生成物の取り扱いです。とくに、社内でAzure SDKを再生成して社内パッケージとして配布している場合、setup.py 前提の古いチェックが残っていないか確認してください。
推奨する確認手順は次の流れです。
| 手順 | 実施内容 | 合格条件 |
|---|---|---|
| 仕様リポジトリ更新 | 最新のAzure REST API specsを取得 | 対象 tspconfig.yaml に basic-setup-py がない |
| SDK再生成 | 通常のTypeSpec/SDK生成手順を実行 | Python生成が失敗しない |
| パッケージビルド | pyproject.toml ベースでビルド | wheelまたはsdistが作成できる |
| 単体テスト | SecurityDomainClient周辺のテストを実行 | import、認証、モデル参照が通る |
| ステージング検証 | 検証用Managed HSMで代表操作を確認 | Download、Transfer Key、Uploadの流れが想定通り |
| リリース判断 | 生成差分とAPI差分をレビュー | REST API仕様差分がないことを確認 |
Pythonパッケージのビルド確認では、環境に応じて次のようなコマンドを使えます。
python -m pip install --upgrade build
python -m buildただし、本番環境でManaged HSMのSecurity Domain操作を実行する場合は、単なるSDKテストとして扱ってはいけません。Security DomainはManaged HSMの所有権や災害復旧に関わるため、検証用環境を使い、承認済みの手順で実施する必要があります。
REST API直接利用の場合に確認すること
REST APIを直接使っている場合、今回の変更で見るべきポイントは限定的です。Microsoft LearnのREST APIリファレンスでは、Security DomainのDownloadは POST {vaultBaseUrl}/securitydomain/download?api-version=2025-07-01 として掲載され、プロビジョニング済みManaged HSMの有効化にも使えると説明されています。(Microsoft Learn)
REST API利用者は、次の項目を確認すれば十分です。
api-versionを固定している場合、社内で利用しているバージョンと公式ドキュメントの差分を確認する- Managed HSMのデータプレーン権限が正しく付与されているか確認する
- 長時間操作に対するポーリング処理が正常に動くか確認する
- エラー時にSecurity Domainや鍵情報をログへ出していないか確認する
- 本番HSMではなく検証環境で代表的な操作をテストする
今回のPRそのものはREST APIのリクエストボディ、レスポンス、URL構造を変更するものではないため、RESTクライアントの大規模な移行は通常不要です。ただし、SDK経由に切り替える計画がある場合は、SDKのパッケージングと認証方式も合わせて確認してください。
誤解しやすいポイント
REST APIの廃止告知ではない
「Removed basic setup」という表現だけを見ると、何らかの機能廃止に見えるかもしれません。しかし、今回削除されたのはSecurityDomain SDKのPython生成設定にある basic-setup-py の行です。REST APIそのものの廃止期限や移行期限が示された更新ではありません。
Key Vault全体の変更ではない
対象はKey Vault Managed HSMのSecurityDomain SDKです。通常のKey Vaultシークレット操作、証明書操作、キー操作を行うアプリケーションに対して、今回のPRだけで変更が必要になる可能性は高くありません。
Azure RBACだけでは十分とは限らない
Managed HSMでは、制御プレーンとデータプレーンの認可が分かれています。Security Domain操作はデータプレーン側のManaged HSM local RBACに関係するため、AzureサブスクリプションのContributor権限があるだけでは、Security Domain操作ができるとは限りません。(Microsoft Learn)
Security Domainの秘密鍵管理を軽視しない
Microsoftのドキュメントでは、Security Domainの秘密鍵はオフラインで分散保管し、クォーラムを定期的に見直すことが推奨されています。Security Domainを失うと災害復旧ができなくなる可能性があり、漏えいした場合は攻撃者がManaged HSMインスタンスを作成して鍵バックアップの悪用を試みるリスクがあります。(Microsoft Learn)
移行が必要かどうかの判断基準
今回の更新で移行作業が必要かどうかは、次の基準で判断できます。
| 状況 | 対応 |
|---|---|
| REST APIを直接呼び出しているだけ | 既存テストの再実行で十分 |
| pipで公開済みSDKを使っている | バージョン固定と主要操作の回帰テストを実施 |
| Azure REST API specsからPython SDKを生成している | 生成・ビルド・配布手順を確認 |
社内スクリプトが basic-setup-py を読んでいる | スクリプト修正が必要 |
setup.py 前提でパッケージ検証している | pyproject.toml ベースに更新 |
| Managed HSMのDR手順を管理している | RBAC、クォーラム、保管記録を再点検 |
判断に迷う場合は、まず「自分たちはREST APIの利用者なのか、SDK生成物のメンテナーなのか」を切り分けてください。今回の変更で主に影響を受けるのは後者です。
いま取るべき実務対応
今回のAzure REST API documentation updateは、緊急の仕様変更ではなく、SecurityDomain SDKの生成設定を整理する更新です。REST API利用者は過度に反応する必要はありませんが、SDK生成やCI/CDを管理しているチームは、pyproject.toml 前提のパッケージングに移行できているかを確認してください。
実務上は、次の順で対応すると無駄がありません。
| 優先度 | 対応内容 |
|---|---|
| 高 | 社内リポジトリで basic-setup-py と setup.py 前提の処理を検索する |
| 高 | SDK再生成・ビルド・テストが pyproject.toml ベースで通るか確認する |
| 中 | SecurityDomainClient を使うコードの回帰テストを実施する |
| 中 | Managed HSM local RBACとPIM、監査設定を見直す |
| 中 | Security Domainのクォーラム、秘密鍵保管、DR手順を再点検する |
| 低 | 社内ドキュメントから古いSDK生成手順を削除する |
今回の変更をきっかけに、REST API仕様、SDK生成、Managed HSM運用を分けて棚卸ししておくと、将来のAzure REST API updatesにも対応しやすくなります。特にSecurity Domainは「動けばよい」領域ではなく、復旧性と権限分離まで含めて管理すべき領域です。REST API利用者は既存の呼び出しテストを、SDKメンテナーは生成・ビルド手順を、管理者はRBACとクォーラム管理を確認するところから始めましょう。
コメント