Get-CsAdminRole [-Identity <String>] [-LocalStore <SwitchParameter>]

Get-CsAdminRole [-Sid <String>] [-LocalStore <SwitchParameter>]

Get-CsAdminRole [-Filter <String>] [-LocalStore <SwitchParameter>]

Parameters

Role-Based Access control (RBAC) enables administrators to delegate control of specific management tasks in Microsoft Communications Server. For example, instead of granting help desk and support personnel full administrator privileges, you can give these employees very specific rights: the right to manage user accounts, and only user accounts; the right to manage Enterprise Voice components, and only Enterprise Voice components; the right to manage archiving and Archiving Server, and only archiving and Archiving Server. In addition, these rights can be limited in scope: someone can be given the right to manage Enterprise Voice, but only in the Redmond site; someone else can be given the right to manage users, but only if those user accounts are in the Finance OU.

The Microsoft Communications Server implementation of RBAC is based on two key elements: Active Directory security groups and Windows PowerShell cmdlets. When you install Microsoft Communications Server, a number of universal security groups - CsAdministrator, CsArchivingAdministrator, CsBranchOfficeTechnician, etc. - are created for you. These universal security groups have a one-to-one correspondence with RBAC roles; that means that any user who is in the CsArchivingAdministrator security group has all the rights granted to the CsArchivingAdministrator RBAC role. In turn, the rights granted to an RBAC role are based on the cmdlets assigned to that role (cmdlets can be assigned to multiple RBAC roles). For example, the CsArchivingAdministrator role has been assigned the following cmdlets:

Get-ArchivingPolicy

Grant-ArchivingPolicy

New-ArchivingPolicy

Remove-ArchivingPolicy

Set-ArchivingPolicy

Get-ArchivingConfiguration

New-ArchivingConfiguration

Remove-ArchivingConfiguration

Set-ArchivingConfiguration

Get-CsUser

Export-CsArchivingData

Get-CsComputer

Get-CsPool

Get-CsService

Get-CsSite

The preceding list represents the only cmdlets that an Archiving Administrator is allowed to run. If he or she tries to run, say, the Disable-CsUser cmdlet, that command will fail; that’s because Archiving Administrators do not have the right to run Disable-CsUser. This applies to the Communications Server Control Panel as well. An Archiving Administrator cannot disable a user by using the Control Panel simply because the Control Panel is aware of, and abides by, RBAC roles. (Any time you run a command in Control Panel you are actually calling a PowerShell cmdlet. If you are not allowed to run Disable-CsUser it won’t matter whether you directly run that cmdlet from Windows PowerShell or if you indirectly run the cmdlet from within the Communications Server Control Panel: the command will fail.)

Note that RBAC applies only to remote management. If you are logged on to a computer running Microsoft Communications Server and you open the Communications Server Management Shell RBAC roles will not be enforced.

When you install Communications Server the setup program creates a dozen or so built-in RBAC roles, roles that cover such common administrative areas such as voice administration, user management, Response Group administration, and so on. These built-in roles cannot be modified in any way: you cannot add or remove cmdlets to the roles and you cannot delete these roles. (Any attempt to delete a built-in role will result in an error message.) However, you can use the built-in roles to create custom RBAC roles. These custom roles can then be modified by changing the administrative scopes; for example, you could limit the role to managing user accounts with a particular Active Directory OU.

The Get-CsAdminRole cmdlet provides a way for you to return information about all the RBAC roles available for use in your organization.

Get-CsAdminRole returns instances of the Microsoft.Rtc.Management.WriteableConfig.Settings.Roles.Role object.

-------------------------- Example 1 ------------------------

	Copy Code
Get-CsAdminRole

The command shown in Example 1 returns information about all the RBAC roles configured for use in your organization. This is done by calling Get-CsAdminRole without any parameters.

-------------------------- Example 2 ------------------------

	Copy Code
Get-CsAdminRole -Identity "CsHelpDesk"

In Example 2, a single RBA role is returned: the role that has the Identity CsHelpDesk.

-------------------------- Example 3 ------------------------

	Copy Code
Get-CsAdminRole -Filter "*Voice*"

The preceding command returns all the RBAC roles that have the string value "Voice" somewhere in their Identity (e.g., CsVoiceAdministrator; RedmondVoiceAdministrators; etc.). To do this, Get-CsAdminRole is called along with the -Filter parameter; the filter value "*Voice*" limits the returned data to RBAC roles that have the string value "Voice" anywhere in their Identity.

-------------------------- Example 4 ------------------------

	Copy Code
Get-CsAdminRole | Where-Object {$_.IsStandardRole -eq $False}

Example 4 returns all the custom RBAC roles that have been created for use in your organization. To carry out this task, the command first uses Get-CsAdminRole to return a collection of all the RBAC roles currently in use. This collection is then piped to the Where-Object cmdlet, which selects only those roles where the IsStandardRole property is equal to (-eq) False ($False). By definition, any role that meets that criterion is a custom RBAC role.

-------------------------- Example 5 ------------------------

	Copy Code
Get-CsAdminRole | Where-Object {$_.Cmdlets -contains "Set-CsUser"}

The command shown in Example 5 returns all the RBAC roles that include the Set-CsUser cmdlet. To do this, the command first calls Get-CsAdminRole 9without any parameters) in order to return a collection of all the RBAC roles in the organization. This collection is then piped to Where-Object, which picks out any role where the Cmdlet property includes (-contains) the cmdlet Set-CsUser.

-------------------------- Example 6 ------------------------

	Copy Code
Get-CsAdminRole | Where-Object {$_.UserScopes -contains "OU: ou=Redmond,dc=litwareinc,dc=com"}

Example 6 returns information about all the RBAC roles that include the specified OU (ou=Redmond, dc=litwareinc, dc=com) in their UserScopes property. To perform this task, the command first calls Get-CsAdminRole in order to return a collection of all the RBAC roles currently in use. This collection is then piped to Where-Object, which selects all of the roles that include (-contains) the "OU:ou=Redmond,dc=litwareinc,dc=com" in the UserScopes property.

-------------------------- Example 7 ------------------------

	Copy Code
Get-CsAdminRole -Identity "CsVoiceAdministrator" | Select-Object -ExpandProperty Cmdlets

The preceding command returns a list of all the cmdlets included in the CsVoiceAdministrator role. To do this, the command first uses Get-CsAdminRole to return all the properties and property values for CsVoiceAdministrator. This information is then piped to the Select-Object cmdlet, which uses the -ExpandProperty parameter to display all of the items contained in the Cmdlets property.