In the previous posts on RBAC we have looked at customising various roles to ensure that the role contained the minimum amount of cmdlets. RBAC provides even more granularity, and we can add or remove specific parameters from a cmdlet. Since some folks asked for examples on this topic here are a couple of quick examples and some considerations….
If you want to use ECP, please read all the way down to the bottom. The initial examples will work with the Exchange Management Shell but there are a couple of extra considerations for ECP.
Setting The Stage
As a scenario, let’s invent a crappy work task that some unlucky person could be asked to perform. Let’s say there is a mobile phone management team within a large business and their sole responsibility is to assign mobile phones and numbers to people. As part of this they need to be able to update the MobilePhone property of all users. They should not be able to modify any other attributes at all.
The cmdlet that we want is Set-User and the MobilePhone parameter.
Locate The Cmdlets
This section builds and creates the custom RBAC role that we will use. Firstly lets see where the relevant cmdlets and parameters live!
We can use the Get-ManagementRole cmdlet to see where the cmdlet lives using the -Cmdlet and -CmdletParameters respectively. Below we can see where both the Set-User and MobilePhone exist:
Since the Set-User with the MobilePhone parameter exists in the Mail Recipients role, let’s use that role. As before the built-in roles are read only and we cannot make any changes to them. So we need to make a copy of the role, and since this copy is writable we can make the necessary changes. Our custom role will be called Mobile-Phone-Jockeys.
New-ManagementRole -Name "Mobile-Phone-Jockeys" -Parent "Mail Recipients"
If we check the contents of our new Management Role, we will see that it contains all the cmdlets and parameters present in the original parent role – not surprising since it was a copy….
Get-ManagementRoleEntry "Mail Recipients*" | Measure-Object
Get-ManagementRoleEntry "Mobile-Phone-Jockeys*" | Measure-Object
We need to remove all the cmdlets that we do not want, so the quickest way to do this is to get a list of cmdlets that do not match Get-User and then once we check the list, remove them.
Note: Always check the objects returned are as expected prior to piping to the remove cmdlet!
So in this case we would run:
Get-ManagementRoleEntry -Identity "Mobile-Phone-Jockeys\*" | Where-Object {$_.Name -ne 'Get-User'}
Only when we are happy with what is returned should we run:
Get-ManagementRoleEntry -Identity "Mobile-Phone-Jockeys\*" | Where-Object {$_.Name -ne 'Get-User'} | Remove-ManagementRoleEntry
If we check to see what’s now in the Mobile-Phone-Jockeys Role, it only contains the Get-User cmdlet.
Get-ManagementRoleEntry –Identity "Mobile-Phone-Jockeys\*"
Add A Single Parameter
At this point the Get-User cmdlet is the only entry left in the Management Role.
Let’s add back the Set-User cmdlet, with *ONLY* the ability to set the MobilePhone parameter, and the identity parameter.
Add-ManagementRoleEntry "Mobile-Phone-Jockeys\Set-User" -Parameters MobilePhone, Identity
Get-ManagementRoleEntry "Mobile-Phone-Jockeys\*"
This is a great example of adding in a specific parameter, when the cmdlet did not already exist.
If you are wondering about the Identity parameter that is also present with MobilePhone, keep reading!
Add Multiple Parameters
Taking the example above we could have specified multiple parameters in the same command. if we deviate from the example above slightly and pretend that our Mobile-Phone-Jockey role has now become responsible for also assigning office phones then they need to also set the Phone attribute. You can specify multiple parameters, separated with commas.
Add-ManagementRoleEntry "Mobile-Phone-Jockeys\Set-User" -Parameters MobilePhone, Phone, Identity
Changing Existing Parameters
If we want to go about modifying a cmdlet’s list of parameters, a good guess would be that we would use the Add-ManagementRoleEntry or Remove-ManagementRoleEntry but neither will do what we need. They just add or remove the entire Management Role Entry. In the case of changing the available parameters on an existing role entry we need to use the Set-ManagementRoleEntry cmdlet. Its Parameters switch has the following modes:
-
When used with the AddParameter parameter, the parameters you specify are added to the role entry.
-
When used with the RemoveParameter parameter, the parameters you specify are removed from the role entry.
-
When neither the AddParameter nor RemoveParameter parameters are used, only the parameters you specify are included in the role entry. If you specify a value of
$Nulland neither the AddParameter nor RemoveParameter parameters are used, all of the parameters on the role entry are removed.
So if we want to remove all parameters from the Set-User cmdlet apart from MobilePhone and Identity we could run:
Set-ManagementRoleEntry "Mobile-Phone-Jockeys\Set-User" -Parameters MobilePhone, Identity
Get-ManagementRoleEntry "Mobile-Phone-Jockeys\*"
An alternative would have be to remove just the Phone parameter:
Set-ManagementRoleEntry "Mobile-Phone-Jockeys\Set-User" -Parameters Phone –RemoveParameter
Get-ManagementRoleEntry "Mobile-Phone-Jockeys\*"
The end result is the same in this case, and you can choose the method that makes the most sense!
Want To Live Like Common People
< Common People courtesy of Pulp >
One interesting thing to note is that when we try to prune out the parameters that we do not want, the common ones should typically be left. They are needed to ensure that we can perform the basic aspects of the cmdlet. This includes parameters like WhatIf, DomainController or Verbose. None of these apply changes to a mailbox or user, but they allow us to control how the operation is performed.
Trying to see them can be a little tricky. Look at the truncated display here indicated by the three periods:
To review all the parameters present in a Management Role Entry I like to do the following:
$Params = Get-ManagementRoleEntry "Mail Recipients\Set-user" | Select Parameters $Params.Parameters
$Params.Parameters will output the entire content of the attribute to the screen. If we split the output to see what parameters are the common ones and what are specific to the Set-User cmdlet we will see:
Specific Parameters
AssistantName, CertificateSubject, City, Company, CountryOrRegion, Department, DisplayName, Fax, FirstName, HomePhone, Initials, LastName, Manager, MobilePhone, Name, Notes, Office, OtherFax. OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostalCode, PostOfficeBox, ResetPasswordOnNextLogon, SamAccountName, SeniorityIndex, SimpleDisplayName, StateOrProvince, StreetAddress, TelephoneAssistant, Title, UserPrincipalName, WebPage, WindowsEmailAddress
Common Parameters
Confirm, Debug, DomainController, ErrorAction, ErrorVariable, Identity, IgnoreDefaultScope, LinkedCredential, LinkedDomainController, LinkedMasterAccount, OutBuffer, OutVariable, RemotePowerShellEnabled, Verbose, WarningAction, WarningVariable, WhatIf
Why is this worth mentioning, well if the necessary common parameters to run cmdlet are not present then it does not run, savvy?
If Identity is not specified for the Set-User cmdlet then you are going to see this fun error:
The operation couldn't be performed because object 'test-6' couldn't be found on 'exch-dc.tailspintoys.com'.
+ CategoryInfo : NotSpecified: (0:Int32) [Set-User], ManagementObjectNotFoundException
+ FullyQualifiedErrorId : 98454A26,Microsoft.Exchange.Management.RecipientTasks.SetUser
Why can we not find the account? It is clearly there as we can see with the first command Get-User.
The identity parameter is not present on the Set-User cmdlet in the custom Management Role. This can be a little confusing as we can type "Set-user -Identity" so where is the Identity parameter coming from? Note that the –identity parameter is visible since it is present within the Role Assignment Policy. Role Assignment Policy is just for end user RBAC and is scoped to the individual user thus it cannot be used to modify other users. When we want to modify a user account that is not our own the Role Assignment Policy does not apply as it does not fall within the scope of 'SELF", and we look to the other Management Role which is Mobile-Phone-Jockeys in this case. Since Mobile-Phone-Jockeys does not have the Identity parameter the command fails to change the properties of user account Test-6".
Morale of the story? Be sure to include the necessary common parameters else you will get some “interesting” results…
Testing
Testing time, and arguable the most important section!! Let’s assign the Mobile-Phone-Jockeys management role to a test user called User-15.
And to confirm the Mobile-Phone-Jockeys management role contains:
Testing via Exchange Management Shell on User-15’s Windows 7 x64 desktop shows that RBAC is working and they can modify the Mobile number for a separate user (Test-6):
Happy days? Well almost…
You think you are done, and the testing was OK. But then you get a call saying that ECP cannot be used, as the option to view other mailboxes is not present. Huh? Are the permissions not correct? Permissions are correct as we tested them, so what gives? This is what User-15 sees in ECP, note there is no Manage My Organization option along the top, and the shortcut on the right pane does not take us their either. The shortcut has this link:
https://mail.tailspintoys.com/ecp/PersonalSettings/HomePage.aspx?showhelp=false&#
How to fix this? We need to make ECP display the Manage My organization option. We do this by adding cmdlet(s) that will force the option to be displayed, and the in this case we will add Get-Mailbox and Get-Recipient. Lets add them in:
Add-ManagementRoleEntry Mobile-Phone-Jockeys\Get-Mailbox
Add-ManagementRoleEntry Mobile-Phone-Jockeys
Get-Recipient
Get-ManagementRoleEntry Mobile-Phone-Jockeys\*
With the modified Management Role Entries, User-15 now sees:
Note that the Manage My Organization is visible, and so are the mailboxes in the organization. The shortcut to Manage your organization link now takes us to the organization management page in ECP .
Double clicking to edit one shows that that User-15 has the permissions to edit the Mobile Phone field as it is not locked out. Fields in grey are locked out.
Concluding Thoughts
We can see that RBAC allows for a great deal of customisation, right down to the individual parameters that are available! This is an amazing amount of flexibility, and there is one glaring thing that should be striking Exchange 2003 and 2007 admins at this point. Did we change a single ACL to the objects in AD? NO! Not a single one. We focussed on the business requirement, which was to allow the phone team to update the mobile number assigned to users, and did not have to think about ACLs. This is a huge win as having to get change records cut to modify AD ACLs is a challenge.
This is made possible by the Exchange Trusted Subsystem universal security group as it is that group that has the permissions to the AD objects. RBAC enforces and controls the cmdlets and parameters that you can see and thus use thereby controlling what changes are made to the Exchange objects.
Cheers,
Rhoderick
>>
