Configure Access Management

Introduction

This chapter explains what has to be considered when managing users in the Industrial Asset Hub (IAH) app. It will answer the questions:

What are the prerequisites to manage users?
How are users and their roles maintained?
What are Access groups used for?

The following content provides additional information about the aspects of user and access management and is not mandatory for using the IAH Access management. If you only want to know how to use IAH Access management, you can skip the following chapters and start with Getting started with IAH Access management right away. Nevertheless, we strongly recommend to read the whole document to completely understand the impact of your actions. Access management is about information and asset protection and therefore must be done carefully.

Authentication and authorization

The user management consists of two different parts in the context of IAH. The first part is authentication and the second part is authorization.

Authentication is about "Who is the person trying to get access to the application?" and "Should this person's request be granted?". This question is handled by the XF service and your task is to define the service's answer by adding the respective people via the Xcelerator Admin Console.

Authorization is about "What is a person allowed to do in the application?". This question is handled by the IAH authorization service. Here, your task is to define the permissions of your users by assigning the required roles.

If a user tries to access the application, first the XF service checks if the user is allowed to access the application at all. Only if access is granted, the user is forwarded to the IAH app, where the IAH authorization service checks if the user is allowed to perform the requested action.

Roles and permissions

Understanding Roles and Permissions

Roles define what actions users can perform within the application by grouping specific permissions. They are designed to streamline user access management based on common tasks and responsibilities.

The application utilizes two main types of roles: Basic Roles and Extension Roles.

Basic Roles

Basic roles provide a broad set of general permissions across different areas of the application. They are designed to function independently, covering common user needs and responsibilities.

Examples: The basic roles available are Read Only, Operator, Supervisor, and Admin.
Hierarchy: Basic roles have a hierarchical structure:
Operator permissions are a subset of Supervisor permissions.
Supervisor permissions are a subset of Admin permissions.
This means an Admin role includes all permissions of a Supervisor and Operator, and a Supervisor role includes all permissions of an Operator.

Extension Roles

Extension roles offer a distinct and specialized set of permissions focused on a very specific area or functionality. They are primarily used to enhance a basic role, providing access to functionalities that are either:

Highly sensitive
Very specialized
Only required by a small number of users for specific, rare tasks
Example: The Credential Manager role. This role provides specific permissions not included in any basic role.

Using extension roles without any basic role is possible but strongly advised against. This will lead to errors in the UI application and restrict basic functionalities for the user.

Roles and permissions overview

Authorization Service

Role	view_users (Deprecated)	assign_access_group (Deprecated)	assign_role (Deprecated)	authz_read_users	authz_resolve_user_id	authz_write_access_groups	glb_authz_read_access_groups (Global)	glb_authz_write_access_groups (Global)	glb_authz_read_user_roles (Global)
`access_group_admin`	❌	❌	❌	❌	❌	❌	✅	✅	❌
`admin`	❌	❌	❌	❌	✅	❌	❌	❌	❌
`contextualization`	❌	❌	❌	❌	❌	❌	❌	❌	❌
`credential_manager`	❌	❌	❌	❌	❌	❌	❌	❌	❌
`gateway`	❌	❌	❌	❌	❌	❌	❌	❌	❌
`operator`	❌	❌	❌	❌	✅	❌	❌	❌	❌
`read_only`	❌	❌	❌	❌	✅	❌	❌	❌	❌
`supervisor`	❌	❌	❌	❌	✅	❌	❌	❌	❌
`user_admin`	✅	✅	✅	✅	❌	✅	❌	❌	✅

Contextualization Service

Role	glb_write_context (Global)
`access_group_admin`	❌
`admin`	❌
`contextualization`	✅
`credential_manager`	❌
`gateway`	❌
`operator`	❌
`read_only`	❌
`gateway`	❌
`supervisor`	❌
`user_admin`	❌

Credential Management

Role	write_credentials	read_credentials	use_credentials	write_template (Global)	read_template (Global)	glb_write_credentials (Global)	glb_read_credentials (Global)	glb_use_credentials (Global)
`access_group_admin`	❌	❌	❌	❌	❌	❌	❌	❌
`admin`	❌	❌	✅	❌	❌	❌	❌	✅
`contextualization`	❌	❌	❌	❌	❌	❌	❌	❌
`credential_manager`	✅	✅	✅	✅	✅	✅	✅	✅
`gateway`	❌	❌	❌	❌	❌	❌	❌	❌
`operator`	❌	❌	✅	❌	❌	❌	❌	✅
`read_only`	❌	❌	❌	❌	❌	❌	❌	❌
`supervisor`	❌	❌	✅	❌	❌	❌	❌	✅
`user_admin`	❌	❌	❌	❌	❌	❌	❌	❌

