Roles

Roles can be regarded as distinct tasks or activities of an application. They are defined during development, as it requires detailed knowledge of the application's functionality.

It is important for the developer to closely assess the tasks or activities, so there is as little overlap in rights between different roles as possible. Furthermore, the nomenclature of the roles must be clear for the IAM administrators responsible for setting up the authorization of an application. They have no knowledge of the functionality and therefore have to deduce the purpose of the roles from the role name and description.

Roles are often named after the corresponding activity, such as Approve hours or Report a ticket.

Roles can be added or modified using the Roles screen.

Set up a role

Create a role

To create a role:

menu Access control > Roles > tab Role > tab Form

1. Enter a name for the Role. We advise to use lowercase characters, which is a common convention to maintain consistency and readability.

   note

   In IAM, the role translations are shown so that main administrators, application administrators, and application owners can see the roles in their own language.

2. Optional: Select the Role group from the drop-down list. See Create a role group. As soon as a role is assigned to a group, the group appears in the grid so you can drag/drop other roles into it.

3. Only for the administrator role: select the checkbox All rights. All other roles should provide a minimum set of rights required for the corresponding task or feature.

4. Only for public API calls: select the checkbox Allow as public API. For more information, see Public API roles.

5. Only if you want to allow the use of personal access tokens: select the checkbox Allow for PAT. For more information, see Allow a role for personal access tokens.

If necessary, you can add a tag to a role in tab Role tags. For more information, see Tags.

Create a role

Create a role group

Role groups are a grouping of roles to support setting up and viewing role authorization. You can use them to display roles in a logical and process-oriented manner.

• The role translations are synchronized to IAM so that the main administrators, application administrators, and application owners can see the roles in their own language.
• For users who create Personal Access Tokens (PATs) for their application, role groups give context to the roles (permissions) in the PAT screen. Add a good translation that they can understand. Without a role group, the roles are listed in a virtual group Miscellaneous. See also Allow a role for personal access tokens.

note

Do not confuse role groups with default user groups and modules. For more information, see Default user groups and Modules.

To create a role group:

menu Access control > Roles > tab Role groups > tab Form

1. Enter a name for the Role group. We advise to use lowercase characters, which is a common convention to maintain consistency and readability.
2. Go to the tab Translations and add a translation that users can understand.

The role group is now available for selection if you create or edit a role.

Public API roles

To integrate your application with other systems, you can use Indicium calls with authentication. For example, as a client application or with an OpenID provider.

However, methods like webhooks or subscriptions do not always allow authentication.

In these cases, you can make the API call public for access without authentication. You can use this for actions like processing appointments and emails with Microsoft Graph. For more information about the base URL for a public API call, see Public API call.

note

You can only use this for individual API calls. Authentication is always required for your application if you use it with the Universal GUI.

To make a role suitable for a public API call:

menu Access control > Roles > tab Role > tab Form

1. Select the checkbox Allow as public API. This option does not affect how the role is used in a GUI.
2. Configure the role by assigning rights for objects. See Configure a role.
3. Synchronize the role to IAM as usual.
4. In IAM, an application administrator or application owner can complete the configuration. See Configure a public API role in IAM.

Allow a role for personal access tokens

Personal access tokens (PATs) are a secure way to authenticate access to your application. If you have decided which roles should be available for PATs, you can set them up in the Software Factory.

To users, these roles are visible as permissions when they create PATs in their application, so add a good translation that they can understand.

note

For more information about personal access tokens, see Personal Access Tokens in IAM

To make a role available as permission in personal access tokens (PATs):

menu Access control > Roles > tab Role > tab Form

1. Select the checkbox Allow for PAT.
2. Check the role translation (tab Translations).
3. Add the role to a Role group and check the role group translation (see Create a role group). A role group adds context to the roles (permissions) in the PAT screen. Without a role group, the roles are listed in a virtual group Miscellaneous.
4. Synchronize the role to IAM to make it available there.

Configure a role

Once a role has been created, it can be configured using the tabs on the right.

Role rights

1. To assign rights to a role, select the required objects and click the Assign rights task.
2. Select a Preset or check the rights you want to assign to the object.

The Assign rights task also provides the option to assign rights to any child objects, for example the columns and details of a table, and to the parent objects required for this object, for example a task for its task parameters.

Assign rights task

The Available checkbox, visible in the grid for certain objects, indicates if the required rights are granted to the parent objects of the selected object.

Access types

menu Access control > Roles > tab Tables/Tasks/Reports/Process flows/Subroutines/Menus

For each role, the colored icons indicate the resolved rights of an object, based on the granted rights and the availability:

• Full rights (editable): the user has full rights to see, add, edit and delete data in the column.
• Read-only: the user can see the data but has no rights to add, edit or delete data in the column.
• Visually hidden: the user can't see the data in the user interface, which is quite safe, but in some cases the data might still be approached through Indicium.
• Unauthorized (no rights): the data is unknown to the user interface and any API, so it's impossible for the user to see the data or to approach the column through Indicium. This is the safest option when it comes to data security in general and to protect sensitive data in accordance with GDPR laws.

Full rights, read-only and visually hidden can be applied by combining two settings:

• Column type in the data model (menu Data > Data model > tab Tables > tab Columns).
• Access type (menu Access control > Roles > tab Tables/Reports/Tasks).
• To fully anonymize data, see: Data sensitivity.

note

• If you are using variants, an object can be unauthorized in its base object, but hidden and thus available in its variant. This reduces the redundant model information that the GUI receives.
• See also The effective access type explained.
• The access type for each user group and user is available in IAM. See Effective group rights and Effective user rights.

Unauthorized columns

For columns, the option Unauthorized is set automatically by the Software Factory. It also combines the Column type and Access type to decide whether a column is unauthorized: if either the Column type or the Access type is hidden, the column will automatically get 'Unauthorized' as Effective access type.

Unauthorized column

Unauthorized task and report parameters

The same applies to task and report parameters. The first setting the Software Factory uses is the Column type used in the Task parameter or Report parameter (menu Processes > Tasks/Reports > tab Task parameters/Report parameters). The second setting is the parameter's Access type (menu Access control > Roles > tab Tasks/Reports > tab Task parameters/Report parameters). If either the Column type in a task or report parameter or the Access type applied to the task or report parameter is hidden, the column will automatically get 'Unauthorized' as Effective access type.

Unauthorized report parameter

Exceptions (never unauthorized)

There are a few exceptions to these rules however. In some instances a column will never be unauthorized but only hidden because making data unauthorized would break the user interface:

• A role is an administrator role with All rights assigned to it.
• A column is used as a primary key.
• A column is used as the primary look-up display column.
• A column is used as a conditional layout target.
• A column is used as a conditional layout condition.
• A column is used by any extender in any way, shape or form.
• A column is used in a tree for grouping (parent or child), display or icon (base or variant).
• A column is used in default sorting of a variant default sorting.
• A column is used by another column in the same role as look-up display field.
• A column is used by a granted cube field in the same role.

The effective access type explained

To get a better understanding of the effective access type, an explanation is available in the screens:

• For table (variant) columns: menu Access control > Roles > tab Tables > tab Columns
• For task (variant) parameters: menu Access control > Roles > tab Tasks > tab Task parameters
• For report (variant) parameters: menu Access control > Roles > tab Reports > tab Report parameters

1. Execute the Explain the effective access type task to view why the column or parameter has certain rights.

   The reason for the effective access type is explained in a pop-up. See also Access types.

2. Execute the Show variant effective rights task to view why the variant column or parameter has certain rights.