New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest

What is New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest?

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest is a Microsoft Graph PowerShell cmdlet used to create a role eligibility schedule request in Microsoft Entra ID (Azure AD).

This cmdlet is primarily used in Privileged Identity Management (PIM) scenarios to make a user eligible for a directory role for a defined period.

Instead of permanently assigning high-privilege roles like:

• Global Administrator
• Privileged Role Administrator
• Application Administrator

This cmdlet allows you to grant time-bound eligibility, meaning the user must activate the role when required. It is part of the Role Management API under Microsoft Graph.

Why Use New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest?

Permanent admin roles increase risk.

Modern security models follow Zero Trust + Just-In-Time (JIT) access principles.

This cmdlet enables:

• Temporary admin eligibility
• Time-bound privileged access
• Project-based admin delegation
• Reduced standing privileges
• Compliance with security frameworks (ISO, SOC, NIST)

Real-World Scenarios

• Grant 10-hour eligibility for emergency troubleshooting
• Provide 1-day access for weekend maintenance
• Assign 30-day eligibility for onboarding or projects
• Automate role lifecycle via scripts

For organizations using Microsoft Entra PIM, this cmdlet is essential.

Prerequisites

Before using this cmdlet:

• Microsoft Graph PowerShell SDK installed
• Connected to Microsoft Graph
• Privileged Identity Management (PIM) enabled
• Required API permissions granted

Required API Permissions

Delegated Permissions

• RoleManagement.ReadWrite.Directory
• Directory.Read.All

Application Permissions (for automation)

• RoleManagement.ReadWrite.Directory
• Directory.Read.All

⚠️ Admin consent is required for RoleManagement permissions.

Install Microsoft Graph (If Needed)

Install-Module Microsoft.Graph -Scope CurrentUser

Connect to Microsoft Graph

Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory","Directory.Read.All"

How to use New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest?

This cmdlet requires the -BodyParameter hashtable.

Syntax

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter <Hashtable>

The hashtable must include:

• PrincipalId (User Object ID)
• RoleDefinitionId (Role ID)
• DirectoryScopeId (Usually "/" for tenant-wide)
• Action (AdminAssign)
• ScheduleInfo
• Justification

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest Examples

Example 1: Create an Eligible Role Assignment for 10 Hours

This assigns a user as eligible for a role for 10 hours.

$params = @{
  PrincipalId      = "d29e358a-a443-4d83-98b3-499a5405bb5b"
  RoleDefinitionId = "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
  Justification    = "Add eligible assignment"
  DirectoryScopeId = "/"
  Action           = "AdminAssign"
  ScheduleInfo     = @{
    StartDateTime = Get-Date
    Expiration    = @{
      Type     = "AfterDuration"
      Duration = "PT10H"
    }
  }
}

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter $params |
  Format-List Id, Status, Action, DirectoryScopeId, RoleDefinitionId, Justification, PrincipalId
                                        

Duration Format Explanation

• "PT10H" = 10 hours
• PT indicates time duration
• H represents hours

Example 2: Create an Eligible Role Assignment for 1 Day (24 Hours)

This assigns eligibility for 1 full day.

                                            
$params = @{
  PrincipalId      = "d29e358a-a443-4d83-98b3-499a5405bb5b"
  RoleDefinitionId = "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
  Justification    = "Grant eligibility for 1 day for support work"
  DirectoryScopeId = "/"
  Action           = "AdminAssign"
  ScheduleInfo     = @{
    StartDateTime = Get-Date
    Expiration    = @{
      Type     = "AfterDuration"
      Duration = "P1D"
    }
  }
}

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter $params |
  Format-List Id, Status, Action, DirectoryScopeId, RoleDefinitionId, Justification, PrincipalId
                                            
                                        

Duration Format Explanation

• "P1D" = 1 day
• P represents period
• D represents days

Example 3: Create an Eligible Role Assignment for 30 Days

This assigns eligibility for 30 days, which is common for temporary projects or onboarding.

$params = @{
  PrincipalId      = "d29e358a-a443-4d83-98b3-499a5405bb5b"
  RoleDefinitionId = "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
  Justification    = "Grant 30-day eligibility for project administration"
  DirectoryScopeId = "/"
  Action           = "AdminAssign"
  ScheduleInfo     = @{
    StartDateTime = Get-Date
    Expiration    = @{
      Type     = "AfterDuration"
      Duration = "P30D"
    }
  }
}

New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter $params |
  Format-List Id, Status, Action, DirectoryScopeId, RoleDefinitionId, Justification, PrincipalId
                                        

Important Notes

• PrincipalId must be the Object ID, not UPN.
• RoleDefinitionId must match the directory role ID.
• DirectoryScopeId "/" applies at tenant level.
• Duration must follow ISO 8601 format.
• This creates eligibility — not active assignment.
• Activation still requires PIM workflow approval (if configured).