Getting started with Azure AD PIM PowerShell Module

This is a short blog post showing how you can get started and some examples of using the PIM PowerShell Module for Azure AD Privileged Identity Management.

You can read more about Azure AD Privileged Identity Management here:, or by just using the following short URL:!

Installing the Azure AD PIM PowerShell Module

Since there are no PIM related commands in the AzureAD or AzureADPreview PowerShell Modules, we will have to install a separate module for PIM. You can find this module at the PowerShell Gallery here:

To install the module just run the following command in an elevated PowerShell session:

Install-Module Microsoft.Azure.ActiveDirectory.PIM.PSModule


After installing you can list the available commands in the PIM module:

Get-Command -Module Microsoft.Azure.ActiveDirectory.PIM.PSModule


Here is a short explanation of the available commands:

  • Connect-PimService. Prompts you to log on with an Azure AD Account that might have any PIM roles assigned. You can optionally specify a username, tenantname or credential object as parameters. Especially tenantname would be useful if you are a guest user with roles assigned in another tenant.
  • Show-PimServiceConnection. This will show the active PimService session details you have, after connecting with Connect-PimService.
  • Get-PrivilegedRoleAssignment. This would list any permanent or eligible role assignments the user you connected with using Connect-PimService has.
  • Enable-PrivilegedRoleAssignment. This command will enable a specified role assignments. It is required to specify which role either by RoleId or by a RoleAssignment variable. It is also required to specify a Duration for activation. Optional parameters includes Reason, TicketNumber, TicketSystem and StartTimeUtc.
  • Disable-PrivilegedRoleAssignment. If you previously have activated one or more roles with Enable-PrivilegedRoleAssignement, you can preemptively deactivate these roles again before the duration expires. You must specify a RoleId or RoleAssignment variable.
  • Disconnect-PimService. Disconnects any previous sessions to PimService.

Examples of Azure AD PIM Commands

In the following I will show some examples of using the Azure AD PIM Module.


In the following I’m connecting with a specified username, if it is required to use Azure MFA for this user I will be prompted for that as well:

Connect-PimService –UserName <username>



After authenticating, PIM service connection details are returned, here slightly masked:


The above returned is exactly the same as would be returned by running the command:



This command will list any role assignments, permanent or eligible your user might have. Here is a couple of examples for outputs for two different admin users. The first user is eligible for Security Administrator and Privileged Role Administrator, and permanent for Global Administrator:


The second admin user is eligible for Exchange Administrator and Global Administrator:


If I want to assign a variable to a role assignment, I can do it like the following command:

$roleAssignment = Get-PrivilegedRoleAssignment | Where {$_.RoleName -eq "Privileged Role Administrator"}

I now have a role assignment variable I can use in the following commands.


To enable one of my roles, I need to specify a duration (PS! keep inside the allowed role settings for max duration!), and specify which role either by RoleId or RoleAssignment variable. Optional parameters like Reason etc can also be specified.

Here is a working example:

Enable-PrivilegedRoleAssignment –Duration 1 –RoleAssignment $roleAssignment –Reason “Add crmadmin to CRM Administrators”

After running the command, if successful it will return as a submitted request for activating role membership.


By running Get-PrivilegedRoleAssignment again, we can now see that the role of “Privileged Role Administrator” is indeed activated (elevated), and with a ExpirationTime (UTC time):


PS! If you have required MFA on activation for the role, one of two things will happen:

  1. If the user already has verified the identity with Azure MFA when authenticating with Connect-PimService, the user will not be asked again. This is the same experience as by using the Azure Portal for activating roles.
  2. If the user hasn’t verified with Azure MFA, the user will be prompted when activating the role, similar to this example:



Any roles you have activated will automatically deactivate after the duration specified has passed. However, if you are finished doing administrative tasks with your role, you can deactivate the role manually.

To deactivate an active assignment, run the following command specifying a RoleId or RoleAssignment variable:

Disable-PrivilegedRoleAssignment –RoleAssignment $roleAssignment



To end your connection to Azure AD PIM Service, run the following command:


After running that command you can also see that there are no role assignments to list anymore.


Hope these commands and examples have been helpful, enjoy working with Azure AD PIM!

9 thoughts on “Getting started with Azure AD PIM PowerShell Module

  1. Deepak


    Thanks for the article.

    I am having an issue. Get-PrivilegedRoleAssignment is not giving any data even though in the portal I can see many eligible roles for me.

    Can you please help me in explaining this.


    1. Jan Vidar Elven Post author

      Can you verify that you have connected til PIM with the correct user, by running Show-PimServiceConnection?

  2. Chris

    Hi, great article thank you – max time here is 2 hrs, how do you specify 2 hrs under duration? I can’t get it to accept it, thanks!

    1. Jan Vidar Elven Post author

      Hi Chris and thanks. You will have to go to the Azure Portal, and under Home | Privileged Identity Management | Azure AD directory roles – Settings | Roles, and from there either set a default max duration settings for all roles, or for each applicable role individually.

  3. William Lee

    I noticed if I do just connect-pimservice -credentials $admincred it logs in but without the username in the credential object (I used the same $admincred to connect to azurerm successfully). So I tried to use both -credentials and -username but it will not take both (see error below).
    UserName :
    WriteVerboseLogs : System.Action`1[System.String]
    RedirectUri : urn:ietf:wg:oauth:2.0:oob
    PromptBehavior : Auto
    ResourceUri : 01fc33a7-78ba-4d2f-a4b7-000000000
    PromptMfa : False
    ClientId : 1950a258-227b-4e31-a9cf-0000000000
    IsPPE : False
    TenantName :

    Connect-PimService -UserName -Credentials $AdminCred
    Connect-PimService : Parameter set cannot be resolved using the specified named parameters.
    At line:1 char:1
    + Connect-PimService -UserName -Credentials $Admi …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidArgument: (:) [Connect-PimService], ParameterBindingException
    + FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.Azure.ActiveDirectory.PIM.PSModule.Cmdlets.ConnectPimService

  4. Chris

    Hi Jan, nice article and thank you!
    Question, I am not experiencing exactly the same behavior when Enable-PrivilegedRoleAssignment. I am being prompted to login again (even after completing connect-pimservice) and then completing second factor challenge. How can I bypass the second login?


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