Public/Get-EntraVacAccessPackageDrift.ps1
|
function Get-EntraVacAccessPackageDrift { <# .SYNOPSIS Returns users who should be assigned to an access package but are not, and vice versa. .DESCRIPTION Compares the expected membership (derived from the active auto-assignment policy's membershipRule) against actual assignments and returns a drift report without making any changes. Reads every page of results, so large packages are fully covered. Only Microsoft.Graph.Authentication (Invoke-MgGraphRequest) is needed. The rule is translated to a Graph user filter for a fast first pass. Every disagreement is then confirmed with Entra's evaluateDynamicMembership API using the real rule, so a user is only reported in ShouldAdd / ShouldRemove when Entra agrees. An assignment whose user was deleted from the directory is reported in ShouldRemove. If the API call fails the function throws and reports nothing. Assignment states handled: Delivered - included in current membership check. A user who no longer matches and already has an expiry date is in the grace period: reported in InGracePeriod, not ShouldRemove (unless -IncludeGracePeriod). PartiallyDelivered - user in target: reported in ShouldReprocess. User not in target: reported in ShouldRemove. Delivering - in flight. Counted as assigned (never added again) and reported in Delivering. Never reported for removal. If Entra confirms the user no longer matches the rule, it is also listed in DeliveringNotInRule (a likely stuck request to cancel in the portal). Microsoft only permits one auto-assignment policy per access package. If more than one active policy is detected this indicates a misconfiguration and an error is emitted. Ref: https://learn.microsoft.com/en-us/entra/id-governance/entitlement-management-access-package-auto-assignment-policy .PARAMETER AccessPackageId The object ID of the access package to inspect. .PARAMETER IncludeGracePeriod Also report assignments in ShouldRemove when Entra has already started their grace period (an expiry date is set). By default these are listed in InGracePeriod and left for Entra to remove when the grace period ends. .EXAMPLE Get-EntraVacAccessPackageDrift -AccessPackageId "ad524555-24ef-412a-8d20-e070c088a42d" #> [CmdletBinding()] param ( [Parameter(Mandatory)] [string] $AccessPackageId, [switch] $IncludeGracePeriod ) # Ref: https://learn.microsoft.com/en-us/graph/api/entitlementmanagement-list-assignmentpolicies?view=graph-rest-1.0 $policies = Invoke-EntraVacGraphGetAll ` -Uri "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/assignmentPolicies?`$filter=accessPackage/id eq '$AccessPackageId'" # Validate the auto-assignment policy state. # Ref: https://learn.microsoft.com/en-us/graph/api/resources/accesspackageautomaticrequestsettings?view=graph-rest-1.0 # Non-auto policies can carry an empty automaticRequestSettings object, so test the flag itself. $autoPolicies = $policies | Where-Object { $null -ne $_.automaticRequestSettings.requestAccessForAllowedTargets } $activePolicies = $autoPolicies | Where-Object { $_.automaticRequestSettings.requestAccessForAllowedTargets -eq $true } $inactivePolicies = $autoPolicies | Where-Object { $_.automaticRequestSettings.requestAccessForAllowedTargets -ne $true } if (-not $autoPolicies) { Write-Warning "No auto-assignment policy found for access package $AccessPackageId" return } if ($inactivePolicies) { Write-Warning "The auto-assignment policy for access package $AccessPackageId is inactive (requestAccessForAllowedTargets = false). Skipping." return } if (($activePolicies | Measure-Object).Count -gt 1) { Write-Error "Access package $AccessPackageId has more than one active auto-assignment policy. This is a misconfiguration - only one is supported. Resolve in the Entra portal before running this command." return } $activePolicy = $activePolicies | Select-Object -First 1 # PartiallyDelivered = provisioning started but at least one resource role failed. # Delivering = still being provisioned; counted as assigned so it is not requested twice. # Ref: https://learn.microsoft.com/en-us/graph/api/entitlementmanagement-list-assignments?view=graph-rest-1.0 $assignments = @(Invoke-EntraVacGraphGetAll ` -Uri "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/assignments?`$filter=accessPackage/id eq '$AccessPackageId' and (state eq 'Delivered' or state eq 'PartiallyDelivered' or state eq 'Delivering')&`$expand=target") $deliveringAssignments = $assignments | Where-Object { $_.State -eq 'Delivering' } $settledAssignments = $assignments | Where-Object { $_.State -ne 'Delivering' } $partialAssignments = $assignments | Where-Object { $_.State -eq 'PartiallyDelivered' } $assignedUserIds = $assignments | ForEach-Object { $_.Target.ObjectId } $membershipRule = $activePolicy.specificAllowedTargets | Where-Object { $_.'@odata.type' -eq '#microsoft.graph.attributeRuleMembers' } | Select-Object -First 1 | ForEach-Object { $_.membershipRule } if ([string]::IsNullOrWhiteSpace($membershipRule)) { Write-Warning "The auto-assignment policy for access package $AccessPackageId has no membershipRule. Skipping to avoid unintended removals." return } # ConsistencyLevel + count required for advanced filter properties such as # onPremisesExtensionAttributes. Safe to use for all filter expressions. # Ref: https://learn.microsoft.com/en-us/graph/aad-advanced-queries?tabs=http $graphFilter = Convert-PolicyFilterToGraphFilter -PolicyFilter $membershipRule $targetUsers = @(Invoke-EntraVacGraphGetAll ` -Uri "https://graph.microsoft.com/v1.0/users?`$filter=$graphFilter&`$select=id,displayName,userPrincipalName&`$top=999&`$count=true" ` -Headers @{ ConsistencyLevel = 'eventual' }) if (-not $targetUsers) { Write-Warning "The membershipRule for access package $AccessPackageId returned no users. Skipping to avoid unintended removals." return } $targetUserIds = $targetUsers | ForEach-Object { $_.id } # The translated filter is only a shortlist: Entra confirms every disagreement with the real # rule. A failed call throws, so nothing is reported from a partial answer. $isMember = { param ($UserId) try { # Ref: https://learn.microsoft.com/en-us/graph/api/group-evaluatedynamicmembership?view=graph-rest-beta $result = Invoke-MgGraphRequest -Method POST -ErrorAction Stop ` -Uri 'https://graph.microsoft.com/beta/groups/evaluateDynamicMembership' ` -ContentType 'application/json' ` -Body (@{ memberId = $UserId; membershipRule = $membershipRule } | ConvertTo-Json) } catch { # A deleted user cannot match the rule. Any other failure stops the run. if ("$($_.Exception.Message) $($_.ErrorDetails.Message)" -match 'Request_ResourceNotFound') { Write-Verbose "User $UserId no longer exists in the directory." return $false } throw } if ($null -eq $result.membershipRuleEvaluationResult) { throw "evaluateDynamicMembership returned no result for user $UserId." } [bool] $result.membershipRuleEvaluationResult } $addCandidates = $targetUsers | Where-Object { $_.id -notin $assignedUserIds } $leavers = $settledAssignments | Where-Object { $_.Target.ObjectId -notin $targetUserIds } $inGrace = $leavers | Where-Object { $_.Schedule.Expiration.EndDateTime -and -not $IncludeGracePeriod } $removeCandidates = $leavers | Where-Object { $_ -notin $inGrace } $shouldAdd = [System.Collections.Generic.List[object]]::new() $excludedByRule = [System.Collections.Generic.List[object]]::new() foreach ($user in $addCandidates) { if (& $isMember $user.id) { $shouldAdd.Add($user) } else { $excludedByRule.Add($user) } } $deliveringNotInRule = $deliveringAssignments | Where-Object { $_.Target.ObjectId -notin $targetUserIds } | Where-Object { -not (& $isMember $_.Target.ObjectId) } [PSCustomObject]@{ AccessPackageId = $AccessPackageId AssignmentPolicyId = $activePolicy.id MembershipRule = $membershipRule GraphFilter = $graphFilter AssignmentsRead = $assignments.Count TargetUsersRead = $targetUsers.Count ShouldAdd = $shouldAdd ShouldReprocess = $partialAssignments | Where-Object { $_.Target.ObjectId -in $targetUserIds } ShouldRemove = $removeCandidates | Where-Object { -not (& $isMember $_.Target.ObjectId) } InGracePeriod = $inGrace Delivering = $deliveringAssignments DeliveringNotInRule = $deliveringNotInRule ExcludedByRule = $excludedByRule } } |