Update-MgDirectoryAdministrativeUnit: Update Administrative Units

It’s easy for Administrative Units (AUs) to lose their purpose —names change, departments merge, and descriptions get stale. When that happens, scoped admin boundaries become confusing and audits get harder. Instead of recreating AUs, you can update them in place with Update-MgDirectoryAdministrativeUnit, keeping least-privilege clean and current.

i) Cmdlet Syntax

Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId <String> [-DisplayName <String>] [-Description <String>] [-Visibility <String>] [-AdditionalProperties <Hashtable>] [-IfMatch <String>][-WhatIf] [-Confirm]

# Body parameter form (advanced)

Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId <String> -BodyParameter 7lt;IMicrosoftGraphAdministrativeUnit>

Heads-up: You’ll typically identify the AU with the Id (GUID). If you only know the name, look it up first with Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Sales AU'".

ii) Usage Examples

1. Rename an AU and refresh its description

$auId = "00000000-0000-0000-0000-000000000000"
Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId $auId `
-DisplayName "Sales & Marketing AU" `
-Description "Scoped admin boundary for Sales + Marketing"


2. Update only the description (minimal change)

Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId $auId `
-Description "Regional Sales AU for APAC"


3. Convert an AU into a dynamic group

$params = @{
    description = "Marketing AU"
    displayName = "Marketing"
    membershipRule = "(user.department -eq `"Marketing`")"
    membershipRuleProcessingState = "On"
}
                                  
Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId $auId -BodyParameter $params

This example updates the AU so that it behaves like a dynamic group. Membership is automatically managed based on the rule (user.department -eq "Marketing").

iii) Cmdlet Tips

• Permissions: Connect with Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All". App-only flows require the equivalent application permission plus admin consent.
• Find the Id quickly:

Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Sales AU'" | Select-Object Id,DisplayName

• Idempotent mindset: Only pass the fields you want to change; untouched properties remain as-is.
• Dry-run safely: Use -WhatIf to preview effects; pair with -Confirm in sensitive environments.
• Concurrency guard: When multiple admins/automations edit AUs, consider -IfMatch to avoid overwriting someone else’s change.
• Audit trail: Before updating, snapshot the current state:

Get-MgDirectoryAdministrativeUnit -AdministrativeUnitId $auId | Format-List *

iv) Use Cases

• Department rename: Marketing merges with Sales; update AU name/description without rebuilding scope.
• Regional split/realignment: Adjust descriptions or metadata to reflect new territory boundaries.
• Compliance readiness: Keep AU labels and notes aligned with your RBAC model so audits map cleanly to business units.

v) Possible Errors & Solutions

Error	Cause	Solution
Authorization_RequestDenied or insufficient privileges	Missing AdministrativeUnit.ReadWrite.All	Reconnect with the correct scope or grant app permission with admin consent.
Request_ResourceNotFound	Wrong AU Id or the AU was deleted	Re-query with Get-MgDirectoryAdministrativeUnit to confirm Id, then retry.
PreconditionFailed (412) when using -IfMatch	ETag mismatch due to a recent change	Retrieve the AU again to get the latest ETag and re-run the update.
Properties don’t change	Passing incorrect parameter names or only read-only fields	Verify parameter names (-DisplayName, -Description, -AdditionalProperties) and try again.
Throttling / intermittent errors	Burst updates in large tenants	Add retry/backoff or batch updates over time.

Conclusion

Update-MgDirectoryAdministrativeUnit lets you fix and refine AUs without starting over. Grab the AU Id, connect with the right permissions, change only what you need, and lean on -WhatIf (plus optional -IfMatch) for safe, collaborative edits. Keeping AU metadata tidy pays off in cleaner RBAC scopes, happier auditors, and fewer surprises for admins down the line.