New-MgDirectoryAdministrativeUnit: Create Administrative Units with Microsoft Graph PowerShell

Administrative Units (AUs) let you scope admin permissions to a subset of your tenant (e.g., a department or region). With Microsoft Graph PowerShell, you can create them quickly—individually or in bulk from a CSV.

Cmdlet Syntax

# Core cmdlet (expanded)
New-MgDirectoryAdministrativeUnit [-DisplayName <String>] [-Description <String>] [-AdditionalProperties <Hashtable>] [-WhatIf] [-Confirm]
                                
# Core cmdlet (BodyParameter pattern)
New-MgDirectoryAdministrativeUnit -BodyParameter <IMicrosoftGraphAdministrativeUnit>
                            

The cmdlet accepts direct parameters (e.g., -DisplayName, -Description) or a hashtable via -BodyParameter. It lives in the Microsoft.Graph.Identity.DirectoryManagement module.

What is an Administrative Unit? An AU is a container for users, groups, and devices that lets you delegate RBAC at a smaller scope than the whole tenant. Some AU features (like dynamic membership) have license requirements.

Usage Examples

1. Single Administrative Unit Creation

Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
New-MgDirectoryAdministrativeUnit `
-DisplayName "Sales Team AU" `
-Description "AU for Sales Department"

This creates a standard (non-dynamic) AU with the given display name and description.


2. Bulk Administrative Unit Creation (from CSV)

CSV file (sample content)

Save as administrative-units.csv:

DisplayName,Description
Sales Team AU,AU for Sales Department
HR Team AU,AU for Human Resources
Marketing AU,AU for Marketing Department

Bulk creation script (based on Example 1)

Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
$path = "C:\temp\administrative-units.csv"
if (-not (Test-Path $path)) { throw "CSV not found at $path" }
$rows = Import-Csv -Path $path
foreach ($row in $rows) {
    $name = $row.DisplayName.Trim()
    $desc = $row.Description
                                    
    if ([string]::IsNullOrWhiteSpace($name)) {
    Write-Warning "Skipped a row with empty DisplayName."
    continue
    }
                                    
    try {
        # Optional: check if an AU with same DisplayName already exists
        $existing = Get-MgDirectoryAdministrativeUnit -All `
        | Where-Object { $_.DisplayName -eq $name }
                                    
        if ($existing) {
        Write-Host "Already exists: $name — skipping."
        continue
        }
                                    
        New-MgDirectoryAdministrativeUnit `
        -DisplayName $name `
        -Description $desc
                                    
        Write-Host "Created AU: $name"
    }
    catch {
        Write-Warning "Failed to create AU '$name'. Error: $($_.Exception.Message)"
    }
}
                                

Notes:

• The pre-existence check uses Get-MgDirectoryAdministrativeUnit -All. Keep it if you want idempotent runs.
• If you later need dynamic AUs, you can add -MembershipRule "<rule>" plus the required properties.

Cmdlet Tips

• Permissions / Scopes: Use Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All" when creating AUs. App-only flows require the equivalent app permission.
• Module: Ensure the Microsoft.Graph.Identity.DirectoryManagement module is available (it’s part of the unified Graph module).
• Dynamic AUs: To create a dynamic AU, supply a valid membership rule via -MembershipRule (for example, target users where department -eq "Sales"). Dynamic features are subject to license requirements; review the Entra AU article.
• Open Type / Extensions: AUs are an “open type,” so you can add custom data using extensions or -AdditionalProperties.
• Next Steps: After creating an AU, add members with New-MgDirectoryAdministrativeUnitMember or view members with Get-MgDirectoryAdministrativeUnitMember.

Possible Errors & Solutions

Error	Cause	Solution
Authorization_RequestDenied or insufficient privileges	Missing or insufficient Graph scopes/permissions	Re-connect with Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All" (user delegated) or grant app permissions and consent.
BadRequest when using -MembershipRule	Invalid rule syntax or unsupported property	Validate the rule format and properties allowed for AU dynamic membership; check Entra AU docs and adjust.
Module/cmdlet not found	Graph module not installed/loaded	Install/Update and import the Microsoft Graph PowerShell modules, then retry.
Members can’t be managed via app permissions in a restricted AU	Restricted management AU blocks app modification	Assign a Microsoft Entra role to the application at the AU scope to allow programmatic changes.
Throttling or intermittent failures at scale	Service throttling	Add retry logic with backoff in your bulk script; batch runs or pause between creates (not shown above). (General Graph practice.)

Use Cases

• Departmental Delegation: Create per-department AUs (Sales, HR, Marketing) and assign Helpdesk roles scoped to each AU—no tenant-wide rights.
• Regional Administration: AU per country/region to align with data residency or local IT teams.
• Device/Group Segmentation: Target device or group management tasks to specific AUs for safer RBAC boundaries.
• Dynamic AUs for Lifecycle: Use membership rules to auto-group users by attributes (e.g., department, officeLocation) and keep scopes current.

Conclusion

New-MgDirectoryAdministrativeUnit is the fastest way to stand up least-privilege boundaries in Microsoft Entra ID. Start with a single AU (your Sales example), then scale using the CSV-based bulk script. As your needs mature, layer in dynamic membership (with the right licenses), add members, and assign roles scoped to each AU for clean, auditable RBAC.