Azure AD Role Activation

I’ve been trying to start using one of the many directory roles which Microsoft has defined for Azure AD. See for the primary documentation on Azure AD roles.

If you’ve looked at Azure AD directory roles, you know that there are some roles which are immediately usable and others for which you have to do something to “turn them on.” I got stuck at the point of turning one on, and I figured an information post about this would be useful to others.

Behind the scenes there are two AAD objects in play. There is the DirectoryRole—which are all the roles that are usable in your tenant. And then there is the DirectoryRoleTemplate—which are all the roles which might be usable in your tenant. You “activate” a template to create a role object, which is effectively “turning it on”. I wrote a detailed blog post about this several months ago at: if you want to learn more, but for the purposes of this post, you don’t need to know what’s in that other post.

From what I’ve been able to determine, there are three ways to turn these things on (listed in order I think they were available):

  1. MSOnline PowerShell module, via Add-MsolRoleMember,
  2. Azure AD Graph API, via REST call documented at
  3. AzureAD PowerShell module, via Enable-AzureADDirectoryRole cmdlet, documented

I also suspect that there may be ways to silently activate a role via one of the GUI admin consoles, but I have not extensively explored this.

Speaking of silent activation, I think that’s what option #1 does—you don’t have to know anything about DirectoryRoles, DirectoryTemplates, or even be aware there is an activation. But since that module is “old”, I’ve been purposely avoiding it, and I have to believe that’s what at least some others are doing.

Option #2 is likely not an option that many try. But I happen to like the Azure AD Graph Explorer because I find I can get more low-level details from it than any other AAD tool, so this is an option I tried. However, the documentation referenced is pretty opaque to me, with a recommended call that didn’t even include the required parameter—which I have to guess is because the documentation is incomplete. I couldn’t find a way to make it work, even by adding in the required parameter and the objectId of the DirectoryRoleTemplate I wanted to activate. I’m left wondering what the right incantation is to get this option to work.

Option #3 is where I started because I’ve come to like the AzureAD module. And I followed the example in the documentation ending up with the error message:

Enable-AzureADDirectoryRole : A parameter cannot be found that matches parameter name 'DirectoryRole'.

This drove me batty for a while, especially since it is a required parameter.

Eventually, I realized that the example listed is for a prior version of the AzureAD module, and they made major changes to the parameters. This issue was masked by two things:

  • the example in the documentation is completely incorrect for the current version—it must be based on a prior version
  • the help for this cmdlet is also incorrect, and not just the example but all of the help is incorrect

Making major changes to the parameters, especially when you drop the only required parameter, and not updating the documentation is bad, and that’s what seems to have happened here.

The good news is that the steps required, which used to include instantiating a special object to pass into the cmdlet, are much less complicated. From a high-level, you grab the objectId of the DirectoryRoleTemplate you want to activate, then pass that into the cmdlet as a string. So the example *should* read this:

$InviterRole = Get-AzureADDirectoryRoleTemplate | Where-Object {$_.DisplayName -eq "Guest Inviter"}



ObjectId                             DisplayName   Description

--------                             -----------   -----------

95e79109-95c0-4d8e-aee3-d01accf2d47b Guest Inviter Guest Inviter has access to invite guest users.


Enable-AzureADDirectoryRole -RoleTemplateId $InviterRole.ObjectId


ObjectId                             DisplayName   Description

--------                             -----------   -----------

03618579-3c16-4765-9539-86d9163ee3d9 Guest Inviter Guest Inviter has access to invite guest users.

I hope this helps save someone else time. And I hope Microsoft takes note of the mess here and the places they might improve the documentation to help others in the future.

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.


Get-ADGroupMember and ADWS parameter MaxGroupOrMemberEntries

By default, ADWS restricts several of the AD PowerShell cmdlets, like Get-ADGroupMember, to returning a mere 5,000 member entries. Which is annoying when you have larger groups, like we do.  Back in July 2015, we were pondering bumping up that limit, as described here:, but couldn’t find othe4rs who had made this change.

I ran into this annoying limitation again recently, and after a bit of fresh research found, as someone who actually did make the limit change and had specific syntax to make the change, although there is no real report on impact.

I went ahead and changed this ADWS limit to 200,000 on one of our DCs and re-ran my PS script against that DC. One of many large groups had a timeout (as might occasionally be expected due to other load), but otherwise there was no significant impact (to the DC) and I didn’t have to use the awkward & annoying workarounds of:

$members = Get-ADGroup <groupname> -properties Member | select-object -expandproperty member


(Get-ADGroup <groupname> -properties members).members | Get-ADUser -properties samAccountName | Select-Object samAccountName


$group =[adsi]”LDAP://CN=Group1,OU=Groups,DC=msad”

$members = $group.psbase.invoke("Members") | foreach {$_.GetType().InvokeMember("name",'GetProperty',$null,$_,$null)}


As a domain which has large groups, we seem to run into quite a few Microsoft design constraints, and after trying this in a large AD at 40 times the existing limit, I’m not sure I really understand why Microsoft chose such a low number, although I guess it is because of customers which run DCs on underpowered hardware.

Managing Azure AD Applications

About 10 months ago, it came to my attention that there was a fundamental problem related to Azure AD and applications.

This was a surprise to me–I had cheered on the product team manifesto that applications were first-class citizens in Azure AD.

Since then, I’ve been on a journey of discovery and advocacy. My journey eventually led me to talking with several PMs on the Azure AD product team.