Discovery Service

Role	scan (Deprecated)	read_discovery_job	write_discovery_job	delete_discovery_job
`access_group_admin`	❌	❌	❌	❌
`admin`	✅	✅	✅	✅
`contextualization`	❌	❌	❌	❌
`credential_manager`	❌	❌	❌	❌
`gateway`	❌	❌	❌	❌
`operator`	❌	✅	✅	❌
`read_only`	❌	❌	❌	❌
`supervisor`	✅	✅	✅	✅
`user_admin`	❌	❌	❌	❌

File Import Service

Role	glb_file_import (Global)
`user_admin`	❌
`access_group_admin`	❌
`admin`	✅
`supervisor`	❌
`operator`	❌
`credential_manager`	❌
`read_only`	❌
`gateway`	❌

Inventory Service

Role	view_asset (Deprecated)	edit_asset (Deprecated)	edit_asset_responsible (Deprecated)	inventory_read_asset_data	inventory_write_asset_data	inventory_write_asset_responsible	glb_inventory_write_custom_property (Global)
`access_group_admin`	❌	❌	❌	❌	❌	❌	❌
`admin`	✅	✅	✅	✅	✅	✅	✅
`contextualization`	❌	❌	❌	❌	❌	❌	❌
`credential_manager`	❌	❌	❌	❌	❌	❌	❌
`gateway`	❌	❌	❌	❌	❌	❌	❌
`operator`	✅	✅	❌	✅	✅	❌	❌
`read_only`	✅	❌	❌	✅	❌	❌	❌
`supervisor`	✅	✅	❌	✅	✅	❌	✅
`user_admin`	❌	❌	❌	❌	❌	❌	❌

Onboarding Service

Role	glb_read_asset_gateway (Global)	create_gateway (Global, Deprecated)	glb_write_asset_gateway (Global)
`access_group_admin`	❌	❌	❌
`admin`	❌	❌	❌
`contextualization`	❌	❌	❌
`credential_manager`	❌	❌	❌
`gateway`	✅	✅	✅
`operator`	❌	❌	❌
`read_only`	❌	❌	❌
`supervisor`	❌	❌	❌
`user_admin`	❌	❌	❌

Remote Connect

Role	control_rc (Deprecated)	read_remote_connect_job	write_remote_connect_job	read_active_connection	write_active_connection
`access_group_admin`	❌	❌	❌	❌	❌
`admin`	✅	✅	✅	✅	✅
`contextualization`	❌	❌	❌	❌	❌
`credential_manager`	❌	❌	❌	❌	❌
`gateway`	❌	❌	❌	❌	❌
`operator`	❌	❌	❌	❌	❌
`read_only`	❌	❌	❌	❌	❌
`supervisor`	✅	✅	✅	✅	✅
`user_admin`	❌	❌	❌	❌	❌

Role Configuration

Role	Restricted to Default Group
`access_group_admin`	✅
`admin`	❌
`contextualization`	✅
`credential_manager`	❌
`gateway`	✅
`operator`	❌
`read_only`	❌
`supervisor`	❌
`user_admin`	❌

Legend:

✅ = Has permission
❌ = No permission
(Global) = Global permission that applies across all Access groups
(Deprecated) = Permission is deprecated

Notes:

Only access_group_admin and gateway roles are restricted to the default Access group
Global permissions (marked with "(Global)") apply across all Access groups, not scoped to a specific Access group
Deprecated permissions (marked with "(Deprecated)") are still functional but should not be used for new implementations

The gateway role provides the permission to create gateways, which allows a respective user to get access to a server-user token. This token provides full access to the IAH APIs. Therefore, this role should only be assigned to trusted users and be handled very cautious. Additionally, the gateway role can only be assigned in the context of the default Access group. This prevents users with access management permissions in a custom Access group to grant themselves or others the gateway role and thus potentially full API access.

Server users

To use the APIs in a machine to machine interaction, you need a server user. It allows all necessary actions to be performed without human interaction. When a new tenant is set up, a server user is already pre-configured with the full permission set in IAH. This server user will be created for you and is automatically used by any onboarded Asset Gateway, but can also be used by other IAH API consumers. The server user has full access and therefore, it’s crucial to keep the server user’s credentials strictly confidential to avoid misuse.

