从 Azure 密钥保管库 API 版本 2026-02-01 起,新保管库的默认访问控制模型将更改为 Azure RBAC,这与 Azure 门户中的体验一致。 Azure RBAC 和访问策略都完全受支持。 API 版本 2026-02-01 已在公共 Azure 区域、由世纪互联运营的 Azure 和 Azure 政府 中提供。
本文重点介绍新密钥保管库和现有密钥保管库的访问控制行为。 有关控制平面 API 停用以及如何更新应用程序、脚本、模板、SDK、Azure CLI和Azure PowerShell的指南,请参阅更新使用的 Azure 密钥保管库 API 版本。
-
新的密钥保管库创建行为:使用 API 版本
2026-02-01或更高版本创建新保管库时,默认访问控制模型Azure RBAC(enableRbacAuthorization = true)。 此默认值仅适用于 创建 操作。 若要对新保管库使用访问策略,请在创建时设置为enableRbacAuthorizationfalse。 -
现有密钥保管库行为:现有保管库保留其当前访问控制模型,除非显式更改
enableRbacAuthorization。 使用 API 版本2026-02-01或更高版本更新保管库不会自动更改访问控制。enableRbacAuthorization为null的保管库(来自较旧的 API 版本)继续使用访问策略。
Important
所有在 2026-02-01 之前的 密钥保管库 控制平面 API 版本将于 2027 年 2 月 27 日停用。 此停用与访问控制迁移不同。 有关 API 版本更新清单,请参阅更新使用的 Azure 密钥保管库 API 版本。
Important
升级到 Azure CLI 2.90.0 或更高版本或Azure PowerShell 16.3.0 或更高版本,支持 API 版本 2026-02-01 及更高版本。 使用早于 2026-02-01 的 API 版本将在 2027 年 2 月 27 日之后暂停。
我们建议您将当前使用访问策略的密钥保管库迁移到 Azure RBAC,以提高安全性。 有关建议使用 Azure RBAC 的原因的详细信息,请参阅 Azure 基于角色的访问控制(Azure RBAC)与访问策略。 有关分步迁移指南,请参阅从访问策略迁移到 Azure RBAC。
您需要执行的操作
如果已经知道保管库的访问控制模型,请跳到 “确定后续步骤”。 否则,请先 检查当前配置 。
使用本文确定应如何配置访问控制:
- 如果使用 API 版本
2026-02-01或更高版本创建新的保管库,请决定是否接受 Azure RBAC 默认值或显式设置访问策略。 - 如果使用 API 版本
2026-02-01或更高版本更新现有保管库,请了解 API 版本更新不会自动更改访问控制。 - 如果要将现有保管库从访问策略迁移到 Azure RBAC,请使用专用迁移指南。
Important
若要更改密钥保管库的 enableRbacAuthorization 属性,必须具有 Microsoft.KeyVault/vaults/write 权限(包括在参与者和所有者等角色中)。 Azure 门户还要求 Microsoft.Authorization/roleAssignments/write(包含在所有者和用户访问管理员等角色中),以确保在变更后能够分配 密钥保管库 RBAC 角色并避免锁定。 有关详细信息,请参阅 在 密钥保管库 上启用 Azure RBAC 权限。
检查当前配置
检查保管库的访问配置是否已设置为 Azure RBAC 或访问策略。 通过 Azure CLI 或 PowerShell 命令检查此配置。
检查配置后:
- 如果保管库使用 Azure RBAC (
enableRbacAuthorization=true),请转到使用 Azure RBAC 的保管库。 - 如果保管库使用 访问策略(旧版) (
enableRbacAuthorization=false或null),请转到 使用访问策略的保管库。
检查单个保管库
- Azure CLI
- PowerShell
使用 az keyvault show 命令检索保管库详细信息:
az keyvault show --name <vault-name> --resource-group <resource-group>检查密钥保管库中 的 RBAC 授权已启用 属性(
enableRbacAuthorization)。
按资源组检查多个保管库
- Azure CLI
- PowerShell
使用 az keyvault list 命令列出资源组中的所有保管库,并检查其 RBAC 授权状态:
# List all key vaults in the resource group and check Azure RBAC status
az keyvault list --resource-group <resource-group> --query "[].{name:name, rbacEnabled:properties.enableRbacAuthorization}" --output table
检查您的订阅中的多个保管库
- Azure CLI
- PowerShell
使用 az keyvault list 命令列出订阅中的所有保管库,并检查其 RBAC 授权状态:
# List all key vaults in the subscription and check Azure RBAC status
az keyvault list --query "[].{name:name, rbacEnabled:properties.enableRbacAuthorization}" --output table
确定后续步骤
根据当前的访问控制模型,请遵循以下相应指南。
使 API 版本更新与访问控制迁移分开
如果应用程序、脚本、模板或 SDK 使用的是早于 2026-02-01 的控制平面 API 版本,则无论密钥保管库使用的是 Azure RBAC 还是访问策略,都应更新它们。 此 API 版本更新独立于从访问策略迁移到 Azure RBAC。 有关识别和更新应用程序、脚本、模板和 SDK 使用的 API 版本的指南,请参阅更新使用的 Azure 密钥保管库 API 版本。
使用 Azure RBAC 的保管库
如果密钥保管库已使用 Azure RBAC,则无需更改访问控制。 使用 API 版本 2026-02-01 或更高版本创建的新密钥保管库也会默认使用 Azure RBAC,除非你显式地将 enableRbacAuthorization 设置为 false。
使用访问策略的保管库
如果密钥保管库使用访问策略(旧版)(enableRbacAuthorization = false 或 null),则决定是否要迁移到基于角色的访问(建议)或继续使用访问策略。 有关访问控制模型的详细信息,请参阅 使用 Azure RBAC 来管理对 密钥保管库 的访问和 Azure 密钥保管库最佳做法。
选择路径:
- Azure RBAC(建议): 迁移到 Azure RBAC 以提高安全性。
-
访问策略(旧版):通过在创建新保管库时将设置为
enableRbacAuthorization来false。
迁移到 Azure RBAC (建议)
利用此机会,通过从保管库访问策略迁移到 Azure RBAC 来提高安全状况。 有关迁移过程,请参阅从访问策略迁移到 Azure RBAC。
继续使用访问策略
访问策略仍然是完全支持的访问控制模型。
-
现有保管库:除非你显式更改
enableRbacAuthorization,否则已在使用访问策略的保管库将继续使用访问策略。 -
新保管库:使用 API 版本
2026-02-01或更高版本创建新保管库时,必须显式设置为enableRbacAuthorizationfalse使用访问策略,如以下部分所述。
根据方案选择以下方法之一:
使用 ARM、Bicep、Terraform 模板
使用 API 版本 2026-02-01 或更高版本创建新的密钥保管库时,请在所有 密钥保管库 ARM、Bicep、Terraform 模板和 REST API 调用中将 enableRbacAuthorization 设置为 false,以使用访问策略(旧版)。
使用“创建 密钥保管库”命令
使用 API 版本 2026-02-01 或更高版本创建新的密钥保管库时,必须指定访问策略配置,以避免默认Azure RBAC。
将Azure CLI或 PowerShell 模块更新到最新版本。
- Azure CLI
- PowerShell
将 Azure CLI 更新到最新版本。 有关详细信息,请参阅如何更新 Azure CLI。
使用相应的命令创建具有访问策略的密钥保管库:
- Azure CLI
- PowerShell
使用 az keyvault create 命令并设置 --enable-rbac-authorization false:
az keyvault create --name "testCreateTutorial" --resource-group "testResourceGroup" --enable-rbac-authorization false
使用“创建资源”命令
当您使用 API 版本 2026-02-01 或更高版本创建新的密钥保管库时,设置enableRbacAuthorization为false以使用访问策略(旧版)。 如果未指定此属性,则默认为 true (Azure RBAC)。
- Azure CLI
- PowerShell
使用 az resource create 命令并设置 "enableRbacAuthorization": false 和 --api-version "2026-02-01":
az resource create --resource-group $resourceGroup --name $vaultName --resource-type "Microsoft.KeyVault/vaults" --location $location --api-version "2026-02-01" --properties "{\"sku\": { \"family\": \"A\", \"name\": \"standard\" }, \"tenantId\": \"$tenantID\",\"enableRbacAuthorization\": false, \"accessPolicies\": []}"
后续步骤
- 更新使用的 Azure 密钥保管库 API 版本
- Azure基于角色的访问控制(Azure RBAC)与访问策略
- 从访问策略迁移到 Azure RBAC
使用 Azure RBAC 来管理对 密钥保管库 - 保护密钥保管库
- Azure 密钥保管库 REST API 参考