Managing Azure AD Administrative Units via the Graph API

While browsing the Graph API documentation earlier today, I spotted a new addition to the \beta APIs – endpoints to manage Azure AD administrative units. For those of you that aren’t aware of AUs, here’s the one-minute version: AUs are “containers” for user and group objects, which you can then use in order to delegate someone control over said objects. For example, you can delegate permissions for Admin1 to manage all objects inside AU1.

Simple. And very limited. And overlooked for years. AUs first appeared in 2015, and I covered them in this article. Nothing changed for few years, until 2018 when Microsoft finally added support for AUs for the Office 365 Admin Center, as detailed in this article. Now, we get to manage those via the Graph API as well, which hopefully means AUs will finally get some love and be made more useful, or maybe even better – we might get full-fledged RBAC controls for Azure AD.

Anyway, to the subject at hand. You can use the /beta/administrativeUnits endpoint to list all AUs created in the tenant. To get the properties of a specific AU, use the /beta/administrativeUnits/{id} one, as shown below:

Graph explorer exampleLooking at the output, we can spot a new property listed, namely visibility. This property is not available via the MSOnline AU cmdlets, nor the Azure AD ones, and serves to limit visibility of the AU members. Here’s the description straight from the documentation:

Controls whether the adminstrative unit and its members are hidden or public. Can be set to HiddenMembership or Public. If not set, default behavior is Public. When set to HiddenMembership, only members of the administrative unit can list other members of the adminstrative unit.

To test this new property, we will create a new AU, using the Graph API explorer. In order to do so however, we first need to make sure permission requirements are met, meaning add the Directory.AccessAsUser.All scope (alternatively you can use the AdministrativeUnit.ReadWrite.All scope, but that’s not available for selection in the Graph explorer, so you will have to add it by other methods). Once we have sufficient permissions, we can execute the request:

Graph explorer exampleAfter running the request, I noticed I made a small typo in the description field, which we can easily remedy with a PATCH operation. Next, we want to add some members to the AU, which unfortunately can be done one object at a time only. This is done by calling the corresponding /beta/administrativeUnits/18560689-d221-4f88-a713-17e973cf6498/members/$ref endpoint.

Once we have added a member to this AU, we can explore how the visibility setting is affecting it. If we try to list the members of this AU with a Global admin account, we can still see all its members, which I’d wager is the expected behavior. If we use a scoped-role user, such as the ones you’d assign to manage other AUs, the membership will return empty. This is illustrated on the screenshot below, where the first user cannot see members of the AU, while my GA account can see members of the same AU just fine:

AUGraph3Other than that, managing AUs remains pretty much the same. We still can only assign either the User account administrator or the Helpdesk administrator roles, so not much flexibility there. Still no way to dynamically add members, and as mentioned above you can only add them one at a time.

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.