Getting a list of users whole PIM role assignments are about to expire

Question

Getting a list of users whole PIM role assignments are about to expire

MrFlinstone 761

I would like to know if its possible to get a list of users whose PIM directory role assignments are about to expire, usually an email gets sent with 14 days to go, but keen to understand if there is a powershell script that can be executed to show eligible role assignments that are about to expire

Sridevi Machavarapu 33,305 Microsoft External Staff Moderator

Hey there! You can absolutely pull back upcoming expirations via PowerShell. The easiest approach is to use the Microsoft Graph PowerShell SDK to enumerate eligible PIM assignments in your tenant and then filter on the end date. Here’s a quick script you can run:


# Install & connect

Install-Module Microsoft.Graph -Scope CurrentUser -Force

Import-Module Microsoft.Graph

Connect-MgGraph -Scopes "RoleManagement.Read.Directory"

# Define window

$now       = (Get-Date).ToUniversalTime()

$threshold = $now.AddDays(14)

# Grab all eligible role assignments and filter for those ending in the next 14 days

$expiring = Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance -All |

  Where-Object {

    $end = [datetime]$_.ScheduleInfo.EndDateTime

    $end -gt $now -and $end -le $threshold

  } |

  Select-Object `

    @{n='User';   e={$_.PrincipalDisplayName}},

    @{n='Role';   e={$_.RoleDefinitionId}},

    @{n='Expires';e={$_.ScheduleInfo.EndDateTime}}

# Output to screen (or export to CSV)

$expiring | Format-Table -AutoSize

# $expiring | Export-Csv expiring-pim-assignments.csv -NoTypeInformation

What this does:

Connects to Microsoft Graph with PIM read rights.
Pulls all eligible (time-bound) role assignments.
Filters where the EndDateTime is between now and 14 days out.
Shows you the user, the role definition ID, and the exact expiry timestamp.

If you’re managing Azure Resource roles via PIM (instead of directory roles), you can do something similar with the Az module:


Install-Module Az.Resources -Scope CurrentUser -Force

Connect-AzAccount

Get-AzRoleEligibilitySchedule -Scope /subscriptions/<yourSubId> |

  Where-Object {

    $_.EndDateTime -ne $null -and

    $_.EndDateTime -le (Get-Date).AddDays(14)

  } |

  Select-Object PrincipalName, RoleDefinitionName, EndDateTime

That will list all eligible RBAC assignments in the subscription that expire within the next 14 days.

Hope that gets you exactly the visibility you need!

References:

https://learn.microsoft.com/entra/id-governance/privileged-identity-management/pim-how-to-renew-extend

https://learn.microsoft.com/azure/role-based-access-control/pim-integration

1 answer

Your answer

Answer 1

Yes. PIM already sends emails 14 days before expiration, but eligible and time‑bound assignments can also be queried via PowerShell.

There are two main approaches, depending on whether the roles are Azure resource roles (Azure RBAC) or Microsoft Entra roles.

1. Azure resource roles (Azure RBAC via PIM)

Use the Azure PowerShell PIM schedule cmdlets against the relevant scope and filter by end date.

Example for a subscription scope:

$subscriptionId = "<subscriptionId>"
$cutoff = (Get-Date).AddDays(14)

# Eligible role assignments
$eligible = Get-AzRoleEligibilitySchedule -Scope "/subscriptions/$subscriptionId" |
    Where-Object { $_.EndDateTime -ne $null -and $_.EndDateTime -le $cutoff }

# Active time-bound role assignments (exclude permanent)
$activeTimeBound = Get-AzRoleAssignmentSchedule -Scope "/subscriptions/$subscriptionId" |
    Where-Object { $_.EndDateTime -ne $null -and $_.EndDateTime -le $cutoff }

$expiring = $eligible + $activeTimeBound
$expiring | Select-Object PrincipalId, RoleDefinitionName, StartDateTime, EndDateTime, Scope

Get-AzRoleEligibilitySchedule returns eligible assignments; Get-AzRoleAssignmentSchedule returns active assignments. Filtering on EndDateTime within the next 14 days gives the list of users whose PIM-backed Azure RBAC roles are about to expire.

2. Microsoft Entra roles (directory roles via PIM)

For Microsoft Entra roles, use Microsoft Graph PowerShell PIM APIs. Role assignment requests and schedules support actions such as AdminExtend, AdminRenew, SelfExtend, and SelfRenew, and include schedule information.

Conceptually, the steps are:

Query eligible role assignment schedule instances for directory roles.
Filter where scheduleInfo (or equivalent end date property) is within the next 14 days.
Project principal, role definition, and end date.

Example pattern (principal filter shown in context; extend it to all principals and add date filtering):

# Example from context to list eligible role assignments for a user
Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance `
    -Filter "principalId eq '<user-object-id>'" | Format-List

To build a report of expiring assignments, iterate over schedule instances, inspect their schedule/end date, and filter to those expiring within 14 days. The same model supports actions SelfExtend and SelfRenew, which are what users invoke when they extend/renew expiring or expired assignments.

3. Portal alternative (quick check)

If a one-off check is sufficient, the Azure portal can list eligible and time‑bound Azure RBAC assignments:

In the Azure portal, open Access control (IAM) for the resource (for example, a subscription).
Go to Role assignments.
Group/sort by State and look for assignments that are not Active permanent.

This view shows eligible and time‑bound assignments; you can visually identify those nearing expiration.

References:

Share via

Getting a list of users whole PIM role assignments are about to expire

1 answer

1. Azure resource roles (Azure RBAC via PIM)

2. Microsoft Entra roles (directory roles via PIM)

3. Portal alternative (quick check)

Your answer