Remove-MgDirectoryAdministrativeUnitMemberByRef — Remove Users/Groups/Devices from Administrative Units

Note: Use Get-MgDirectoryAdministrativeUnit to fetch Administrative Unit (AU) IDs before removing members.

This cmdlet removes users, groups, or devices from an Administrative Unit (AU) in Microsoft Entra ID by deleting the membership reference at .../administrativeUnits/{id}/members/{directoryObjectId}/$ref.

i) Cmdlet Syntax

Remove-MgDirectoryAdministrativeUnitMemberByRef
-AdministrativeUnitId 
-DirectoryObjectId     # Id of the user/group/device to remove

Required Graph permissions (one of):

• Delegated: AdministrativeUnit.ReadWrite.All
• Application: AdministrativeUnit.ReadWrite.All

Result: No content on success (HTTP 204).

ii) Usage Examples

1. Remove a Single Member (user/group/device)

$administrativeUnitId = "00000000-0000-0000-0000-000000000000"   # AU Id
$directoryObjectId    = "11111111-1111-1111-1111-111111111111"   # User/Group/Device Id
                                    
Remove-MgDirectoryAdministrativeUnitMemberByRef `
  -AdministrativeUnitId $administrativeUnitId `
  -DirectoryObjectId $directoryObjectId
                                

To remove a group or device, you can use Get-MgGroup cmdlet and find out the object’s Id 
(e.g., (Get-MgGroup -Filter "displayName eq 'HR Managers'").Id)

2. Remove Multiple Users from CSV (by UPNs)

CSV (save as upns-to-remove.csv):

UserPrincipalName
alexw@contoso.com
meganb@contoso.com
diegoS@contoso.com
                                

3. Script:

# Bulk remove users (by UPN) from an Administrative Unit
# Prereqs: Connect-MgGraph; ensure AdministrativeUnit.ReadWrite.All
                                    
$administrativeUnitId = "00000000-0000-0000-0000-000000000000"  #  replace
$csvPath = ".\upns-to-remove.csv"
                                    
$rows = Import-Csv -Path $csvPath
                                    
foreach ($row in $rows) {
$upn = ($row.UserPrincipalName).Trim()
if (-not $upn) {
Write-Warning "Row has an empty 'UserPrincipalName'. Skipping."
continue
}
                                    
try {
# Resolve UPN to directory object Id
$user = Get-MgUser -UserId $upn -ErrorAction Stop
                                    
# Remove from AU
Remove-MgDirectoryAdministrativeUnitMemberByRef `
-AdministrativeUnitId $administrativeUnitId `
-DirectoryObjectId $user.Id `
-ErrorAction Stop
                                    
Write-Host ("Removed {0} ({1}) from AU {2}" -f $upn, $user.Id, $administrativeUnitId)
}
catch {
Write-Warning ("Failed to remove {0}: {1}" -f $upn, $_.Exception.Message)
}
}
                                

iii) Cmdlet Tips

• Know your AU: Retrieve the AU Id with Get-MgDirectoryAdministrativeUnit and confirm the member’s Id (user/group/device) before removal.
• No output on success: Use your own logging (as above) or follow up by listing AU members to verify.
• Use -WhatIf first when testing bulk removals to preview actions safely.
• Permissions matter: AdministrativeUnit.ReadWrite.All is required (delegated or app).
• Throttling-safe loops: For large CSVs, add Start-Sleep -Milliseconds 200 or implement simple retry logic.

iv) Use Cases

• Offboarding: Automatically detach leavers from region/department AUs as part of deprovisioning.
• Reorgs: Cleanly move large sets of users/groups/devices between AUs by removing from the old AU, then adding to the new one.
• Scope cleanup: Periodically prune AUs to ensure delegated admins only see what they should.

v) Possible Errors & Solutions

Error	Cause	Solution
Authorization_RequestDenied (403)	Missing permission/consent	Grant/admin-consent AdministrativeUnit.ReadWrite.All. Re-authenticate.
ResourceNotFound (404)	Wrong AU Id or object Id not found in AU	Validate AU Id with Get-MgDirectoryAdministrativeUnit. Confirm the user/group/device Id exists and is a member of the AU.
Request_BadRequest (400)	Malformed Id or invalid input	Ensure -DirectoryObjectId is a valid GUID of a directory object. Resolve UPNs to Ids using Get-MgUser.
Request_ResourceNotFound during bulk	Target wasn’t a member	Treat as non-fatal in loops; log and continue.
Throttling 429	Too many requests quickly	Add delay or retry with backoff.

Quick verification (optional):

# List first page of AU members after removals

Get-MgDirectoryAdministrativeUnitMember -AdministrativeUnitId $administrativeUnitId -All

vi) Conclusion

Remove-MgDirectoryAdministrativeUnitMemberByRef provides a clean, reliable way to detach users, groups, and devices from Administrative Units. Resolve friendly identifiers (like UPNs) to Ids, confirm the AU Id with Get-MgDirectoryAdministrativeUnit, and use bulk CSV workflows for scale. With the right permissions and simple logging, AU cleanup and re-scoping become safe, auditable, and repeatable.