Tutorial: Grant a group access to Azure resources using RBAC and Azure PowerShell

Role-based access control (RBAC) is the way that you manage access to Azure resources. In this tutorial, you grant a group access to view everything in a subscription and manage everything in a resource group using Azure PowerShell.

In this tutorial, you learn how to:

  • Grant access for a group at different scopes
  • List access
  • Remove access

If you don't have an Azure subscription, create a free account before you begin.

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Prerequisites

To complete this tutorial, you will need:

  • Permissions to create groups in Azure Active Directory (or have an existing group)
  • Azure Cloud Shell

Role assignments

In RBAC, to grant access, you create a role assignment. A role assignment consists of three elements: security principal, role definition, and scope. Here are the two role assignments you will perform in this tutorial:

Security principal Role definition Scope
Group
(RBAC Tutorial Group)
Reader Subscription
Group
(RBAC Tutorial Group)
Contributor Resource group
(rbac-tutorial-resource-group)

Role assignments for a group

Create a group

To assign a role, you need a user, group, or service principal. If you don't already have a group, you can create one.

  • In Azure Cloud Shell, create a new group using the New-AzureADGroup command.

    New-AzureADGroup -DisplayName "RBAC Tutorial Group" `
       -MailEnabled $false -SecurityEnabled $true -MailNickName "NotSet"
    
    ObjectId                             DisplayName         Description
    --------                             -----------         -----------
    11111111-1111-1111-1111-111111111111 RBAC Tutorial Group
    

If you don't have permissions to create groups, you can try the Tutorial: Grant a user access to Azure resources using RBAC and Azure PowerShell instead.

Create a resource group

You use a resource group to show how to assign a role at a resource group scope.

  1. Get a list of region locations using the Get-AzLocation command.

    Get-AzLocation | select Location
    
  2. Select a location near you and assign it to a variable.

    $location = "westus"
    
  3. Create a new resource group using the New-AzResourceGroup command.

    New-AzResourceGroup -Name "rbac-tutorial-resource-group" -Location $location
    
    ResourceGroupName : rbac-tutorial-resource-group
    Location          : westus
    ProvisioningState : Succeeded
    Tags              :
    ResourceId        : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rbac-tutorial-resource-group
    

Grant access

To grant access for the group, you use the New-AzRoleAssignment command to assign a role. You must specify the security principal, role definition, and scope.

  1. Get the object ID of the group using the Get-AzureADGroup command.

    Get-AzureADGroup -SearchString "RBAC Tutorial Group"
    
    ObjectId                             DisplayName         Description
    --------                             -----------         -----------
    11111111-1111-1111-1111-111111111111 RBAC Tutorial Group
    
  2. Save the group object ID in a variable.

    $groupId = "11111111-1111-1111-1111-111111111111"
    
  3. Get the ID of your subscription using the Get-AzSubscription command.

    Get-AzSubscription
    
    Name     : Pay-As-You-Go
    Id       : 00000000-0000-0000-0000-000000000000
    TenantId : 22222222-2222-2222-2222-222222222222
    State    : Enabled
    
  4. Save the subscription scope in a variable.

    $subScope = "/subscriptions/00000000-0000-0000-0000-000000000000"
    
  5. Assign the Reader role to the group at the subscription scope.

    New-AzRoleAssignment -ObjectId $groupId `
      -RoleDefinitionName "Reader" `
      -Scope $subScope
    
    RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleAssignments/44444444-4444-4444-4444-444444444444
    Scope              : /subscriptions/00000000-0000-0000-0000-000000000000
    DisplayName        : RBAC Tutorial Group
    SignInName         :
    RoleDefinitionName : Reader
    RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
    ObjectId           : 11111111-1111-1111-1111-111111111111
    ObjectType         : Group
    CanDelegate        : False
    
  6. Assign the Contributor role to the group at the resource group scope.

    New-AzRoleAssignment -ObjectId $groupId `
      -RoleDefinitionName "Contributor" `
      -ResourceGroupName "rbac-tutorial-resource-group"
    
    RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rbac-tutorial-resource-group/providers/Microsoft.Authorization/roleAssignments/33333333-3333-3333-3333-333333333333
    Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rbac-tutorial-resource-group
    DisplayName        : RBAC Tutorial Group
    SignInName         :
    RoleDefinitionName : Contributor
    RoleDefinitionId   : b24988ac-6180-42a0-ab88-20f7382dd24c
    ObjectId           : 11111111-1111-1111-1111-111111111111
    ObjectType         : Group
    CanDelegate        : False
    

List access

  1. To verify the access for the subscription, use the Get-AzRoleAssignment command to list the role assignments.

    Get-AzRoleAssignment -ObjectId $groupId -Scope $subScope
    
    RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleAssignments/22222222-2222-2222-2222-222222222222
    Scope              : /subscriptions/00000000-0000-0000-0000-000000000000
    DisplayName        : RBAC Tutorial Group
    SignInName         :
    RoleDefinitionName : Reader
    RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
    ObjectId           : 11111111-1111-1111-1111-111111111111
    ObjectType         : Group
    CanDelegate        : False
    

    In the output, you can see that the Reader role has been assigned to the RBAC Tutorial Group at the subscription scope.

  2. To verify the access for the resource group, use the Get-AzRoleAssignment command to list the role assignments.

    Get-AzRoleAssignment -ObjectId $groupId -ResourceGroupName "rbac-tutorial-resource-group"
    
    RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rbac-tutorial-resource-group/providers/Microsoft.Authorization/roleAssignments/33333333-3333-3333-3333-333333333333
    Scope              : /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rbac-tutorial-resource-group
    DisplayName        : RBAC Tutorial Group
    SignInName         :
    RoleDefinitionName : Contributor
    RoleDefinitionId   : b24988ac-6180-42a0-ab88-20f7382dd24c
    ObjectId           : 11111111-1111-1111-1111-111111111111
    ObjectType         : Group
    CanDelegate        : False
    
    RoleAssignmentId   : /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleAssignments/22222222-2222-2222-2222-222222222222
    Scope              : /subscriptions/00000000-0000-0000-0000-000000000000
    DisplayName        : RBAC Tutorial Group
    SignInName         :
    RoleDefinitionName : Reader
    RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
    ObjectId           : 11111111-1111-1111-1111-111111111111
    ObjectType         : Group
    CanDelegate        : False
    

    In the output, you can see that both the Contributor and Reader roles have been assigned to the RBAC Tutorial Group. The Contributor role is at the rbac-tutorial-resource-group scope and the Reader role is inherited at the subscription scope.

(Optional) List access using the Azure Portal

  1. To see how the role assignments look in the Azure portal, view the Access control (IAM) blade for the subscription.

    Role assignments for a group at subscription scope

  2. View the Access control (IAM) blade for the resource group.

    Role assignments for a group at resource group scope

Remove access

To remove access for users, groups, and applications, use Remove-AzRoleAssignment to remove a role assignment.

  1. Use the following command to remove the Contributor role assignment for the group at the resource group scope.

    Remove-AzRoleAssignment -ObjectId $groupId `
      -RoleDefinitionName "Contributor" `
      -ResourceGroupName "rbac-tutorial-resource-group"
    
  2. Use the following command to remove the Reader role assignment for the group at the subscription scope.

    Remove-AzRoleAssignment -ObjectId $groupId `
      -RoleDefinitionName "Reader" `
      -Scope $subScope
    

Clean up resources

To clean up the resources created by this tutorial, delete the resource group and the group.

  1. Delete the resource group using the Remove-AzResourceGroup command.

    Remove-AzResourceGroup -Name "rbac-tutorial-resource-group"
    
    Confirm
    Are you sure you want to remove resource group 'rbac-tutorial-resource-group'
    [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):
    
  2. When asked to confirm, type Y. It will take a few seconds to delete.

  3. Delete the group using the Remove-AzureADGroup command.

    Remove-AzureADGroup -ObjectId $groupId
    

    If you receive an error when you try to delete the group, you can also delete the group in the portal.

Next steps