Getting started with IAH Access management

This chapter is a step-by-step guide to get started with IAH Access management.

To manage users in the Industrial Asset Hub (IAH) app, your users need to be created in the Xcelerator Admin Console first. The Xcelerator Admin Console is the central place to manage users for all applications in the Xcelerator platform. Once they have been added in the Xcelerator Admin Console for use with IAH, they will be visible in the IAH Access management page and users with respective permissions can then maintain the users' roles the IAH app. The roles which can be selected in the Xcelerator Admin Console, can be neglected. IAH has its own roles and permissions layer in place.

Add users to the Xcelerator Admin Console

Go to the Xcelerator Admin Console and log in with your credentials.
Navigate to 'Products' in the left menu bar, if not already selected.
Select the Industrial Asset Hub app under the 'Products' column.
Select the 'Assigned Users' tab.
Use the 'Assign User' function to add all users you need at the beginning.
Fill in the required fields and click on 'Assign'.

Maintain users in IAH

The first user who accesses the IAH app, will automatically get the roles admin, user_admin, gateway and access_group_admin and can therefore be seen as an elevated user. This happens regardless of whether the application was accessed via the user interface or the API. Initially, this user is the only one who is able to modify the role of other users. This can only be changed by elevating other users and adding respective roles to them as well.

Log into the IAH app as first user to become the IAH user with elevated permissions.
Open the Access management page via the side menu.
Assign roles to the users as required. This is done by clicking on the role cell and replacing or adding other roles.
Click outside the cell to save the changes or press enter instead.

Note: The last existing user with user_admin role cannot be degraded to a user with no user_admin role. This is prevented to not create a situation where all remaining users are excluded from access management.

Delete a user from IAH

If a user needs to be deleted from IAH, this should be done in the Xcelerator Admin Console only. IAH synchronizes with the XF service, detects the difference in the authorized users and removes them from IAH as well.

If a user with the user_admin role is removed via Admin Console, no other user will get the role instead automatically. If there is no IAH user with the user_admin role anymore, only adding a new user who logs into IAH, will cause a reassignment of the user_admin and access_group_admin role and solve the issue of having no access manager anymore.

Working with Access groups

What are Access groups and what are they used for?

The idea behind Access groups is to model the real-world structure of a factory, where different users work in different areas with different assets.

IAH allows you to define Access groups, which can be used to group assets and dedicated users. A user can be assigned to multiple Access groups. E.g., if you have a factory with two production lines, you can create two Access groups, one for each production line. In each Access group you can assign the users which are responsible for the production line and the assets which are part of the production line. Altering the assignments of an Access group can only be done by users who have the respective permissions from within the Access group.

All users are assigned to the default Access group, which is created automatically and cannot be deleted. The default Access group is used for all assets, which are not assigned to a specific Access group. So if the property of an Access group is not set, the default Access group is used. Deleting the property Access group of an asset will move the asset back to the default Access group.

Enable the Access group column in the Asset list

In the List settings of the Asset list, enable the Access group column to view the Access group entries for each asset.

Creating or selecting an Access group

To be able to create new Access groups, a user needs to have the role access_groups_admin within the default Access group. When such users create a new Access group, they will be automatically added to it and get locally the user_admin role. Access groups can be created or selected in IAH in the following ways:

Asset list

Add Asset Gateway dialog, define an Access group or enter an existing Access group
Add asset dialog, define an Access group or enter an existing Access group
Rename the default Access group or existing Access group of an asset or Asset Gateway

Inbox

Scan network dialog, define an Access group or enter an existing Access group

Assign users to an Access group

A user with role user_admin can change the roles of users within the same Access groups. In custom Access groups this also implies adding and removing users from the respective Access group. Once a user is assigned to an Access group, they will have the operator role, regardless of their role in the default Access group.

Click on the default Access group.
Select the users who should be assigned to the Access Group using the checkbox.
Click Assign access group and choose the desired Access group entry from the drop-down menu.

Remove users from an Access group

Only a user with user_admin role within a custom Access group can remove users from it.

Click on the Access group from where the users should be removed.
Select via the checkbox the users which should be removed.
Click on Remove from Access group.

Delete Access groups

The default Access group, which is created automatically cannot be deleted. All other Access groups can be deleted through an automatic delete.

Automatic delete

An Access group will be automatically deleted if there are no assets and users assigned to it.

Any questions left?

Ask the community