As organizations grow and adopt cloud services, managing role assignments in Entra ID becomes critical. Role assignments are necessary to grant access to resources and to delegate administrative privileges. However, it’s important to ensure that only the right users have access to the right resources and that the access is properly monitored and audited. In this blog post, we’ll show you how to audit eligible Entra ID role assignments using PowerShell.
Entra ID offers a feature called Privileged Identity Management (PIM), which provides time-based and approval-based role activation, auditing, and reporting. PIM allows you to assign eligible roles to users and groups for a limited duration of time and review audit logs of role activations and deactivations. In this post, we’ll focus on auditing eligible roles, which are roles that users or groups are eligible to activate but haven’t yet.
It’s important to periodically audit role assignments in Entra ID to ensure that only the necessary permissions are granted to the right users, groups, or applications. In this blog post, we will show you how to use PowerShell and Microsoft Graph API to audit only the eligible Entra ID role assignments.
You can read my previous post Audit Entra ID Privileged Identity Management Role Settings – Kaido Järvemets (kaidojarvemets.com)
Prerequisites:
- Entra ID Global Administrator
- Latest Microsoft Graph PowerShell module
- PowerShell 7.x
- Visual Studio Code
Step 1: Install Microsoft.Graph PowerShell Module
First we need to install the Microsoft Graph PowerShell module:
Install-Module -Name Microsoft.Graph -Force -Verbose
Step 2: Define the desired permission scopes
We need to define the permission scopes required to access role management information in Entra ID. The following scopes are required to retrieve information about eligible role assignments:
$Scopes = @(
"RoleManagement.ReadWrite.Directory"
)
If you are unsure how to define the permissions scope for a particular command, you can try using the Find-MgGraphCommand cmdlet. While this command may not provide all the information you need, it can still give you some helpful hints.
Step 3: Connect to Microsoft Graph API
To connect to the Microsoft Graph API run the following command:
Select-MgProfile -Name 'beta'
Connect-MgGraph -Scopes $Scopes
Step 4: Get eligible role assignments
We can use the Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance cmdlet to retrieve eligible role assignments. Eligible role assignments are those that meet the following conditions:
- The role is a privileged role
- The role is assigned to a user or group with an active role assignment
- The user or group has a P2 license assigned
Here’s the PowerShell script to retrieve eligible role assignments:
$EligibleAADUserData = @()
$EligibleAADGroupData = @()
$EligileAssignments = Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance -ExpandProperty "*" -All
foreach($Role in $EligileAssignments){
If($Role.Principal.AdditionalProperties.'@odata.type' -eq "#microsoft.graph.user"){
$UserProperties = [pscustomobject]@{
displayName = $Role.Principal.AdditionalProperties.displayName
accountEnabled = $Role.Principal.AdditionalProperties.accountEnabled
StartDateTime = $Role.StartDateTime
EndDateTime = $Role.EndDateTime
MemberType = $Role.MemberType
RoleName = $Role.RoleDefinition.DisplayName
RoleID = $Role.RoleDefinition.Id
}
$EligibleAADUserData += $UserProperties
}
Else{
$GroupProperties = [pscustomobject]@{
displayName = $Role.Principal.AdditionalProperties.displayName
isAssignableToRole = $Role.Principal.AdditionalProperties.isAssignableToRole
StartDateTime = $Role.StartDateTime
EndDateTime = If($null -eq $Role.EndDateTime){"Permanent"}
MemberType = $Role.MemberType
RoleName = $Role.RoleDefinition.DisplayName
RoleID = $Role.RoleDefinition.Id
}
$EligibleAADGroupData += $GroupProperties
}
}
#Print out the details
$EligibleAADUserData
$EligibleAADGroupData
Complete Script
$Scopes = @(
"RoleManagement.ReadWrite.Directory"
)
Select-MgProfile -Name 'beta'
Connect-MgGraph -Scopes $Scopes
$EligibleAADUserData = @()
$EligibleAADGroupData = @()
$EligileAssignments = Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance -ExpandProperty "*" -All
foreach($Role in $EligileAssignments){
If($Role.Principal.AdditionalProperties.'@odata.type' -eq "#microsoft.graph.user"){
$UserProperties = [pscustomobject]@{
displayName = $Role.Principal.AdditionalProperties.displayName
accountEnabled = $Role.Principal.AdditionalProperties.accountEnabled
StartDateTime = $Role.StartDateTime
EndDateTime = $Role.EndDateTime
MemberType = $Role.MemberType
RoleName = $Role.RoleDefinition.DisplayName
RoleID = $Role.RoleDefinition.Id
}
$EligibleAADUserData += $UserProperties
}
Else{
$GroupProperties = [pscustomobject]@{
displayName = $Role.Principal.AdditionalProperties.displayName
isAssignableToRole = $Role.Principal.AdditionalProperties.isAssignableToRole
StartDateTime = $Role.StartDateTime
EndDateTime = If($null -eq $Role.EndDateTime){"Permanent"}
MemberType = $Role.MemberType
RoleName = $Role.RoleDefinition.DisplayName
RoleID = $Role.RoleDefinition.Id
}
$EligibleAADGroupData += $GroupProperties
}
}
#Print out the details
$EligibleAADUserData
$EligibleAADGroupData
Conclusion
Auditing Entra ID PIM roles is a critical task to ensure proper access controls and maintain a secure environment. By using PowerShell and the Microsoft Graph API, you can quickly and easily retrieve information about role assignments.
If you haven’t yet performed an assessment of your Entra ID environment, now is the time to do so. Regular assessments can help you identify potential security risks and implement appropriate controls to mitigate them. So, take action today and conduct an Entra ID assessment to ensure the security of your organization’s digital assets.
