使用 Azure PowerShell 添加或删除 Azure 角色分配Add or remove Azure role assignments using Azure PowerShell

Azure 基于角色的访问控制 (Azure RBAC) 是用于管理 Azure 资源访问权限的授权系统。Azure role-based access control (Azure RBAC) is the authorization system you use to manage access to Azure resources. 若要授予访问权限,请将角色分配给特定范围内的用户、组、服务主体或托管标识。To grant access, you assign roles to users, groups, service principals, or managed identities at a particular scope. 本文介绍如何使用 Azure PowerShell 分配角色。Azure 基于角色的访问控制 (Azure RBAC) 是用于管理 Azure 资源访问权限的授权系统。Azure role-based access control (Azure RBAC) is the authorization system you use to manage access to Azure resources. 若要授予访问权限,请将角色分配给特定范围内的用户、组、服务主体或托管标识。To grant access, you assign roles to users, groups, service principals, or managed identities at a particular scope. This article describes how to assign roles using Azure PowerShell.

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

先决条件Prerequisites

若要添加或删除角色分配,必须拥有以下权限:To add or remove role assignments, you must have:

角色分配的添加步骤Steps to add a role assignment

在 Azure RBAC 中,若要授予访问权限,请添加角色分配。In Azure RBAC, to grant access, you add a role assignment. 角色分配包含三个要素:安全主体、角色订阅和范围。A role assignment consists of three elements: security principal, role definition, and scope. 若要添加角色分配,请执行以下步骤。To add a role assignment, follow these steps.

步骤 1:确定谁需要访问权限Step 1: Determine who needs access

可以将角色分配到用户、组、服务主体或托管标识。You can assign a role to a user, group, service principal, or managed identity. 若要添加角色分配,你可能需要指定对象的唯一 ID。To add a role assignment, you might need to specify the unique ID of the object. ID 的格式为:11111111-1111-1111-1111-111111111111The ID has the format: 11111111-1111-1111-1111-111111111111. 可以使用 Azure 门户或 Azure PowerShell 获取 ID。You can get the ID using the Azure portal or Azure PowerShell.

UserUser

对于 Azure AD 用户,请获取用户主体名称(例如 patlong@contoso.com)或用户对象 ID。For an Azure AD user, get the user principal name, such as patlong@contoso.com or the user object ID. 若要获取该对象 ID,可以使用 Get-AzADUserTo get the object ID, you can use Get-AzADUser.

Get-AzADUser -StartsWith <userName>
(Get-AzADUser -DisplayName <userName>).id

Group

对于 Azure AD 组,你需要组对象 ID。For an Azure AD group, you need the group object ID. 若要获取该对象 ID,可以使用 Get-AzADGroupTo get the object ID, you can use Get-AzADGroup.

Get-AzADGroup -SearchString <groupName>
(Get-AzADGroup -DisplayName <groupName>).id

服务主体Service principal

对于 Azure AD 服务主体(应用程序使用的标识),你需要服务主体对象 ID。For an Azure AD service principal (identity used by an application), you need the service principal object ID. 若要获取该对象 ID,可以使用 Get-AzADServicePrincipalTo get the object ID, you can use Get-AzADServicePrincipal. 对于服务主体,使用对象 ID,而不是应用程序 ID。For a service principal, use the object ID and not the application ID.

Get-AzADServicePrincipal -SearchString <principalName>
(Get-AzADServicePrincipal -DisplayName <principalName>).id

托管的标识Managed identity

对于系统分配的或用户分配的托管标识,你需要对象 ID。For a system-assigned or a user-assigned managed identity, you need the object ID. 若要获取该对象 ID,可以使用 Get-AzADServicePrincipalTo get the object ID, you can use Get-AzADServicePrincipal.

Get-AzADServicePrincipal -SearchString <principalName>
(Get-AzADServicePrincipal -DisplayName <principalName>).id

步骤 2:查找适当的角色Step 2: Find the appropriate role

