Azure Key Vault 开发人员指南

Azure Key Vault 是一项云服务，提供加密密钥、机密和证书的安全存储和管理。 本指南可帮助开发人员将 Key Vault 集成到其应用程序中。

概述

使用 Azure Key Vault 可以：

• 安全存储：在不编写自定义安全代码的情况下保护密钥、机密和证书。
• 简化的密钥管理：集中加密作和密钥生命周期管理。
• 客户拥有的密钥：允许客户管理自己的密钥，同时专注于核心应用程序功能。
• 外部密钥管理：使用密钥进行签名和加密，同时将密钥保留在应用程序外部。

有关 Azure Key Vault 的一般信息，请参阅 关于 Azure Key Vault。

开发者场景

Key Vault 的常见开发人员任务包括：

• 存储和检索机密：安全地管理连接字符串、密码、API 密钥和 SAS 令牌。 有关详细信息，请参阅关于机密。
• 使用密钥进行加密和签名：执行加密作，而不向应用程序公开密钥材料。 有关详细信息，请参阅关于密钥。
• 管理证书：自动执行 SSL/TLS 的证书预配、续订和部署。 有关详细信息，请参阅关于证书。

公共预览版

我们定期发布新的 Key Vault 功能的公共预览版。 若要尝试预览功能并提供反馈，请与我们联系 azurekeyvault@microsoft.com。 有关最新功能和更新的信息，请参阅 Azure Key Vault 中的新增功能。

创建和管理密钥保管库

Key Vault 使用双平面访问模型：

• 控制平面：管理 Key Vault 资源本身（创建、删除、更新属性、分配访问策略）。 作通过 Azure 资源管理器进行管理。 有关访问控制，请参阅 分配 Key Vault 访问策略。
• 数据平面：管理 Key Vault 中存储的数据（密钥、机密、证书）。 通过 Azure RBAC 和 Key Vault 控制访问。

使用预定义 的 Key Vault 参与者 角色授予对 Key Vault 资源的管理访问权限。 有关身份验证和授权的详细信息，请参阅 Azure Key Vault 中的身份验证。

网络安全

通过配置专用终结点、防火墙或服务终结点来减少网络暴露。 有关全面的网络安全指南，包括从大多数到最低限制的配置选项，请参阅 保护 Azure Key Vault：网络安全 和 配置 Azure Key Vault 网络设置。

用于密钥保管库管理的 API 和 SDK

下表列出了用于管理 Key Vault 资源的 SDK 和快速入门（控制平面操作）。 有关最新版本和安装说明，请参阅 客户端库。

在代码中向 Key Vault 进行身份验证

Key Vault 使用 Microsoft Entra 身份验证，这要求Microsoft Entra 安全主体授予访问权限。 Microsoft Entra 安全主体可以是用户、应用程序服务主体、Azure 资源的托管标识，也可以是任何这些类型的组。

身份验证最佳做法

对于部署到 Azure 的应用程序，请使用托管标识来消除在代码中存储凭据的需求。 有关不同环境（生产、开发、本地）的详细身份验证指南和安全主体建议，请参阅 Azure Key Vault 中的身份验证 和保护 Azure Key Vault。

Azure 标识客户端库

Azure 标识客户端库支持上述身份验证方案，并与 Key Vault SDK 集成。 无需更改代码，即可跨环境和平台使用 Azure 标识客户端库。 该库通过 Azure CLI、Visual Studio、Visual Studio Code 和其他方式自动从登录到 Azure 用户的用户中检索身份验证令牌。

有关 Azure 标识客户端库的详细信息，请参阅：

有关如何在应用程序中对 Key Vault 进行身份验证的教程，请参阅：

• 在 .NET 中将 Azure Key Vault 与虚拟机配合使用
• 在 Python 中将 Azure Key Vault 与虚拟机配合使用
• 使用托管标识将 Key Vault 连接到 .NET 中的 Azure Web 应用

管理密钥、证书和机密

数据平面控制对密钥、证书和机密的访问。 可以将 Azure RBAC 与 Key Vault 配合使用 ，通过数据平面进行访问控制。

API 和 SDK 用于密钥

下表列出了用于处理密钥（数据平面操作）的 SDK 和快速入门。 有关密钥的详细信息，请参阅关于密钥。

