New-ManagementRoleAssignment — usage, script and reference

Quick start script

# New-ManagementRoleAssignment — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-ManagementRoleAssignment
$before | Format-List

# 3. Make the change (dry run first)
New-ManagementRoleAssignment -App <ServicePrincipalIdParameter> -Computer <ComputerIdParameter> -Policy <MailboxPolicyIdParameter> -WhatIf
New-ManagementRoleAssignment -App <ServicePrincipalIdParameter> -Computer <ComputerIdParameter> -Policy <MailboxPolicyIdParameter>

# 4. Verify and diff
$after = Get-ManagementRoleAssignment
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 5 parameter sets

App

New-ManagementRoleAssignment [[-Name] <String>] -Role <RoleIdParameter> -App <ServicePrincipalIdParameter> [-CustomResourceScope <ManagementScopeIdParameter>]
 [-Confirm]
 [-Delegating]
 [-Force]
 [-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
 [-RecipientGroupScope <GroupIdParameter>]
 [-WhatIf]
 [<CommonParameters>]

Computer

New-ManagementRoleAssignment [[-Name] <String>] -Computer <ComputerIdParameter> -Role <RoleIdParameter>
 [-Confirm]
 [-CustomConfigWriteScope <ManagementScopeIdParameter>]
 [-CustomRecipientWriteScope <ManagementScopeIdParameter>]
 [-DomainController <Fqdn>]
 [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>]
 [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>]
 [-Force]
 [-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
 [-RecipientGroupScope <GroupIdParameter>]
 [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>]
 [-RecipientRelativeWriteScope <RecipientWriteScopeType>]
 [-UnScopedTopLevel]
 [-WhatIf]
 [<CommonParameters>]

Policy

New-ManagementRoleAssignment [[-Name] <String>] -Policy <MailboxPolicyIdParameter> -Role <RoleIdParameter>
 [-Confirm]
 [-CustomConfigWriteScope <ManagementScopeIdParameter>]
 [-CustomRecipientWriteScope <ManagementScopeIdParameter>]
 [-DomainController <Fqdn>]
 [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>]
 [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>]
 [-Force]
 [-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
 [-RecipientGroupScope <GroupIdParameter>]
 [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>]
 [-RecipientRelativeWriteScope <RecipientWriteScopeType>]
 [-UnScopedTopLevel]
 [-WhatIf]
 [<CommonParameters>]

SecurityGroup

New-ManagementRoleAssignment [[-Name] <String>] -Role <RoleIdParameter> -SecurityGroup <SecurityGroupIdParameter>
 [-Delegating]
 [-Confirm]
 [-CustomConfigWriteScope <ManagementScopeIdParameter>]
 [-CustomRecipientWriteScope <ManagementScopeIdParameter>]
 [-DomainController <Fqdn>]
 [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>]
 [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>]
 [-Force]
 [-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
 [-RecipientGroupScope <GroupIdParameter>]
 [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>]
 [-RecipientRelativeWriteScope <RecipientWriteScopeType>]
 [-UnScopedTopLevel]
 [-WhatIf]
 [<CommonParameters>]

1 more parameter sets — see the parameter table below.

Parameters (22)

Parameter	Type	Required	What it controls
-Name	String		The Name parameter specifies a name for the new management role assignment. The maximum length of the name is 64 characters. If the management role assignment name contains spaces, enclose the name in quotation marks...
-App	ServicePrincipalIdParameter	yes	This parameter is available only in the cloud-based service.
-Computer	ComputerIdParameter	yes	This parameter is available only in on-premises Exchange.
-Policy	MailboxPolicyIdParameter	yes	The Policy parameter specifies the name of the management role assignment policy to assign the management role to. If the value contains spaces, enclose the value in quotation marks (").
-Role	RoleIdParameter	yes	The Role parameter specifies the existing role to assign. You can use any value that uniquely identifies the role. For example:
-SecurityGroup	SecurityGroupIdParameter	yes	The SecurityGroup parameter specifies the name of the management role group or mail-enabled universal security group to assign the management role to. If the value contains spaces, enclose the value in quotation marks (").
-User	UserIdParameter	yes	The User parameter specifies the user to assign the management role to.
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-CustomConfigWriteScope	ManagementScopeIdParameter		This parameter is available only in on-premises Exchange.
-CustomRecipientWriteScope	ManagementScopeIdParameter		The CustomRecipientWriteScope parameter specifies the existing recipient-based management scope to associate with this management role assignment. If the management scope name contains spaces, enclose the name in...
-CustomResourceScope	ManagementScopeIdParameter		This parameter is available only in the cloud-based service.
-Delegating	SwitchParameter		The Delegating switch specifies whether the user or USG assigned to the role can delegate the role to other users or groups. You don't need to specify a value with this switch.
-DomainController	Fqdn		This parameter is available only in on-premises Exchange.
-ExclusiveConfigWriteScope	ManagementScopeIdParameter		This parameter is available only in on-premises Exchange.
-ExclusiveRecipientWriteScope	ManagementScopeIdParameter		The ExclusiveRecipientWriteScope parameter specifies the exclusive recipient-based management scope to associate with the new role assignment. If you use the ExclusiveRecipientWriteScope parameter, you can't use the...
-Force	SwitchParameter		This parameter is available only in the cloud-based service.
-RecipientAdministrativeUnitScope	AdministrativeUnitIdParameter		This parameter is functional only in the cloud-based service.
-RecipientGroupScope	GroupIdParameter		This parameter is available only in the cloud-based service.
-RecipientOrganizationalUnitScope	OrganizationalUnitIdParameter		The RecipientOrganizationalUnitScope parameter specifies the OU to scope the new role assignment to. If you use the RecipientOrganizationalUnitScope parameter, you can't use the CustomRecipientWriteScope or...
-RecipientRelativeWriteScope	RecipientWriteScopeType		The RecipientRelativeWriteScope parameter specifies the type of restriction to apply to a recipient scope. The available types are None, Organization, MyGAL, Self, and MyDistributionGroups. The...
-UnScopedTopLevel	SwitchParameter		This parameter is available only in on-premises Exchange.
-WhatIf	SwitchParameter		The WhatIf switch shows what the command does without making any changes. You don't need to specify a value with this switch.