Activate your Azure AD PIM roles with PowerShell

Daniel Chronlund Azure AD, Cloud, Microsoft, PowerShell, Security September 17, 2021September 23, 2021 2 Minutes

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

Published by Daniel Chronlund

Daniel is an IT consultant at Altitude 365, specialized in Microsoft cloud infrastructure design and implementation. Daniel provides consultative services around Azure IaaS and PaaS services, Microsoft 365, EM+S and Office 365. He helps customers to work smarter, more secure and to get the most value out of the Microsoft cloud. View all posts by Daniel Chronlund

Published September 17, 2021September 23, 2021

25 thoughts on “Activate your Azure AD PIM roles with PowerShell”

Anonymous says:

October 13, 2021 at 14:43

fantastic script is it possible to add in the ticket number into the script?
Daniel Chronlund says:

October 15, 2021 at 12:50

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.”
Derek says:

January 7, 2022 at 12:08

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
OpenAzureADMSPrivilegedRoleAssignmentRequest
Code: InvalidScope
Message: The resource scope is not valid.
InnerError:
RequestId:
DateTimeStamp:
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
nAzureADMSPrivilegedRoleAssignmentRequest
Role Scope Membership End time Action
Authentication Administrator (Administrative unit) Direct Permanent Activate
Daniel Chronlund says:

January 7, 2022 at 14:24

Thanks! I will look into that!
Jeff says:

January 19, 2022 at 19:07

Wow what a time saver this script has been!! Thank you for the share.

I have one question. Once I activate a PIM Profile is there a way to NOT reactivate it ? I looked into your script and it seems to be already in there. if ($Role.AssignmentState -eq ‘Active’) is never true here all I have in the AssignmentState is the Eligible one .

Thank you again for the script.
Jeff says:

January 19, 2022 at 22:10

My first comment got deleted I think. So here goes. Your script is a real time saver. Thank you. Can you tell me why I never get a message saying that my PIM is already activated. All I get is the Eligible ones. Thank you
Minhaj Ahmed says:

January 30, 2022 at 16:30

HI Daniel,
Nice script. Can you please add the date and time if we want to put for activation in advance dates so that it is approved and get activated on future date and time.
SteiniMinni says:

March 14, 2022 at 12:51

Hi,

i love your Script. But i wonder if it is Possible to Deactivate PIM Roles the same way again. For normal Roles i let them time Out but for Higher Privileges like Sec Admin it would be great to Deactivate them after your Work.
I’ve tried Running “Close-AzureADMSPrivilegedRoleAssignmentRequest” but it gets always an Error back. So that cant be the right Command but I dind’t find anything else…
Appreciate xour work!
Daniel Chronlund says:

March 21, 2022 at 09:12

Hi Jeff! That’s how PIM works. It’s the same in the GUI. You can activate already activated roles to extend its activation time. I see no point in removing this behaviour. But if I understand your question, you would like to see in my PowerShell tool if a role has been activated already. I will look into that.
steiniminni says:

March 21, 2022 at 09:19

Hi Daniel,
I love your Script and I’m using it everyday.
But do you think it is Possible to end An PIM assignemt via Powershell? I think fpr High Priveleged Roles (Global Admin/Sec Reader etc) it would be nice to end them after the Specific task you needed them for.

Have a nice day and keep up the lovely Scripts!
Daniel Chronlund says:

March 21, 2022 at 09:20

Thanks! I might build a tool for that in the future. It’s not on the list now though.
Daniel Chronlund says:

March 21, 2022 at 09:22

Thank you! It is possible but I haven’t built such a tool yet.
Jack says:

March 25, 2022 at 16:12

Daniel,
Great article. We have privileged access group. Do you know if there is a way to activate privilege access groups through PowerShell?

Thanks,
Jack
Anonymous says:

May 21, 2022 at 18:01

Thanks for putting this together. Unfortunately, I am having some issues — I ran through both the admin and non-admin instructions and still receive an error indicating I need to install AzureADPreview. Not sure what I am missing,. FYSA, doing this via a Mac. Much appreciated!

PS /Users/xxxx> Install-Module -Name DCToolbox -Force
PS /Users/xxxx> Install-Module -Name AzureADPreview -Force
PS /Users/xxxx> Install-Package msal.ps -Force

Name Version Source Summary
—- ——- —— ——-
MSAL.PS 4.37.0.0 PSGallery The MSAL.PS PowerShell module wraps MSAL.NET functionality into Powe…

PS /Users/xxxx> Enable-DCAzureADPIMRole
Enable-DCAzureADPIMRole: The Azure AD Preview PowerShell module is not installed. Please, run ‘Install-Module AzureADPreview -Force’ as an admin and try again.
Dirk Rober says:

June 2, 2022 at 07:19

Nice tool, but it would be nice to specify a explicit TimeAllowed. Now it seems that you can only automate with UseMaxiumTimeAllowed. Or am I missing something?
Austin P says:

July 7, 2022 at 23:01

I am getting the same error message as Derek in the comments above. Have you looked into adding support for scoped access?

”
OpenAzureADMSPrivilegedRoleAssignmentRequest
Code: InvalidScope
Message: The resource scope is not valid.
“
pbollwerk says:

July 7, 2022 at 23:33

Hello Daniel,
I tried the script, but it said “Found no eligible PIM roles to activate”
In the portal, I go to PIM -> My roles -> Azure Resources -> ‘Contributor’
The ‘Contributor’ I’m activating is in the ‘Tenant Root Group’ resource.
Perhaps your module only works with “Azure AD roles” and not “Azure Resources” ?
I’m not sure what to do.
Santosh Ramachandra says:

September 9, 2022 at 18:34

Hello Daniel,

this is a wonderful script, it works flawlessly, but in an MFA environment, i get the below error. is there an updated script/module that I can use sir?

PS C:\Users\a79270>09-09-22 09:59:26> Enable-DCAzureADPIMRole -RolesToActivate ‘Teams Administrator’ -UseMaxiumTimeAllowed -Reason ‘Performing some Exchange security coniguration according to change #12345.’

*** Activate PIM Role ***

Roles to activate:

Teams Administrator

VERBOSE: Activating PIM role ‘Teams Administrator’…
Open-AzureADMSPrivilegedRoleAssignmentRequest : Error occurred while executing OpenAzureADMSPrivilegedRoleAssignmentRequest
Code: RoleAssignmentRequestPolicyValidationFailed
Message: The following policy rules failed: [“MfaRule”]
sankarasubramanian parameswaran says:

October 20, 2022 at 13:24

Hi this is not working if we have MFA enabled for PIM
Jordan Jones says:

December 2, 2022 at 14:50

In the last script you misspelt -UseMaxiumTimeAllowed should be -UseMaximumTimeAllowed
caught me out at first
Daniel Chronlund says:

January 25, 2023 at 13:58

Thanks! No, that is not part of the API yet.
Daniel Chronlund says:

January 25, 2023 at 14:02

I’ve not tested this on Mac so maybe it doesn’t work the same way. Do you still have issues?
Daniel Chronlund says:

January 25, 2023 at 14:04

Run it without the parameter and it will ask you for a custom time of your choice.
Daniel Chronlund says:

January 25, 2023 at 14:10

It currently only supports Azure AD roles, yes.
Daniel Chronlund says:

January 25, 2023 at 14:20

It does work with MFA. Try a different PowerShell version.