身份验证、请求和响应

Azure Key Vault 提供两种类型的容器来存储和管理云应用程序的机密：

下面是用于访问每种对象类型的 URL 的后缀

Azure Key Vault 支持 JSON 格式的请求和响应。 Azure Key Vault 请求会与部分 URL 参数、JSON 编码的请求和响应正文一起定向到使用 HTTPS 的有效 Azure Key Vault URL。

本文介绍 Azure Key Vault 服务的具体内容。 有关使用 Azure REST 接口（包括身份验证/授权以及如何获取访问令牌）的一般信息，请参阅 Azure REST API 参考。

请求 URL 结构

密钥管理操作使用 HTTP 请求方法，包括 DELETE、GET、PATCH 和 PUT。 对现有密钥对象的加密操作使用 HTTP POST。

对于不支持特定 HTTP 谓词的客户端，Azure Key Vault 允许将 HTTP POST 与标头一起使用 X-HTTP-REQUEST 来指定预期谓词。 使用 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

• 若要获取密钥保管库中名为 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 服务支持协议版本控制，以提供与下层客户端的兼容性，尽管并非所有功能都可供这些客户端使用。 客户端必须使用 api-version 查询字符串参数来指定它们支持的协议版本，因为没有默认值。

Azure Key Vault 协议版本遵循一种日期编号方案，采用 {YYYY}.{MM}.{DD} 格式。

请求正文要求

根据 HTTP 规范，GET 操作不应具有请求正文，POST 和 PUT 操作必须具有请求正文。 在 HTTP 的 DELETE 操作中，正文是可选的。

除非在作说明中另有说明，否则请求正文内容类型必须是 application/json，并且必须包含符合内容类型的序列化 JSON 对象。

除非在作说明中另有说明，否则 Accept 请求标头必须包含应用程序/json 媒体类型。

响应正文格式

除非在操作说明中另有说明，否则成功和失败操作的响应正文内容类型都是application/json，并且包含详细的错误信息。

将 HTTP POST 用作替代方法

某些客户端可能无法使用某些 HTTP 谓词，例如 PATCH 或 DELETE。 如果客户端还包含“X-HTTP-METHOD”标头来指定原始 HTTP 谓词，则 Azure Key Vault 支持使用 HTTP POST 作为这些客户端的替代方法。 本文档中定义的每个 API 都记录了对 HTTP POST 的支持。

处理错误响应

错误处理使用 HTTP 状态代码。 典型结果包括：

• 2xx - 成功：用于常规操作。 响应正文包含预期结果

• 3xx – 重定向：可能会返回 304“未修改”来响应条件性 GET 请求。 将来可以使用其他 3xx 代码来指示 DNS 和路径更改。

• 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 授权标头将访问令牌发送到服务：

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 授权服务的地址。

• 资源：在授权请求中使用的资源名称（https://vault.azure.net）。