权限组合成角色。Permissions are grouped together into roles. 可以从包含多个 Azure 内置角色的列表中选择,也可以使用自己的自定义角色。You can select from a list of several Azure built-in roles or you can use your own custom roles. 最佳做法是以所需的最少权限授予访问权限,因此避免分配范围更广泛的角色。It's a best practice to grant access with the least privilege that is needed, so avoid assigning a broader role.

若要列出角色并获取唯一的角色 ID,可以使用 Get-AzRoleDefinitionTo list roles and get the unique role ID, you can use Get-AzRoleDefinition.

Get-AzRoleDefinition | FT Name, IsCustom, Id

下面介绍了如何列出特定角色的详细信息。Here's how to list the details of a particular role.

Get-AzRoleDefinition <roleName>

有关详细信息,请参阅列出 Azure 角色定义For more information, see List Azure role definitions.

步骤 3:识别所需的范围Step 3: Identify the needed scope

Azure 提供四个级别的范围:资源、资源组、订阅,以及管理组Azure provides four levels of scope: resource, resource group, subscription, and management group. 最佳做法是以所需的最少权限授予访问权限,因此避免在更广泛的范围分配角色。It's a best practice to grant access with the least privilege that is needed, so avoid assigning a role at a broader scope. 有关范围的详细信息,请参阅了解范围For more information about scope, see Understand scope.

资源范围Resource scope

对于资源范围,你需要资源的资源 ID。For resource scope, you need the resource ID for the resource. 可以通过在 Azure 门户中查看资源的属性来找到资源 ID。You can find the resource ID by looking at the properties of the resource in the Azure portal. 资源 ID 采用以下格式。A resource ID has the following format.

/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/<providerName>/<resourceType>/<resourceSubType>/<resourceName>

资源组范围Resource group scope

对于资源组范围,你需要资源组的名称。For resource group scope, you need the name of the resource group. 可以在 Azure 门户的“资源组”页上找到此名称,也可以使用 Get-AzResourceGroupYou can find the name on the Resource groups page in the Azure portal or you can use Get-AzResourceGroup.

Get-AzResourceGroup

订阅范围Subscription scope

对于订阅范围,你需要订阅 ID。For subscription scope, you need the subscription ID. 可以在 Azure 门户的“订阅”页上找到此 ID,也可以使用 Get-AzSubscriptionYou can find the ID on the Subscriptions page in the Azure portal or you can use Get-AzSubscription.

Get-AzSubscription

管理组范围Management group scope

对于管理组范围,你需要管理组名称。For management group scope, you need the management group name. 可以在 Azure 门户的“管理组”页上找到此名称,也可以使用 Get-AzManagementGroupYou can find the name on the Management groups page in the Azure portal or you can use Get-AzManagementGroup.

Get-AzManagementGroup

步骤 4:添加角色分配Step 4: Add role assignment

若要添加角色分配,请使用 New-AzRoleAssignment 命令。To add a role assignment, use the New-AzRoleAssignment command. 根据范围,命令通常采用以下格式之一。Depending on the scope, the command typically has one of the following formats.

资源范围Resource scope

New-AzRoleAssignment -ObjectId <objectId> `
-RoleDefinitionName <roleName> `
-Scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/<providerName>/<resourceType>/<resourceSubType>/<resourceName>
New-AzRoleAssignment -ObjectId <objectId> `
-RoleDefinitionId <roleId> `
-ResourceName <resourceName> `
-ResourceType <resourceType> `
-ResourceGroupName <resourceGroupName>

资源组范围Resource group scope

New-AzRoleAssignment -SignInName <emailOrUserprincipalname> `
-RoleDefinitionName <roleName> `
-ResourceGroupName <resourceGroupName>
New-AzRoleAssignment -ObjectId <objectId> `
-RoleDefinitionName <roleName> `
-ResourceGroupName <resourceGroupName>

订阅范围Subscription scope

New-AzRoleAssignment -SignInName <emailOrUserprincipalname> `
-RoleDefinitionName <roleName> `
-Scope /subscriptions/<subscriptionId>
New-AzRoleAssignment -ObjectId <objectId> `
-RoleDefinitionName <roleName> `
-Scope /subscriptions/<subscriptionId>

管理组范围Management group scope

