認証、要求、および応答

2025-04-22

Azure Key Vault には、クラウドアプリケーションのシークレットを格納および管理するための 2 種類のコンテナーが用意されています。

コンテナーの種類	サポートされているオブジェクトの種類	データプレーンエンドポイント
資格情報コンテナー	ソフトウェアで保護されるキー HSM で保護されたキー (Premium SKU を使用) 証明書ストレージアカウントキー	https://{vault-name}.vault.azure.net
マネージド HSM	HSM で保護されたキー	https://{hsm-name}.managedhsm.azure.net

各種類のオブジェクトにアクセスするために使用される URL のサフィックスを次に示します。

オブジェクトの種類	URL サフィックス
ソフトウェアで保護されるキー	/keys
HSM で保護されたキー	/keys
シークレット	/シークレット
証明書	/certificates
ストレージアカウントキー	/storageaccounts

Azure Key Vault では、JSON 形式の要求と応答がサポートされます。 Azure Key Vault への要求は、一部の URL パラメーターと JSON でエンコードされた要求と応答本文を含む HTTPS を使用して、有効な Azure Key Vault URL に送信されます。

この記事では、Azure Key Vault サービスの詳細について説明します。認証/承認、アクセストークンの取得方法など、Azure REST インターフェイスの使用に関する一般的な情報については、 Azure REST API リファレンスを参照してください。

要求 URL の構造

キー管理操作では、DELETE、GET、PATCH、PUT などの HTTP 動詞が使用されます。既存のキーオブジェクトに対する暗号化操作では、HTTP POST が使用されます。

特定の HTTP 動詞をサポートできないクライアントの場合、Azure Key Vault では、 X-HTTP-REQUEST ヘッダーで HTTP POST を使用して目的の動詞を指定できます。代わりに POST を使用する場合 (たとえば、DELETE の代わりに)、通常は不要な要求には空の本文を含めます。

Azure Key Vault 内のオブジェクトを操作するには、URL の例を次に示します。

Key Vault で TESTKEY という名前のキーを作成するには、 PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1
IMPORTEDKEY という名前のキーを Key Vault にインポートするには、 POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1
Key Vault で MYSECRET というシークレットを取得するには、 - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Key Vault で TESTKEY という名前のキーを使用してダイジェストに署名するには、 POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
Key Vault に対する要求の権限は常に次のとおりです。
- 資格情報コンテナーの場合: https://{keyvault-name}.vault.azure.net/
- マネージド HSM の場合、 https://{HSM-name}.managedhsm.azure.net/ キーは常に /keys パスの下に格納され、シークレットは常に /secrets パスの下に格納されます。

サポートされる API バージョン

Azure Key Vault Service では、下位レベルのクライアントとの互換性を提供するプロトコルのバージョン管理がサポートされていますが、これらのクライアントですべての機能を利用できるわけではありません。クライアントは、 api-version クエリ文字列パラメーターを使用して、既定がないため、サポートするプロトコルのバージョンを指定する必要があります。

Azure Key Vault プロトコルのバージョンは、{YYYY}.{MM}.{DD} 形式の日付番号付けスキームに従います。

要求本文の要件

HTTP 仕様に従って、GET 操作には要求本文を含めず、POST および PUT 操作には要求本文が必要です。 DELETE 操作の本文は HTTP では省略可能です。

操作の説明で特に明記されていない限り、要求本文のコンテンツタイプは application/json である必要があり、コンテンツタイプに準拠するシリアル化された JSON オブジェクトを含める必要があります。

操作の説明で特に明記されていない限り、Accept 要求ヘッダーには application/json メディアの種類が含まれている必要があります。

応答本文の形式

操作の説明で特に明記されていない限り、成功した操作と失敗した操作の両方の応答本文コンテンツタイプは application/json であり、詳細なエラー情報が含まれています。

HTTP POST を代替として使用する

一部のクライアントでは、PATCH や DELETE などの特定の HTTP 動詞を使用できない場合があります。 Azure Key Vault では、クライアントに元の HTTP 動詞を特定するための "X-HTTP-METHOD" ヘッダーも含まれている場合、これらのクライアントの代替手段として HTTP POST がサポートされます。 HTTP POST のサポートについては、このドキュメントで定義されている各 API について説明します。

エラー応答の処理

エラー処理では HTTP 状態コードが使用されます。一般的な結果は次のとおりです。

2xx – 成功: 通常の操作に使用されます。応答本文には、予期される結果が含まれています
3xx – リダイレクト: 条件付き GET を満たすために、304 "Not Modified" が返される場合があります。今後、DNS とパスの変更を示すために、他の 3xx コードが使用される可能性があります。
4xx – クライアントエラー: 不適切な要求、キーの不足、構文エラー、無効なパラメーター、認証エラーなどに使用されます。応答本文には、エラーの詳細な説明が含まれています。
5xx – サーバーエラー: 内部サーバーエラーに使用されます。応答本文には、要約されたエラー情報が含まれています。

システムは、プロキシまたはファイアウォールの背後で動作するように設計されています。そのため、クライアントは他のエラーコードを受け取る可能性があります。

Azure Key Vault では、問題が発生したときに応答本文にエラー情報も返されます。応答本文は JSON 形式で、次の形式になります。


{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}

認証要件

Azure Key Vault へのすべての要求を認証する必要があります。 Azure Key Vault では、OAuth2 [RFC6749] を使用して取得できる Microsoft Entra アクセストークンがサポートされています。

アプリケーションを登録し、Azure Key Vault を使用するための認証の詳細については、「 Microsoft Entra ID を使用してクライアントアプリケーションを登録する」を参照してください。

アクセストークンは、HTTP Authorization ヘッダーを使用してサービスに送信する必要があります。

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>

アクセストークンが指定されていない場合、またはサービスがトークンを受け入れない場合、HTTP 401 エラーがクライアントに返され、WWW-Authenticate ヘッダーが含まれます。次に例を示します。

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"

WWW-Authenticate ヘッダーのパラメーターは次のとおりです。

authorization: 要求のアクセストークンを取得するために使用できる OAuth2 承認サービスのアドレス。
resource: 承認要求で使用するリソース (https://vault.azure.net) の名前。

注

シークレット、証明書、およびキーについて、Key Vault SDK クライアントは Key Vault への最初の呼び出しでテナント情報を取得するためのアクセストークンを提供しません。 Key Vault SDK クライアントを使用して HTTP 401 を受け取ることが想定されています。Key Vault からアプリケーションに示されるのは、リソースを含む WWW-Authenticate ヘッダーとテナントであり、そこにアクセスしてトークンを要求する必要があります。すべてが正しく構成されている場合、アプリケーションから Key Vault への 2 回目の呼び出しには有効なトークンが含まれているため正常に終了します。