Azure AD Roles

I’ve been exploring AAD roles, but there’s a lot left unexplained by Microsoft. This is a bit of discovery, via stream of consciousness which hopefully will be helpful to others.

The general task I’m looking at is finding out all possible AAD roles and the membership of each. This task is not as straightforward as it seems. For one, the various interfaces to AAD don’t agree on what the AAD roles are. None of the GUI interfaces give you a way to discover who is in a role. When I run into ‘can’t do that with the GUI’, I generally turn to Graph because then I get full details. Yes, there are ways to approach this with PowerShell, but I note that it also doesn’t list a couple of the possible roles.

Via Graph, there are role template objects and role objects. You can find out the members of a given role by querying graph ( However, I note that in Graph, there is not alignment between the role objects and the superset of roles listed in the GUI interfaces (nor with a list presented to MVPs as ‘recently released’). The missing role objects are present as role template objects (and even the list of “roles coming soon” are present as role template objects).

This left me wondering … how do those role objects get created? Is my tenant out of expected state because some Microsoft task failed or hasn’t reached my tenant yet? Or is there a ‘just in time’ provisioning of role objects when the first user is assigned to them? Or is there some step a tenant is expected to do to activate a role?

Aha. I partially see now. Graph documentation says that I have to activate directory roles from newly added templates.

However, the general documentation about roles doesn’t mention this, whereas the developer documentation for Graph does … this makes me wonder if it might be both of the possibilities I mentioned. In other words, if you are using graph to do role assignment you must manually activate roles, but if you are using the GUI interfaces or PowerShell cmdlets, it silently does that for you via a just-in-time creation of the role object. Is that accurate?

I also wonder what controls which roles are present in each of the various interface’s experience—heck, let’s get really specific and talk specifically about the new Azure portal. Why does the new Azure portal not list every possible role in my tenant?

I wonder about these role templates which are present in my tenant Microsoft told MVPs aren’t yet released. What happens if I activate one of them now? If there is a downside to doing that, how is a tenant admin expected to know that a given role template isn’t ready?

I got around to testing the AzureAD PS module. When you combine the two cmdlets it provides, it returns more roles than the MSOnline module. Its approach follows the AAD Graph object types.

The MSOnline PS module seems to return roles which are both a role object and a role template object, minus a couple. 🙁

The AzureAD PS module cmdlets returns the AAD objects they are named for. So get-azureAdDirectoryRole returns only roles which are a role object, and get-azureAdDirectoryRoleTemplate returns role template objects.

The output of get-azureAdDirectoryRoleTemplate does not match the output of the MSOnline get-msolrole. The difference is that get-azureAdDirectoryRoleTemplate has a couple additional roles:

  • Mailbox Administrator
  • User
  • Email Verified User Creator
  • Adhoc License Administrator

This gives me greater confidence in the AzureAD PS module than the MSOnline PS module.

Lacking verification from Microsoft, I think my hypothesis that some of the tools do just-in-time activation of role templates (i.e. create a role object based on the template) and some require you to do that yourself seems to fit what I can see. I’m still left wondering what happens if you activate a role template that Microsoft has added to your tenant but not said was “released”.


Gaps I see that Microsoft might want to address:

  • *Should* document that some roles can only be provisioned via some tools
  • *Should* be more accessible listing of all the possible roles—the fact that you have to use either Graph or a non-GA PS module to get that info comprehensively is not a good state of affairs
  • Might want to talk more about role activation in IT Pro documentation
  • Depending on whether some role templates that are deployed are dangerous or not, there should be some definitive list of released roles, or an attribute on the role template that says whether it is usable, or even something at the Graph layer that blocks certain templates from being activated until they are ready. I haven’t dived very deep on this topic, so there is some ambiguity on this that I might explore further by trying to activate some of those roles that aren’t yet “released”.
  • Deeper documentation on role assignments.
  • What objects can be assigned? I see users and servicePrincipals, and I think I heard that groups can be assigned. What else? Put it in the documentation.
  • Sub-delegation of roles. When a servicePrincipal is a role holder there is some ambiguity about who has the permissions associated with that role. For example, the ‘Office 365 Service Trust Portal’ is a “Directory Writer’ in any tenant with O365 in it. I presume that some of the roles defined by that AAD application  sub-delegate some portions of the ‘Directory Writer’ role out. The point here is calling attention to the fact that when a servicePrincipal has a role, you are extending some trust to users of that AAD app. Documentation should call this out.

Note: A specific example that I’m worried about is the ‘Microsoft Power BI Information Service’ servicePrincipal having been added as a Global Admin (I presume by Microsoft). That seems like an extreme amount of permissions and assuming Microsoft added it is a bit of a violation of Azure first principles (you own your own tenant). I haven’t dug into that one via the Audit API to find out who/when it was added, but it is on my list to investigate further.


Leave a Reply

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