Get PIM Role Assignment Status For Azure AD Using Powershell

If you’re like me and you love to run reports to get valuable information for your tenant and settings, the get PIM role assignment status is the script for you. Recently I was running a report to audit user permissions in Azure AD and realized that my data was off by a bit. I knew some users were added to Privilege Identity Management (PIM) roles but they weren’t showing up in my report.
 

The reason they weren’t showing up is because I was using the Get-AzureADDirectoryRoleMember cmdlet and that only shows users with current or activated access. If a user was not elevated in PIM, they basically didn’t have access so it skewing my results.

To give you a better idea of what I’m talking about, the above is a sample of the Helpdesk Administrators role. In the Azure AD GUI, the user is added as an eligible role, meaning he can elevate his just in time access. However in Powershell, since the role is not activated, it is not going to display.

Therefore we are going to use the Get-AzureADMSPrivilegedRoleDefinition Azure AD cmdlet to display the list of roles available and the Get-AzureADMSPrivilegedRoleAssignment to filter for the user we’re specifying.

Requirements for this script to work

In order to make this work you’ll need the following:

• AzureADPreview Powershell module.

I want to emphasize the “preview” in the name of the module. Using just the regular AzureAD module is not not going to work so that’s something to keep in mind.

Script Parameters

UserPrincipalName

Specify the UserPrincipalName for the user you want to check roles for.

RoleName

Specify the RoleName you want to filter for. This will display all PIM roles that are granted directly or through a group.

TenantId

By default it will use the TenantId from your current session. If you’re connected to a multi-tenant, you can specify the tenant here.

Get PIM Role Assignment Status For Azure AD Using Powershell

By using this script you’ll be able to see all the people who have standing access as well as PIM eligible roles.

