Parmalink: https://doc.oneportal.fi/x/D4EW
| Table of Contents |
|---|
| Note | ||
|---|---|---|
| ||
Starting version 3.0 System and Custom Roles will be merged to just Roles. New schema is shown at the end of this page. |
onePortal™ utilise role-based access control. In practise it means what selections you see in the Main Menu, depends on assigned roles at any particular time. There are about 30 different pre-defined roles. Each user account may have several roles. What one can do in onePortal™ is determined by the assigned Roles (and the Permissions tied to those Roles).
onePortal™
| Table of Contents |
|---|
Trivore Identity Service (TIS) utilises Role-Based Access Control (RBAC). The basic building blocks or RBAC are roles, permissions and resources. Permissions allow a principal, such as a user, to access some specific resource or perform some specific action like editing user accounts, for example.
Roles consist of one or more permissions and can be simply thought to be a group of permissions. Users are then given one or more roles depending what kinds of tasks they need to perform. In practise, the views which a user sees in the Main Menu and can access, depends on assigned roles and permissions at any particular time. Also many views will only allow users read-only access if the users do not have the required permission to manage the objects.
TIS extends the basic RBAC model by introducing groups. In addition to giving users roles, roles can be added to a group so that all user members of that group will gain the roles. The paths from permission to user will be covered in more detail later in this chapter.
Roles and permissions
Role is a management unit in TIS. Roles are preferably assigned to user groups, but may still be assigned to user accounts directly. This direct assignment is being phased away in a future release. TIS has two roles classes: built-in static System Roles and flexible Custom Roles. Most System Roles have two permission levels: Admin and Auditor, which are depicted in the role names. Admin may administrate and manage, Auditor may view.
The picture below describes the relations between Permissions, Roles, Group Policies, Groups and Accounts. This is the current functionality for platform versions before 2.8.
Starting version 2.8 the Group Policy is omitted from the flow, and the following scheme will be used.
Image below shows the different paths from Permissions to Accounts.
For comprehensive picture on how RBAC is implemented in onePortal™, please see the image below.
Later sections of this chapter elaborate on role-related issues.
Role classes and a the special roles
Roles If we look at the roles more carefully, we see there is an additional concept tightly related to a role, namely a permission. A permission is a detailed item. There is a large number of permissions in TIS each allowing a certain small thing to be done. If that permission is missing (example: list user accounts), the signed in user account is not able to do any task which requires that permission.
Some permissions, like listing user accounts, are required by many roles, so there is some overlapping. Due to the rather technical nature of permissions, they are not widely or often discussed, but it is important to understand they exist and they make the basis for roles to function. If you need to make a Custom Roles, you need to understand Permissions, as you are essentially assigning Permissions to a Custom Role, and then later via Group to a user Account.
The access model in TIS is very fine grained and there are over 130 different permissions in the core system alone. The business extensions may also introduce additional permissions to the system. Event though there is a large number of permissions, they are well organised and their structure is logical. There are about 30 different pre-defined roles, which makes it easy to give each user a functional set of permissions so that they can complete their tasks.
| Expand | ||
|---|---|---|
| ||
Role classesBy default roles are divided into two main classes: Admin and Auditor. In addition there are two special roles: Multi-namespace and Developer. System RolesPredefined System Roles are designed to cover 99 % of use cases. This is why getting to know the System Roles is important. The full list of these roles is below in section 6.3. Next we will discuss the most important System Roles, and the difference between the two classes.
In general, Admin class has full read-write access to its objects, and Auditor class has only read-only access. For roles Namespace Admin and Namespace Auditor the object in question is the namespace and its settings. For roles Account Admin and Account Auditor the object in question is a user account and user account policies. For roles Role Admin and Role Auditor the objects in question are the role definitions in a namespace and on each user account in the namespace. For roles Group Admin and Group Auditors the object is a group, which may have different kind of members (user accounts, other groups, or contacts, which are covered in a later chapter). Group Admin is able to manage groups, and Group Auditor is able to review the current state and settings. Custom RolesIf the selection of built-in system roles does not serve the technical and business requirements of your organisation, it is possible to create custom roles which may have virtually any set of permission.
Special RolesMulti-namespace is a special role. It allows for the role holder to switch from a namespace (usually same as a tenant) to another for convenient management of multiple namespaces and the user accounts, groups, and roles in those namespaces. The Multi-namespace role itself does only allow for switching |
...
namespace. Other roles are required for actual management. On the user interface, the switching is done by selecting the namespace name on Namespace Menu on the Top Bar. Multi-namespace role also allows creating Management API Clients with access to multiple namespaces. This is a very powerful role, and the holders of this role are always considered trusted persons. Developer is another special role. It is reserved for external application developers. Developers may create and manage their own Management API clients and OpenID Connect clients. Those are clients for external applications utilising |
...
TIS platform. The |
...
Developer Guide explains the use of external applications in more detail. |
Roles and Permissions
Role is a management unit in onePortal™. Roles are preferably assigned to user groups, but may still be assigned to user accounts directly. This direct assignment is being phased away in a future release. If we look at the roles more carefully, we see there is an additional concept tightly related to a role, namely a permission. A permission is a detailed item. There are hundreds of permissions in onePortal™ each allowing a certain small thing to be done. If that permission is missing (example: list user accounts), the signed in user account is not able to do any task which requires that permission.
...
User permission paths
Users may gain permissions through multiple paths. The paths are listed below in order of preference. Directly setting roles, and permissions to user is deprecated and should be avoided if possible.
- Custom roles through groups
- Custom roles through namespace default account policy (special case, gives roles to all accounts within a namespace)
- Direct Custom roles (deprecated)
- Direct System roles (deprecated)
- Direct permissions (deprecated)
The recommended role structure
From time to time it is necessary to refresh architecture, and now it is time for simpler and more understandable RBAC. Then new schema is shown below, and as you can see, it is more elegant.
There are just Roles, and you can freely manage them in your namespace.
All Roles are assigned normally to a Group. There is one special use case, where groups are not used in name space, yet some roles and related permissions should be assigned to those all users. In this case it is possible to assign role(s) to the Default Account Policy, as it is applied to all users when they sign in.
The current complexity is being reduced after collecting and analysing customer feedback. You know, sometimes there can be too much flexibility, as it may reduce usability and learnability.
Namespaces can define a set of custom roles to be given to all user accounts in the namespace by adding one or more custom roles to the namespace default account policy.
Direct permission paths
As mentioned before, these permission paths are considered outdated and their use is not recommended. They are still documented and technically working for the sake of backwards compatibility and to allow smooth transition to the newer role structure.
The direct roles, both System and Custom Roles, and permissions can be managed in the user account editor in the Web UI. The Management API also has endpoints to manage direct roles and permissions.
Migrating to the newer role structure
When migrating to the new role structure, it can be done in small steps. There is no need to change all roles right away, but rather use the new role path when making changes to existing structures. For example, when assigning a new role to a user, instead of using the old system role, add the user to a group with a new role with same permissions as the old system role.
The Web UI provides some tools to ease the migration to the new role Within the Roles view is another view, where administrators can re-create the old system roles as new customisable roles.
| Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Role assignmentThere are multiple pre-defined roles and rules on how each role can be assigned to a user account or group. The following table contains this information in one place for System Roles. Custom Roles follow the same schema.
Role assignment matrix. There are few limitations on role assignment and especially removal. This is to avoid lock-out situations.
Assigning namespace for account with role Multi-namespaceIt is important to understand:
Results from above are:
Tip: Familiarise yourself with information in section below. |
| Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||
Role to Permission matrixThe table below discusses the relationship between the roles an account has, and the permissions the account is then given as a result.
Role to Permission matrix. The table above could be expanded with more examples. Send us feedback if we |
...
New schema coming for version 3.0
From time to time it is necessary to refresh architecture, and now it is time for simpler and more understandable RBAC. Then new schema is shown below, and as you can see, it is more elegant.
There are just Roles, and you can freely manage them in your namespace.
...
should |
...
. |
...
. |