New-EntraAdministrativeUnit

New-EntraAdministrativeUnit

    -DisplayName <String>
    [-Description <String>]
    [-MembershipType <String>]
    [-MembershipRule <String>]
    [-MembershipRuleProcessingState <String>]
    [-Visibility <String>]
    [<CommonParameters>]

The New-EntraAdministrativeUnit cmdlet creates an administrative unit in Microsoft Entra ID. Specify DisplayName parameter to create an administrative unit.

In delegated scenarios, the signed-in user must be assigned a supported Microsoft Entra role or a custom role that includes the microsoft.directory/administrativeUnits/allProperties/allTasks permission. The following least-privileged roles are supported for this operation:

• Privileged Role Administrator

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
New-EntraAdministrativeUnit -DisplayName 'TestAU'

DeletedDateTime Id                                   Description DisplayName Visibility
--------------- --                                   ----------- ----------- ----------
                bbbbbbbb-1111-2222-3333-cccccccccccc             TestAU

This example demonstrates how to create an administrative unit.

• -DisplayName parameter specifies the display name for the Administrative unit object.

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
New-EntraAdministrativeUnit -DisplayName 'Pacific Administrative Unit' -Description 'Administrative Unit for Pacific region'

DeletedDateTime Id                                   Description DisplayName IsMemberManagementRestricted Visibility
--------------- --                                   ----------- ----------- ---------------------------- ----------
                bbbbbbbb-1111-2222-3333-cccccccccccc Pacific Administrative Unit     test111     False

This example demonstrates how to create an administrative unit.

• -DisplayName parameter specifies the display name for the Administrative unit object.
• -Description parameter specifies a description for the Administrative unit object.

Connect-Entra -Scopes 'AdministrativeUnit.ReadWrite.All'
$displayName = 'Seattle District Technical Schools'
$description = 'Seattle district technical schools administration'
$membershipRule = '(user.country -eq "United States")'

New-EntraAdministrativeUnit `
    -DisplayName $displayName `
    -Description $description `
    -MembershipType 'Dynamic' `
    -MembershipRule $membershipRule `
    -MembershipRuleProcessingState 'On' `
    -Visibility 'HiddenMembership'

DeletedDateTime Id                                   Description                                       DisplayName                        Visibility
--------------- --                                   -----------                                       -----------                        ----------
                bbbbbbbb-1111-2222-3333-cccccccccccc Seattle district technical schools administration Seattle District Technical Schools HiddenMembership

This example demonstrates how to create an administrative unit with detailed configuration information.

• -DisplayName parameter specifies the display name for the Administrative unit object.
• -Description parameter specifies a description for the Administrative unit object.
• -MembershipRule parameter specifies the dynamic membership rule applied to the administrative unit.
• -MembershipType parameter specifies the membership type of the administrative unit. Possible values are: dynamic and assigned. If not set, the default value is null, and the membership type defaults to assigned.
• -MembershipRuleProcessingState parameter controls if the dynamic membership rule is active. Set to On to enable it or Paused to stop updates.
• -Visibility parameter specifies the visibility of the administrative unit. Defaults to public if not set. Set to HiddenMembership to hide membership from nonmembers.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.