Create a custom user role in Exchange Online using RBAC - part 1

  • Article

Hi Exchange Online bloggers,

I have wrote the script below in order to automate the creation of a custom user role. In order to achieve that, we need to mention the Role Assignment Policy name, the cmdlet and the name of the parameter that we want to exclude from a root (end user) management role.

What do you need to know before you begin?

  • The parameter that you provide should be granular so that we exclude specific permissions that are unique. However, if the parameter is being found in more than one user management roles, then, the child management role is being created under the first match from the policy assigned roles list. With the command below we can check if the parameter that we input is unique among the precanned management roles. Also, the second command shows us in how many such roles we can find the provided cmdlet.
 Get-ManagementRole -CmdletParameters ForwardingAddress | ? {$_.IsEndUserRole -match 'True' -and $_.IsRootRole -match 'True'} 

Name          RoleType
 ----          -------- 
MyBaseOptions MyBaseOptions

Get-ManagementRole -Cmdlet Set-Mailbox | ? {$_.IsEndUserRole -match 'True' -and $_.IsRootRole -match 'True'} 

Name                 RoleType
 ----                 -------- 
MyMailboxDelegation  MyMailboxDelegation
MyBaseOptions        MyBaseOptions
MyProfileInformation MyProfileInformation
  • Before running the script make sure that the parent user roles from the role assignment policy that you change are ticked. If not, it won't have a pool where to look for the data you enter.
  • When a child (user) management role is being created, the parent management role assignment is removed (unticked on the GUI) and the child is becoming active (ticked). If you later run the script to create another custom user role and the cmdlet plus parameter would match the parent root role that was removed, now it will of course match the child role which will become the parent for the new role that we create. So basically, you will have a user role that contains two exclusions, the initial one, when the first child was created, and the second one, from the newly created user role.

Example:
The user role RootWithoutAcceptMessagesOnlyFromSendersOrMembers is the child of the root role MyBaseOptions and the next one, PrevWithoutExternalOofOptions, is the child of the RootWithoutAcceptMessagesOnlyFromSendersOrMembers role. There are two parameters that were excluded from the second user role: AcceptMessagesOnlyFromSendersOrMembers and ExternalOofOptions. In case you want to create a child user role under the root role MyBaseOptions, you would have to recreate the management role assignment (tick MyBaseOptions).

In short, the management role containing the prefix "Root" has as parent the root role above it, and the one with the "Prev" prefix has as parent, the previous custom user role.

userroles

 

 

 

 

 

 

 

 DISCLAIMER:  This application is a sample application. The sample is provided “as is” without warranty of any kind. Microsoft further disclaims all implied warranties including without limitation any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the samples remains with you. in no event shall Microsoft or its suppliers be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss arising out of the use of or inability to use the samples, even if Microsoft has been advised of the possibility of such damages). Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you. 



$RAP = Read-Host "What's the name of your Role Assignment Policy? (e.g. Default Role Assignment Policy)"
$cmdlet = Read-Host "Type the PowerShell cmdlet that is containing the parameter to which you want to cut access to (e.g. Set-Mailbox)"
$param = Read-Host "Name the parameter to exclude from $($cmdlet) (e.g. ForwardingAddress)"

$i=0;

foreach ($a in (Get-RoleAssignmentPolicy $RAP).AssignedRoles) {

if (!$i)
{
Get-ManagementRoleEntry $a\* | % {

if($_.Name -eq $cmdlet) {

(Get-ManagementRoleEntry $a\$($_.Name)).parameters | % {

if($_ -eq $param) {

if((Get-ManagementRole $a).IsRootRole -eq 'True') { $b="RootWithout"+ $param; New-ManagementRole -Parent $a -Name $b }

    else { $b="PrevWithout"+ $param; New-ManagementRole -Parent $a -Name $b }

Get-ManagementRoleAssignment -RoleAssignee $RAP -Role $a | Remove-ManagementRoleAssignment -Confirm:$false

Set-ManagementRoleEntry $b\$cmdlet -Parameters $param -RemoveParameter -Confirm:$false

New-ManagementRoleAssignment -Name "$b-RAP" -Role $b -Policy $RAP

$i++;               
                     }
                                                       }
if($i) {break;} 
                          }
  
                              }
}
       else {break;}
                                                          }

if(!$i -and $error[0].Exception -notmatch "$($RAP)") { Write-Host "It might be that the cmdlet or the parameter that you provided is not correct. If they are correct, then they were not found within the assigned roles" -ForegroundColor Yellow }