其他库

适用于密钥保管库和托管 HSM 的加密客户端

本模块为 适用于 Go 的 Azure Key Vault 密钥客户端模块提供加密客户端。

证书的 API 和 SDK

下表列出了用于证书数据平面操作的 SDK 和快速入门。 有关证书的详细信息，请参阅 “关于证书”。

用于管理机密的 API 和 SDK

下表列出了用于处理机密（数据平面操作）的 SDK 和快速入门。 有关机密的详细信息，请参阅 “关于机密”。

机密的使用

使用 Azure Key Vault 仅存储应用程序的机密。 应存储在 Key Vault 中的机密示例包括：

• 客户端应用程序机密
• 连接字符串
• Passwords
• 共享访问密钥
• SSH 密钥

任何机密相关信息（如用户名和应用程序 ID）都可以作为标记存储在机密中。 对于任何其他敏感的配置设置，应使用 Azure 应用配置。

有关安装包和源代码，请参阅 客户端库。

在应用程序中使用 Key Vault

若要利用 Key Vault 中的最新功能，建议使用可用的 Key Vault SDK 在应用程序中使用机密、证书和密钥。 Key Vault SDK 和 REST API 会在新功能为产品发布时进行更新，并遵循最佳实践和指导方针。

对于基本方案，还有其他库和集成解决方案可用于简化使用，Microsoft合作伙伴或开源社区提供支持。

对于证书，可以使用：

• Key Vault 虚拟机（VM）扩展，它提供 Azure 密钥保管库中存储的证书的自动刷新。 有关详细信息，请参阅：
  • 适用于 Windows 的 Key Vault 虚拟机扩展
  • 适用于 Linux 的 Key Vault 虚拟机扩展
  • 用于 Azure Arc 启用服务器的 Key Vault 虚拟机扩展
• Azure 应用服务集成，它可以从 Key Vault 导入和自动刷新证书。 有关详细信息，请参阅 从 Key Vault 导入证书。

对于机密，可以使用：

• Key Vault 机密，用于应用服务应用程序设置。 有关详细信息，请参阅使用应用程序服务和 Azure Functions 的 Key Vault 引用。
• 参照 Azure 应用程序配置设置密钥保管库引用，以简化应用程序对配置和机密的访问。 有关详细信息，请参阅 Azure 应用配置中的“使用 Key Vault 引用”。

代码示例

有关将 Key Vault 与应用程序配合使用的完整示例，请参阅 Azure Key Vault 代码示例。

特定于任务的指南

以下文章和方案提供了有关使用 Azure Key Vault 的任务特定指南：

• 若要访问密钥保管库，客户端应用程序需要能够访问多个终结点以获取各种功能。 请参阅访问防火墙保护下的 Key Vault。
• 在 Azure VM 中运行的云应用程序需要证书。 如何将此证书获取到此 VM？ 请参阅 适用于 Windows 的 Key Vault 虚拟机扩展 或 适用于 Linux 的 Key Vault 虚拟机扩展。
• 若要使用 Azure CLI、PowerShell 或 Azure 门户分配访问策略，请参阅 “分配 Key Vault 访问策略”。
• 有关密钥保管库的使用和生命周期以及启用了软删除的各种密钥保管库对象的指南，请参阅 使用软删除和清除保护进行 Azure Key Vault 恢复管理。
• 在部署期间需要将安全值（如密码）作为参数传递时，可以将该值存储为密钥保管库中的机密，并引用其他资源管理器模板中的值。 请参阅 使用 Azure Key Vault 在部署期间传递安全参数值。

与 Key Vault 集成

以下服务和方案使用或与 Key Vault 集成：

