New-ManagementRoleAssignment

Syntax

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

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>]

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>]

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>]

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

Description

When you add a new role assignment, you can specify a built-in or custom role that was created using the New-ManagementRole cmdlet and specify an organizational unit (OU) or predefined or custom management scope to restrict the assignment.

You can create custom management scopes using the New-ManagementScope cmdlet and can view a list of existing scopes using the Get-ManagementScope cmdlet. If you choose not to specify an OU, or predefined or custom scope, the implicit write scope of the role applies to the role assignment.

For more information about management role assignments, see Understanding management role assignments.

You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.

Examples

Example 1

New-ManagementRoleAssignment -Role "Mail Recipients" -SecurityGroup "Tier 2 Help Desk"

This example assigns the Mail Recipients role to the Tier 2 Help Desk role group.

Example 2

Get-ManagementRole "MyVoiceMail" | Format-Table Name, IsEndUserRole

New-ManagementRoleAssignment -Role "MyVoiceMail" -Policy "Sales end-users"

This example assigns the MyVoiceMail role to the "Sales end-users" role assignment policy. First, the IsEndUserRole property on the MyVoiceMail role is verified to be sure it's set to $true, indicating it's an end-user role.

After the role has been verified to be an end-user role, the role is assigned to the "Sales end-users" role assignment policy.

Example 3

New-ManagementRoleAssignment -Role "Eng Help Desk" -SecurityGroup "Eng HD Personnel" -RecipientOrganizationalUnitScope contoso.com/Engineering/Users

This example assigns the Eng Help Desk role to the Eng HD Personnel role group. The assignment restricts the recipient write scope of the role to the contoso.com/Engineering/Users OU. Users who are members of the Eng HD Personnel role group can only create, modify, or remove objects contained within that OU.

Example 4

New-ManagementRoleAssignment -Role "Distribution Groups" -SecurityGroup "North America Exec Assistants" -CustomRecipientWriteScope "North America Recipients"

This example assigns the Distribution Groups role to the North America Exec Assistants role group. The assignment restricts the recipient write scope of the role to the scope specified in the North America Recipients custom recipient management scope. Users who are members of the North America Exec Assistants role group can only create, modify, or remove distribution group objects that match the specified custom recipient management scope.

Example 5

New-ManagementRoleAssignment -Name "Exchange Servers_John" -Role "Exchange Servers" -User John -CustomConfigWriteScope "Sydney Servers"

This example assigns the Exchange Servers role to John. Because John should only manage the servers running Exchange located in Sydney, the role assignment restricts the configuration write scope of the role to the scope specified in the Sydney Servers custom configuration role group. John can only manage servers that match the specified custom configuration management scope.

Example 6

New-ManagementRoleAssignment -Name "Excl-Mail Recipients_Executive Administrators" -Role "Mail Recipients" -SecurityGroup "Executive Administrators" -ExclusiveRecipientWriteScope "Exclusive-Executive Recipients"

This example assigns the Mail Recipients role to the Executive Administrators role group. The assignment restricts the recipient write scope of the role to the scope specified in the Exclusive-Executive Recipients exclusive recipient management scope. Because the Exclusive-Executive Recipients scope is an exclusive scope, only users of the Executive Administrators can manage the executive recipients that match the exclusive recipient scope. No other users, unless they're also assigned an assignment that uses an exclusive scope that matches the same users, can modify the executive recipients.

Example 7

New-ManagementRoleAssignment -Name "Mail Recipients_Contoso Seattle" -Role "Mail Recipients" -SecurityGroup "Contoso Sub - Seattle" -CustomConfigWriteScope "Contoso Databases" -RecipientOrganizationalUnitScope adatum.com/Contoso/Seattle/Users

This example assigns the Mail Recipients role to the Contoso Sub - Seattle role group. The administrators in this role group should only be allowed to create and manage mail recipients in specific databases that have been allocated for use by the Contoso subsidiary, A. Datum Corporation (adatum.com). Also, this group of administrators should only be allowed to manage the Contoso employees located in the Seattle office. This is done by creating a role assignment with both a database scope, to limit management of mail recipients to only the databases in the database scope and a recipient OU scope, to limit access to only the recipient objects within the Contoso Seattle OU.

Parameters

-App

-Computer

-Confirm

-CustomConfigWriteScope

-CustomRecipientWriteScope

-CustomResourceScope

-Delegating

-DomainController

-ExclusiveConfigWriteScope

-ExclusiveRecipientWriteScope

-Force

-Name

-Policy

-RecipientAdministrativeUnitScope

-RecipientGroupScope

-RecipientOrganizationalUnitScope

-RecipientRelativeWriteScope

-Role

-SecurityGroup

-UnScopedTopLevel

-User

-WhatIf

Inputs

Input types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn't accept input data.

Outputs

Output types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn't return data.