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: https://docs.microsoft.com/en-us/azure/active-directory/active-directory-privileged-identity-management-configure, or by just using the following short URL: https://aka.ms/AzureADPIM!

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: https://www.powershellgallery.com/packages/Microsoft.Azure.ActiveDirectory.PIM.PSModule

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

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

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

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

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.

Connect-PimService

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>
image
image

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

image

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

Show-PimServiceConnection

Get-PrivilegedRoleAssignment

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:

image

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

image

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.

Enable-PrivilegedRoleAssignment

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.

image

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):

image

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:
    image

Disable-PrivilegedRoleAssignment

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
image

Disconnect-PimService

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

Disconnect-PimService

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

image

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

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

  1. Deepak

    Hi,

    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.

    Thanks

    Reply
    1. Jan Vidar Elven Post author

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

      Reply
  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!

    Reply
    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.

      Reply
  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 : domain.com

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

    Reply
  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?

    Reply
  5. Jeremy Waters

    I have a hybrid on-prem-azure-ad environment and use Azure MFA. When I execute Connect-PimService, I am redirected to my ADFS to authenticate and do not get an MFA challenge. When I subsequently execute Enable-PrivilegedRoleAssignment, I am again redirected to my ADFS to reauthenticate and this time I get an Azure MFA challenge. How can I prevent the double ADFS username/password challenges? Is there a way to force MFA on the initial Connect-PimService call? Can I target this “app” with a CA policy requiring MFA?

    Reply
      1. Jeremy

        That article looks like a good match. Looking at my Fiddler trace, I do see wfresh=0 in both calls to ADFS. Alas I am running ADFS 2.0, so the prescribed fix won’t work for me.

  6. Patrick

    Im trying to automate this as much as possible
    Its flaking on the last bit…any ideas?

    Enable-PrivilegedRoleAssignment : Cannot bind parameter ‘RoleAssignment’. Cannot convert the “Teams Service
    Administrator” value of type “System.String” to type “Microsoft.Azure.ActiveDirectory.PIM.API.ODataClient.Micro
    soft.Azure.PrivilegedIdentities.PrivilegedRoleAssignment”.

    Connect-PimService -UserName here@thisplace.com
    $roles = Get-PrivilegedRoleAssignment | Where {$_.IsElevated -ne “True”}
    $menu = @{}
    for ($i=1;$i -le $roles.count; $i++)
    {
    Write-Host “$i. $($roles.RoleName[$i-1])”
    $menu.Add($i, ($roles.RoleName[$i – 1])) }

    [int]$ans = Read-host ‘enter-Selection’
    $reason = Read-Host ‘What is the reason for elevation’
    $selection = $menu.Item($ans) ; Enable-PrivilegedRoleAssignment -duration 2 -RoleAssignment $selection -Reason $reason 2

    Reply
    1. Jan Vidar Elven Post author

      Interesting script! So when you create the selection menu you are converting the role object to a string, and thus cannot activate the role. Change the last line to something like this::
      $selection = $menu.Item($ans) ; $selectedRole = Get-PrivilegedRoleAssignment | Where-Object {$_.RoleName -eq $selection}
      Enable-PrivilegedRoleAssignment -Duration 1 -RoleAssignment $selectedRole -Reason $reason

      Reply
  7. Jason

    I am definitely getting the show-pimserviceconnection but I get null on Get-PrivilegedRoleAssignment. Can you please tell me what’s going on? This module has not been updated in 6 months, has it been depracated?

    PS C:\windows\system32> Show-PimServiceConnection

    UserName : xxxxxxx
    WriteVerboseLogs : System.Action`1[System.String]
    RedirectUri : xxxxx
    PromptBehavior : Auto
    ResourceUri : xxxxxxx
    PromptMfa : False
    ClientId : xxxxxxxxxx
    IsPPE : False
    TenantName : xxxxxx.com

    PS C:\windows\system32> Get-PrivilegedRoleAssignment
    Get-PrivilegedRoleAssignment : The operation has timed out
    At line:1 char:1
    + Get-PrivilegedRoleAssignment
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Get-PrivilegedRoleAssignment], DataServiceTransportException
    + FullyQualifiedErrorId : Microsoft.OData.Client.DataServiceTransportException,Microsoft.Azure.ActiveDirectory.PIM
    .PSModule.Cmdlets.GetPrivilegedRoleAssignments

    Reply

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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