Role-Based Access Control (RBAC) cmdlets
Tachyon PowerShell Toolkit cmdlets that allow you to interact with the Tachyon RBAC subsystem.
About Tachyon RBAC
Tachyon supports a granular and flexible role-based access control system that allows you to control the actions which can be performed by users.
RBAC Key Concepts
Tachyon RBAC uses the following key entities and concepts to support RBAC.
Principal
A principal is a security identity that can be associated with roles and permissions. Currently in Tachyon a principal can be either a primary Windows domain account or a domain group.
You can report on the principals associated with a Tachyon installation using the Get-TachyonPrincipal cmdlet discussed below.
Note
The initial version of the PowerShell Integration Toolkit allows only primary accounts to be added and removed from roles, although it does report on all existing associations, both for primary and group accounts.
Administrator Principals
A principal who has been granted full administrative rights is an Administrator Principal. You can report on these principals using the get-TachyonAdminPrincipal cmdlet discussed below.
Roles
A principal can be associated with zero or more roles. Roles define relatively broad areas of functionality with which the principal can interact. For example, 'View Experience Dashboards'.
You can create new roles, as well as work with existing roles in the system.
Role Permissions
Role permissions, often abbreviated as just 'permissions' are more fine-grained sets of functionality which, when collated together, define the overall role's capabilities.
Role permissions associate a role with a set of operations that can be performed on securable types. These concepts are discussed below.
For example, the role 'Infrastructure Administrators' is associated with three role permissions. These permissions associate the role with three operations 'Read','Write' and 'Delete'. These operations in turn are defined to be performed against the securable type 'Infrastructure'.
Therefore every role permission must be associated with three entities
A role
An operation
A securable type associated with the operation.
Securable types
As discussed above, each role permission is associated with a securable type. For example, 'InstructionSet' is a securable type.
Operations
For each securable type, an allowed range of operations is defined. For example, the InstructionSet securable type defines the following operations:
Actioner
Approver
Questioner
Viewer
Combining securable types and operations to create role permissions
If we look at the above example 'InstructionSet' securable type, then we can define a set of permissions which we can give a role. As shipped, the following roles are associated with instruction sets.
Role name (pre v8) | Role name (v8) | Permissions |
|---|---|---|
Global Administrators | Full Administrator | This role has many permission, including four permissions that are available for the InstructionSet securable type: Actioner, Approver, Questioner or Viewer. |
Global Actioners | All Instructions Actioner | This role has only one permission assigned to it, Actioner. |
Global Approvers | All Instructions Approver | This role has only one permission assigned to it, Approver. |
Global Questioners | All Instructions Questioner | This role has only one permission assigned to it, Questioner. |
Global Viewers | All Instructions Viewer | This role has only one permission assigned to it, Viewer. |
Note
Although all the role permissions discussed in the example above used the same securable type (InstructionSet), there is nothing to stop you creating a role permission that is associated with another securable type. In other words, the set of permissions that a role can have can involve more than one securable type, if required.
Grant and Deny Permissions
At present all permissions defined in the system are affirmative i.e, GRANT permissions. While there is a property 'Allowed' on a permission which is intended to support DENY permissions (when set to false), this functionality is not currently supported by the RBAC subsystem and is reserved for future enhancement.
Securable Type Instances and Role Permissions
Instruction sets, unlike the remaining securable types, can be associated with role permissions at the instance level. As discussed below for the Add-TachyonPermissionTorRole, you can specify a securable type instance id (which corresponds to the id of the instruction set itself) to this cmdlet to define a particular instruction set to which the permission should apply. If an instance Id is not specified or does not correspond to a valid instruction set id, then the permission is granted to all instruction sets
Management groups, permissions and roles
Management groups (see Working with management groups and the Tachyon PowerShell Toolkit) can be associated with roles (Tachyon versions prior to release 8) or with role/principal pairs (Tachyon versions from 8 onwards). This allows administrators to constrain the rights of other principals to a subset of devices defined by the management group rules.
Principal management cmdlets
Get-TachyonPrincipal [-Id <id>]
Returns all principals that have been defined, or, if the Id parameter is specified, the details for the principal whose Id is provided.
Add-TachyonPrincipal -Account <account name> [-Email <email addr>] [-DisplayName <displayname>]
Adds the specified account name as a principal. Specify the account in domain\user format. Optionally an email address and/or display name can be provided
Note
The account name is currently assumed to refer to a primary account and not a Windows group
Remove-TachyonPrincipal -Id <id>
Removes the principal whose Id is specified
Get-TachyonAdminPrincipal
Returns all administrator principals in the same format as get-TachyonPrincipal
Role management cmdlets
Get-TachyonRole [-Id <id>|-Name <name>]
Returns all roles defined, or the specific role if the optional -Id or -Name parameter is supplied
Add-TachyonRole -Name <name> -Description <description> [-CanBeDelegated]
Adds the role specified by the name and description. No two roles may have the same name; an error is raised if you attempt to add a duplicate role.
The -CanBeDelegated parameter is ignored for versions of Tachyon earlier than v8. For versions v8 and later, it defines whether the role can be delegated by a use who lacks global system administrator privileges
Specifically:-
CanBeDelegated = $false means only a Person who has Security -> Write on All Devices Management Group (i.e a so called "Global Security Admin" type of person) can assign that Role.
CanBeDelegated = $true means you need Security -> Read on a management group to assign, or delegate, the role to another principal
CanBeDelegated must be false if any of the permissions for the role use global securable types. The Get-TachyonSecurableType cmdlet will return whether a securable type is global or not in the IsGlobal member
If you attempt to assign a permission to a role with CanBeDelegated set to $true and that permission has global scope, then an error is thrown.
Remove-TachyonRole -Id <id> [-Force] [-Whatif]
Removes the specified role. If the role is associated with any principals, then an error is raised unless the -Force parameter is supplied. In that case the role is removed regardless.
The -Whatif parameter allows you to view the principals, if any, associated with the role, but without any further action being taken
Note
Roles whose 'SystemRole' property is true cannot be removed. They are defined as part of the Tachyon system.
A role with no associated principal, but with associated permissions, can be removed without using the -Force parameter. Role permissions are automatically removed when a role is removed.
Get-TachyonPrincipalRole -Id <id>
Returns the roles (if any) associated with the principal whose Id is specified.
Get-TachyonRolePrincipal -Id <id>
Returns the principals (if any) associated with the role whose Id is specified
 |
