Skip to main content

1E 23.11 (SaaS)

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.

233276840.png
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

233276839.png
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.

233276838.png
Get-TachyonRolePrincipal -Id <id>

Returns the principals (if any) associated with the role whose Id is specified

233276837.png
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

Management group changes in Tachyon v8

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.

233276832.png
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

233276836.png
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

233276835.png
Operations cmdlets
Get-TachyonOperationForSecurableType -Id <id>

Returns the valid operations for the specified securable type

233276834.png