認証、要求、および応答

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

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

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://<vault-name>.vault.azure.net/
  • マネージド HSM の場合、 https://{HSM-name}.managedhsm.azure.net/ キーは常に /keys パスの下に格納され、シークレットは常に /secrets パスの下に格納されます。

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

Azure Key Vault サービスでは、下位レベルのクライアントとの互換性を提供するプロトコルのバージョン管理がサポートされていますが、これらのクライアントですべての機能を使用できるわけではありません。 クライアントは、 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) の名前。