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 msal.ps -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 msal.ps -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 msal.ps 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.
Connect-AzureAD

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.
Enable-DCAzureADPIMRole

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!

@DanielChronlund