Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

Topic Last Modified: 2012-11-19

Use the New-ManagementRoleAssignment cmdlet to assign a management role to a management role group, management role assignment policy, user, or universal security group (USG).

Syntax

New-ManagementRoleAssignment [-Name <String>] -Role <RoleIdParameter> -User <UserIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-Delegating <SwitchParameter>] [-DomainController <Fqdn>] [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>] [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>] [-Force <SwitchParameter>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-RecipientRelativeWriteScope <None | NotApplicable | Organization | MyGAL | Self | MyDirectReports | OU | CustomRecipientScope | MyDistributionGroups | MyExecutive | ExclusiveRecipientScope | MailboxICanDelegate>] [-UnScopedTopLevel <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
New-ManagementRoleAssignment [-Name <String>] -Role <RoleIdParameter> -SecurityGroup <SecurityGroupIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-Delegating <SwitchParameter>] [-DomainController <Fqdn>] [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>] [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>] [-Force <SwitchParameter>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-RecipientRelativeWriteScope <None | NotApplicable | Organization | MyGAL | Self | MyDirectReports | OU | CustomRecipientScope | MyDistributionGroups | MyExecutive | ExclusiveRecipientScope | MailboxICanDelegate>] [-UnScopedTopLevel <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
New-ManagementRoleAssignment [-Name <String>] -Policy <MailboxPolicyIdParameter> -Role <RoleIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-DomainController <Fqdn>] [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>] [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>] [-Force <SwitchParameter>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-RecipientRelativeWriteScope <None | NotApplicable | Organization | MyGAL | Self | MyDirectReports | OU | CustomRecipientScope | MyDistributionGroups | MyExecutive | ExclusiveRecipientScope | MailboxICanDelegate>] [-UnScopedTopLevel <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
New-ManagementRoleAssignment [-Name <String>] -Computer <ComputerIdParameter> -Role <RoleIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-DomainController <Fqdn>] [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>] [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>] [-Force <SwitchParameter>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-RecipientRelativeWriteScope <None | NotApplicable | Organization | MyGAL | Self | MyDirectReports | OU | CustomRecipientScope | MyDistributionGroups | MyExecutive | ExclusiveRecipientScope | MailboxICanDelegate>] [-UnScopedTopLevel <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Detailed 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 all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Role assignments" entry in the Role Management Permissions topic.

Parameters

Parameter Required Type Description

Name

Optional

System.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 (").

Computer

Required

Microsoft.Exchange.Configuration.Tasks.ComputerIdParameter

The Computer parameter specifies the name of the computer to assign the management role to.

If you specify the Computer parameter, you can't specify the SecurityGroup, User, or Policy parameters.

Policy

Required

Microsoft.Exchange.Configuration.Tasks.MailboxPolicyIdParameter

The Policy parameter specifies the name of the management role assignment policy to assign the management role to.

The IsEndUserRole property of the role you specify using the Role parameter must be set to $true.

If you specify the Policy parameter, you can't specify the SecurityGroup, Computer, or User parameters. If the policy name contains spaces, enclose the name in quotation marks (").

Role

Required

Microsoft.Exchange.Configuration.Tasks.RoleIdParameter

The Role parameter specifies the existing role to assign. If the role name contains spaces, enclose the name in quotation marks (").

SecurityGroup

Required

Microsoft.Exchange.Configuration.Tasks.SecurityGroupIdParameter

The SecurityGroup parameter specifies the name of the management role group or universal security group (USG) to assign the management role to.

If you specify the SecurityGroup parameter, you can't specify the Policy, Computer, or User parameters. If the role group or USG name contains spaces, enclose the name in quotation marks (").

User

Required

Microsoft.Exchange.Configuration.Tasks.UserIdParameter

The User parameter specifies the name or alias of the user to assign the management role to.

If you specify the User parameter, you can't specify the SecurityGroup, Computer, or Policy parameters. If the value contains spaces, enclose the name in quotation marks (").

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

CustomConfigWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.ManagementScopeIdParameter

The CustomConfigWriteScope parameter specifies the existing configuration scope to associate with this management role assignment. If you use the CustomConfigWriteScope parameter you can't use the ExclusiveConfigWriteScope parameter. If the management scope name contains spaces, enclose the name in quotation marks (").

CustomRecipientWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.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 quotation marks ("). If you use the CustomRecipientWriteScope parameter, you can't use the RecipientOrganizationalUnitScope or ExclusiveRecipientWriteScope parameters.

Delegating

Optional

System.Management.Automation.SwitchParameter

The Delegating parameter specifies whether the user or USG assigned to the role can delegate the role to other users or groups. You don't have to specify a value with the Delegating parameter.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that writes this configuration change to Active Directory.

ExclusiveConfigWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.ManagementScopeIdParameter

The ExclusiveConfigWriteScope parameter specifies the exclusive configuration-based management scope to associate with the new role assignment. If you use the ExclusiveConfigWriteScope parameter, you can't use the CustomConfigWriteScope parameter. If the scope name contains spaces, enclose the name in quotation marks (").

ExclusiveRecipientWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.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 CustomRecipientWriteScope or RecipientOrganizationalUnitScope parameters. If the scope name contains spaces, enclose the name in quotation marks (").

Force

Optional

System.Management.Automation.SwitchParameter

This parameter is available for multi-tenant deployments. It isn't available for on-premises deployments. For more information about multi-tenant deployments, see Multi-Tenant Support.

The Force switch specifies whether to suppress warning or confirmation messages. This switch can be used when the task is run programmatically and prompting for administrative input is inappropriate. If the Force switch isn't provided in the command, you're prompted for administrative input. You don't have to specify a value with this parameter.

Organization

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationIdParameter

This parameter is available for multi-tenant deployments. It isn't available for on-premises deployments. For more information about multi-tenant deployments, see Multi-Tenant Support.

The Organization parameter specifies the organization in which you'll perform this action. This parameter doesn't accept wildcard characters, and you must use the exact name of the organization.

RecipientOrganizationalUnitScope

Optional

Microsoft.Exchange.Configuration.Tasks.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 ExclusiveRecipientWriteScope parameters. To specify an OU, use the syntax: domain/ou. If the OU name contains spaces, enclose the domain and OU in quotation marks (").

RecipientRelativeWriteScope

Optional

Microsoft.Exchange.Data.Directory.SystemConfiguration.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 RecipientRelativeWriteScope parameter is automatically set when the CustomRecipientWriteScope or RecipientOrganizationalUnitScope parameters are used.

Note:
Even though the NotApplicable, OU, MyDirectReports, CustomRecipientScope, MyExecutive, and ExclusiveRecipientScope values appear in the syntax block for this parameter, they can't be used directly on the command line. They are used internally by the cmdlet.

UnScopedTopLevel

Optional

System.Management.Automation.SwitchParameter

The UnScopedTopLevel switch specifies that the role provided with the Role parameter is an unscoped top level management role. You can only create a role assignment using the UnScopedTopLevel switch if the role specified using the Role parameter is an unscoped top level role.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

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.

Return 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.

Examples

EXAMPLE 1

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

Copy Code
New-ManagementRoleAssignment -Name "Mail Recipients_Tier 2 Help Desk" -Role "Mail Recipients" -SecurityGroup "Tier 2 Help Desk"

EXAMPLE 2

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:

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

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

Copy Code
New-ManagementRoleAssignment -Name "MyVoiceMail_Sales end-users" -Role "MyVoiceMail" -Policy "Sales end-users"

EXAMPLE 3

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 with that OU.

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

EXAMPLE 4

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.

Copy Code
New-ManagementRoleAssignment -Name "Distribution Groups_North America Exec Assistants" -Role "Distribution Groups" -SecurityGroup "North America Exec Assistants" -CustomRecipientWriteScope "North America Recipients"

EXAMPLE 5

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.

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

EXAMPLE 6

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 are also assigned an assignment that uses an exclusive scope that matches the same users, can modify the executive recipients.

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

EXAMPLE 7

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 that are 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.

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