Export (0) Print
Expand All

New-RoleGroup

Applies to: Exchange Server 2010

Topic Last Modified: 2011-03-19

Use the New-RoleGroup cmdlet to create a management role group on a server running Microsoft Exchange Server 2010.


New-RoleGroup -Name <String> -Roles <RoleIdParameter[]> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-Description <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-ManagedBy <MultiValuedProperty>] [-Members <MultiValuedProperty>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-SamAccountName <String>] [-WhatIf [<SwitchParameter>]]


New-RoleGroup -Name <String> -LinkedDomainController <String> -LinkedForeignGroup <UniversalSecurityGroupIdParameter> -Roles <RoleIdParameter[]> [-Confirm [<SwitchParameter>]] [-CustomConfigWriteScope <ManagementScopeIdParameter>] [-CustomRecipientWriteScope <ManagementScopeIdParameter>] [-Description <String>] [-DisplayName <String>] [-DomainController <Fqdn>] [-LinkedCredential <PSCredential>] [-ManagedBy <MultiValuedProperty>] [-Members <MultiValuedProperty>] [-Organization <OrganizationIdParameter>] [-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>] [-SamAccountName <String>] [-WhatIf [<SwitchParameter>]]

Parameter Required Type Description

LinkedDomainController

Required

System.String

The LinkedDomainController parameter specifies the fully qualified domain name (FQDN) or IP address of the domain controller in the forest where the foreign USG resides. The domain controller you specify is used to get security information for the foreign USG specified by the LinkedForeignGroup parameter.

If you use the LinkedDomainController parameter, you must specify a foreign USG with the LinkedForeignGroup parameter, and you can't use the Members parameter.

LinkedForeignGroup

Required

Microsoft.Exchange.Configuration.Tasks.UniversalSecurityGroupIdParameter

