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.

Leave a Reply

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