クイックスタート: Azure CLIを使用して最初の外部キーを作成する (プレビュー)

Important

Managed HSM 外部キー管理は プレビュー段階です。プレビュー機能は、追加の使用条件に同意した場合に利用できます。この機能の一部の側面は、一般公開前に変更される可能性があります。

このクイックスタートでは、マネージド HSM に EKM プロキシ接続を登録し、顧客が運用する HSM のキーを指す Managed HSM キー参照を作成します。最後に、ラップ/アンラップの一連の処理を行い、統合が正しく機能することを確認します。

Azure ポータルを使用する場合は、「クイックスタート: Azure ポータルを使用して最初の外部キーを作成する」を参照してください。

前提条件

開始する前に、次のものが必要です。

お客様の Microsoft アカウントチームによってサブスクリプションで外部キー管理が有効化されている、任意の Azure パブリックリージョンにデプロイされた既存の Managed HSM。有効化を要求するには、アカウントチームに問い合わせてください。 Managed HSM を作成するには、「クイックスタート: Azure CLIを使用して Managed HSM をプロビジョニングしてアクティブ化する」を参照してください。
Azure からアクセス可能な稼働中の EKM プロキシ。プロキシは、EKM プロキシ API 仕様を実装する必要があります。サポートされているベンダーについては、「 Managed HSM 外部キー管理とは」を参照してください。
既知の外部キー識別子を持つ外部 HSM で作成されたキー。外部キー識別子は、プロキシがキーを検索するために使用する識別子です。
プロキシの TLS サーバー証明書に署名したルート CA 証明書 (PEM 形式)。
最新のkeyvault拡張機能がインストールされた Azure CLI バージョン 2.x az extension add --name keyvaultまたはaz extension update --name keyvaultを実行して最新バージョンを取得します。
外部キー管理接続を管理する Managed HSM EKM Administrator ロールと、キーを作成して使用する Managed HSM Crypto User ロール。ロールの割り当て手順については、 Managed HSM のアクセス制御に関するページを参照してください。

az login

複数ある場合は、サブスクリプションを設定します。

az account set --subscription "<subscription-id>"

Managed HSM クライアント証明書を表示する

Managed HSM は、受信相互 TLS (mTLS) 接続ごとに、X.509 クライアント証明書を EKM プロキシに提示します。外部キー管理接続を作成する前に、証明書サブジェクトの共通名とルート CA 証明書を取得し、プロキシで許可リストします。これは、プロキシが任意の呼び出し元ではなく、Managed HSM からの接続であることを検証する方法です。

az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name>

出力は次のようになります。

{
  "caCertificates": [
    "MIIDj...<truncated>...MrY="
  ],
  "subjectCommonName": "contoso.managedhsmclient.azure.net"
}

subjectCommonName を使用して証明書を提示し、上記の caCertificates 一覧内のいずれかの証明書をルートとする接続を信頼するように、プロキシを構成してください。正確な手順は、プロキシベンダーによって異なります。

Note

ローテーション手順と証明書のライフサイクルの詳細については、 Managed HSM 外部キー管理用のネットワークと mTLS の構成に関するページを参照してください。

外部キー管理接続を作成する

外部キー管理接続は、マネージド HSM を 1 つの EKM プロキシにバインドします。これには、プロキシアドレス、サーバー CA トラストアンカー、およびオプションのパスプレフィックスが含まれます。

az keyvault ekm-connection create \
    --hsm-name <Managed HSM Name> \
    --host <EKMProxy Host> \
    --server-ca-certificate <Root cert> \
    [--path-prefix <prefix>]

パラメーターリファレンス:

--hsm-name: マネージド HSM の名称。
--host: EKM プロキシの完全修飾ホスト名。たとえば、「 proxy.contoso.com 」のように入力します。プロキシは TCP ポート 443 でリッスンする必要があります。非標準ポートはプレビューではサポートされていません。
--server-ca-certificate: プロキシの TLS サーバー証明書の検証に使用するルート CA 証明書ファイル (PEM または DER 形式) へのパスを指定します。
--path-prefix (省略可能): プロキシが複数の顧客またはプールをパスで多重化する場合の URL パスプレフィックス。たとえば、「 /contoso/prod 」のように入力します。

Note

ルート CA 証明書をプロキシのリーフ証明書ではなく、--server-ca-certificateに渡します。 Managed HSM では、この CA を使用して、mTLS ハンドシェイク中にプロキシによって提示される証明書チェーン全体を検証します。代わりにリーフ証明書を渡すと、証明書の更新でハンドシェイクが失敗します。

接続を確認する

接続を作成した後、Managed HSM がプロキシに到達できることを確認します。

az keyvault ekm-connection check --hsm-name <Managed HSM Name>

このコマンドは、構成された接続を介してプロキシの /info エンドポイントを呼び出します。正常な出力は次のようになります。

{
  "apiVersion": "1.0",
  "ekmProduct": "Contoso HSM v1.0.0",
  "ekmVendor": "Contoso HSM",
  "proxyName": "Contoso Proxy Service",
  "proxyVendor": "Contoso Proxy"
}

一般的なエラーの原因としては、プロキシポートをブロックするファイアウォール規則、正しくない --host 値、Managed HSM クライアント証明書を拒否するプロキシなどがあります。修復手順については、「 Managed HSM 外部キー管理のトラブルシューティング」を参照してください。

外部キーを作成する

