Active Directory & Office 365 Reporting Tool

How to Automate Azure AD RBAC Role Management with PowerShell. Do you want to learn the automation and management of Azure AD Role-based access control with PowerShell? Whether you’re new to PowerShell or a pro, after reading this article you’ll know to automate Azure RBAC roles using PowerShell. 

Azure has built in roles with pre-defined permissions. These roles are assigned to Azure identities at various scopes

Before you start assigning roles, it is essential to know these roles. So, in the first section, you learn how to list built-in and custom Azure RBAC roles using PowerShell. 

Once you’ve got the assignable roles, the next logical step is to find the roles already assigned to your Azure tenant. We explain the PowerShell commands required to list assigned roles in Azure. 

Finally, the article ends by explaining how to remove existing role assignments or add new assignments. 

Before proceeding, you must install the AzureAD module to run the commands discussed in this article. After that, run the Connect-AzureAD command. 

List Azure AD Roles (Build-in and Custom RBAC Role)

The first step in the automation of Azure AD role-based access control (RBAC) with PowerShell is identifying the roles. The Get-AzRoleDefinition command lists all roles (built-in and custom) available in the current subscription.

Before running the Get-AzRoleDefinition command, ensure you’ve installed the AzureAD module and run the Connect-AzureAD command. 


When you run the command without any parameters, it lists the roles. Unfortunately, the default (list) format makes it difficult to see all the roles.

To return the results in a table, pipe Get-AzRoleDefinition to Format-Table.

					Get-AzRoleDefinition | Format-Table -wrap

Running the command this way displays the result in a table with the following headings:

1. Name – the name of the Azure Role
2. Id – the Object ID for the role
3. IsCustom – returns a boolean value of true (specifying that the role is a custom role) or false (indicating that it is a built-in role)
4. Description – A short description of the Azure role

The default table view is great, but some parts of the last column (description) are hidden. To force PowerShell to display the hidden values, include the Wrap parameter of the Format-Table cmdlet.

You may also want to export the list of roles to a text or CSV file. If you need to export all Azure roles in your current subscription to a text file, use this command below.

					Get-AzRoleDefinition | Format-Table -Wrap | Out-File D:\report\Azure-roles.txt

However, to export the roles to a CSV file, replace Out-File with the Export-CSV command:

					Get-AzRoleDefinition | Format-Table -Wrap | Export-CSV D:\report\Azure-roles.CSV -NoTypeInformation

Before we move on from this section, let’s explore some other ways to run the Get-AzRoleDefinition.

Although listing all the roles provides an overview, you may want to see a specific role. To return a specific Azure role, use the Name parameter to specify the role.

For instance, the command below returns information about the Azure Reader role

					Get-AzRoleDefinition -Name Reader

Finally, list all custom roles by including the Custom parameter.

					Get-AzRoleDefinition -Custom

In the remaining parts of the article, we would be using the information from this section as we explore various ways to automate Azure role management with PowerShell.

Try our Active Directory & Office 365 Reporting & Auditing Tools

Try us out for Free.  100’s of report templates available. Easily customise your own reports on AD, Azure AD & Office 355.

Next with How to Automate Azure AD RBAC Role Management with PowerShell is to list Azure AD Role Assignments with PowerShell. Let me show you how to do it!

Azure AD Role-Based Access Control Automation: List Azure AD Role Assignments with PowerShell

Another important element in the automation of Azure AD role-based access control (RBAC) with PowerShell is reporting on Azure role assignments. The Get-AzRoleAssignment is used to list role assignments for subscriptions, users, groups, and other identities.

For example, to list all the role assignments in the current subscription, run the Get-AzRoleAssignment without any parameters.


The command displays current role assignments in a list with default values. 

To display the roles in a table with specified headers, run this sample command.

					Get-AzRoleAssignment | Select-Object DisplayName,ObjectId,ObjectType,RoleDefinitionName,RoleDefinitionId,Scope | Format-Table -Wrap -AutoSize

The displays the following information:

1. DisplayName – the display name of the Azure object assigned the role
2. ObjectId – the Id 
3. RoleDefinitionName – the name
4. RoleDefinitionId – displays the object Id
5. Scope – the scope of the assigned role.

All the information in the above custom report is essential to manage (add or remove) role assignments in Azure using Windows PowerShell.

By combining this information and the information from the role assignment report (previous section), you’re ready for the automation and management of Azure AD role-based access control with PowerShell.

Add or Remove Azure AD Role Assignments with PowerShell

Assigning a role to an Azure identity object uses the New-AzRoleAssignment PowerShell cmdlet. Moreover, using this cmdlet to assign a role requires 3 parameters:

