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

Topic Last Modified: 2012-11-19

Use the Set-ManagementRoleAssignment cmdlet to modify existing management role assignments.

Syntax

Set-ManagementRoleAssignment -Identity <RoleAssignmentIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-DomainController <Fqdn>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-RecipientRelativeWriteScope <None | NotApplicable | Organization | MyGAL | Self | MyDirectReports | OU | CustomRecipientScope | MyDistributionGroups | MyExecutive | ExclusiveRecipientScope | MailboxICanDelegate>] [-WhatIf [<SwitchParameter>]]
Set-ManagementRoleAssignment -Identity <RoleAssignmentIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-DomainController <Fqdn>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
Set-ManagementRoleAssignment -Identity <RoleAssignmentIdParameter> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-DomainController <Fqdn>] [-Enabled <$true | $false>] [-Force <SwitchParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-WhatIf [<SwitchParameter>]]
Set-ManagementRoleAssignment -Identity <RoleAssignmentIdParameter> [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Enabled <$true | $false>] [-ExclusiveConfigWriteScope <ManagementScopeIdParameter>] [-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>] [-Force <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Detailed Description

When you modify a role assignment, you can specify a new predefined or custom management scope or provide an organizational unit (OU) to scope the existing role 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, predefined scope, 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

Identity

Required

Microsoft.Exchange.Configuration.Tasks.RoleAssignmentIdParameter

The Identity parameter specifies the name of the management role assignment to modify. If the name of the management role contains spaces, enclose it 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 management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the CustomConfigWriteScope parameter, you can't use the ExclusiveConfigWriteScope parameter.

To remove a scope, specify a value of $null.

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 it in quotation marks (").

If you use the CustomRecipientWriteScope parameter, you can't use the RecipientOrganizationalUnitScope, RecipientRelativeWriteScope, or ExclusiveRecipientWriteScope parameters, and any configured OU or predefined scope on the role assignment is overwritten.

To remove a scope, specify a value of $null.

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.

Enabled

Optional

System.Boolean

The Enabled parameter specifies whether the management role assignment is enabled or disabled. The valid values are $true and $false.

ExclusiveConfigWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.ManagementScopeIdParameter

The ExclusiveConfigWriteScope parameter specifies the existing configuration exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveConfigWriteScope parameter, you can't use the CustomConfigWriteScope parameter.

To remove a scope, specify a value of $null.

ExclusiveRecipientWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.ManagementScopeIdParameter

The ExclusiveRecipientWriteScope parameter specifies the existing recipient-based exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveRecipientWriteScope parameter, you can't use the CustomRecipientWriteScope, RecipientOrganizationalUnitScope, or RecipientRelativeWriteScope parameters, and any configured OU or predefined scope on the role assignment is overwritten.

To remove a scope, specify a value of $null.

Force

Optional

System.Management.Automation.SwitchParameter

This parameter is reserved for internal Microsoft use.

RecipientOrganizationalUnitScope

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

The RecipientOrganizationalUnitScope parameter specifies the OU to scope the new role assignment to. If the OU name contains spaces, enclose the domain and OU in quotation marks (").

If you use the RecipientOrganizationalUnitScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientRelativeWriteScope parameters, and any predefined scopes or custom scopes on the role assignment are overwritten.

To specify an OU, use the syntax: domain/ou. To remove an OU, specify a value of $null.

RecipientRelativeWriteScope

Optional

Microsoft.Exchange.Data.Directory.SystemConfiguration.RecipientWriteScopeType

The RecipientRelativeWriteScope parameter specifies the type of restriction to apply to a recipient scope.

If you use the RecipientRelativeWriteScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientOrganizationalUnitScope parameters.

The available types are: None, Organization, MyGAL, Self, and MyDistributionGroups. If you specify a predefined scope, any custom scope or configured OU on the role assignment is overwritten.

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.

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 disables the Mail Recipients_Denver Help Desk role assignment. When a role assignment is disabled, the users assigned the role can no longer run cmdlets granted by the role.

Copy Code
Set-ManagementRoleAssignment "Mail Recipients_Denver Help Desk" -Enabled $false

EXAMPLE 2

This example changes the recipient scope for the MyGAL_KimA role assignment to MyGAL. When the recipient scope is changed to a predefined value, any previously defined OUs or custom scopes are overwritten.

Copy Code
Set-ManagementRoleAssignment "MyGAL_KimA" -RecipientRelativeWriteScope MyGAL

EXAMPLE 3

This example restricts the Mail Recipients_Marketing Admins role assignment to the contoso.com/North America/Marketing/Users OU. Users who are members of the Marketing Admins role group assigned the role assignment can create, modify, and remove objects only in the specified OU. When the RecipientOrganizationalUnitScope parameter is used, any predefined or custom scopes on the role assignment are overwritten.

Copy Code
Set-ManagementRoleAssignment "Mail Recipients_Marketing Admins" -RecipientOrganizationalUnitScope "contoso.com/North America/Marketing/Users"

EXAMPLE 4

This example restricts the Distribution Groups_Cairns Admins role assignment using the Cairns Recipients custom recipient management scope. Users that are members of the Cairns Admins role group assigned the role assignment can create, modify, and remove only the distribution group objects that match the Cairns Recipients custom recipient management scope.

Copy Code
Set-ManagementRoleAssignment "Distribution Groups_Cairns Admins" -CustomRecipientWriteScope "Cairns Recipients"