Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2
Topic Last Modified: 2012-11-30
Use the New-RoleGroup cmdlet to create a management role group on a server running Microsoft Exchange Server 2010.
Syntax
New-RoleGroup <COMMON PARAMETERS>
|
New-RoleGroup -LinkedPartnerGroupId <String>
-LinkedPartnerOrganizationId <String> <COMMON
PARAMETERS>
|
New-RoleGroup -LinkedDomainController <String>
-LinkedForeignGroup <UniversalSecurityGroupIdParameter>
[-LinkedCredential <PSCredential>] <COMMON
PARAMETERS>
|
<COMMON PARAMETERS> -Name <String> [-Confirm
[<SwitchParameter>]] [-CustomConfigWriteScope
<ManagementScopeIdParameter>] [-CustomRecipientWriteScope
<ManagementScopeIdParameter>] [-Description <String>]
[-DisplayName <String>] [-DomainController <Fqdn>]
[-ExternalDirectoryObjectId <String>][-Force
<SwitchParameter>] [-ManagedBy <MultiValuedProperty>]
[-Members <MultiValuedProperty>] [-Organization
<OrganizationIdParameter>] [-PartnerManaged
<SwitchParameter>] [-RecipientOrganizationalUnitScope
<OrganizationalUnitIdParameter>][-Roles
<RoleIdParameter[]>] [-SamAccountName <String>]
[-ValidationOrganization <String>] [-WhatIf
[<SwitchParameter>]]
|
Detailed Description
You don't have to add members or assign management roles to the role group when you create it. However, until you add members or assign roles to the role group, the role group grants no permissions to users. 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.
Parameters
| 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. |
||
|
LinkedPartnerGroupId |
Required |
System.String |
This parameter is reserved for internal Microsoft use. |
||
|
LinkedPartnerOrganizationId |
Required |
System.String |
This parameter is reserved for internal Microsoft use. |
||
|
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 (").
|
||
|
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. |
||
|
ExternalDirectoryObjectId |
Optional |
System.String |
This parameter is reserved for internal Microsoft use. |
||
|
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. |
||
|
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 |
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. |
||
|
PartnerManaged |
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 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, use the syntax: domain/ou. If the OU name contains spaces, enclose the domain and OU in quotation marks ("). |
||
|
Roles |
Optional |
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. |
||
|
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). |
||
|
ValidationOrganization |
Optional |
System.String |
This parameter is reserved for internal Microsoft use. |
||
|
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. |
Note: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 creates a role group. The Mail Recipients and Mail Enabled Public Folders 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.
 Copy Code |
|
|---|---|
New-RoleGroup -Name "Limited Recipient Management" -Roles "Mail Recipients", "Mail Enabled Public Folders" -Members Kim, Martin |
|
EXAMPLE 2
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 Mail Enabled Public Folders roles are assigned to the role group, and the users John and Carol are added as members.
| Copy Code |
|
|---|---|
New-RoleGroup -Name "Seattle Limited Recipient Management" -Roles "Mail Recipients", "Mail Enabled Public Folders" -Members John, Carol -CustomRecipientWriteScope "Seattle Recipients" |
|
EXAMPLE 3
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.
| Copy Code |
|
|---|---|
New-RoleGroup -Name "Transport Rules Management" -Roles "Transport Rules" -Members "Compliance Group" -ManagedBy Isabel |
|
EXAMPLE 4
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.
| Copy Code |
|
|---|---|
$Credentials = Get-Credential |
|
Then the linked role group is created using the following command.
| Copy Code |
|
|---|---|
New-RoleGroup -Name "ContosoUsers: Toronto Recipient Admins" -LinkedDomainController dc02.contosousers.contoso.com -LinkedCredential $Credentials -LinkedForeignGroup "Toronto Administrators" -CustomRecipientWriteScope "Toronto Recipients" -Roles "Mail Recipients" |
|
EXAMPLE 5
This example takes an existing role group and copies the roles from that role group into a new custom role group. This can be useful if you want to create a role group similar to an existing role group but don't want to manually create all the role assignments. For example, you might want to create a role group that has most, but not all, of the management roles assigned to the "Recipient Management" role group.
First, store the existing role group in a variable using the following command.
| Copy Code |
|
|---|---|
$RoleGroup = Get-RoleGroup "Recipient Management" |
|
Then, create the custom role group using the following command.
| Copy Code |
|
|---|---|
New-RoleGroup "Limited Recipient Management" -Roles $RoleGroup.Roles |
|
The new "Limited Recipient Management" role group now has the same roles as "Recipient Management". Remove the role assignments you don't want using the Remove-ManagementRoleAssignment cmdlet. For example, you might not want members of the "Limited Recipient Management" role group to manage distribution groups. Use the following command to remove the role assignment between the "Distribution Groups" management role and the "Limited Recipient Management" role group.
| Copy Code |
|
|---|---|
Remove-ManagementRoleAssignment "Distribution Groups-Limited Recipient Management" |
|
This example uses variables to store information. For more information about variables, see User-Defined Variables.
EXAMPLE 6
You need to provide an Exchange 2010 Hybrid Edition product key on the hybrid server when you configure a hybrid deployment with Office 365. To obtain a Hybrid Edition product key, contact Office 365 support.