The LinkedForeignGroup parameter specifies the name of the foreign USG you want to link this role group to. If the foreign USG name contains spaces, enclose the name in quotation marks (").

If you use the LinkedForeignGroup parameter, you must specify a domain controller in the LinkedDomainController parameter, and you can't use the Members parameter.

Name

Required

System.String

The Name parameter specifies the name of the new role group. The name can have a maximum of 64 characters. If the name contains spaces, enclose the name in quotation marks (").

Dd638181.note(en-us,EXCHG.140).gifNote:
If you create a linked role group, we recommend that you include the name of the foreign forest in the name of the role group so that you can more easily associate the linked role group and the associated foreign forest. This is especially important if you have multiple forests.

Roles

Required

Microsoft.Exchange.Configuration.Tasks.RoleIdParameter[]

The Roles parameter specifies the management roles to assign to the role group when it's created. If a role name contains spaces, enclose the name in quotation marks ("). If you want to assign more that one role, separate the role names with commas.

For a list of built-in management roles that you can assign to a role group, see Built-in Management Roles.

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-based management scope to associate with management role assignments created with this role group. If the management scope name contains spaces, enclose the name in quotation marks ("). Use the Get-ManagementScope cmdlet to retrieve a list of existing management scopes.

CustomRecipientWriteScope

Optional

Microsoft.Exchange.Configuration.Tasks.ManagementScopeIdParameter

The CustomRecipientWriteScope parameter specifies the existing recipient-based management scope to associate with management role assignments created with this role group. If the management scope name contains spaces, enclose the name in quotation marks (").

Use the Get-ManagementScope cmdlet to retrieve a list of existing management scopes.

If you use the CustomRecipientWriteScope parameter, you can't use the RecipientOrganizationalUnitScope parameter.

Description

Optional

System.String

The Description parameter specifies the description that's displayed when the role group is viewed using the Get-RoleGroup cmdlet. Enclose the description in quotation marks (").

DisplayName

Optional

System.String

The DisplayName parameter specifies the friendly name of the role group. If the name contains spaces, enclose the name in quotation marks ("). This parameter can have a maximum length of 256 characters.

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.

LinkedCredential

Optional

System.Management.Automation.PSCredential

The LinkedCredential parameter specifies credentials to use to access the domain controller specified by the LinkedDomainController parameter.

This parameter requires the creation and passing of a credential object. This credential object is created by using the Get-Credential cmdlet. For more information, see Get-Credential.

ManagedBy

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The ManagedBy parameter specifies the users or USGs who can modify the configuration of a role group or add and remove members to or from a role group.

You can use the name, distinguished name (DN), or primary SMTP address of the user or USG that you want to add. If the name of the user or USG contains spaces, enclose the name in quotation marks (").

If you want to add more than one user or USG, separate them using commas.

Members

Optional

Microsoft.Exchange.Data.MultiValuedProperty

The Members parameter specifies the mailboxes or USGs to add as a member of the role group. You can use the name, DN, or primary SMTP address of the user or USG you want to add. If the name of the user or USG contains spaces, enclose the name in quotation marks ("). If you want to add more than one user or USG, separate them using commas.

If you use the Members parameter, you can't use the LinkedForeignGroup, LinkedDomainController, or LinkedCredential parameters.

Organization

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationIdParameter

The Organization parameter is reserved for internal Microsoft use.

RecipientOrganizationalUnitScope

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

The RecipientOrganizationalUnitScope parameter specifies the organizational unit (OU) scope added to the role assignments created when the role group is created. If you use the RecipientOrganizationalUnitScope parameter, you can't use the CustomRecipientWriteScope parameter. To specify an OU (or several OUs), use the syntax: domain /OU 1/OU 2/OU N (where N is the designation of each of the specified OUs).

SamAccountName

Optional

System.String

The SamAccountName parameter specifies the logon name used to support clients and servers running older versions of the operating system, such as Microsoft Windows NT 4.0, Windows 98, Windows 95, and LAN Manager. This attribute must contain fewer than 20 characters.

If you don't specify this parameter, Active Directory creates a value for the SamAccountName parameter automatically, based on the user principal name (UPN).

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.

When you create a role group, you must specify the management roles you want to assign to the role group. You don't have to add members to the role group when you create it. However, until you add members to the role group, no users are granted the permissions provided by the role group. You can also specify custom configuration or recipient scopes when you create a role group. These scopes are applied to the management role assignments created when the role group is created.

When you create a role group, you can create the group and add members to it directly, or you can create a linked role group. A linked role group links the role group to a universal security group (USG) in another forest. Creating a linked role group is useful if your servers running Exchange reside in a resource forest and your users and administrators reside in a separate user forest. If you create a linked role group, you can't add members directly to it. You must add the members to the USG in the foreign forest.

For more information about role groups, see Understanding Management Role Groups.

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 groups" entry in the Role Management Permissions topic.

Error Description

 

This example creates a role group. The Mail Recipients and Reset Password roles are assigned to the role group, and the users Kim and Martin are added as members. Because no scopes were provided, Kim and Martin can manage any recipient and reset passwords for any users in the organization.

New-RoleGroup -Name "Limited Recipient Management" -Roles "Mail Recipients", "Reset Password" -Members Kim, Martin

This example creates a role group with a custom recipient scope. The custom recipient scope, Seattle Recipients, limits the scope of the roles assigned to the role group to recipients who have their City property set to Seattle. The Mail Recipients and Reset Password roles are assigned to the role group, and the users John and Beth are added as members.

New-RoleGroup -Name "Seattle Limited Recipient Management" -Roles "Mail Recipients", "Reset Password" -Members John, Beth -CustomRecipientWriteScope "Seattle Recipients"

This example creates a role group and enables Isabel to add or remove members to and from the role group by adding her to the ManagedBy property. The Transport Rules role is assigned to the role group, and the Compliance Group USG is added as a member.

New-RoleGroup -Name "Transport Rules Management" -Roles "Transport Rules" -Members "Compliance Group" -ManagedBy Isabel

This example creates a linked role group that enables the members of the Toronto Administrators USG in the Contoso user forest to manage recipients located in the Toronto office. The custom recipient scope, Toronto Recipients, limits the scope of the roles assigned to the role group to recipients who have their City property set to Toronto. The Mail Recipients role is assigned to the role group.

First, the credentials for the user forest need to be stored in a variable so they can be used with the New-RoleGroup cmdlet. The following command retrieves the credentials using the Get-Credential cmdlet and stores them in the $Credentials variable.

$Credentials = Get-Credentials

Then the linked role group is created using the following command.

New-RoleGroup -Name "ContosoUsers: Toronto Recipient Admins" -LinkedDomainController dc02.contosousers.contoso.com -LinkedCredential $Credentials -LinkedForeignGroup "Toronto Administrators" -CustomRecipientWriteScope "Toronto Recipients" -Roles "Mail Recipients"
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft