身份验证、请求和响应

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 POST。 不支持特定 HTTP 谓词的客户端也可能使用 HTTP POST（使用 X-HTTP-REQUEST 标头）来指定所需谓词，通常不需要正文的请求在使用 HTTP POST 时应添加一个空的正文，比如使用 POST 而不是 DELETE 时。

若要使用 Azure Key Vault 中的对象，请参考以下示例 URL：

• 若要在 Key Vault 中创建名为 TESTKEY 的密钥，请使用 - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• 若要在 Key Vault 中导入名为 IMPORTEDKEY 的密钥，请使用 - 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.cn/

密钥始终存储在 /keys 路径下，机密始终存储在 /secrets 路径下。

API 版本

Azure Key Vault 服务支持协议版本控制，可与下层客户端兼容，但并非所有功能都可供这些客户端使用。 客户端必须使用 api-version 查询字符串参数，指定无默认协议时支持的协议版本。

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

请求正文

根据 HTTP 规范，GET 操作不得包含请求正文，而 POST 和 PUT 操作必须包含请求正文。 DELETE 操作中的正文在 HTTP 中是可选的。

除非操作说明中另有说明，否则请求正文内容类型必须为 application/json，且必须包含与内容类型一致的序列化 JSON 对象。

除非操作说明中另有说明，否则接受请求标头必须包含 application/json 媒体类型。

响应正文

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

使用 HTTP POST

部分客户端可能无法使用某些 HTTP 谓词，例如 PATCH 或 DELETE。 Azure Key Vault 支持使用 HTTP POST 作为这些客户端的替代方法，前提是客户端也包括“X-HTTP-METHOD”标头以指定原始 HTTP 谓词。 本文档中定义的每个 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 授权服务的地址。

• resource：要在授权请求中使用的资源 (https://vault.azure.cn) 的名称。