HSM の外部キーを指す Managed HSM キー参照を作成します。 Managed HSM 内にキーマテリアルは生成されません。このコマンドは、外部キー識別子によって識別される既存のキーへの参照を登録します。

az keyvault key create \
    --external-key-id <external-key-identifier> \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

パラメーターリファレンス:

--external-key-id: プロキシに登録されている外部キー識別子。これは、プロキシが外部 HSM で正しいキーを検索するために使用する識別子です。
--hsm-name: マネージド HSM の名称。
--name: Managed HSM キー参照を指定する名前。これは、Azureサービスが使用するキー URI の一部になります。

Important

外部キー識別子は、キーバージョンの有効期間中は 変更できません 。作成後に変更することはできません。キーをローテーションするには、同じaz keyvault key createの--nameを使用して、新しい外部キー識別子を持つ新しいキーバージョンを作成します。キー URI (HSM URI + キー名) は、バージョン間で安定しています。バージョンセグメントのみが変更されます。

このコマンドは、 https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>形式のキー URI を返します。この URI は、Azure サービスでカスタマーマネージドキー (CMK) 設定を構成するときに使用します。

ラップ/アンラップを確認する

wrap/unwrap の往復処理で、統合がエンドツーエンドで機能することを確認します。実際のラップ操作とラップ解除操作は、プロキシと外部 HSM で行われます。Managed HSM は要求をルーティングし、結果を返します。

Important

az keyvault key encryptを使用して外部キーをテストしないでください。このコマンドは、外部キー管理がサポートしていない encrypt 操作を発行します。外部キー管理は、 wrapKey と unwrapKey にのみ機能します。代わりに、az rest を使用して wrapkey と unwrapkey のデータプレーンエンドポイントを直接呼び出します。

wrap 操作のリクエスト本文を作成します。ラップする対象の、base64url エンコードされたキーマテリアルを value に設定します。
```
{
  "alg": "RSA-OAEP-256",
  "value": "<base64url-encoded-plaintext-key>"
}
```
wrapkey.jsonとして保存します。 AES 外部キーの場合は、"alg": "A256KW"の代わりに RSA-OAEP-256 を使用します。
キー参照で wrapkey エンドポイントを呼び出します。
```
az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/wrapkey?api-version=7.5" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body @wrapkey.json
```
応答は、キーのバージョン (kid) と base64url でエンコードされたラップされたキーを含む value フィールドを返します。次の手順の value をコピーします。
前の手順でラップされた value を使用して、ラップ解除操作の要求本文を作成します。
```
{
  "alg": "RSA-OAEP-256",
  "value": "<wrapped-value-from-previous-step>"
}
```
unwrapkey.jsonとして保存します。
unwrapkey エンドポイントを呼び出して、ラウンドトリップの正確性を確認します。
```
az rest --method POST \
    --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/unwrapkey?api-version=7.5" \
    --resource "https://managedhsm.azure.net" \
    --headers "Content-Type=application/json" \
    --body @unwrapkey.json
```
応答が成功すると、最初の手順でラップした元のプレーンテキスト value が返されます。ラップ解除が失敗した場合は、プロキシエラーコードと修復手順に関する Managed HSM 外部キー管理のトラブルシューティングを参照してください。

監査ログの表示

すべての EKM プロキシ呼び出しでは、Managed HSM 診断ログに EkmProxyOperation エントリが生成されます。 Log Analyticsでクエリを実行するには:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.KEYVAULT"
| where OperationName contains "Ekm"
| project TimeGenerated, Resource, OperationName, requestUri_s, ResultType, ResultDescription

ログには、操作の種類 (ラップまたはラップ解除)、外部キー識別子、プロキシによって返される HTTP 状態コード、ラウンドトリップ待機時間が含まれます。アラートの構成とプロキシ側のログの関連付けなど、ログと監視の完全なガイドについては、 Managed HSM 外部キー管理のログ記録と監視に関するページを参照してください。

リソースをクリーンアップする

このクイックスタートで作成したリソースを削除するには:

Managed HSM キー参照を削除します。

az keyvault key delete \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

外部キー管理接続を削除します。

az keyvault ekm-connection delete \
    --hsm-name <Managed HSM Name>

Managed HSM キー参照を削除しても、外部 HSM のキーマテリアルには影響しません。そのキーは、削除するまで HSM に残ります。

次のステップ

クイックスタート: Azure ポータルを使用して最初の外部キーを作成する - Azure ポータルで同じフローを完了する
Managed HSM 外部キー管理の外部キーライフサイクル - 外部キーのローテーション、バージョン管理、および使用停止
Managed HSM 外部キー管理 ( パブリックインターネット接続と証明書ローテーション) 用にネットワークと mTLS を構成する
Managed HSM 外部キー管理のログと監視 - アラートルール、Kusto クエリ言語 (KQL) クエリ、プロキシログの関連付け
Managed HSM 外部キー管理のトラブルシューティング - エラーコード、プロキシ診断、修復手順

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-07

クイック スタート: Azure CLIを使用して最初の外部キーを作成する (プレビュー)

前提条件

Azure にサインインする

Managed HSM クライアント証明書を表示する

外部キー管理接続を作成する

接続を確認する

外部キーを作成する

ラップ/アンラップを確認する

監査ログの表示

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

クイックスタート: Azure CLIを使用して最初の外部キーを作成する (プレビュー)