1. ObjectId – used to define the Id of the Azure object you’re assigning the role
2. RoleDefinitionName – the name of the Azure role you’re assigning.
3. Scope – specifies the scope of the role. 

How to Assign an Azure AD Role with PowerShell

Follow the steps below to get the ObjectId, RoleDefinitionName and Scope and assign a role using PowerShell:

1. To get the ObjectId of the Azure Identity, run this sample command. My command below returns the object Ids for an Azure user and a group

					$userid = (Get-AzADUser -DisplayName "Carol Olotu").id
$groupid = (Get-AzADGroup -DisplayName "Helpdesk administrators").id

Before running the commands, change the DisplayName to your object’s display name in Azure AD.  

2. Once you’ve saved the Ids of the Azure objects in the defined variables, get the name of the role you want to assign. I want to assign the Reader role to the user and group in step 1. 

					$rolename = (Get-AzRoleDefinition -Name Reader).Name

To get a list of Azure roles, refer to the first section. We used the command below to display all roles in the Azure tenant. 

					Get-AzRoleDefinition | Format-Table -wrap

Pick the name of the Azure role from the list. After that, use the previous command to save the information in the $rolename variable. 

3. The final information is the role assignment scope. The Get-AzResource command is used to return the scope of an Azure resource. 

However, running the command requires the name of the resource.

To get a list of resources in your subscription, run this command. 

					Get-AzResource | Format-Table

The command displays all the resources in the current Azure subscription, including the Name of the resource. Additionally, the command displays the resource type. 

I am using the Azure-Ark-servers resource scope. This is a vault, as indicated in the ResourceType column.  

To identify this scope and save it in a variable, run this sample command. 

					$rolescope = (Get-AzResource -Name Azure-Ark-servers).ResourceID

4. The final step is to use the New-AzRoleAssignment, specifying the ObjectId, RoleDefinitionName, and Scope variables in steps 1 to 3 above. 

					New-AzRoleAssignment -ObjectId $userid -RoleDefinitionName $rolename -Scope $rolescope
New-AzRoleAssignment -ObjectId $groupid -RoleDefinitionName $rolename -Scope $rolescope

The first command above assigns the Reader role to the defined in the $userid variable. Similarly, the second command assigns the same role to a group assigned to the $groupid variable. 

If the commands run successfully, they return information about the assigned roles. 

To confirm that the Reader role was assigned at the defined scope, open the object in Azure Portal. 

How to Display and Remove an Azure AD Role with PowerShell

To display the role assigned then user in the last subsection, run the sample command below. 

					Get-AzRoleAssignment -ObjectId $userid

Finally, to remove the role, pipe the above command to the Remove-AzRoleAssignment command. 

					Get-AzRoleAssignment -ObjectId $userid | Remove-AzRoleAssignment

After a while, PowerShell confirms that the role assignment has been removed. Below is the result of the last two commands. 

Finally, I remove the role I assigned to the group by specifying the group’s Id. 

					Get-AzRoleAssignment -ObjectId $groupid | Remove-AzRoleAssignment

To confirm that the commands worked and that the roles were removed successfully, I refresh the objects in the Azure portal. 

The Reader role is gone!

Thank you for reading How to Automate Azure AD RBAC Role Management with PowerShell. We shall conclude the article.

How to Automate Azure AD RBAC Role Management with PowerShell Conclusion

This article explored three areas necessary for the management and automation of Azure AD role-based access control using PowerShell. Firstly, we discussed using the Get-AzRoleDefinition command to list all built-in and custom roles in Azure.

Furthermore, the section explained pipping the command to Format-Table to display the result in a table. Beyond that, we also demonstrated how to export the result of the command to a text or CSV file. 

Secondly, we examined how to use the Get-AzRoleAssignment command to list all role assignments in the current Azure subscription. As we explained later in the article this information is vital for removing role assigning. 

Finally, we explained how to combine the knowledge gained in the first two sections to add or remove role assignments. 


Try InfraSOS for FREE

Try InfraSOS Active Directory, Azure AD & Office 365 Reporting & Auditing Tool

Victor Ashiedu

Victor Ashiedu

Victor is an IT pro based in Manchester, UK. With over 22 years of experience managing Windows Server, Active Directory, and Powershell, and 7 years of expertise in Azure AD and Office 365, he's a seasoned expert in his field. When he's not working, he loves spending time with his family - a wife and a 5-year-old. Victor is passionate about helping businesses succeed in today's fast-changing tech landscape.

Leave a comment

Your email address will not be published. Required fields are marked *