I’ve learned that there is a lot about Azure AD applications and the AAD settings governing them that is poorly documented. I’ve encouraged the product team to fill the documentation gap, and amend the design to provide the right access controls. That journey still continues, and I’m here now to share what I know.

First, I’ll call your attention to the published documentation and relevant links related to the topic of AAD and applications.

The Application object vs. ServicePrincipal document is important in that provides some key understanding if you want to go about identifying all the applications in your AAD tenant. You won’t find all of your AAD applications in *any* of the GUI interfaces, such as the Azure Management Portal or the AAD Access Panel. This omission of some AAD applications in the GUI interfaces is unfortunate because it makes it harder to understand what’s really going on specific to your tenant. You can use the MSOnline Powershell module or the AAD Graph API to discover all of your AAD applications.

The Consent framework document is useful, but it’s one of the documents which is flawed in my opinion–it is incredibly misleading about reality. The reality is that only a fraction of your AAD apps allow user consent–all the others *assume* that the user consent is unnecessary. To my way of thinking, this is a significant design flaw, and the documentation isn’t doing anyone favors by not pointing out that not all apps are subject to user consent.

This brings me to the heart of the new information I have to share. The first link above likely isn’t known to you–it reveals some behind-the-scenes details that aren’t revealed elsewhere, and documents published in that platform are harder to find for some reason. Note that every AAD application has a “home” tenant. Some are enabled for multiple tenancy and some aren’t.

Note that some applications are “curated” by Microsoft–these are the pre-integrated applications in the Azure AD App Gallery. These pre-integrated applications live in a special tenant that Microsoft owns/runs.

Note that there are some applications “owned” by Microsoft–these are applications like Sharepoint Online. It turns out that these applications are “special” in that they are automatically deployed to *every* AAD tenant without any explicit acceptance on your part.

And then there are the applications that anyone might create/develop. These applications fall into two sub-categories:

  • Those that are only in your tenant–one of your users adds them. Microsoft sometimes uses the code words “line of business” apps to refer to these.
  • Those which live in some other tenant and have been added to work with your tenant. Microsoft has two different nicknames for these: consented apps or multi-tenant apps.

It turns out that the only type of AAD app which permits user consent are that sub-category with the consented app nickname.

Down below is a handy reference table I put together while interacting with the AAD PMs that own each of these different AAD app categories that includes all of these details.

Moving beyond the documentation gap and the user consent design flaw, there are several other fundamental problems.

One problem I implied above–that Microsoft can deploy applications to your tenant without notice or consent. I think this assumption on Microsoft’s part is very problematic and I’d encourage them to rethink it and provide enterprise controls for each app they would like to deploy. This is problematic because it violates the design principle that we own our Azure properties. I do not want Bing for Business published to my users–or the latest app that Microsoft has created but which has no HIPAA and BAA agreement. Putting such an application in front of my users will lead to regulatory problems, and is a significant deal breaker. Microsoft’s hubris in thinking they know my environment or that they can use a captive audience to instantly gain market share for their latest creation is ultimately not good for their long-term business relationship with their customer. They need to provide a control here.

Another is in the lack of controls Microsoft has provided around application permissions. OAuth is really cool–it is the protocol Microsoft has adopted that allows one application to be given permissions to another. But Microsoft hasn’t provided the right controls to manage these permissions. Here’s how things work: a developer somewhere writes an application. That developer decides which application permissions their application needs. That developer publishes their application so it is multiple tenant aware. Someone in your tenant comes along and decides to add that application. In the current state, that decision to add the application is an acceptance that the application permissions are acceptable. For many of the types of AAD applications, the person adding the application has no understanding of the implications nor responsibility in your organization for the consequences. A better design would involve a workflow where individuals with specific roles had to approve any application that asked for certain application permissions. Global admins should be required to approve any application that requires the ability to query AAD. Exchange Online admins should be required to approve any application that requires the ability to query Exchange Online. And so on. In the absence of this kind of design, Microsoft needs a stop-gap where it notifies global admins that an application has been added which grants permissions to high-value and high-risk applications like AAD and the set of O365 applications.

Another problem in this area is the poor presentation and documentation specific to the AAD tenant application settings. The Configure tab in the AAD section of the Azure Management Portal has two settings under an “integrated applications” heading.


The names of these settings imply something very different from reality. If you set the first one to yes, you’d think that users can consent to all applications now. And if you set the second one to no, you’d think that no users can add applications. In both cases, you’d be wrong. What’s worse is that if you try to educate yourself by following the help link for these settings, you are sent to a useless AAD product “marketing” page which doesn’t tell you anything about Azure AD applications at all. Of course, there is no Microsoft documentation which informs you that what these settings claim to do isn’t really possible.

To the best of my knowledge, here is what those two settings really mean:

Users may give applications permission to access their data

If the AAD app is a multi-tenant application which is neither a Microsoft nor AAD App Gallery application, then user consent to access their data is possible with that application . The data might be in any number of other AAD applications, including Azure AD itself.

Note that some applications have no user consent or explicit admin consent whatsoever.

Users may add integrated applications

If this setting is yes, then any user in your tenant can add a developed application whether it is a consented/multi-tenant application or a “line of business”/single tenant application. If this setting is no, then only global admins can add these kinds of applications.

Note that if users can add applications, there is no enterprise controls for which data a given application can access. The only control in this case is the user.

A Reference Table for different types of Azure AD Applications

Here’s a handy reference table for keeping things straight: