First look at Administrative Units for Office 365 and WAAD management

The Administrative Units feature was first announced last month, over at the AD Team Blog.​ In a nutshell, it allows you to group WAAD objects in containers, called Administrative Units, so that you can later delegate access to specific person to perform administrative tasks on said users. This has been easily one of the most requested features ever since Office 365 was launched, and the team has finally delivered the first step. As this is a Public Preview however, there are certain limitations you should be aware of. For example, only user objects can be added to AUs at this time, and you can only assign “User administrator” or “Password administrator” permissions. Another important limitation is that they are only manageable from the WAAD PowerShell module at this time, with support for the Azure Portal coming soon. This includes not only managing the actual AU, but performing administrative tasks as the person that has been granted access via AU scoped role!

So how do we create and use an AU? First of all, you need the 1.0.8262.2 version of the WAAD PowerShell module, which you can get from here. Then, you need Azure AD Premium! Bummer yes, but you can get the free trial. Although the cmdlets will be still available if you don’t have Azure AD Premium active, you will run into an “Access Denied. You do not have permissions to call this cmdlet.” error once you try to run any of them. Lastly, you need to be a Global Administrator for the Office 365 tenant, which of course makes perfect sense. Now, off to creating the first AU.

If you have read the blog article above, you have already seen that all it takes is few lines of PowerShell code. Indeed, there total of 10 PowerShell cmdlets around AUs available today, and you can get the detailed documentation on them here. To create a new AU, you can use the New-MsolAdministrativeUnit cmdlet. Even without providing any parameters! Strange, eh? Well, all the cmdlet does is to create a new container, to which you can later add the user objects. Display name and Description are optional, but of course highly recommended if you actually intend to use the functionality. So, here’s my first AU:

PS C:\> New-MsolAdministrativeUnit

ExtensionData                                Description                                  DisplayName                                  ObjectId
-------------                                -----------                                  -----------                                  --------
System.Runtime.Serialization.ExtensionDat...                                                                                           6ee4baa4-f864-4467-9cd2-f0832a323546

As I forgot to label it appropriately, I then used the Set-MsolAdministrativeUnit cmdlet to put a proper description on it:

PS C:\> Set-MsolAdministrativeUnit -ObjectId 6ee4baa4-f864-4467-9cd2-f0832a323546 -Description "Includes all users with AAD Premium license"

It’s probably worth mentioning that the AU related cmdlets don’t have any user-friendly parameters, so be prepared to use long PowerShell cmdlets with parameter names such as AdministrativeUnitObjectId. Anyway, now that we have actually created the first container (AU), let’s add some users into it! We can use as filter any of the parameters returned by the Get-MsolUser cmdlet, or add users based on random criteria one by one or via CSV file. In my case, I decided to pick up all the users that had *only* the “Azure AD Premium” license applied:

PS C:\> $testAUusers = Get-MsolUser | ? {$_.Licenses.AccountSKUId -eq "michev:AAD_PREMIUM" -and $_.Licenses.count -eq "1"}

Then, to add those users to the already created AU, we use the Add-MsolAdministrativeUnitMember cmdlet:

PS C:\> $testAUusers | % { Add-MsolAdministrativeUnitMember -AdministrativeUnitObjectId 6ee4baa4-f864-4467-9cd2-f0832a323546 -AdministrativeUnitMemberObjectId $_.ObjectId }

As simple as that. Now we have an AU and a list of users added to it:

PS C:\> Get-MsolAdministrativeUnitMember -AdministrativeUnitObjectId 6ee4baa4-f864-4467-9cd2-f0832a323546

ExtensionData                                DisplayName                                  EmailAddress                                 ObjectId
-------------                                -----------                                  ------------                                 --------
System.Runtime.Serialization.ExtensionDat... Bathroom                                     bathroom@michev.info                         edf96cf3-8037-43a3-9e4a-795675bea83e
System.Runtime.Serialization.ExtensionDat... HuKu                                         huku@michev.info                             ea545873-c904-47cd-8b6e-567dfed9374a
... ... ... ...

All that’s left is to grant someone the administrative privileges to manage those users. This in turn is done with the Add-MsolScopedRoleMember cmdlet. Some clarification is probably needed here. What you are creating is a “copy” of a normal MSOL role, which will only apply to the users in the AU scope. The only two roles supported at the moment are the “User Account Administrator” one and the “Password Administrator” one. The parameters we need are the Object IDs of the AU, the Object ID of said MSOL Role and the object ID or UPN of the user. In this case, I’ve chosen the “User Account Administrator” (you can get the object ID via Get-MsolRole). Here’s the full cmdlet:

PS C:\> Add-MsolScopedRoleMember -RoleObjectId fe930be7-5e62-47db-91af-98c3a49a38b1 -AdministrativeUnitObjectId 6ee4baa4-f864-4467-9cd2-f0832a323546 -RoleMemberUserPrincipalName huku@michev.info

And here’s the confirmation:

PS C:\> Get-MsolScopedRoleMember -RoleObjectId fe930be7-5e62-47db-91af-98c3a49a38b1

ExtensionData              : System.Runtime.Serialization.ExtensionDataObject
AdministrativeUnitObjectId : 6ee4baa4-f864-4467-9cd2-f0832a323546
DisplayName                : HuKu
ObjectId                   : ea545873-c904-47cd-8b6e-567dfed9374a
RoleMemberType             : User
UserPrincipalName          : huku@michev.info

All done, let’s go test it! Well, there’s a gotcha. Remember that remark I made in the beginning about management currently possible only via PowerShell? The user that has been granted permission *must* also use PowerShell. If logging to the Office 365 portal, he will NOT have access to the admin console (unless he has been granted ‘unscoped’ role, but we are trying to avoid just that!). This is important limitation, but surely will be lifted in the coming months. Now, when you login to WAAD using PowerShell, all works as expected. The cmdlets will all be there (remember that you are using a module installed on the local machine, not remote session with cmdlets stripped down by RBAC), but trying to use any ‘company’ related one will result error. For example:

PS C:\> Set-MsolCompanySecurityComplianceContactInformation -SecurityComplianceNotificationEmails vasil@michev.info

Set-MsolCompanySecurityComplianceContactInformation : Access Denied. You do not have permissions to call this cmdlet.

Yes, new cmdlet, very long name, had to test it! 🙂

Same error will popup if you try to edit the settings on a user not included in the AU scope. For users included in the scope however, everything will run as expected. Changing names, passwords, license information, UPN, ImmutableID – all possible, provided you have been granted the necessary rights.

Two more gotcha’s though: first, the scoped roles/AUs are NOT dynamic. That is, they are not based on updateable criteria (such as user attribute X equals Y). They are managed manually and you need to make sure that the user is added/removed to/from the relevant AUs when attributes change! Second, determining what roles a user has is now a bit harder. You have to remember to check for scoped role members against every ‘normal’ role, as the Get-MsolUserRole cmdlet will NOT return the scoped ones. Instead, you will have to use the Get-MsolScopedRoleMember cmdlet, and leave feedback for the team to improve on that! OK, and a third one: unscoped roles have precedence over scoped ones. So if you wonder why the newly created AU and scoped role doesn’t seem to work as expected, remember to check if you have removed the scoped role from the user!

This entry was posted in Azure AD, Office 365, PowerShell. Bookmark the permalink.

Leave a Reply

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