准备 密钥保管库 API 的 2026-02-01 及更高版本:采用 Azure RBAC 作为默认访问控制

Azure 密钥保管库 API 版本 2026-02-01 及更高版本将新保管库的默认访问控制模型更改为 Azure RBAC,以保持与 Azure 门户用户体验的一致性。 Azure RBAC 和访问策略都完全受支持。 API 版本 2026-02-01 在世纪互联运营的Azure中提供。

  • 新的密钥保管库创建行为:使用 API 版本 2026-02-01 或更高版本创建新保管库时,默认访问控制模型Azure RBAC(enableRbacAuthorization = true)。 此默认值仅适用于 创建 操作。 若要对新保管库使用访问策略,请在创建时设置为enableRbacAuthorizationfalse
  • 现有密钥保管库行为:现有保管库保留其当前访问控制模型,除非显式更改 enableRbacAuthorization。 使用 API 版本 2026-02-01 或更高版本更新保管库不会自动更改访问控制。 enableRbacAuthorizationnull 的保管库(来自较旧的 API 版本)继续使用访问策略。

Important

2027 年 2 月 27 日,2026-02-01 之前的所有 密钥保管库 控制平面 API 版本将全部停用。 密钥保管库将继续存在,并且只能通过控制平面 API 版本 2026-02-01 或更高版本进行访问。 数据平面 API 不受影响。

Important

升级到 Azure CLI 2.90.0 或更高版本或Azure PowerShell 16.3.0 或更高版本,支持 API 版本 2026-02-01 及更高版本。 使用早于 2026-02-01 的 API 版本将在 2027 年 2 月 27 日之后暂停。

预览版 API 版本将在提前 90 天通知后弃用。 Azure powershell 始终使用最新的 API 版本。 如果脚本在Cloud Shell中运行,请确保它们与 API 版本 2026-02-01 或更高版本兼容。 有关支持的 API 版本的列表,请参阅 支持的控制平面 API 版本。 有关 SDK 包的详细信息,请参阅 Azure 密钥保管库

我们鼓励你将当前使用访问策略(旧版)的密钥保管库迁移到 Azure RBAC,以提高安全性。 有关建议使用 Azure RBAC 的原因的详细信息,请参阅 Azure 基于角色的访问控制(Azure RBAC)与访问策略

您需要执行的操作

如果已经知道保管库的访问控制模型,请跳到 “确定后续步骤”。 否则,请先 检查当前配置

Important

若要更改密钥保管库的 enableRbacAuthorization 属性,必须具有 Microsoft.KeyVault/vaults/write 权限(包括在参与者和所有者等角色中)。 Azure 门户还要求 Microsoft.Authorization/roleAssignments/write(包含在所有者和用户访问管理员等角色中),以确保在变更后能够分配 密钥保管库 RBAC 角色并避免锁定。 有关详细信息,请参阅 在 密钥保管库 上启用 Azure RBAC 权限

检查当前配置

检查保管库的访问配置是否已设置为 Azure RBAC 或访问策略。 通过 Azure CLI 或 PowerShell 命令检查此配置。

检查配置后:

检查单个保管库

  1. 使用 az keyvault show 命令检索保管库详细信息:

    az keyvault show --name <vault-name> --resource-group <resource-group>
    
  2. 检查密钥保管库中 的 RBAC 授权已启用 属性(enableRbacAuthorization)。

按资源组检查多个保管库

使用 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

检查您的订阅中的多个保管库

使用 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

确定后续步骤

根据当前的访问控制模型,请遵循以下相应指南。

使用 Azure RBAC 的保管库

如果密钥保管库已使用 Azure RBAC,则无需更改访问控制。 在 2027 年 2 月 27 日之前,您必须更新所有 密钥保管库 控制平面管理 SDK、ARM、Bicep、Terraform 模板和 REST API 调用,以使用 API 版本 2026-02-01 或更高版本,因为旧的控制平面 API 版本将被弃用。

使用访问策略的保管库

如果密钥保管库使用访问策略(旧版)(enableRbacAuthorization = falsenull),则决定是否要迁移到基于角色的访问(建议)或继续使用访问策略。 有关访问控制模型的详细信息,请参阅 使用 Azure RBAC 来管理对 密钥保管库 的访问和 Azure 密钥保管库最佳做法

选择路径:

  • Azure RBAC(建议)迁移到 Azure RBAC 以提高安全性。
  • 访问策略(旧版):通过在创建新保管库时将设置为enableRbacAuthorizationfalse

利用此机会,通过从保管库访问策略迁移到 Azure RBAC 来提高安全状况。 有关详细的迁移指南,请参阅 从保管库访问策略迁移到 Azure 基于角色的访问控制权限模型

迁移后,更新所有密钥保管库控制平面管理 SDK、ARM、Bicep、Terraform 模板和 REST API 调用,以使用 API 版本 2026-02-01 或更高版本。

继续使用访问策略

访问策略仍然是完全支持的访问控制模型。

  • 现有保管库:已使用访问策略的保管库将继续工作,无需更改。 只需确保在 2027 年 2 月 27 日之前使用 API 版本 2026-02-01 或更高版本的控制平面管理 SDK、ARM、Bicep、Terraform 模板和 REST API 调用。
  • 新保管库:使用 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 更新到最新版本。 有关详细信息,请参阅如何更新 Azure CLI

使用相应的命令创建具有访问策略的密钥保管库:

使用 az keyvault create 命令并设置 --enable-rbac-authorization false

az keyvault create --name "testCreateTutorial" --resource-group "testResourceGroup" --enable-rbac-authorization false
使用“创建资源”命令

当您使用 API 版本 2026-02-01 或更高版本创建新的密钥保管库时,设置enableRbacAuthorizationfalse以使用访问策略(旧版)。 如果未指定此属性,则默认为 true (Azure RBAC)。

使用 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\": []}"

后续步骤