Do you have an existing AD OU/domain structure that you use to group and/or delegate administrative access to on-premises Exchange resources? This includes examples such as Role Based Access Control (RBAC) delegations for de-centralized resource administration and also Dynamic Distribution Groups (DDGs) based on AD hierarchy. Do you wish you had the same sort of OU/domain-based organization capabilities in Exchange Online (EXO)?
Then this post is for you.
NOTE: This solution was designed for an Exchange organization running in a Hybrid configuration, where they synchronize their Exchange resource data with EXO. Having said that, this solution could be used for other purposes such as delegation of resource administration within any Office 365 service that can take advantage of this approach.
DISCLAIMER: This is not an official Microsoft offering nor is it supported by Microsoft. This is a solution I came up with and am sharing with the community.
Background/Challenge
Some Businesses/Organizations have multiple AD OUs, and even multiple AD domains, that they deployed in a structured and hierarchical configuration to organize resources (such as users) in a meaningful way (such as regions of resources that aren’t reflected in City/State/Country AD attributes). The two most common scenarios where I have seen this approach leveraged with on-premises Exchange resources are creating custom RBAC scoped delegations to support decentralized administration of resources, and also creating DDGs of resources when no AD attributes are a good substitute for organizing users in the same DDG. For example custom RBAC delegations can use the “RecipientOrganizationalUnitScope” custom write-scope filter to target a specific AD OU/domain structure, and DDGs can use the “RecipientContainer” to do the same thing.
For Exchange organizations that use this administration approach, one perceivable downside to the way EXO resources are stored in each tenant is that they are stored in a very flat manner, without any reference to the AD OU/domain structure they reside in on-premises. Subsequently the on-premises AD OU/domain structure can’t be leveraged for resource organization purposes. This lack of AD OU/domain based delegated administration was a major EXO adoption blocker for one of my customers as they weren’t prepared to centralize administration of their very decentralized (think world-wide) Exchange resources.
To be clear there are alternative ways to group and/or delegate administration of your EXO resources to different administrative groups in your organization. For instance, you could use the City attribute to group users in an administrative boundary/grouping, but that approach has its challenges:
- All AD users need to have their City attribute populated (and consistently). Unless you are using some sort of AD attribute enforcement mechanism, like a 3rd party AD resource management tool, this can be difficult to achieve as the Active Directory Users and Computers MMC does not have this type of enforcement natively.
- AD groups don’t have a City attribute, so you would not be able to use a City based RBAC delegation to manage group resources in EXO.
- City names are not unique in the USA, much less the rest of the world. For example, Vienna Virginia USA and Vienna Austria are two completely different set of users/resources, but a “Vienna” City based organization would lump these two different groups of users together in an administrative boundary.
I evaluated using various AD attributes that are replicated from on-premises AD to EXO through Azure AD (AAD) Connect and kept running into one or more of the type of road blocks above.
NOTE: I was told a couple of years ago that a version of AAD Connect would replicate the on-premises AD OU structure of objects to AAD, but unfortunately not in attribute is that is consumable as a custom write scope for Exchange RBAC delegations. I wish I could recall the details of this discussion, but it may have had to do with mirroring OUs into Administrative Units.
I also think it’s worth pointing out that when running in an Exchange hybrid configuration, most administration of users and groups resources is performed through on-premises AD and Exchange administration tools. Typically, the only aspects of synchronized EXO resources I see managed in EXO are mailbox permissions and Send As rights.
Solution – Replicating the OU/Domain Path to Exchange Online
To solve this challenge and get my customer’s EXO adoption back on track, I had to think “outside the box” and come up with something new. So, I took a step back and looked again at what attributes are replicated to EXO that are also useable for EXO RBAC custom write scopes (for targeted delegated administration) and DDG filtering logic. I determined that a Custom Attribute met this need if I could somehow populate it with the OU/domain structure that each object lives in. Then I could create an EXO RBAC custom write scope that looked for a partial string match for the domain/OU structure in the Custom Attribute, and any object that met that criteria would be considered in scope for the RBAC delegation. Likewise, DDGs could use this same Custom Attribute to group resources based on the AD OU/domain the object lives in on-premises.
The next challenge was how to populate the on-premises domain/OU structure into each mail-enabled object’s designated Custom Attribute programmatically and consistently. Additionally, the Custom Attribute would need to be updated periodically as objects are moved around between OUs and even domains. To solve this challenge, I created a PowerShell script to run periodically (at least daily) on-premises that does the following:
- It targets only mail-enabled users and groups, but not contacts. This is because there are no mailbox access permissions on contacts and it would be very unusual to grant Send As permissions on contacts.
- It excludes any M365 (or what I like to call Unified/Modern) Groups written back to on-premises, because they will always be written to a single on-premises OU which wouldn’t be of value in this solution.
- It pulls the full AD canonicalName attribute (for example “contoso.com/US/East Coast/Maryland/Users/Sheehan, Daniel”) from each targeted object, strips the object’s “cn” (AKA “Sheehan, Daniel”) off the end of the canonicalName to obtain just the object’s domain/OU path (“contoso.com/US/East Coast/Maryland/Users/”). It also handles AD escape characters in the canonicalName.
NOTE: The canonicalName attribute was chosen to represent the domain/OU path over the AD distinguishedName attribute because it is arguably more “user friendly” to read than the DN, it follows the same format the customers already use for the “RecipientOrganizationalUnitScope” with on-premises Exchange RBAC custom wright scopes, and admins can quickly reference it from the “Object” tab of an object in Active Directory Users and Computers:
- The current value in the object’s Custom Attribute is comparted to the value derived above, and if it matches then there is no change. If the Custom Attribute is blank or has a different value (as in the object moved between OUs/domains since the last time the script was run), then it is updated to reflect the value derived above.
- The script can be run with the following optional parameters:
- A Domains array where one or more AD domains can be specified for the script to execute against. If none are supplied, then the script processes all domains it finds in the forest.
- A Verbose switch to show what it’s updating as it goes.
- A WhatIf switch so it doesn’t make any changes, rather just report on what it would have done. This is highly recommended until you get a comfort level with running the script and the changes it would make.
- An OutCSVFile parameter so you can specify what CSV file to log what changes were (or might have been if WhatIf is used) changed, including any errors it ran into updating entries. This is highly recommended all the time, so you have a history of what the script did and when. I almost made this a mandatory attribute but figured some people might not want this file long term.
Here is an example of the script in action:
NOTE: This approach requires that Azure AD Connect replicate the chosen Custom Attribute contents to EXO. This is the default for AAD Connect Hybrid Exchange deployments, but some customers choose to turn off replicating some attributes, so double check that the chosen Custom Attribute is replicating all the way through to EXO.
Creating Custom Management Delegations in Exchange Online
Once the domain/OU path is populated into a Custom Attribute of the desired resources, and replicated to EXO, all that is left to do is create custom RBAC delegations that target the users and groups for delegated administration. This includes which roles, or even more granularly which cmdlets are included to those delegations. The steps in this procedure are as follow (which are covered more in depth below):
- Create a custom write scope that targets the specific domain/OU string representing the on-premises hierarchy of objects that should be included in the delegation.
- Select existing or create custom roles to be assigned for administration of the targeted resources.
- Create a RBAC role group assigning it the roles and custom write scope created/selected above.
- Add administrators to that RBAC role group.
- Rinse and repeat as many times as you need for each administrative boundary.
Creating a Custom RBAC Write Scope
In this solution, the EXO PowerShell is be used to create a custom RBAC Write Scope to target just those objects with appropriate value in the designated Custom Attribute. Since the Custom Attribute field check is a string comparison operation, a wild card can be used at the end to denote any objects in the defined path or below. Using the domain/OU example from Solution Part 1, the following custom RBAC Write Scope will target all objects under the “East Coast” OU, not just the ones in the “Maryland” sub-OU:
New-ManagementScope -Name "East Coast Users" -RecipientRestrictionFilter {CustomAttribute7 -like "contoso.com/US/East Coast/*"}
Taking this methodology a step further, the string comparison operation supports multiple comparisons via the -or operator which can be used to designate multiple OU paths or even domains. For example, here a custom RBAC Write Scope targeting all “East Coast” and “West Coast” OU objects:
New-ManagementScope -Name "East/West Coast Users" -RecipientRestrictionFilter {(CustomAttribute7 -like "contoso.com/US/East Coast/*") -or (CustomAttribute7 -like "contoso.com/US/West Coast/*")}
NOTE: Do not modify the Read Scope on any custom RBAC roles as this can cause issues such as only accounts having that custom RBAC Read Scope being the only ones to see the targeted objects in the Exchange Org.
Selecting or Customizing RBAC Roles
The next part of the solution is to determine what rights should be assigned to the administrators for their targeted resources. Probably the easiest approach is to grant them control over Full Mailbox Permissions or Send As rights would be to assign them the Recipient Administrator role which includes these rights. However, this role includes the ability to create new objects in EXO, and in my experience admins can get confused between managing resources between on-premises and EXO and subsequently create new “cloud only” objects such as traditional Distribution Groups (formerly known as Distribution Lists).
To help prevent the scenario where administrators have rights to manage select resources from accidentally creating “cloud only” resources that should only be created on-premises, the following customizations can be used to restrict what cmdlets they have access to:
New-ManagementRole -Name "O365MailRecipients" -Parent "Mail Recipients" Remove-ManagementRoleEntry "O365MailRecipients\New-Mailbox" Remove-ManagementRoleEntry "O365MailRecipients\Enable-Mailbox" New-ManagementRole -Name "O365DistributionGroups" -Parent "Distribution Groups" Remove-ManagementRoleEntry "O365DistributionGroups\New-DistributionGroup" Remove-ManagementRoleEntry "O365DistributionGroups\New-DyanmicDistributionGroup"
NOTE: The removal of the Unified Group cmdlets was omitted from these custom RBAC roles because those are cloud only resources that need to be created and managed in EXO. However, if this level of permission is not desired, then these cmdlets can be removed just as easily by repeating the removal examples used above. In fact it’s a good idea to use the “Get-ManagementRoleEntry ‘ManagementRole*'” command to review what entries are assigned to each custom role.
Creating Custom RBAC Role Assignment
Now that the custom RBAC Write Scope(s) and Roles have been determined and created, all that is left is to create RBAC groups to link them all together. Here is an example of creating a custom RBAC Role Assignment:
New-RoleGroup -Name "East Coast Administrators" -Roles "O365MailRecipients", "O365DistributionGroups", "Message Tracking", "User Options", "View-Only Configuration", "View-Only Recipients" -CustomRecipientWriteScope "East Coast Users"
NOTE: If you create custom Write Back scopes to encompass multiple OUs/domains, then make sure to name the Role Group appropriate to denote it manages multiple groupings of resources.
Adding Administrators to RBAC Role Groups
This is standard group membership changes inside EXO, where you add the admin accounts to the role group created above, so I won’t bother with screen shots or instructions. 😊
Creating OU/Domain Based Dynamic Distribution Groups in Exchange Online
Targeting Exchange resources with an EXO DDG based on the OU/domain structure is just as easy with the custom RBAC delegations discussed above. Instead of using the “RecipientContainer” DDG parameter to specific an AD OU/domain structure, the DDG recipient filter is expanded to include a search of the populated Custom Attribute. For example, here is code to create a DDG for all East Coast users using the information populated into the custom attribute:
New-DynamicDistributionGroup -Name "East Coast Users DDG" -Alias "EastCoastUsersDDG" -RecipientFilter {((RecipientType -eq "UserMailbox") -or (RecipientType -eq "MailUser")) -and (CustomAttribute7 -like "contoso.com/US/East Coast/*")}
Another advantage to this solution is just like with the custom RBAC delegations mentioned above, EXO DDGs aren’t limited to specifying a single OU/domain structure when using this solution. Instead, you can specify multiple matches to the Custom Attribute field, so the DDG targets multiple OU/domain structures of Exchange resources. For example, here is code to create a DDG for all East Coast and North West users (again on-premises or EXO mailboxes):
New-DynamicDistributionGroup -Name "East/West Coast Users DDG" -Alias "EastWestCoastUsersDDG" -RecipientFilter {((RecipientType -eq "UserMailbox") -or (RecipientType -eq "MailUser")) -and ((CustomAttribute7 -like "contoso.com/US/East Coast/*") -or (CustomAttribute7 -like "contoso.com/US/West Coast/*"))}
NOTE: Don’t forget to apply whatever mail flow controls normally used for DDGs on-premises in EXO. I.E. should everyone be able to email every newly created DDG?
You can also preview your DDG group membership to make sure it is targeting everything you think it should be:
Get-Recipient -RecipientPreviewFilter (Get-DynamicDistributionGroup "East Coast Users DDG").RecipientFilter
While this post has been focused on using this solution to organize objects in EXO, there is nothing preventing the creation of multi-OU/domain structure based DDGs in the on-premises Exchange environment. It might even make sense to do so if you create duplicate/redundant DDGs on both sides, so they will always dynamically expand the resources the exact same way.
Closing Thoughts
I’m sure as others discover and test this code they will have feedback and other ideas, so if you start to use this code consider checking back occasionally to see what changes to the code are made as I will update this blog post over time.
Please feel free to leave me comments here if you wish, I promise I will try to respond to each in kind.
Thanks!
Dan Sheehan
Senior Customer Engineer