Public/Sync-EntraVacAccessPackage.ps1

function Sync-EntraVacAccessPackage {
    <#
    .SYNOPSIS
        Syncs membership for an Entra ID access package based on its auto-assignment policy filter.

    .DESCRIPTION
        Uses Get-EntraVacAccessPackageDrift to find what differs (all pages, confirmed with
        Entra's evaluateDynamicMembership), then performs adminAdd/reprocess/adminRemove.
        Nothing is sent when -WhatIf is used, or when drift detection fails.

        Assignment states handled:
          Delivered - user in target: keep. Not in target: adminRemove.
          PartiallyDelivered - user in target: reprocess. Not in target: adminRemove.
          Delivering - in flight: left alone.

        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 sync.

    .PARAMETER MaxRemovals
        Safety cap. If more assignments than this would be removed, nothing is sent and an error is
        raised, because adminRemove skips the policy's grace period. Defaults to 100. With -WhatIf
        the planned actions are still listed and a warning is shown instead.

    .PARAMETER IncludeGracePeriod
        Also remove assignments that are already in their grace period. By default Entra is left to
        remove them when the grace period ends.

    .PARAMETER Force
        Allow more removals than MaxRemovals.

    .PARAMETER WhatIf
        Preview changes without applying them.

    .EXAMPLE
        Sync-EntraVacAccessPackage -AccessPackageId "ad524555-24ef-412a-8d20-e070c088a42d"
    #>

    [CmdletBinding(SupportsShouldProcess)]
    param (
        [Parameter(Mandatory)]
        [string] $AccessPackageId,

        [ValidateRange(0, [int]::MaxValue)]
        [int] $MaxRemovals = 100,

        [switch] $IncludeGracePeriod,

        [switch] $Force
    )

    $drift = Get-EntraVacAccessPackageDrift -AccessPackageId $AccessPackageId -IncludeGracePeriod:$IncludeGracePeriod
    if (-not $drift) { return }

    $toAdd       = @($drift.ShouldAdd)
    $toReprocess = @($drift.ShouldReprocess)
    $toRemove    = @($drift.ShouldRemove)

    Write-Verbose "Access package $AccessPackageId - adding $($toAdd.Count), reprocessing $($toReprocess.Count), removing $($toRemove.Count)"

    if ($toRemove.Count -gt $MaxRemovals -and -not $Force) {
        $message = "Access package $AccessPackageId would remove $($toRemove.Count) assignments, which is over the limit of $MaxRemovals. Review with -WhatIf, then rerun with -Force or a higher -MaxRemovals."
        if ($WhatIfPreference) { Write-Warning $message } else { throw $message }
    }

    # Ref: https://learn.microsoft.com/en-us/graph/api/entitlementmanagement-post-assignmentrequests?view=graph-rest-1.0
    $requestsUri = 'https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/assignmentRequests'
    foreach ($user in $toAdd) {
        if ($PSCmdlet.ShouldProcess("$($user.userPrincipalName) ($($user.id))", "adminAdd to access package $AccessPackageId")) {
            Invoke-MgGraphRequest -Method POST -Uri $requestsUri -ContentType 'application/json' -Body (@{
                requestType = 'adminAdd'
                assignment  = @{
                    targetId           = $user.id
                    assignmentPolicyId = $drift.AssignmentPolicyId
                    accessPackageId    = $AccessPackageId
                }
            } | ConvertTo-Json -Depth 5) | Out-Null
        }
    }

    # Reprocess PartiallyDelivered assignments where the user still belongs.
    # Ref: https://learn.microsoft.com/en-us/graph/api/accesspackageassignment-reprocess?view=graph-rest-1.0
    foreach ($assignment in $toReprocess) {
        $name = $assignment.Target.DisplayName ?? $assignment.Target.ObjectId
        if ($PSCmdlet.ShouldProcess("$name ($($assignment.Target.ObjectId))", "reprocess PartiallyDelivered assignment in access package $AccessPackageId")) {
            Invoke-MgGraphRequest -Method POST `
                -Uri "https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/assignments/$($assignment.id)/reprocess" | Out-Null
        }
    }

    foreach ($assignment in $toRemove) {
        $name = $assignment.Target.DisplayName ?? $assignment.Target.ObjectId
        if ($PSCmdlet.ShouldProcess("$name ($($assignment.Target.ObjectId))", "adminRemove from access package $AccessPackageId")) {
            Invoke-MgGraphRequest -Method POST -Uri $requestsUri -ContentType 'application/json' -Body (@{
                requestType = 'adminRemove'
                assignment  = @{ id = $assignment.id }
            } | ConvertTo-Json -Depth 5) | Out-Null
        }
    }
}