title	Tutorial: Grant a group access to Azure resources using Azure PowerShell - Azure RBAC
description	Learn how to grant a group access to Azure resources using Azure PowerShell and Azure role-based access control (Azure RBAC) in this tutorial.
author	rolyon
manager	pmwongera
ms.service	role-based-access-control
ms.custom	devx-track-azurepowershell, has-azure-ad-ps-ref, azure-ad-ref-level-one-done
ms.topic	tutorial
ms.date	02/02/2019
ms.author	rolyon

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

Azure role-based access control (Azure 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:

[!div class="checklist"]

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.

[!INCLUDE az-powershell-update]

Prerequisites

To complete this tutorial, you will need:

Permissions to create groups in Microsoft Entra ID (or have an existing group)
Azure Cloud Shell
Microsoft Graph PowerShell SDK

Role assignments

In Azure 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)

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-MgGroup command.

New-MgGroup -DisplayName "RBAC Tutorial Group" -MailEnabled:$false `
   -SecurityEnabled:$true -MailNickName "NotSet"

DisplayName         Id                                   MailNickname Description GroupTypes
-----------         --                                   ------------ ----------- ----------
RBAC Tutorial Group aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb NotSet                   {}

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

Create a resource group

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

Get a list of region locations using the Get-AzLocation command.
```
Get-AzLocation | select Location
```
Select a location near you and assign it to a variable.
```
$location = "westus"
```

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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.

Get the object ID of the group using the Get-MgGroup command.

Get-MgGroup -Filter "DisplayName eq 'RBAC Tutorial Group'"

DisplayName         Id                                   MailNickname Description GroupTypes
-----------         --                                   ------------ ----------- ----------
RBAC Tutorial Group aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb NotSet                   {}

Save the group object ID in a variable.

$groupId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

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 : aaaabbbb-0000-cccc-1111-dddd2222eeee
State    : Enabled

Save the subscription scope in a variable.

$subScope = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"

Assign the Reader role to the group at the subscription scope.

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

RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
DisplayName        : RBAC Tutorial Group
SignInName         :
RoleDefinitionName : Reader
RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
ObjectId           : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType         : Group
CanDelegate        : False

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rbac-tutorial-resource-group/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rbac-tutorial-resource-group
DisplayName        : RBAC Tutorial Group
SignInName         :
RoleDefinitionName : Contributor
RoleDefinitionId   : b24988ac-6180-42a0-ab88-20f7382dd24c
ObjectId           : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType         : Group
CanDelegate        : False

List access

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleAssignments/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
DisplayName        : RBAC Tutorial Group
SignInName         :
RoleDefinitionName : Reader
RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
ObjectId           : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
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.

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rbac-tutorial-resource-group/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rbac-tutorial-resource-group
DisplayName        : RBAC Tutorial Group
SignInName         :
RoleDefinitionName : Contributor
RoleDefinitionId   : b24988ac-6180-42a0-ab88-20f7382dd24c
ObjectId           : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType         : Group
CanDelegate        : False

RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleAssignments/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
DisplayName        : RBAC Tutorial Group
SignInName         :
RoleDefinitionName : Reader
RoleDefinitionId   : acdd72a7-3385-48ef-bd42-f606fba81ae7
ObjectId           : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
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

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

Remove access

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

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"

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.

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"):

When asked to confirm, type Y. It will take a few seconds to delete.
Delete the group using the Remove-MgGroup command.
```
Remove-MgGroup -GroupID $groupId
```
If you receive an error when you try to delete the group, you can also delete the group in the portal.

Next steps

[!div class="nextstepaction"] Assign Azure roles using Azure PowerShell

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Prerequisites

Role assignments

Create a group

Create a resource group

Grant access

List access

(Optional) List access using the Azure portal

Remove access

Clean up resources

Next steps

FilesExpand file tree

tutorial-role-assignments-group-powershell.md

Latest commit

History

tutorial-role-assignments-group-powershell.md

File metadata and controls

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

Prerequisites

Role assignments

Create a group

Create a resource group

Grant access

List access

(Optional) List access using the Azure portal

Remove access

Clean up resources

Next steps