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.

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.

This example creates a role group and enables Isabel to add or remove members to or 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.

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.

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.

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.

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.

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.

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.

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

Note:

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.

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

This parameter is available only in on-premises Exchange 2013.

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

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

This parameter is available only in on-premises Exchange 2013.

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

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

This parameter is available only in on-premises Exchange 2013.

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.

PartnerManaged

Optional

System.Management.Automation.SwitchParameter

This parameter is reserved for internal Microsoft use.

RecipientOrganizationalUnitScope

Optional

Microsoft.Exchange.Configuration.Tasks.OrganizationalUnitIdParameter

This parameter is available only in on-premises Exchange 2013.

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.

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.

WellKnownObjectGuid

Optional

System.Guid

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.