New-AzRoleAssignment -SignInName <emailOrUserprincipalname> `
-RoleDefinitionName <roleName> `
-Scope /providers/Microsoft.Management/managementGroups/<groupName>
New-AzRoleAssignment -ObjectId <objectId> `
-RoleDefinitionName <roleName> `
-Scope /providers/Microsoft.Management/managementGroups/<groupName>

添加角色分配示例Add role assignment examples

为存储帐户资源范围中的所有 blob 容器添加角色分配Add role assignment for all blob containers in a storage account resource scope

在名为 storage12345 的存储帐户的资源范围内将存储 Blob 数据参与者角色分配给对象 ID 为 55555555-5555-5555-5555-555555555555 的服务主体。Assigns the Storage Blob Data Contributor role to a service principal with object ID 55555555-5555-5555-5555-555555555555 at a resource scope for a storage account named storage12345.

PS C:\> New-AzRoleAssignment -ObjectId 55555555-5555-5555-5555-555555555555 `
-RoleDefinitionName "Storage Blob Data Contributor" `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345"

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345/providers/Microsoft.Authorization/roleAssignments/cccccccc-cccc-cccc-cccc-cccccccccccc
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345
DisplayName        : example-identity
SignInName         :
RoleDefinitionName : Storage Blob Data Contributor
RoleDefinitionId   : ba92f5b4-2d11-453d-a403-e96b0029c9fe
ObjectId           : 55555555-5555-5555-5555-555555555555
ObjectType         : ServicePrincipal
CanDelegate        : False

为特定 blob 容器资源范围添加角色分配Add role assignment for a specific blob container resource scope

在名为 blob-container-01 的 blob 容器的资源范围内将存储 Blob 数据参与者角色分配给对象 ID 为 55555555-5555-5555-5555-555555555555 的服务主体。Assigns the Storage Blob Data Contributor role to a service principal with object ID 55555555-5555-5555-5555-555555555555 at a resource scope for a blob container named blob-container-01.

PS C:\> New-AzRoleAssignment -ObjectId 55555555-5555-5555-5555-555555555555 `
-RoleDefinitionName "Storage Blob Data Contributor" `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345/blobServices/default/containers/blob-container-01"

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345/blobServices/default/containers/blob-container-01/providers/Microsoft.Authorization/roleAssignm
                     ents/dddddddd-dddd-dddd-dddd-dddddddddddd
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/storage12345/blobServices/default/containers/blob-container-01
DisplayName        : example-identity
SignInName         :
RoleDefinitionName : Storage Blob Data Contributor
RoleDefinitionId   : ba92f5b4-2d11-453d-a403-e96b0029c9fe
ObjectId           : 55555555-5555-5555-5555-555555555555
ObjectType         : ServicePrincipal
CanDelegate        : False

为特定虚拟网络资源范围内的某个组添加角色分配Add role assignment for a group in a specific virtual network resource scope

虚拟机参与者角色分配给名为 pharma-sales-project-network 的虚拟网络的资源范围内 ID 为“aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa”的“医药销售管理员”组。Assigns the Virtual Machine Contributor role to the Pharma Sales Admins group with ID aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa at a resource scope for a virtual network named pharma-sales-project-network.

PS C:\> New-AzRoleAssignment -ObjectId aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa `
-RoleDefinitionName "Virtual Machine Contributor" `
-ResourceName pharma-sales-project-network `
-ResourceType Microsoft.Network/virtualNetworks `
-ResourceGroupName MyVirtualNetworkResourceGroup

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyVirtualNetworkResourceGroup
                     /providers/Microsoft.Network/virtualNetworks/pharma-sales-project-network/providers/Microsoft.Authorizat
                     ion/roleAssignments/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyVirtualNetworkResourceGroup
                     /providers/Microsoft.Network/virtualNetworks/pharma-sales-project-network
DisplayName        : Pharma Sales Admins
SignInName         :
RoleDefinitionName : Virtual Machine Contributor
RoleDefinitionId   : 9980e02c-c2be-4d73-94e8-173b1dc7cf3c
ObjectId           : aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
ObjectType         : Group
CanDelegate        : False

