5. Performing Advanced Permissions Management
Advanced
permissions areas you can work with are related to custom management
roles, management scopes, and role entries. Management roles define the
management tasks users can perform. Management scopes identify the
objects that are allowed to be managed. Role entries are the individual
permission entries on a management role that allow users to perform management tasks.
5.1. Creating Custom Roles
The built-in roles were listed previously in Tables Table 8-5 to Table 8-7.
The built-in roles are fixed, and you cannot create role entries to
define additional management tasks for built-in roles. You can, however,
create your own custom roles based on built-in roles and then extend
the custom roles as necessary to meet the needs of your organization. In
this way, custom management roles allow you to do things you can't do
with the built-in roles.
Commands you use to create your own custom roles and to view any existing roles include the following:
Get-ManagementRole
Displays a complete or filtered list of management roles defined in the
organization. Role types are the same as those listed previously
without spaces in their names.
Get-ManagementRole [-Identity RoleName] [-DomainController
FullyQualifiedName] [-Organization OrganizationId] [-RoleType
RoleType] {AddtlParams}
{AddtlParams}
{ [-Cmdlet Cmdlet] [-CmdletParameters Parameters] |
[-GetChildren {$True|$False}] |
[-Script Script] [-ScriptParameters Parameters] |
[-Recurse {$True|$False}] }
New-ManagementRole Creates a new management role.
New-ManagementRole -Name RoleName
[-Parent ParentRoleToCopy | -UnScopedTopLevel {$True|$False}]
[-Description Description] [-DomainController FullyQualifiedName]
[-Organization OrganizationId]
Remove-ManagementRole Removes a management role.
Remove-ManagementRole [-Identity RoleName]
[-DomainController FullyQualifiedName] [-Recurse {$True|$False}]
[-UnScopedTopLevel {$True|$False}]
To view management roles, you
use Get-ManagementRole. Entering Get-ManagementRole by itself without
parameters lists all the roles in your organization. Additional options
include using
–Identity, to view information about a specific role
–Cmdlet, to list all roles that include a specified cmdlet
–CmdletParameters, to list all roles that include the specified cmdlet parameter or parameters
–GetChildren, to list only the child roles of a specified parent role
–Recurse, to list the role specified in the –Identity parameter, its child roles, and their children
–RoleType, to list all roles of a particular type
–Script, to list all roles that include a specified script
–ScriptParameters, to list all roles that include the specified script parameter or parameters
In the following example, you list all the roles associated with the Mail Recipient Creation role:
Get-ManagementRole "Mail Recipient Creation" -Recurse
You can create your own custom
roles using New-ManagementRole. New roles can either be empty top-level
roles or based on an existing parent role. In this example, you create
an empty role:
New-ManagementRole -Name "Change Management"
-UnscopedTopLevel
In the following example, you create a new role based on the Organization Client Access role:
New-ManagementRole -Name "Organization Client Access View-Only"
-Parent "Organization Client Access"
After you create a role based
on another role, you might need to remove role entries that are not
required. In the following example, you ensure the Organization Client
Access View-Only role grants only permission to view Client Access
information by removing any entries for commands that don't begin with
Get:
Get-ManagementRoleEntry "Organization Client Access View-Only\*" |
Where { $_.Name -NotLike "Get*" } | Remove-ManagementRoleEntry
To remove a custom role, you use Remove-ManagementRole. You can remove a role by name as shown in the following example:
Remove-ManagementRole "Organization Client Access View-Only"
Using the –Recurse
parameter, you can remove all child roles of a role. Using the
–UnscopedTopLevel parameter, you can remove an unscoped top-level role.
You also can use Get-ManagementRole to obtain a list of roles to remove
as shown in this example:
Get-ManagementRole *MyTestRole* | Remove-ManagementRole
Tip:
To avoid accidentally removing a number of important roles, you should run Get-ManagementRole
by itself first or add the –WhatIf parameter to Remove-ManagementRole.
Either technique will ensure you know exactly which roles you are
working with.
5.2. Creating Custom Role Scopes
Every management role
has a management scope that determines where in Active Directory objects
can be viewed or modified by users assigned the management role.
Management scopes can be defined as either regular or exclusive. Regular
scopes can be either implicitly or explicitly created. They are simply
the standard type of scope, and they define the set of recipients that
can be managed. Exclusive scopes on the other hand must always be
explicitly created, and they allow you to deny users access to objects
contained within the exclusive scope if those users aren't assigned a
role associated with the exclusive scope.
Scopes can be
Inherited from the management role
Specified as a predefined relative scope on a management role assignment
Created using custom filters, and added to a management role assignment.
Scopes inherited from management roles are called implicit scopes, while predefined and custom scopes are called explicit scopes. Implicit scopes include
Recipient read scope Determines which recipient objects the user assigned the management role is allowed to read from Active Directory.
Recipient write scope Determines which recipient objects the user assigned the management role is allowed to modify in Active Directory.
Configuration read scope Determines which configuration objects the user assigned the management role is allowed to read from Active Directory.
Configuration write scope
Determines which organizational and server objects the user assigned
the management role is allowed to modify in Active Directory.
Commands you use to work with scopes include the following:
Get-ManagementScope Displays a complete or filtered list of management scopes defined in the organization.
Get-ManagementScope [-Identity ScopeName]
[-Exclusive {$True|$False}] [-DomainController FullyQualifiedName]
[-Organization OrganizationId] [-Orphan {$True|$False}]
New-ManagementScope Creates a new management scope.
New-ManagementScope -Name ScopeName -RecipientRestrictionFilter
Filter [-RecipientRoot Root] {AddtlParams}
New-ManagementScope -Name ScopeName
-ServerList Servers | -ServerRestrictionFilter Filter{AddtlParams}
{AddtlParams}
[-DomainController FullyQualifiedName] [-Organization
OrganizationId] [-Exclusive {$True|$False}] [-Force {$True|$False}]
Remove-ManagementScope Removes a management scope.
Remove-ManagementScope [-Identity Scope]
[-DomainController FullyQualifiedName]
Set-ManagementScope Modifies the settings of a management scope.
Set-ManagementScope -Identity ScopeName-ServerRestrictionFilter
Filter[-DomainController FullyQualifiedName] [-Name Name]
Set-ManagementScope -Identity ScopeName-RecipientRestrictionFilter
Filter [-RecipientRoot Root] [-DomainController FullyQualifiedName]
[-Name Name]
You use Get-ManagementScope to
retrieve a list of existing management scopes. If you want to list only
exclusive scopes, use the –Exclusive parameter. If you want to list only
management scopes that aren't associated with role assignments, use the
–Orphan parameter, as shown here:
Get-ManagementScope -Orphan
You can create custom
management scopes using New-ManagementScope. After you create a regular
or exclusive scope, you need to associate the scope with a management
role assignment. One way to do this is to use
New-ManagementRoleAssignment.
You define scopes using
recipient restriction filters, explicit server lists, or server
restriction filters. In the following example, you create the Sales Team
scope that applies only to mailboxes located in the Sales
organizational unit:
New-ManagementScope -Name "Sales Team Scope" -RecipientRoot
"cpandl.com/Sales" -RecipientRestrictionFilter {RecipientType -eq
"UserMailbox"}
In the following example, you create a scope that applies only to MailServer14 and MailServer18:
New-ManagementScope -Name "Main Server Scope" -ServerList
"MailServer14", "MailServer18"
In the following example,
you create a scope that applies only to servers in the Active Directory
site called Seattle-First-Site:
New-ManagementScope -Name "Seattle Site Scope" -ServerRestrictionFilter
{ServerSite -eq "Seattle-First-Site"}
Exclusive scopes work a
bit differently. When an exclusive scope is created, all users are
immediately blocked from modifying the recipients that match the
exclusive scope until the scope is associated with a management role
assignment. If other role assignments are associated with other
exclusive scopes that match the same recipients, those assignments can
still modify the recipients. In the following example, you create a
Protected Managers exclusive scope for users that contain the string
"Manager" in their job title:
New-ManagementScope -Name "Protected Managers"
-RecipientRestrictionFilter { Title -Like "*Manager*" } -Exclusive
You then need to associate the
exclusive scope with a management role assignment that assigns the
appropriate management roles to the appropriate role group or groups. In
the following example, members of the Level 5 Administrators security
group are granted permission to work with Protected Manager mailboxes:
New-ManagementRoleAssignment -Name "Level 5 Administrators_Mail
Recipients" -SecurityGroup "Level 5 Administrators" -Role "Mail
Recipients" -CustomRecipientWriteScope "Protected Managers"
You use Set-ManagementScope
to modify the settings of a management scope. If you change a scope that
has been associated with management role assignments, the updated scope
applies to all of the associated role assignments. To remove a
management scope, you can use Remove-ManagementScope. However, you can't
remove a management scope if it's associated with a role assignment.
5.3. Creating Custom Role Entries
Role entries determine
the management actions that members of a role group can perform. You
create a role entry by specifying the permitted management command and
any permitted command parameters.
When you assign a
management role to a role group, this is essentially similar to creating
the related role entries that allow a user or group to perform related
management tasks. Another way to grant permission to perform a
management action is to create a management role entry and add it to a
management role. However, keep in mind that you can't add role entries
to built-in roles.
Commands you use to work with role entries include
Add-ManagementRoleEntry
Adds role entries to a custom management role. You can't add role
entries to built-in roles. The –UnScopedTopLevel parameter allows you to
specify that you're adding a custom script or non-Exchange cmdlet to an
unscoped top-level management role.
Add-ManagementRoleEntry -Identity RoleEntryToAdd
[-DomainController FullyQualifiedName] [-Overwrite {$True|$False}]
[-Parameters CmdletParametersToUse]
[-PSSnapinName SnapinThatContainsCmdlet]
[-Type <Cmdlet | Script | ApplicationPermission | All>]
[-UnScopedTopLevel {$True|$False}]
Add-ManagementRoleEntry -ParentRoleEntry ParentRoleEntry
-Role Role [-DomainController FullyQualifiedName]
[-Overwrite {$True|$False}]
Get-ManagementRoleEntry Lists the role
entries configured on a particular role. You can list role entries that
match specific criteria such as role name, cmdlet name, parameter name,
role entry type, or associated PowerShell snap-in.
Get-ManagementRoleEntry -Identity RoleEntry
[-DomainController FullyQualifiedName]
[-Parameters CmdletParameters] [-PSSnapinName Snapin]
[-Type <Cmdlet | Script | ApplicationPermission | All>]
Remove-ManagementRoleEntry Removes a management role entry.
Remove-ManagementRoleEntry -Identity RoleEntry
[-DomainController FullyQualifiedName]
Set-ManagementRoleEntry Modifies a management role entry.
Set-ManagementRoleEntry -Identity RoleEntry
[-AddParameter {$True|$False} | -RemoveParameter {$True|$False}]
[-Parameters ParametersToAddOrRemove]
[-DomainController FullyQualifiedName]
[-UnScopedTopLevel {$True|$False}]
Every management role must have
at least one management role entry. A role entry consists of a single
cmdlet and its parameters, a script, or a special permission that you
want to make available. If a cmdlet or script doesn't appear as an entry
on a management role, that cmdlet or script isn't accessible via that
role. Similarly, if a parameter isn't specified in a role entry, the
parameter on that cmdlet or script isn't accessible via that role.
The way you create and
work with role entries depends on whether they are based on the built-in
roles or unscoped roles. Roles based on built-in roles can contain only
role entries that are Exchange 2010 cmdlets. To use custom scripts or
non-Exchange cmdlets, you need to add them as unscoped role entries to an unscoped top-level role.
You can't add management
role entries to child roles if the entries don't appear in parent
roles. For example, if the parent role doesn't have an entry for
New-Mailbox, the child role can't be assigned that cmdlet. Additionally,
if Set-Mailbox is on the parent role but the –Database parameter has
been removed from the entry, the –Database parameter on the Set-Mailbox
cmdlet can't be added to the entry on the child role. With this in mind,
you need to carefully choose the parent role to copy when you want to
create a new customized role.
Role entry names are a
combination of the management role that they're associated with and the
name of the cmdlet or script that you want to make available. The role
name and the cmdlet or script are separated by a backslash character
(\). For example, the role entry name for the New-Mailbox cmdlet on the
Mail Recipient Creation role is Mail Recipient Creation\New-Mailbox.
You can use the
wildcard character (*) in the role entry name to return all of the role
entries that match the input you provide. The wildcard character can be
used with role names as well as with cmdlet or script names. For
example, you can use *\* to return a list of all role entries for all
roles, *\New-Mailbox to return a list of all role entries that contain
the New-Mailbox cmdlet, or Mail Recipient Creation\* to return a list of
all role entries on the Mail Recipient Creation role.
When you create a role
entry, you need to specify all of the parameters that can be used.
Exchange will try to verify the parameters that you provide when you add
the role entry. Only the parameters that you include are available to
the users assigned to the role. You need to update role entries manually
if parameters available for cmdlets or scripts change.
To avoid errors, keep the following in mind:
Scripts that you add
to an unscoped role entry must reside in the Exchange 2010 scripts
directory on every server where administrators and users connect using
the Exchange Management Shell. The default scripts directory is
C:\Program Files\Microsoft\Exchange Server\V14\Scripts.
Non-Exchange
cmdlets that you add to an unscoped role entry must be installed on
every Exchange 2010 server where administrators and users connect using
the Exchange Management Shell. When you add a non-Exchange cmdlet, you
must specify the Windows PowerShell snap-in name that contains the
non-Exchange cmdlet.
You use
Get-ManagementRoleEntry to list role entries that have been configured
on roles. In the following example, you list all the role entries that
exist on the Mail Recipient Creation role:
Get-ManagementRoleEntry "Mail Recipient Creation\*"
You also can list all the role entries that contain a particular command, as shown here:
Get-ManagementRoleEntry *\Get-Recipient
You can list role entries that
match specific criteria such as role name or cmdlet name. Using
Add-ManagementRoleEntry, you can specify role entries to add to a role.
You specify the role entry to add using the –Identity parameter and the
basic syntax for the identity as RoleName\CmdletName. Role entries are
either based on a parent role entry or are unscoped (the default),
specified using the –ParentRoleEntry or –UnScopedTopLevel parameter,
respectively. The –Role parameter specifies the role to which the new
role entry is added.
In the following example, you add a role entry for the Get-Mailbox cmdlet to the LA Recipient Managers role:
Add-ManagementRoleEntry -Identity "LA Recipient Managers\Get-Mailbox"
This entry assigns
permission for the Get-Mailbox cmdlet to members of the LA Recipient
Managers role. You can specify the exact parameters that are permitted
as shown in the following example:
Add-ManagementRoleEntry -Identity "LA Recipient Managers\Get-Mailbox"
-Parameters Archive, Identity, Filter, OrganizationalUnit, SortBy
You can also assign permission for multiple commands. Consider the following example:
Get-ManagementRoleEntry "Mail Recipients\Get-Mailbox*" |
Add-ManagementRoleEntry -Role "Central Help Desk"
Here, you use
Get-ManagementRoleEntry to retrieve a list of all the role entries for
the Mail Recipients role that begin with the string "Get-Mailbox" in the
cmdlet name, and then add them to the Central Help Desk role using the
Add-ManagementRoleEntry cmdlet. The role entries are added to the child
role exactly as they're configured on the parent role, Mail Recipients.
You use
Set-ManagementRoleEntry to change the available parameters on an
existing management role entry. With the –AddParameter parameter, the
parameters you specify are added to the role entry. With the
–RemoveParameter parameter, the parameters you specify are removed from
the role entry. Otherwise, only the parameters you specify are included
in the role entry. For example, with Get-Mailbox you might want users to
be able to specify a server and limit the result set size, and you can
do this by adding the –Server and –ResultSize parameters as shown in
this example:
Set-ManagementRoleEntry -Identity "LA Recipient Managers\Get-Mailbox"
-AddParameter Server, ResultSize
To remove all parameters,
set –Parameters to $Null and don't use either –AddParameter or
–RemoveParameter as shown in this example:
Set-ManagementRoleEntry -Identity "LA Recipient Managers\Get-Mailbox"
-Parameters $Null
You use Remove-ManagementRoleEntry to remove role entries. However, you can't remove role entries from built-in management roles.