Function Get-PIMRoleAssignment {
<#
.SYNOPSIS
    This will check if a user is added to PIM or standing access.
    For updated help and examples refer to -Online version.

.NOTES
    Name: Get-PIMRoleAssignment
    Author: theSysadminChannel
    Version: 1.0
    DateCreated: 2021-May-15

.EXAMPLE
    Get-PIMRoleAssignment -UserPrincipalName [email protected]

.EXAMPLE
    Get-PIMRoleAssignment -RoleName 'Global Administrator'

.LINK
    https://thesysadminchannel.com/get-pim-role-assignment-status-for-azure-ad-using-powershell -
#>

    [CmdletBinding()]
    param(
        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            ParameterSetName = 'User',
            Position  = 0
        )]
        [string[]]  $UserPrincipalName,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            ParameterSetName = 'Role',
            Position  = 1
        )]
        [Alias('DisplayName')]
        [ValidateSet(
            'Application Administrator',
            'Application Developer',
            'Attack Simulation Administrator',
            'Authentication Administrator',
            'Azure Information Protection Administrator',
            'Billing Administrator',
            'Cloud Device Administrator',
            'Compliance Administrator',
            'Conditional Access Administrator',
            'Device Managers',
            'Directory Readers',
            'Directory Writers',
            'Exchange Administrator',
            'Exchange Recipient Administrator',
            'Global Administrator',
            'Global Reader',
            'Helpdesk Administrator',
            'Intune Administrator',
            'License Administrator',
            'Message Center Privacy Reader',
            'Message Center Reader',
            'Power BI Administrator',
            'Power Platform Administrator',
            'Privileged Authentication Administrator',
            'Privileged Role Administrator',
            'Reports Reader',
            'Search Administrator',
            'Security Administrator',
            'Security Reader',
            'Service Support Administrator',
            'SharePoint Administrator',
            'Skype for Business Administrator',
            'Teams Administrator',
            'Teams Communications Administrator',
            'Teams Communications Support Engineer',
            'Teams Communications Support Specialist',
            'User Administrator'
        )]
        [string]    $RoleName,


        [string]    $TenantId
    )

    BEGIN {
        $SessionInfo = Get-AzureADCurrentSessionInfo -ErrorAction Stop
        if (-not ($PSBoundParameters.ContainsKey('TenantId'))) {
            $TenantId = $SessionInfo.TenantId
        }

        $AdminRoles = Get-AzureADMSPrivilegedRoleDefinition -ProviderId aadRoles -ResourceId $TenantId -ErrorAction Stop | select Id, DisplayName
        $RoleId = @{}
        $AdminRoles | ForEach-Object {$RoleId.Add($_.DisplayName, $_.Id)}
    }

    PROCESS {
        if ($PSBoundParameters.ContainsKey('UserPrincipalName')) {
            foreach ($User in $UserPrincipalName) {
                try {
                    $AzureUser = Get-AzureADUser -ObjectId $User -ErrorAction Stop | select DisplayName, UserPrincipalName, ObjectId
                    $UserRoles = Get-AzureADMSPrivilegedRoleAssignment -ProviderId aadRoles -ResourceId $TenantId -Filter "subjectId eq '$($AzureUser.ObjectId)'"

                    if ($UserRoles) {
                        foreach ($Role in $UserRoles) {
                            $RoleObject = $AdminRoles | Where-Object {$Role.RoleDefinitionId -eq $_.id}

                            [PSCustomObject]@{
                                UserPrincipalName = $AzureUser.UserPrincipalName
                                AzureADRole       = $RoleObject.DisplayName
                                PIMAssignment     = $Role.AssignmentState
                                MemberType        = $Role.MemberType
                            }
                        }
                    }
                } catch {
                    Write-Error $_.Exception.Message
                }
            }
        }

        if ($PSBoundParameters.ContainsKey('RoleName')) {
            try {
                $RoleMembers = @()
                $RoleMembers += Get-AzureADMSPrivilegedRoleAssignment -ProviderId aadRoles -ResourceId $TenantId -Filter "RoleDefinitionId eq '$($RoleId[$RoleName])'" -ErrorAction Stop | select RoleDefinitionId, SubjectId, StartDateTime, EndDateTime, AssignmentState, MemberType

                if ($RoleMembers) {
                    $RoleMemberList = $RoleMembers.SubjectId | select -Unique
                    $AzureUserList = foreach ($Member in $RoleMemberList) {
                        try {
                            Get-AzureADUser -ObjectId $Member | select ObjectId, UserPrincipalName
                        } catch {
                            Get-AzureADGroup -ObjectId $Member | select ObjectId, @{Name = 'UserPrincipalName'; Expression = { "$($_.DisplayName) (Group)" }}
                            $GroupMemberList = Get-AzureADGroupMember -ObjectId $Member | select ObjectId, UserPrincipalName
                            foreach ($GroupMember in $GroupMemberList) {
                                $RoleMembers += Get-AzureADMSPrivilegedRoleAssignment -ProviderId aadRoles -ResourceId $TenantId -Filter "RoleDefinitionId eq '$($RoleId[$RoleName])' and SubjectId eq '$($GroupMember.objectId)'" -ErrorAction Stop | select RoleDefinitionId, SubjectId, StartDateTime, EndDateTime, AssignmentState, MemberType
                            }
                            Write-Output $GroupMemberList
                        }
                    }

                    $AzureUserList = $AzureUserList | select ObjectId, UserPrincipalName -Unique
                    $AzureUserHash = @{}
                    $AzureUserList | ForEach-Object {$AzureUserHash.Add($_.ObjectId, $_.UserPrincipalName)}

                    foreach ($Role in $RoleMembers) {
                        [PSCustomObject]@{
                            UserPrincipalName = $AzureUserHash[$Role.SubjectId]
                            AzureADRole       = $RoleName
                            PIMAssignment     = $Role.AssignmentState
                            MemberType        = $Role.MemberType
                        }
                    }
                }
            } catch {
                Write-Error $_.Exception.Message
            }
        }
    }

    END {}

}

We can now see that the Helpdesk Administrator is now showing up in our output and in the Assignment column it is labeled as Eligible. We’ll also take note that we can see if the member type is added through a group or if it was added directly. This script will support that option.

Conclusion

Get PIM role assignment status for Azure AD using Powershell will now be in your arsenal of cool tips and tricks for your Syadmin role. If you’re interested in more scripts like this, be sure to check out our Powershell Gallery or Azure Content. Finally, be sure to check out our Youtube Channel for any video content.