Add-TachyonRoleToPrincipal -Id <id> -RoleId <roleId>
Adds the role whose role id is specified to the principal whose id is specified
Remove-TachyonRoleFromPrincipal -Id <id> -RoleId <roleId>
Removes the role whose role id is specified from the principal whose id is specified
Get-TachyonManagementGroupForRole -Id <id>
Retrieves the management groups associated with a role
Warning
Management groups have changed in Tachyon release 8. This cmdlet will throw an exception if run against a version of Tachyon from release 8 onwards. This is because management groups are now associated with role/principal pairs and not just roles
For more information on management group changes in release 8, see the link below
Get-TachyonPrincipalRoleManagementGroup [ -RoleId <id>| -PrincipalId <id>| -ManagementGroupId <id>] | [ -RoleName <name> | -PrincipalName <name> ]
Warning
This cmdlet is only available for Tachyon releases 8 onwards. See the note for Get-TachyonManagementGroupForRole for more information
Returns the principal/role pairs that have been associated with a management group. In Tachyon 8 onwards, these pairs are associated with management groups as a single entity.
If no arguments are supplied, all principal/role pairs are returned for all management groups.
If a Role Id, Principal Id or Management Group Id is supplied, only the principal/role pairs associated with that Id are returned. Only one of the three Ids can be supplied at any time.
If a RoleName or Principal Name is supplied, only the principal/role pairs associated with the associated name are returned.
Add-TachyonPrincipalRoleManagementGroup -RoleId <id> -PrincipalId <id> -ManagementGroupId <id>
Adds the principal and role specified by their respective IDs to the management group specified. An error is thrown if any id is invalid, or if the principal/role pair is already associated with the specified management group
Warning
This cmdlet is only available for Tachyon releases 8 onwards. See the note for Get-TachyonManagementGroupForRole for more information
Remove-TachyonPrincipalRoleManagementGroup -RoleId <id> -PrincipalId <id> -ManagementGroupId <id>
Removes the principal and role specified by their respective IDs from the management group specified. An error is thrown if any id is invalid, or if the principal/role pair is not associated with the specified management group
Warning
This cmdlet is only available for Tachyon releases 8 onwards. See the note for Get-TachyonManagementGroupForRole for more information
Note
Principals and roles are assigned or removed from management groups as a pair. If you assign or remove a principal/role pair to or from a management group, other pairs, which may share a common principal or role, are not affected.
Permissions cmdlets
Get-TachyonPermission -Id <id> | -TypeId <typeId>
Returns the details for the permission whose Id is specified or all role permissions which are associated with a specified securable type, specified by the -TypeId parameter
Get-TachyonPermissionForRole -Id <id>
Gets the permissions associated with the role whose Id is specified. The format is identical to that from get-tachyonpermission
Add-TachyonPermissionToRole -Id <id> -TypeId <typeid> -OperationId <operationId> [-SecurableId <securableId>]
Adds a permission to the role. The permission must specify a valid securable type and a valid securable operation on that type. To do this, see the sections below on securable type cmdlets and operation cmdlets
You cannot add a permission with the same values for typeid and operationid multiple times; an error is raised if you do so.
Note
The -SecurableId property is only applicable currently to instruction sets, though it is accepted for other securable types. For other securable types the securable Id property currently has no effect.
For instruction sets, the -SecurableId property allows you to specify the Id of the instruction set to which you wish the permission to apply.
If the -SecurableId property is either omitted or set to a value which does not correspond to a valid instruction set Id, then the permission is granted to all instruction sets.
Remove-TachyonPermission -Id <id>
Removes the permission specified by its Id.
Note
When a permission is added to a role, a new permission entry is created with a unique ID. To retrieve the IDs of all permissions associated with a role, use the Get-TachyonPermissionForRole cmdlet.
Securable types cmdlets
Get-TachyonSecurableType
Returns the defined securable types. For each securable type, the set of allowed operations is also returned
Operations cmdlets
Get-TachyonOperationForSecurableType -Id <id>
Returns the valid operations for the specified securable type
 |