New-MgDirectoryAdministrativeUnitMemberByRef — Add Users/Groups/Devices to Administrative Units

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

This cmdlet adds directory objects—users, groups, or devices—to an Administrative Unit (AU) in Microsoft Entra ID using a reference payload (@odata.id). It maps directly to the Graph API’s .../administrativeUnits/{id}/members/$ref endpoint.

i) Cmdlet Syntax

New-MgDirectoryAdministrativeUnitMemberByRef
-AdministrativeUnitId 
-BodyParameter                # must include "@odata.id"

Required Graph permissions (one of):

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

Success result: returns nothing (HTTP 204 NoContent under the hood).

ii) Usage Examples

All examples strictly follow the -BodyParameter hashtable pattern expected by the Graph PowerShell SDK. Replace placeholder IDs with real ones from your tenant.

1. Adding a Single User

# Inputs
$administrativeUnitId = "00000000-0000-0000-0000-000000000000"   # AU Id (use Get-MgDirectoryAdministrativeUnit to fetch ID)
$userId               = "11111111-1111-1111-1111-111111111111"   # User Id (use Get-MgUser)
$params = @{
  "@odata.id" = "https://graph.microsoft.com/v1.0/users/$userId"
}
New-MgDirectoryAdministrativeUnitMemberByRef `
   -AdministrativeUnitId $administrativeUnitId `
   -BodyParameter $params
                                

2. Adding Multiple Users (array loaded in memory)

$administrativeUnitId = "00000000-0000-0000-0000-000000000000"
$upns = @(
    "alexw@contoso.com",
    "meganb@contoso.com",
    "diegoS@contoso.com"
)
foreach ($upn in $upns) {
    $id = (Get-MgUser -UserId $upn).Id
    $params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/users/$id" }
    New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $params
}
                                

3. Adding Multiple Users via CSV

CSV layout (save as upns-to-au.csv):

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

Script:

# Bulk add users (by UPN) to an Administrative Unit
# Prereqs: Connect-MgGraph; ensure you have AdministrativeUnit.ReadWrite.All
# Tip: Use Get-MgDirectoryAdministrativeUnit to fetch the AU Id.
                                    
$administrativeUnitId = "00000000-0000-0000-0000-000000000000"  #  replace
$csvPath = ".\upns-to-au.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 Id
    $user = Get-MgUser -UserId $upn -ErrorAction Stop
                                    
    # Build reference payload
    $params = @{ "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($user.Id)" }

    # Add to AU
    New-MgDirectoryAdministrativeUnitMemberByRef `
    -AdministrativeUnitId $administrativeUnitId `
    -BodyParameter $params `
    -ErrorAction Stop
                                    
    Write-Host ("Added {0} ({1}) to AU {2}" -f $upn, $user.Id, $administrativeUnitId)
    }
catch {
    Write-Warning ("Failed to add {0}: {1}" -f $upn, $_.Exception.Message)
}
}
                                


4. Adding a Group to an AU

$administrativeUnitId = "00000000-0000-0000-0000-000000000000"
$groupId = (Get-MgGroup -Filter "displayName eq 'HR Managers'").Id
                                    
$params = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/groups/$groupId"
}
                                    
New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $params
                                

5. Adding a Device to an AU

$administrativeUnitId = "00000000-0000-0000-0000-000000000000"
$deviceId = (Get-MgDevice -Filter "displayName eq 'LAPTOP-42'").Id
                                    
$params = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/devices/$deviceId"
}
                                    
New-MgDirectoryAdministrativeUnitMemberByRef -AdministrativeUnitId $administrativeUnitId -BodyParameter $params
                                

iii) Cmdlet Tips

• Always use -BodyParameter with @odata.id.

The value must be a fully qualified Graph v1.0 URL:

• Users → https://graph.microsoft.com/v1.0/users/{id}
• Groups → https://graph.microsoft.com/v1.0/groups/{id}
• Devices → https://graph.microsoft.com/v1.0/devices/{id}
• Resolve UPNs to Ids with Get-MgUser before building the @odata.id.
• No output on success. The cmdlet returns nothing. Verify by listing AU members afterward.
• Permissions required. Ensure the account/app has AdministrativeUnit.ReadWrite.All.
• To remove a member, use Remove-MgDirectoryAdministrativeUnitMemberByRef.

iv) Use Cases

• Scoped administration: Grant delegated admins limited control over specific subsets of users, groups, or devices.
• Regional or departmental partitioning: Organize members into AUs for targeted policy application.
• Onboarding automation: Automatically add new users to the correct AU as part of account provisioning.
• Bulk reassignments: Simplify moving entire departments or groups between AUs during reorganization.

v) Possible Errors & Solutions

Error	Cause	Solution
Authorization_RequestDenied / 403	Missing permission	Grant AdministrativeUnit.ReadWrite.All. Re-authenticate if needed.
ResourceNotFound (404)	Wrong AU ID or object not found	Confirm AU ID with Get-MgDirectoryAdministrativeUnit and user/group/device IDs with Get-MgUser, Get-MgGroup, or Get-MgDevice.
Request_BadRequest (400)	Malformed @odata.id	Ensure it follows the correct format: https://graph.microsoft.com/v1.0/{entity}/{id}.
Request_ResourceAlreadyExists (409)	Member already added	Handle gracefully in loops, or check membership before adding.
Throttling (429)	Too many requests	Add delays (Start-Sleep) or implement retry logic.

vi) Conclusion

New-MgDirectoryAdministrativeUnitMemberByRef is the Graph-native way to add users, groups, and devices to Administrative Units. With support for single adds, arrays, and CSV imports, it’s well suited for both small and large-scale admin scenarios.

Stick to the -BodyParameter with @odata.id, confirm AU IDs with Get-MgDirectoryAdministrativeUnit, and ensure proper permissions. With these best practices, you’ll have a reliable, automatable method for scoped administration at scale.