在资源组范围内为某个用户添加角色分配Add a role assignment for a user at a resource group scope

pharma-sales 资源组范围内将 虚拟机参与者角色分配给 patlong@contoso.com 用户。Assigns the Virtual Machine Contributor role to patlong@contoso.com user at the pharma-sales resource group scope.

PS C:\> New-AzRoleAssignment -SignInName patlong@contoso.com `
-RoleDefinitionName "Virtual Machine Contributor" `
-ResourceGroupName pharma-sales

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales/pr
                     oviders/Microsoft.Authorization/roleAssignments/55555555-5555-5555-5555-555555555555
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales
DisplayName        : Pat Long
SignInName         : patlong@contoso.com
RoleDefinitionName : Virtual Machine Contributor
RoleDefinitionId   : 9980e02c-c2be-4d73-94e8-173b1dc7cf3c
ObjectId           : 44444444-4444-4444-4444-444444444444
ObjectType         : User
CanDelegate        : False

另外,也可以使用 -Scope 参数来指定完全限定的资源组:Alternately, you can specify the fully qualified resource group with the -Scope parameter:

PS C:\> New-AzRoleAssignment -SignInName patlong@contoso.com `
-RoleDefinitionName "Virtual Machine Contributor" `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales/providers/Microsoft.Authorization/roleAssignments/55555555-5555-5555-5555-555555555555
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales
DisplayName        : Pat Long
SignInName         : patlong@contoso.com
RoleDefinitionName : Virtual Machine Contributor
RoleDefinitionId   : 9980e02c-c2be-4d73-94e8-173b1dc7cf3c
ObjectId           : 44444444-4444-4444-4444-444444444444
ObjectType         : User
CanDelegate        : False

在资源组范围内使用唯一角色 ID 为某个用户添加角色分配Add role assignment for a user using the unique role ID at a resource group scope

很多时候角色名称可能会更改,例如:There are a couple of times when a role name might change, for example:

  • 你使用的是自己的自定义角色,你决定更改名称。You are using your own custom role and you decide to change the name.
  • 你使用的是预览版角色,其名称中有“(预览)”字样。You are using a preview role that has (Preview) in the name. 发布角色时重命名了角色。When the role is released, the role is renamed.

即使重命名了角色,角色 ID 也不会更改。Even if a role is renamed, the role ID does not change. 如果使用脚本或自动化来创建角色分配,最佳做法是使用唯一的角色 ID 而非角色名称。If you are using scripts or automation to create your role assignments, it's a best practice to use the unique role ID instead of the role name. 这样一来,即使角色重命名,脚本仍可以使用。Therefore, if a role is renamed, your scripts are more likely to work.

以下示例将 “虚拟机参与者”角色分配给 pharma-sales 资源组范围内的 patlong@contoso.com 用户。The following example assigns the Virtual Machine Contributor role to the patlong@contoso.com user at the pharma-sales resource group scope.

PS C:\> New-AzRoleAssignment -ObjectId 44444444-4444-4444-4444-444444444444 `
-RoleDefinitionId 9980e02c-c2be-4d73-94e8-173b1dc7cf3c `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales/providers/Microsoft.Authorization/roleAssignments/55555555-5555-5555-5555-555555555555
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales
DisplayName        : Pat Long
SignInName         : patlong@contoso.com
RoleDefinitionName : Virtual Machine Contributor
RoleDefinitionId   : 9980e02c-c2be-4d73-94e8-173b1dc7cf3c
ObjectId           : 44444444-4444-4444-4444-444444444444
ObjectType         : User
CanDelegate        : False

在资源组范围内为应用程序添加角色分配Add role assignment for an application at a resource group scope

在 pharma-sales 资源组范围内将虚拟机参与者角色分配给服务主体对象 ID 为“77777777-7777-7777-7777-777777777777”的应用程序。Assigns the Virtual Machine Contributor role to an application with service principal object ID 77777777-7777-7777-7777-777777777777 at the pharma-sales resource group scope.

