Activate your Azure AD PIM roles with PowerShell

In the age of Zero Trust and highly sophisticated cyber attacks, you need to protect all privileged roles! In Microsoft 365 this is relatively easy but it can be daunting for the people eligible to use such roles to manage and activate them. This is my contribution to all M365 admins out there to make your work life a little bit easier.

Azure AD Privileged Identity Management (PIM) has been around for many years now. It has slowly grown in popularity and Microsoft is making it better and better. In the beginning it was slow and unpredictable but it is now a central part in any Microsoft 365 customers zero-trust journey where it helps to implement JIT/JEA for admin roles.

In my DCToolbox PowerShell module I’ve included a tool called Enable-DCAzureADPIMRole for some time. I recently released a new version with some highly requested features. This article will explain how you can activate your Azure AD roles in PIM with PowerShell, multiple roles at once, and more or less fully automated (except for authentication and MFA of course).

This image shows a screenshot from VS Code with the tool in action. I’ll explain it further down.

First you need to install DCToolbox from the PowerShell Gallery by running Install-Module. There are also two dependencies for Enable-DCAzureADPIMRole. Run one of the following installation snippets:

# Install required modules (if you are local admin) (only needed first time).
Install-Module -Name DCToolbox -Force
Install-Module -Name AzureADPreview -Force
Install-Package -AcceptLicense -Force

# Install required modules as curren user (if you're not local admin) (only needed first time).
Install-Module -Name DCToolbox -Scope CurrentUser -Force
Install-Module -Name AzureADPreview -Scope CurrentUser -Force
Install-Package -AcceptLicense -Force

The first one is for users with local admin permissions on their workstation, the second one are for users with non-admin permissions.

In some highly locked-down environments I’ve seen the package fail complaining on dependencies. If you get any error messages you can connect with Connect-AzureAD instead before running Enable-DCAzureADPIM. However, if you don’t, Enable-DCAzureADPIM will prompt for credentials automatically.

# If you want to, you can run Connect-AzureAD before running Enable-DCAzureADPIMRole, but you don't have to.

Finally, it’s time for some action! You could just simply run the command as is to interactively select a role and input activation time and reason.

# Enable one of your Azure AD PIM roles.

Or you could do the same but with multiple selected roles via the -RolesToActivate parameter. This is great for times when you need multiple roles to complete your job.

Note: This is not the same as using Privileged Access groups in PIM. Privileged Access groups are created and managed by PIM-administrators where they try to group multiple Azure AD roles to a specific work role in the organisation, for example, a service desk role. This is a great practice of course but Enable-DCAzureADPIMRole helps M365 admins where no such groups are available, or where they need to activate less roles than what’s in an Privileged Access group. They complement each other.

# Enable multiple Azure AD PIM roles.
Enable-DCAzureADPIMRole -RolesToActivate 'Exchange Administrator', 'Security Reader'

Finally you can use this tool to fully automate the role activation by specifying -Reason and -UseMaximumTimeAllowed. This can be helpful for planned changes where you need many roles and where you need to activate the same roles multiple times during the change because of activation time limits.

# Fully automate Azure AD PIM role activation.
Enable-DCAzureADPIMRole -RolesToActivate 'Exchange Administrator', 'Security Reader' -UseMaxiumTimeAllowed -Reason 'Performing some Exchange security coniguration according to change #12345.'

I hope that this tool will help all M365 admins out there. It sure has helped me!

Please follow me here, on LinkedIn and on Twitter!


4 thoughts on “Activate your Azure AD PIM roles with PowerShell

  1. Thank you! I’m afraid that is not possible right now. From Microsoft documentation: “If you require ticket system / ticket number in your role setting, there is no way to supply those as a parameter. Thus, it would not be possible to activate the role beyond the Azure portal. This feature is being rolled out to PowerShell over the next few months.”

  2. Daniel, excellent work. Manual PIM activation is cumbersome at best. Is it feasible to add support for scoped access?
    VERBOSE: Activating PIM role ‘Authentication Administrator’…
    Open-AzureADMSPrivilegedRoleAssignmentRequest : Error occurred while executing
    Code: InvalidScope
    Message: The resource scope is not valid.
    HttpStatusCode: BadRequest
    HttpStatusDescription: Bad Request
    HttpResponseStatus: Completed
    At C:\Program Files\WindowsPowerShell\Modules\DCToolbox\1.0.24\DCToolbox.psm1:1481 char:13
    + Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Open-AzureADMSP…signmentRequest], ApiException
    + FullyQualifiedErrorId : Microsoft.Open.MSGraphBeta.Client.ApiException,Microsoft.Open.MSGraphBeta.PowerShell.Ope
    Role Scope Membership End time Action
    Authentication Administrator  (Administrative unit) Direct Permanent Activate

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s