你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

身份验证、请求和响应

项目
08/08/2024

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

容器类型	支持的对象类型	数据平面终结点
保管库	受软件保护的密钥受 HSM 保护的密钥（含高级 SKU）证书存储帐户密钥	https://{vault-name}.vault.azure.net
托管 HSM	HSM 保护的密钥	https://{hsm-name}.managedhsm.azure.net

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

对象类型	URL 后缀
受软件保护的密钥	/keys
HSM 保护的密钥	/keys
机密	/secrets
证书	/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

密钥管理操作使用 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.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 对象。

除非操作说明中另有说明，否则接受请求标头必须包含 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.net) 的名称。

注意

在第一次调用 Key Vault 时，对于机密、证书和密钥，Key Vault SDK 客户端不提供访问令牌来检索租户信息。预计会使用 Key Vault SDK 客户端接收 HTTP 401，其中 Key Vault 向应用程序显示包含资源的 WWW-Authenticate 标头和要去请求令牌的租户。如果所有内容都已正确配置，则从应用程序到 Key Vault 的第二次调用将包含有效令牌，并将取得成功。

通过