PS C:\> New-AzRoleAssignment -ObjectId 77777777-7777-7777-7777-777777777777 `
-RoleDefinitionName "Virtual Machine Contributor" `
-ResourceGroupName pharma-sales

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleAssignments/66666666-6666-6666-6666-666666666666
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales
DisplayName        : MyApp1
SignInName         :
RoleDefinitionName : Virtual Machine Contributor
RoleDefinitionId   : 9980e02c-c2be-4d73-94e8-173b1dc7cf3c
ObjectId           : 77777777-7777-7777-7777-777777777777
ObjectType         : ServicePrincipal
CanDelegate        : False

在订阅范围内为用户添加角色分配Add role assignment for a user at a subscription scope

在订阅范围内将读者角色分配给 annm@example.com 用户。Assigns the Reader role to the annm@example.com user at a subscription scope.

PS C:\> New-AzRoleAssignment -SignInName annm@example.com `
-RoleDefinitionName "Reader" `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000"

RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleAssignments/66666666-6666-6666-6666-666666666666
Scope              : /subscriptions/00000000-0000-0000-0000-000000000000
DisplayName        : Ann M
SignInName         : annm@example.com
RoleDefinitionName : Reader
RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
ObjectId           : 77777777-7777-7777-7777-777777777777
ObjectType         : ServicePrincipal
CanDelegate        : False

在管理组范围内为用户添加角色分配Add role assignment for a user at a management group scope

在管理组范围内将账单读者角色分配给 alain@example.com 用户。Assigns the Billing Reader role to the alain@example.com user at a management group scope.

PS C:\> New-AzRoleAssignment -SignInName alain@example.com `
-RoleDefinitionName "Billing Reader" `
-Scope "/providers/Microsoft.Management/managementGroups/marketing-group"

RoleAssignmentId   : /providers/Microsoft.Management/managementGroups/marketing-group/providers/Microsoft.Authorization/roleAssignments/22222222-2222-2222-2222-222222222222
Scope              : /providers/Microsoft.Management/managementGroups/marketing-group
DisplayName        : Alain Charon
SignInName         : alain@example.com
RoleDefinitionName : Billing Reader
RoleDefinitionId   : fa23ad8b-c56e-40d8-ac0c-ce449e1d2c64
ObjectId           : 44444444-4444-4444-4444-444444444444
ObjectType         : User
CanDelegate        : False

删除角色分配Remove a role assignment

在 Azure RBAC 中,要删除访问权限,请使用 Remove-AzRoleAssignment 删除角色分配。In Azure RBAC, to remove access, you remove a role assignment by using Remove-AzRoleAssignment.

以下示例在 pharma-sales 资源组上从 patlong@contoso.com 用户删除“虚拟机参与者”角色分配:The following example removes the Virtual Machine Contributor role assignment from the patlong@contoso.com user on the pharma-sales resource group:

PS C:\> Remove-AzRoleAssignment -SignInName patlong@contoso.com `
-RoleDefinitionName "Virtual Machine Contributor" `
-ResourceGroupName pharma-sales

在订阅范围内将读者角色从 ID 为 22222222-2222-2222-2222-222222222222 的“Ann Mack 团队”组中删除。Removes the Reader role from the Ann Mack Team group with ID 22222222-2222-2222-2222-222222222222 at a subscription scope.

PS C:\> Remove-AzRoleAssignment -ObjectId 22222222-2222-2222-2222-222222222222 `
-RoleDefinitionName "Reader" `
-Scope "/subscriptions/00000000-0000-0000-0000-000000000000"

在管理组范围内将账单读者角色从 alain@example.com 用户中删除。Removes the Billing Reader role from the alain@example.com user at the management group scope.

PS C:\> Remove-AzRoleAssignment -SignInName alain@example.com `
-RoleDefinitionName "Billing Reader" `
-Scope "/providers/Microsoft.Management/managementGroups/marketing-group"

如果收到错误消息:“提供的信息未映射到角色分配”,请确保还指定了 -Scope-ResourceGroupName 参数。If you get the error message: "The provided information does not map to a role assignment", make sure that you also specify the -Scope or -ResourceGroupName parameters. 有关详细信息,请参阅 Azure RBAC 疑难解答For more information, see Troubleshoot Azure RBAC.

后续步骤Next steps