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
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.
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>
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:
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:
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.
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.
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:
- 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.
- If the user hasn’t verified with Azure MFA, the user will be prompted when activating the role, similar to this example:
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
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.
Hope these commands and examples have been helpful, enjoy working with Azure AD PIM!
GoToGuy Blog 
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
Can you verify that you have connected til PIM with the correct user, by running Show-PimServiceConnection?
same issue, i’m connected but I can’t call Get-PrivilegedRoleAssignment
Get-PrivilegedRoleAssignment : An error occurred while processing this request.
At line:1 char:1
+ Get-PrivilegedRoleAssignment
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Get-PrivilegedRoleAssignment], DataServiceQueryException
+ FullyQualifiedErrorId : Microsoft.OData.Client.DataServiceQueryException,Microsoft.Azure.ActiveDirectory.PIM.PSModule.Cmdlets.GetPrivilegedRoleAssignments
Nice Article, great work.
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!
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.
Hey Jan, great module. Is there any chance you could share the source code for this module. Thanks.
Hi, the module is not mine, but you can get it at PowerShell Gallery in the following link. Use Save-Module, and the you can look at the source module. https://www.powershellgallery.com/packages/Microsoft.Azure.ActiveDirectory.PIM.PSModule/2.0.0.1513
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 [email protected] -Credentials $AdminCred
Connect-PimService : Parameter set cannot be resolved using the specified named parameters.
At line:1 char:1
+ Connect-PimService -UserName [email protected] -Credentials $Admi …
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidArgument: (:) [Connect-PimService], ParameterBindingException
+ FullyQualifiedErrorId : AmbiguousParameterSet,Microsoft.Azure.ActiveDirectory.PIM.PSModule.Cmdlets.ConnectPimService
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?
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?
Take a look at this article: https://blog.kloud.com.au/2017/07/04/resolving-the-double-auth-prompt-issue-in-adfs-with-azure-ad-conditional-access-mfa/
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.
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 [email protected]
$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
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
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
Is there a way to use powershell command to approve PIM request as well?
Not in that PIM PowerShell module, but it would be possible to use PowerShell and Microsoft Graph https://docs.microsoft.com/en-us/graph/api/privilegedapproval-update?view=graph-rest-beta