• 静态加密 允许在数据持久保存时对数据进行编码（加密）。 数据加密密钥通常使用 Azure Key Vault 中的密钥加密密钥进行加密，以进一步限制访问。
• Azure 信息保护 允许管理自己的租户密钥。 例如，您可以选择自己管理租户密钥而不是使用Microsoft默认管理您的租户密钥，以便遵守适用于您组织的特定法规。 管理自己的租户密钥也称为自带密钥（BYOK）。
• 使用 Azure 专用链接 ，可以通过虚拟网络中的专用终结点访问 Azure 服务（例如 Azure Key Vault、Azure 存储和 Azure Cosmos DB）和 Azure 托管的客户/合作伙伴服务。
• Key Vault 与 Azure 事件网格 的集成允许用户在 Key Vault 中存储的机密的状态发生更改时收到通知。 可以将新版本的机密分发给应用程序，或轮换即将过期的机密，以防止中断。
• 保护 Azure DevOps 机密免受 Key Vault 中不需要的访问。
• 使用 Key Vault 中存储的机密 从 Azure Databricks 连接到 Azure 存储。
• 在 Kubernetes 上配置并运行 机密存储 CSI 驱动程序 的 Azure Key Vault 提供程序。

灾难恢复和业务连续性

Key Vault 提供内置的灾难恢复和自动区域复制。 对于生产部署，请启用软删除和清除保护，并实现常规备份。 有关详细信息，请参阅 Azure Key Vault 可用性和冗余、 Azure Key Vault 恢复管理和Azure Key Vault 备份。

性能和可伸缩性

开发使用 Key Vault 的应用程序时，请考虑以下性能和可伸缩性最佳做法：

• 服务限制：Key Vault 对每个区域的每个保管库的事务都有服务限制。 超出这些限制会导致限制。 有关详细信息，请参阅 Azure Key Vault 服务限制。
• 限制指南：使用指数退避实现重试逻辑来处理限制响应。 有关详细信息，请参阅 Azure Key Vault 限制指南。
• 缓存：在应用程序中缓存机密和证书，以减少对 Key Vault 的调用并提高性能。
• 连接管理：尽可能重复使用与 Key Vault 的 HTTP 连接，以减少延迟并提高性能。

监视和日志记录

启用日志记录和监视，以实现安全性、合规性和故障排除。 为关键事件配置诊断设置、事件网格通知和警报。 有关详细指南，请参阅 监视 Azure Key Vault、 Azure Key Vault 日志记录、 使用 Azure 事件网格监视 Key Vault 以及 保护 Azure Key Vault：日志记录和威胁检测。

常见参数和请求模式

使用 Key Vault REST API 时，了解常见参数和请求/响应模式非常有用：

• API 版本：Key Vault 使用版本控制 API。 始终在请求中指定 API 版本。
• 常见标头：了解 Key Vault 请求的必需和可选的 HTTP 标头。 有关详细信息，请参阅 Azure Key Vault 常见参数和标头。
• 身份验证请求：了解如何获取和使用身份验证令牌。 有关详细信息，请参阅 身份验证、请求和响应。
• 错误代码：熟悉常见的 REST API 错误代码，以正常处理故障。 有关详细信息，请参阅 Azure Key Vault REST API 错误代码。

Troubleshooting

有关解决常见问题的帮助：

• 访问被拒绝错误：验证你的身份验证凭据，以及安全主体是否通过 RBAC 分配获得了必需的权限。 请参阅用于 Key Vault 数据平面操作的 Azure RBAC。
• 网络连接：如果从防火墙后面访问 Key Vault，请确保可访问所需的终结点。 请参阅访问防火墙保护下的 Key Vault。
• 节流：如果收到 429（请求过多）响应，则使用指数退避策略。 请参阅 Azure Key Vault 限制指南。

安全最佳做法

有关全面的安全指南，包括标识和访问管理、数据保护、合规性、治理和备份策略，请参阅 保护 Azure Key Vault。

其他资源

Key Vault 的概念

• Azure Key Vault 基本概念 - 使用 Key Vault 的基础概念。
• Azure Key Vault 软删除概述 - 恢复已删除的对象。
• Azure Key Vault 限流指南 - 应用程序的基本概念及方法。
• Azure Key Vault 安全世界和地理边界 - 区域和安全关系。
• Azure Key Vault 服务限制 - 事务限制和其他服务限制。

管理和操作

• 使用 Azure CLI 管理 Key Vault - 命令行管理作。
• 监控 Azure Key Vault - 配置监控和诊断。
• Azure Key Vault 日志记录 - 启用和分析 Key Vault 日志。

社区和支持

• Microsoft问答 - 提出问题并从社区获取答案。
• Key Vault 的 Stack Overflow - 开发人员的技术问答。
• Azure 反馈 - 提交功能请求和反馈。