Configure Access Management

Introduction

This chapter covers what to consider when managing users in the Industrial Asset Hub (IAH) app. It answers the following 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 user and access management and is not mandatory for using IAH Access management. To skip directly to usage instructions, go to Getting started with IAH Access management. Read the whole document to fully understand the impact of access management actions. Access management is about information and asset protection and must be done carefully.

Authentication and authorization

User management in IAH consists of two parts: authentication and authorization.

Authentication answers "Who is the person trying to access the application?" and "Should this request be granted?". The XF service handles authentication. Add the respective people via the Xcelerator Admin Console to define who has access.

Authorization answers "What is a person allowed to do in the application?". The IAH authorization service handles this. Assign the required roles to define user permissions.

When a user accesses the application, the XF service first checks whether the user is allowed access at all. Only if access is granted, the user is forwarded to the IAH app, where the IAH authorization service checks whether 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, streamlining user access management based on common tasks and responsibilities.

The application uses 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, functioning independently to cover 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 specific area or functionality. Use them 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.

Note

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_read_custom_property (Global)	glb_inventory_write_custom_property (Global)	glb_inventory_read_relation_data (Global)	glb_inventory_write_relation_data (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

Note

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

Warning

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

Use a server user for machine-to-machine API interactions. A server user performs all necessary actions without human interaction. When a new tenant is set up, a server user is pre-configured with the full permission set in IAH. This server user is automatically used by any onboarded Asset Gateway but can also be used by other IAH API consumers. The server user has full access. Keep the server user’s credentials strictly confidential to avoid misuse.

Getting started with IAH Access management

Follow this step-by-step guide to get started with IAH Access management.

Create users in the Xcelerator Admin Console first before managing them in the IAH app. The Xcelerator Admin Console is the central place to manage users for all applications in the Xcelerator platform. Once added in the Xcelerator Admin Console for use with IAH, users appear on the IAH Access management page. Users with respective permissions can then maintain user roles in the IAH app. Disregard the roles available in the Xcelerator Admin Console. 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 Assign.

Maintain users in IAH

The first user who accesses the IAH app automatically receives the roles admin, user_admin, gateway and access_group_admin, making them 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 can modify the roles of other users. Elevate other users by 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

Delete users from IAH via the Xcelerator Admin Console only. IAH synchronizes with the XF service, detects the difference in 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 automatically receives the role. If no IAH user with the user_admin role remains, add a new user who logs into IAH to trigger a reassignment of the user_admin and access_group_admin role.

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.

Define Access groups to group assets and dedicated users. A user can be assigned to multiple Access groups. For example, a factory with two production lines can have two Access groups, one for each production line. In each Access group, assign the users responsible for the production line and the assets that are part of the production line. Only users with the respective permissions from within the Access group can alter its assignments.

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

Enable the Access group column in the List settings of the Asset list to view the Access group entries for each asset.

Creating or selecting an Access group

To create new Access groups, a user needs the role access_groups_admin within the default Access group. When such users create a new Access group, they are automatically added to it and receive the local user_admin role. Create or select Access groups in IAH in the following ways:

Asset list

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

Inbox

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

Gateway configuration

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

Note

When a new access group is created through any of the methods described above, all users in the default Access group with the user_admin role are automatically assigned to it.

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 includes adding and removing users from the respective Access group. Once assigned to an Access group, a user receives 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 is automatically deleted when no assets and users are assigned to it.

Any questions left?

Ask the community