Role-Based Access Control cmdlets
Role-Based Access Control (RBAC) cmdlets allow you to interact with the 1E Platform RBAC subsystem.
The 1E Platform 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
RBAC uses the following key entities and concepts.
Principal
A principal is a security identity that can be associated with roles and permissions. Currently in the platform, a Windows principal can be either a primary Windows domain account or a domain group.
For platform releases 8.2 and later, a principal can be any user principal name (which takes the same format as an email address, for example, Fred.Smith@myorg.com). The principal will be validated against the associated identity provider configured for the platform when an attempt is made to authenticate using that principal name.
You can also define a group as a principal in RBAC. This group will be defined on the associated identity provider which has been configured for the platform.
You can report on the principals associated with a platform installation using the Get-1EPrincipal cmdlet discussed below.
Administrator principals
A principal who has been granted full administrative rights is an administrator principal. You can report on these principals using the get-1EAdminPrincipal cmdlet discussed below.
System principals
A principal that has the System flag set to true cannot be deleted from the RBAC system. For example, the principal that is associated with platform to platform communication between services cannot be deleted.
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 referred to 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.
A securable type can apply to all management groups (global securable type) or it can apply only to specific management groups that have been associated with user roles (local 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 that 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 permissions, 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. |
Although all the role permissions discussed in the example above used the same securable type (InstructionSet), there is nothing to stop you from 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, that is, GRANT permissions.
The RBAC subsystem does implement DENY permissions but these are not formally supported and not available via the platform UI.
A DENY permission will take precedence over a GRANT permission. Thus, DENY permissions inherited via group membership could override permissions associated directly with an RBAC principal.
Note that the underlying permission API will create a DENY permission by default if the Allowed property is not explicitly passed in the model to the API (that is, the model defaults to FALSE if not supplied explicitly). Prior to version 1.1.46 of the 1E PowerShell Toolkit, this would have caused permissions to have been added as DENY permissions, with undesired results.
Since DENY permissions are not formally supported, the corrected cmdlet always adds a GRANT permission.
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-1EPermissionToRole, you can specify a securable type instance id (that 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 can be associated with roles (platform versions prior to release 8) or with role/principal pairs (platform versions from release 8 onwards). This allows administrators to constrain the rights of other principals to a subset of devices defined by the management group rules. Refer to Working with management groups.
Principal management cmdlets
Get-1EPrincipal [-Id <id>] | [ -AccountName <name> ]
This cmdlet returns all principals that have been defined or, if the Id or name parameter is specified, the details for the principal whose Id or name is provided.
Add-1EPrincipal -Account <account name> [-Email <email addr>] [-DisplayName <displayname>] [-IsGroup]
This cmdlet adds the specified account name as a principal. Specify the account in domain\user format or as a UPN (user@org) when using platform-neutral authentication. Optionally, an email address and/or display name can be provided.
The -IsGroup parameter, if specified, adds the principal as a group rather than as a user.
For releases of the 1E Platform prior to 8.2, the underlying API called by this cmdlet requires that the SID of the account to be managed is retrieved and included in the API payload. The cmdlet performs this action automatically but the account under which you are running it must have appropriate Active Directory privileges to retrieve a user SID. If it does not, this cmdlet will return an error.
For releases of the platform from 8.2 onward, this requirement has been removed and SIDs are no longer retrieved.
Remove-1EPrincipal -Id <id>| -Account <account name> [ -Force ] | [ -WhatIf ]
This cmdlet removes the principal whose Id is specified. If the -Force parameter is specified, then any roles associated with the principal are removed first. If not specified, then removing a principal that has roles associated with it will result in an error.
If the -WhatIf parameter is specified, the roles, if any, associated with the principal are returned.
Update-1EPrincipal -Account <account name>|-Id <id> [ -Email <email> ] [ -DisplayName <displayname> ] [ -PrincipalName <principalname> ]
This cmdlet updates the Email address, DisplayName, or PrincipalName (account name) properties for an existing principal. Any or all of these properties can be specified to change multiple properties.
Get-1EAdminPrincipal
This cmdlet returns all administrator principals in the same format as get-1EPrincipal.
Role management cmdlets
Get-1ERole [-Id <id>|-Name <name>]
This cmdlet returns all roles defined or the specific role if the optional -Id or -Name parameter is supplied.
Add-1ERole -Name <name> -Description <description> [-CanBeDelegated]
This cmdlet 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 the 1E Platform earlier than version 8. For versions 8 and later, it defines whether the role can be delegated by a user who lacks global system administrator privileges.
- If CanBeDelegated is not specified, this means only a person who has Security > Write on All Devices management group (that is, a so-called Global Security Admin type of person) can assign that role.
- If CanBeDelegated is specified, you require Security > Read permissions on a management group to assign or delegate the role to another principal.
- CanBeDelegated cannot be specified if any of the permissions for the role use global securable types. The Get-1ESecurableType 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 specified, and that permission has global scope, then an error is thrown.
Remove-1ERole -Id <id> [-Force] [-Whatif]
This cmdlet 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.
Roles whose SystemRole property is true cannot be removed. They are defined as part of the platform RBAC infrastructure.
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-1EPrincipalRole -Id <id>
This cmdlet returns the roles (if any) associated with the principal whose Id is specified.
Get-1ERolePrincipal -Id <id>
This cmdlet returns the principals (if any) associated with the role whose Id is specified.
Add-1ERoleToPrincipal -Id <id> -RoleId <roleId>
This cmdlet adds the role whose role id is specified to the principal whose id is specified.
Remove-1ERoleFromPrincipal -Id <id> -RoleId <roleId>
This cmdlet removes the role whose role id is specified from the principal whose id is specified.
Get-1EManagementGroupForRole -Id <id>
This cmdlet retrieves the management groups associated with a role.
Management groups have changed in release 8 of the platform. This cmdlet will throw an exception if run against a version of the platform from release 8 onwards. This is because management groups are now associated with role/principal pairs and not just roles. Refer to Management group changes in version 8 of the 1E Platform.
Get-1EPrincipalRoleManagementGroup
[ -RoleId <id>| -PrincipalId <id>| -ManagementGroupId <id>] | [ -RoleName <name> | -PrincipalName <name> ]
This cmdlet is only available for platform releases 8 onwards. For more information, refer to Get-1EManagementGroupForRole -Id <id>.
This cmdlet returns the principal/role pairs that have been associated with a management group. In platform releases from 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.
Get-1EPrincipalRoleManagementGroup
Add-1EPrincipalRoleManagementGroup -RoleId <id> -PrincipalId <id> -ManagementGroupId <id>
This cmdlet is only available for platform releases 8 onwards. For more information, refer to Get-1EManagementGroupForRole -Id <id>.
This cmdlet 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.
Remove-1EPrincipalRoleManagementGroup -RoleId <id> -PrincipalId <id> -ManagementGroupId <id>
This cmdlet is only available for platform releases 8 onwards. For more information, refer to Get-1EManagementGroupForRole -Id <id>.
This cmdlet 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.
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-1EPermission -Id <id> | -TypeId <typeId>
This cmdlet returns the details for the permission whose Id is specified or all role permissions that are associated with a specified securable type, specified by the -TypeId parameter.
Get-1EPermissionForRole -Id <id>
This cmdlet gets the permissions associated with the role whose Id is specified. The format is identical to that from get-1Epermission.
Add-1EPermissionToRole -Id <id> -TypeId <typeid> -OperationId <operationId> [-SecurableId <securableId>]
This cmdlet 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, refer to Securable types cmdlets and Operations cmdlets.
You cannot add a permission with the same values for typeid and operationid multiple times. An error is raised if you do so.
Prior to release 1.1.46 of the 1E PowerShell Toolkit, this cmdlet will cause a permission to be added with the Allowed property set to false. This could cause undesirable results as this would result in an unsupported DENY permission instead of the intended GRANT permission.
The -SecurableId property is only applicable currently to instruction sets, though it is accepted for other securable types. For other securable types, the -SecurableId 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 that does not correspond to a valid instruction set Id, then the permission is granted to all instruction sets.
Remove-1EPermission -Id <id>
This cmdlet removes the permission specified by its Id.
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-1EPermissionForRole cmdlet.
Get-1EPermissionForPrincipal -Account <account> |-Id <Id> [ -ManagementGroupId ] [ -TypeName ]
This cmdlet returns the permissions for the specified principal. If -ManagementGroupId is specified, only permissions applicable to that management group are returned. If -TypeName is specified, only permissions applicable to that securable type name are returned.
Securable types cmdlets
Get-1ESecurableType
This cmdlet returns the defined securable types. For each securable type, the set of allowed operations is also returned.
New-1ESecurableType -Name <name> -Description <description> [ -IsLocal ]
This cmdlet creates a new securable type. If IsLocal is not specified, the securable type is set to global. Otherwise, it is set to local.
After creation, the new securable type has no operations defined against it. Use the New-1EOperationForSecurableType to add one or more applicable operations for the securable type.
Remove-1ESecurableType -Id <id> [ -Force ] [ -Whatif ]
This cmdlet removes the specified securable type whose Id is defined. If there are operations associated with the securable type, an error is thrown unless -Force is specified, in which case these are deleted. Use the -WhatIf parameter to see which securable types would be deleted.
If the securable type has been associated with role permissions, then you will need to remove it from those permissions before it can be removed.
Exercise caution when removing securable types. An error is thrown when you attempt to remove a securable type that has associated role permissions. You must remove the securable type from the role before you can delete the type. Removing securable types and permissions already defined on the platform may result in access to subsystems being denied.
Operations cmdlets
Get-1EOperationForSecurableType -Id <id>
This cmdlet returns the valid operations for the specified securable type.
New-1EOperationForSecurableType -Id <id> -Name <name>
This cmdlet adds a new operation to the securable type whose Id is specified.
Each operation associated with a securable type must have a unique name, otherwise, an error is thrown. A created operation receives a unique OperationId which is used in the Remove-1EOperationForSecurableType cmdlet.
Remove-1EOperationForSecurableType -OperationId <id>
This cmdlet removes the operation whose Id is specified from whatever security type it was associated with. Each operation has a unique Id, so you do not specify the securable type Id here. It is implied by the relationship stored in the platform for that operation Id entry.
Exercise caution when removing operations for a securable type. Securable types associated with existing platform role permissions should not have operations removed. This may cause system failures.
Principal conversion cmdlets
When migrating from a Windows environment to an environment that uses an external identity provider, existing principal names in domain\user format will not be directly useable.
You can use the convert-1eprincipal cmdlet to remap existing principal names so that they are expressed in User Principal Name (UPN) format, for example, Fred.Smith@megacorp.com.
Convert-1EPrincipal [ -DomainMapping <domainmapping> ] [ -OutPath <path> ] [ -UserMapping <usermapping> ] [ -Path <path> ] [ -WhatIf ]
This cmdlet converts principal names or creates a principal mapping file that can be modified and used to convert one or more principals.
-DomainMapping specifies either a fixed string, for example, megacorp.org, to which all principals will be mapped (for example, \domain\fred.smith > fred.smith@megacorp.com) or a hashtable mapping domains to suffixes, for example, -DomainMapping @{"Domain1" = "megacorp.com"; "Domain2" = "largecorp.com"}, which will map users in domain1 to the suffix megacorp.com and users in domain2 to largecorp.com, leaving principals in other domains unchanged.
-OutPath, if specified, writes the mapping entries out to a file as a CSV file with the first column being the existing names and the second column being the remapped names. This file can be used as an input for remapping if desired.
-UserMapping, if specified, is a hashtable mapping users, for example, -UserMapping @{"FredSmith" = "Fred.Smith"; "RachelJones" = "Rachel.Jones"}, which will cause these users to have their names transformed as shown. Other user entries are left unchanged. You can specify both domain and user mappings.
-Path, if specified, defines the path to a CSV mapping file which specifies one or more source and destination mappings for principals, for example, domain\fred.smith,fred.r.smith@hugecorp.com.
Note that you can specify any arbitrary mapping in an entry. Principals that aren't mapped are left unchanged. All comparisons are case-insensitive for all mapping parameters including file entries.
-WhatIf shows what mapping changes would be made, but does not execute the changes.
For more information about scenarios involving the use of this cmdlet during platform upgrades, refer to Remapping principal names during legacy platform migration.
Principal mapping cmdlets
When interacting with the 1E Platform and using platform-neutral authentication, external integration scripts and services use certificates to authenticate. These certificates must be mapped to principals via the principal mapping cmdlets.
Note that principals that are managed via these cmdlets do not have to actually exist in the primary RBAC principal table.
Add-1EJwtPrincipalMapping -identifier <certificate identifier> -principal <principal> [ -Force ]
This cmdlet adds the specified certificate identifier and principal to the mapping table. For example:
Add-1EJwtPrincipalMapping -identifier "LYwS5N58Xzm5AkTQdm-lcpZdFSM" -principal "Bob.Smith@myorg.com"The certificate identifier is a base-64 encoded representation of the certificate thumbprint. You can obtain this using the get-1Ecertificatethumbprint cmdlet.
If the -Force option is not specified, the principal must exist on the platform RBAC table, or it must be a member of at least one group that is defined on the RBAC table. Otherwise, an error is thrown.
Remove-1EJwtPrincipalMapping -id <id>
This cmdlet removes the specified certificate mapping entry whose Id is specified.
Get-1EJwtPrincipalMapping
This cmdlet returns all mapping entries in the mapping table.
Get-1ECertificateThumbprint -StoreName <storename>
This cmdlet lists all certificates in the specified store, returning the certificate subject, its thumbprint, and the 'kid' which is the base-64 representation of the thumbprint suitable for use with the Add-1EJwtPrincipalMapping cmdlet.
The storename is in standard PowerShell format. For example, to query the local machine personal certificate store, specify -StoreName "LocalMachine\My".
Get-1EGroupMember -Name <name>
This cmdlet returns the members of the specified group. No data is returned if the group does not exist or has no members.
Group membership is determined by the platform's configured identity provider. This information is cached on the platform via a periodic synchronisation process.