Overview

The following sections will walk you through all functionalities of the Administration application in detail. For your convenience find an overview on the content of this document below:

Section Content
Home screen Providing information on your capacity usage and subscribed applications.
Managing users How to add a user, edit, disable or delete them.
Managing permissions How to add and edit global roles and inventory roles, how to assign them to users, and how to grant application access.
Managing applications How to manage subscribed applications and how to manage and configure own applications in your Cumulocity IoT account.
Managing business rules How to reprioritize alarms by alarm mappings.
Managing data How to manage and configure retention rules for your data and how to manage stored files in the file repository.
Two-factor authentication How to activate/deactivate two-factor authentication for a user.
Changing settings How to change account settings like application settings or authentication settings, how to manage the properties library and how to configure single sign-on.

Home screen

The Home screen of the Administration application provides the following content:

Home screen

The capacity sections show:

Managing users

The user management feature allows you to manage the users within your tenant, that is create users, store user details, or configure login and security options.

Requirements

ROLES & PERMISSIONS:

“User management” permission type:

  • To view users: READ permission
  • To manage (create, edit, delete, disable/enable, delegate, manage permissions) all existing users: ADMIN permission
  • To create users: CREATE permission

“Own user management” permission type (has no influence on user management capabilities):

  • To view the own user: READ permission
  • To edit the own user: ADMIN permission

Note that each user created on the platform can edit its own information by default, regardless of the “Own user management” permissions. The purpose of the “Own user management” permission is to manage specific users created for technical purposes, for example, by microservices, and determine whether such users can be managed by respective services.

On tenant creation, there are default roles available that can be used as a sample configuration for the above mentioned permissions:

  • Global User Manager - Can access and modify the full user hierarchy
  • Shared User Manager - Can create new users as his own subusers and manage them (“feature-user-hierarchy” application subscription required)

Note that when subscribed to the “feature-user-hierachy” application, the CREATE permission allows to manage (display, create, edit, delete, disable/enable, delegate, manage permissions) underlying users. For details see Managing user hierarchies.

If your tenant is configured for using single sign-on (SSO) in Software AG Cloud, new users should be created under My Cloud, accessible through the application switcher in the upper right corner, so that they are able to use the single sign-on feature.

For users created via an external authorization server, updating the following settings in Cumulocity IoT will have no effect (will be reset on the next user re-login):

Moreover, password reset in Cumulocity IoT is disabled for users created through an external authentication server.

Info
Users which are using single sign-on cannot change the password of users which are managed by the platform.

To view users

To view all users in your tenant, click Users in the Accounts menu in the navigator.

Expanded view

A user list will be displayed, providing the following information for each user:

To filter the list by username, you can use the filter field at the left of the top menu bar. With the dropdown list you can filter by global roles. For details on filtering, see Getting started > UI functionalities and features > Filtering.

In order to apply the selected filters click Apply.

Initially, the User page only shows the top-level users. To see all users in your account at once, click Expand all at the right of the top bar. This will expand all top-level users, showing their sub-users. Click Collapse all to just show the top-level users again. For details on user hierarchies, refer to Managing user hierarchies.

To add a user

  1. Click Add user at the right of the top menu bar.

    Info
    If single sign-on is enabled for your tenant, a message will show up which reminds you that you are about to create a local user which will not be able to login via single sign-on. Create new users in My Cloud instead, accessible through the application switcher in the upper right corner, to enable them using the single sign-on feature.

    1. At the left of the New user window, provide the following information to identify the user:

      Field Description
      Username Serves as a unique user ID to identify the user at the system. Note that the username cannot be changed once the user has been created. This field is mandatory.
      Login alias In addition to the username, an optional alias can be provided to be used to log on. In contrast to the username, this alias may be changed if required. The login alias cannot be the same as the username. Note that the login alias is not supported for devices.
      Status Enable/disable the user account here. If the user account is disabled the user cannot login.
      Email A valid email address. This field is mandatory.
      First name First name of the user.
      Last name Last name of the user.
      Telephone A valid phone number. The phone number is required if the user is configured to use two-factor authentication.
      Owner Another user that manages ("owns") the new user. Select a user from the dropdown list and click Done to confirm. Refer to Managing user hierarchies for details on user hierarchies.
      Delegated by Can be activated to delegate user hierarchies and permissions to the user. Refer to Managing user hierarchies for details on delegation.
  2. Select the login options for the user.

    • Two-factor authentication (SMS) - if selected, the user will receive a verification code via SMS which is required to complete the authentication. The SMS will be sent to the phone number configured above. For details refer to Two-factor authentication.
    • User must reset password on next login - if selected, you must provide a password which the user must reset on the next login. Enter a password and confirm it. While entering the password, the strength of the password will be checked. See To change your password for further information on password reset and strength.
    • Send password reset link as email - if selected, the user will receive an email message with a link to set a password. The email will be sent to the email address configured above. This option is only available during user creation.
  3. On the right of the page, select the global roles for the user. Details on global roles are described in Managing permissions.

  4. Click Save to save your settings.

The new user will be added to the user list.

Info
By default, manually created users always have the “Own user management” permissions set to active.

To edit a user

  1. Click the menu icon at the right of the respective row and then click Edit. All fields except Username and Send password reset link as email can be changed. For details on the fields, see To add a user.
  2. Click Change password to change the password.
  3. Click Save to apply your settings.

To copy inventory roles

  1. Click the menu icon at the right of the respective row and then click Copy inventory roles from another user.
  2. In the resulting dialog box, select if you want to merge the roles to be copied with the existing user roles (the default) or if you want to replace the existing user roles.
  3. Select the user from which you want to copy roles from the dropdown list.
  4. Click Copy.

The inventory roles will be copied from the selected user.

To delegate/undelegate user hierarchies

Click the menu icon at the right of the respective row and then click Delegate to delegate your user hierarchies and permissions to a user.

Click Undelegate to remove a delegation.

Refer to Managing user hierarchies for details on delegation.

To disable/enable a user

Click the menu icon at the right of the respective row and then click Disable to disable an active user, or click Enable to enable a user that has been disabled.

To delete a user

Click the menu icon at the right of the respective row and then click Delete.

To log out all users

In the event of a security incident involving the session tokens of your tenant’s users, you can invalidate any tokens currently in use.

To log out all users click Log out all users at the right of the top menu bar. This logs out all users currently logged in via OAI-Secure or single sign-on redirect. JWT tokens retrieved by all devices in the current tenant are also invalidated.

Note that, if basic authentication is used, users logged in via base64 token are not logged out.

Requirements
To log out all users, you must have ADMIN permission for the permission type “User management”.

Managing permissions

Permissions define what a user is allowed to do in Cumulocity IoT applications. To manage permissions more easily, they are grouped into so-called “roles”. Every user can be associated with a number of roles, adding up permissions of the user.

The following types of roles can be associated with users:

Moreover, application access can be granted to enable a user to use an application.

Global roles

Click Roles in the Accounts menu to display a list of configured roles.

Context menu

In the Global roles tab you can find the roles which grant permissions on a system level. There are several global roles pre-defined, but you can define your own according to your needs.

Info

The pre-defined roles are configured as samples for a particular purpose. You may use them as a starting point and further adapt them to your individual needs.

On creating a new user, make sure that the global roles you assign to the user contain all necessary permissions relevant for this particular user in either of those roles assigned. Permissions from different roles are merged together when assigned to the same user. If, for example, a user only has the role “Cockpit User” (see below), the user is only able to access the Cockpit application and nothing more. But if you also assign inventory permission via some of the available roles, the user will get access to the whole inventory, such as devices, groups, and configurations.

The roles “admins” and “devices” have a special status:

Role    Description
admins Administrative permissions are enabled. The initial administrator, the first user created in a tenant, has this role.
devices Typical permission setup for devices. After registration, a device automatically has this role. Edit this role if your devices require less or more permissions, or assign other roles to your devices.

Furthermore, the following pre-configured roles are initially provided.

Role Description
CEP Manager Can access all smart rules and event processing rules.
Cockpit User Can access the Cockpit application. In addition, you should add a role providing access to devices.
Devicemanagement User Can access the Device management application. The user will be able to use the simulator and to run bulk operations. In addition, you should add a role providing access to devices.
Global Manager Can read and write all data from all devices.
Global Reader Can read all data from all devices.
Global User Manager Can manage all users.
Shared User Manager Can manage sub-users. The subscription plan needs to include user hierarchies to be able to manage sub-users.
Tenant Manager Can manage tenant-wide settings, such as own applications, data brokerage, data retention, options and tenant statistics.

You may also see the following legacy roles:

Role Description
business Can access all devices and their data but has no management permission in the tenant.
readers Can read all data (including users, in contrast to “Global Readers”).

To add a global role

Click Add global role in the Global roles tab. In the New global role page you will see a list of permission types at the left and a list of applications to be accessed at the right. The following screenshot shows the settings for the “admins” role.

Admin example

Permission levels

For each type, you can select the following permission levels:

Info
CREATE permissions are related to the concept of ownership in Cumulocity IoT. If you have created an object, you are the owner of it and can manage it without requiring any further permissions. For example, if you have CREATE permission for “Inventory”, you can create devices and groups, and fully manage these devices and groups. You cannot manage any devices or groups that you did not create yourself, unless you also have the UPDATE permission or an additional inventory role (see below). This concept helps to assign minimal permissions to devices. It also enables you to limit user management permissions to sub-users, if you subscribed to user hierarchies.

Select the checkbox at the top of a column to set the respective level to all permission types.

Permission categories

The following permission categories are available by default:

Category Description
Alarms View or edit alarms.
Application management View or edit the applications available in this account.
Audits View or create audit logs.
Bulk operations View or create bulk operations.
CEP management View or edit CEP rules.
Data broker Send data to other tenants or receive data from other tenants.
Device control View or edit commands for devices resp. send commands to devices. Also used for device registration.
Events View or create events.
Global smart rules Configure global smart rules.
Identity View or edit identifiers for devices.
Inventory View or edit inventory data.
Measurements View or create measurements.
Option management View or edit account options such as password policies.
Retention rules View or edit retention rules.
Schedule reports Manage the schedule of report exporting.
Simulator Configure simulated devices.
Sms Configure SMS.
Tenant management View, create, edit or delete subtenants.
Tenant statistics View the usage data for this account, as shown on the Home screen of the Administration application.
User management View or edit users, global roles and permissions.
Own user management View or edit your own user. Note that this permission may only be applicable to technical users.

There may be additional permissions visible depending on the features in your subscription plan. These are documented along with the respective feature.

Important
When new features with new permissions are added to Cumulocity IoT, these are not automatically added to existing roles. If you notice that you cannot use a new feature that was recently announced, check your permissions.

Assigning global roles

You can assign global roles to users either directly in the user list, or by opening the details page for a particular user and adding them there.

Important
By default it is not possible to change roles of SSO users (created automatically during SSO login) as those would be overridden by dynamic access mapping. However this behaviour can be changed. For more information refer to Administration > Configuration settings in the User guide.
To assign global roles from the user list
  1. Click the Global roles column of a particular user to open a list of global roles.
  2. Select or clear the respective checkboxes.
  3. Click Apply to save your settings.
To assign global roles from the user page
  1. Click on the row of the respective user in the user list.
  2. In the user page, select or clear the checkboxes for the relevant global roles at the right.
  3. Click Save to save your settings.

Inventory roles

Inventory roles contain permissions that you can assign to groups of devices. For example, an inventory role can contain the permission to restart a device. You can assign this inventory role to a group of devices “region north” and to a user “smith”. The result is that the user “smith” can restart all devices that are in the group “region north” or any of its subgroups.

To view the currently configured inventory roles, click Roles in the Accounts menu and switch to the Inventory roles tab.

Context menu

In the Inventory roles tab you can manage user permissions for particular groups and/or its children. There are several default inventory roles defined, but you can define your own according to your needs.

The following default inventory roles are initially available in new tenants:

Role Description
Manager Can read all data of the asset and manage all inventory data but cannot perform operations. In addition, can manage inventory data (including dashboards) and alarms.
Operations: All Can remotely manage the assets by sending operations to a device (for example software updates, remote configurations).
Operations: Restart Device Can restart devices.
Reader Can read all data of the asset.

To add an inventory role

Click Add inventory role in the Inventory roles tab. In the “New inventory role” page, provide a name and a description, and assign the permissions for the new inventory role.

Role details

Permissions are grouped into the following categories:

Category Description
Alarms Permissions related to working with alarms from devices.
Audits Permissions related to audit logs.
Events Permissions related to working with events from devices.
Inventory Permissions for viewing and editing devices.
Measurements Permissions related to measurements.
Device control Permissions to remote control devices.
Full access Complete access to the associated devices, mainly to simplify configuration.
Info
Service providers will see an additional permission “Support” in their Management tenant. This permission lets users of the service provider give support to their customer’s users, see Support user access.

Add a permission to the role by clicking the plus icon next to the desired category.

In the Type field, specify a type to further restrict the type of data that this permission applies to. Access will be only granted to objects that contain the specified Type.

For example, assume that your device sends measurements related to device management, such as “c8y_SignalStrength”, and actual production measurements. You want a user to only see the device management measurements. In this case, enter “c8y_SignalStrength” as type. This will allow the user to only see measurements that contain the type “c8y_SignalStrength”. Note that the user will be able to see the entire measurement object including other types that may be part of the same measurement object.

By default, the Type field contains an asterisk “*” selecting all types.

Info
For further information on possible types, check your device documentation, the Cumulocity IoT sensor library or the device management library. The type being used here is the so-called “fragment type”, not the “type” property. You must enter all fragment types send in a measurement to make the measurement visible; similar for other types of data.

In the Permission field, select a permission level from the dropdown list:

Important
When you add a permission, you may see a small exclamation mark. The exclamation mark indicates that the permission that you have just added is not effective, because another, “higher” permission set for the user already includes the respective permission. Check if you have set, for example, “Full access” or if there is another permission in the same section with “*” as type and ALL as permission.

As another example, assume that you are using tracking devices. You want to allow your user to see all devices, but not to change anything. In addition, the user should be able to follow tracks of devices on a map. Tracks are recorded using an event with fragment type “c8y_Position” (see Sensor library). To do so, assign READ permission on inventory as well as on events with type “c8y_Position” as shown in the image below.

Permission example

Assigning inventory roles to users

Inventory roles are assigned to a user and a group of devices.

To assign inventory roles, click Users in the Accounts menu, select a user in the user list and switch to its Inventory roles tab.

In the Inventory roles tab you will see a tree of device groups. To assign an inventory role, open the dropdown at the right of the group row. Select the relevant roles and click Apply. For a detailed description of a role click the info icon next to it or refer to Inventory roles.

Important
If a user already has a global role containing inventory permissions, the user will be able to see or change all devices regardless of what inventory roles you set here.

Inventory roles are inherited from groups to all their direct and indirect subgroups, and to the devices in these groups. If you select, for example, a role with read permissions on alarms for a group of devices, the user will be able to see alarms of all devices in this group and all its subgroups.

If a user has inventory access to a group of devices, the user will also have that access to all dashboards for that group of devices in the Cockpit application.

You can also copy inventory roles from another user. To copy roles, click Copy inventory roles from another user. In the upcoming window, select a user from the list and click Copy. At the top you can select if you want to merge the roles with the existing user roles (the default) or if you want to replace the existing user roles. Copying roles makes it easier to manage the permissions of many users as you can create a reference user and then copy the permissions from there.

Troubleshooting permissions

If you try to perform actions without sufficient permissions, an error message will occur.

To help troubleshooting permissions, click the User button (showing the current user name) at the right of the top bar. From the context menu, select Access denied requests. In the resulting window details on the denied accesses are provided. An administrator user or the product support can help in fixing the permissions.

Improving the performance

The Cumulocity IoT platform provides optimized UI performance for users with inventory roles access. In particular, requests for tenants with large inventory hierarchies are faster.

The performance of the following UI pages is improved:

As an administrator, you can disable the performance feature by doing the following:

The option looks like the following in the REST API (see also the Cumulocity IoT OpenAPI Specification):

{"category": "configuration", "key": "acl.algorithm-version", "value": "LEGACY"}

The setting on tenant level has priority over the setting on platform level.

By default, this option is enabled.

Granting application access

The Application Access tab shows a list of all available applications in your tenant in alphabetical order.

To assign applications to the user, simply select the respective applications and click Save.

For more information on application management, see Administration > Managing applications.

Info
If a user has global permission to read all applications, an information box will be shown.

Viewing audit logs

Audit logs show security-relevant operations a user has processed. For example, an audit log is generated when a user logs into a gateway.

Requirements

ROLES & PERMISSIONS:

  • To view audit logs: READ permission for permission type “Audit”
  • To create audit logs you need Admin permission for the permission type “Audit”. Note however, that you cannot create audit logs from the UI. For details on how to create audit logs via REST refer to Audits in the Cumulocity IoT OpenAPI Specification.

To view audit logs

To view the audit log list, click Audit logs in the Accounts menu. For each log entry, the following information is provided:

Column Description
Server time Server time when the operation was processed.
Event Type of operation, for example "Alarm created", "Smart rule deleted". Below it, the user who processed it is displayed.
Description Provides further information depending on the operation, for example, the device name, alarm text, operation status.
Device time Device time when the operation was processed. This can differ from the server time.

Only the last 100 logs are visible. Scroll down the page to Load more to view more log entries.

Audit logs

Info
The audit log list is not automatically refreshed after a realtime update for operations. Click Reload at the right of the top menu bar to update the list to the latest operations.

Filtering logs

In order to easily search through logs, you can filter logs for:

To apply a filter, click the Apply button next to the respective filter field. To discard filters, click the X icon next to the Apply button (only visible if filters are set).

Audit log types

Audit type Actions
Alarm
  • Alarm created
  • Alarm updated
Application
  • Application activated
  • Application subscribed
  • Application unsubscribed
  • Application deployed
  • Application deployment failure
  • Application undeployed
  • Application rescaled
  • Application deleted
This type of audit logs may be created for both hosted applications and microservices.
Bulk operation
  • Bulk operation created
  • Bulk operation updated
  • Bulk operation deleted
Data broker connector
  • Connector created
  • Connector updated
  • Connector deleted
Devices availability monitoring
  • Device availability enabled
  • Device availability disabled
  • Device availability interval updated
  • Device put into maintenance state
Global role
  • Global role updated
  • Global role authorities updated
  • Global role device permissions updated
Inventory
  • Managed object deleted
  • Device registration failed due to missing token
  • Device registration failed due to invalid token
  • Device registration max number of failed attempts reached
Inventory role
  • Inventory role created
  • Inventory role updated
  • Inventory role deleted
Operation
  • Operation created
  • Operation updated
Option
  • Option created
  • Option updated
  • Option deleted
Reliable notification
  • Reliable notification token created
  • Reliable notification subscription created
  • Reliable notification subscription deleted
Report
  • Test tenant statistics accessed
  • Real tenant statistics accessed
Single sign-on
  • SSO login
  • SSO logout
  • SSO logout failed
Smart rule
  • Smart rule created
  • Smart rule updated
  • Smart rule enabled
  • Smart rule disabled
  • Smart rule deleted
Tenant
  • Tenant created
  • Tenant updated
  • Tenant suspended
  • Tenant activated
  • Tenant deleted
Tenant auth configuration
  • Authentication configuration added
  • Authentication configuration updated
  • Authentication configuration deleted
Trusted certificate
  • Trusted certificate uploaded
  • Trusted certificate updated
  • Trusted certificate deleted
User
  • User created
  • User updated
  • User username updated
  • User password updated
  • User roles updated
  • User groups updated
  • User delegation updated
  • User owner updated
  • User inventory assignment updated
  • User device permissions updated
  • User deleted
User login
  • User login
  • User logout
Note that entries of this type are not created when using Basic authentication.
Info
For information on Analytics Builder monitoring including audit logs, see Analytics Builder > Monitoring and configuration in the Streaming Analytics guide.

Managing applications

The Cumulocity IoT platform distinguishes between applications and microservices, see also Developing applications in the Concepts guide.

Both can be accessed via the Ecosystem menu in the navigator.

Additionally, in Enterprise tenants, it is possible to configure Default subscriptions, that means you can specify a list of applications that are subscribed by default to every new tenant on creation and/or to all existing tenants on platform upgrade. For details, see Enterprise tenant > Default subscriptions.

Requirements

ROLES & PERMISSIONS:

  • To view applications and microservices: READ permission for the “Application management” permission type
  • To manage applications and microservices (create, update, copy, delete): ADMIN permission for the “Application management” permission type

On tenant creation there are default roles available that can be used as sample configuration for the above mentioned permissions:

  • Tenant Manager - manages tenant-wide configurations like applications, tenant options and business rules.

Note that for complete application management some additional permission types with different permission levels might be required per feature, for example:

  • Default subscriptions for the Enterprise tenant additionally requires READ and ADMIN permissions for the “Option management” permission type.
  • Managing subscriptions for the Enterprise tenant additionally requires READ and ADMIN permissions for the “Tenant management” permission type.

Applications

Click Applications in the Ecosystem menu in the navigator to display a list or grid of all applications in your account.

All applications

In the All applications tab, you can see all applications available in your tenant. There are two kinds of applications:

Your applications are available through the application switcher in the top bar.

App switcher

Subscribed applications

Cumulocity IoT provides a variety of applications for different purposes. Depending on your installation and/or optional services your tenant will show a selection of the potentially available applications.

Below all applications are listed which are by default available in the Standard tenant or Enterprise tenant. In addition, numerous optional applications might be subscribed to your tenant.

Info
In the All applications tab, subscribed applications are labeled as “Subscribed”. Subscribed applications may not be added, modified or removed by the user but only by a tenant administrator.

Applications subscribed by default

Name in the UI Functionality Identification in the API Technical type Availability
Administration Lets account administrators manage users, roles, tenants and applications administration Web application Standard tenant, Enterprise tenant
Cockpit Manage and monitor IoT assets and data from a business perspective cockpit Web application Standard tenant, Enterprise tenant
Device management Manage and monitor devices, and control and troubleshoot devices remotely devicemanagement Web application Standard tenant, Enterprise tenant
Streaming Analytics Manage and edit Analytics Builder models and EPL apps (if enabled) Streaming Analytics Web application Standard tenant (limited version for Analytics Builder), Enterprise tenant (full version)
Digital twin manager Create and manage basic building blocks for Digital twins: Assets, Asset models and Asset properties digital-twin-manager Web application Standard tenant, Enterprise tenant

Custom applications

Custom applications may be:

In the All applications tab, custom applications are labeled as “Custom”.

To add a custom application

Click Add application at the top right of the All applications tab.

In the resulting dialog box, select one of the following methods:

To upload a web application
  1. Click Add application at the top right of the All applications tab.
  2. Select Upload web application.
  3. In the resulting dialog box, drop a ZIP file or browse for it in your file system.

The application is created once the ZIP file has been successfully uploaded.

Important
The ZIP file must contain the index.html and cumulocity.json in its root directory, otherwise the application will not work.

  1. Click Add application at the top right of the All applications tab.
  2. Select External application.
  3. In the resulting dialog box, enter the name of the application. The name will be shown as title of the application.
  4. Enter an application key, used to identify this application.
  5. Enter the external URL where the application can be reached.
  6. Click Save to create the application.

For details on the fields, see also Application properties below.

To install an application from a blueprint
  1. Click Add application at the top right of the All applications tab.
  2. Select Install from available packages.
  3. Select the desired package.
  4. In the resulting dialog box, enter the name of the application. The name will be shown as title of the application.
  5. Enter an application key, used to identify this application.
  6. Enter the path where the application can be reached.
  7. Click Save to create the application.

For details on the fields, see also Application properties below.

To duplicate an application

Duplicating an application might be useful if you want to customize a subscribed application according to your needs. Duplicating a subscribed application creates a copy of the application as an own application, with a link to the original application.

  1. Click Add application at the top right of the All applications tab.
  2. In the upcoming dialog, select Duplicate existing application.
  3. Select the desired application from the dropdown list, for example “Cockpit”.
  4. In the next window, provide a name for the application, an application key to identify the application, and a path as part of the URL to invoke the application. Per default, the values of the original application are provided, extended by a number. If you set the path to the path of the original subscribed application, your own application will overrule the subscribed application.
    Info
    The platform restricts the use of the prefix “feature-” in the Name field. You cannot create applications using this prefix in the application name. This also applies to existing applications in cases where the duplicate application feature is used.
  5. Finally, click Duplicate to create the application.
Info
In case the application has been subscribed to the tenant, there is an additional toggle Overrule subscribed application. If you turn this toggle on, the values for name, key and path will be inherited from the original application and your duplicated application will overrule the subscribed application. Turn it off, to modify the values.

Duplicate application

For details on the fields, see also Application properties below.

Application properties

To display further details on an application, click it to open its Properties tab.

Application properties

In the Properties tab, each application will show the following information, depending on the application type (hosted or external):

Field Description Hosted (web application) External
ID Unique ID to identify the application Automatically provided Automatically provided
Name Application name; will be shown as title of the application in the top bar and in the application switcher Automatically created Specified by the user
Application key Used to identify the application and to make it available for subscription, see the Concepts guide Automatically created Specified by the user
Type Application type Hosted External
Path Part of the URL invoking the application Automatically created Specified by the user; for example, if you use "hello" as application path, the URL of the application will be "/apps/hello"

Extensions

Extension packages are combinations of plugins and blueprints which can be packed together into a single file and then be deployed to the platform. Thus, they offer better shareability and reusability of UI features across different applications and allow to add UI features to applications without coding knowledge.

Extension packages can contain two types of content:

Blueprint applications must be deployed, while plugins are added to other applications. This allows you to scaffold entire solutions or to extend existing ones. Due to the micro frontend technology, this can happen at runtime without rebuilding.

Packages can be located on the Extensions page.

Packages view

Packages can be filtered by name, creator type, availability and type of content.

To add a new extension package click Add extension package at the top right.

By clicking on a package, you can see the package details such as Extension package overview which includes a description and images as well as some meta information which is taken from the package.json.

Additionally, it is possible to view all available plugins within the selected package at the right. To install a plugin click Install plugin and select the desired application.

Packages overview

In the Versions tab, you see all previously uploaded binaries related to the current package. The binaries displayed on this tab can be downloaded via the context menu next to each package version entry.

Versions view

You can select or upload different versions. Versions indicate the state of the package. They can be used to verify whether a certain package is outdated and needs to be updated. By clicking on a version additional information is provided such as package contents, applications or plugins. Tags can be used to give versions meaningful names. The “latest” tag is used to indicate the default version which will be selected in case no tag is provided. The “latest” tag is set by default to the latest version whenever a version is uploaded without a given tag.

To switch to a different version open the context menu for the desired version and click Set as latest. To delete a version click Delete.

Plugins

Switch to the Plugins tab of an application to view all plugins installed on an application.

Plugins grid

In the Plugins tab you can add and remove plugins. Additionally, you can install plugins to an application.

To edit an application

Simply click the application or click the menu icon at the right of an entry and then click Edit.

In the Properties tab, several fields can be modified, depending on the application type (see Application properties).

Important
Never change the system application names (such as “Device management”, “Cockpit”). Otherwise, tenant initialization will fail.

To delete an application

Click the menu icon at the right of an entry and then click Delete. You can also delete an application directly from the Properties tab in the application details.

If you delete an application that overwrites a subscribed application, the currently subscribed application becomes available to all users. Additionally, the users will then also benefit from future upgrades of the subscribed application.

It is not possible to delete subscribed applications. This can only be done by the owner of the subscribed application.

Uploading archives

For custom applications, multiple file versions can be stored in Cumulocity IoT when they were created by uploading either a ZIP file or a MON file. Each version is called an archive. You can upload different versions at the same time and switch between these versions.

To upload an archive

  1. Open the application properties for the respective application by clicking on it.
  2. Click the plus button at the bottom of the Activity log section and browse for the archive in your file system or simply drop the archive file.
  3. Click Upload to upload the archive to your Cumulocity IoT account.
Application archive

Once uploaded, the recently uploaded version is automatically the active version, that is the version of the application that is currently being served to the users of your account. This version cannot be deleted.

Info
The archive functionality is not available for subscribed applications, as only the owner of the application can perform these actions.

To restore an older application version

Users can restore previous versions of an application from an archive.

  1. Open the application properties for the respective application by clicking on it.
  2. In the Activity log section, open the context menu for the desired version by clicking the menu icon and select Set as active to make it the active version.

To reactivate a single application

If a hosted application is not deployed correctly, users may reactivate it.

  1. Open the application properties for the respective application by clicking on it.
  2. In the Activity log section, open the context menu for the desired version by clicking the menu icon and select Reactivate archive.

The selected application will be reactivated by removing the respective files from the application directory and unpacking the web application package again.

Features

Features are applications which are built-in and not represented by an explicit artifact (like microservices or web applications).

In the Features tab, you will find a list of all features subscribed in your tenant. In an Enterprise tenant, the following features are available by default:

Name in the UI Functionality Identification in the API Availability
Feature-branding Customize the look of your tenants to your own preferences feature-branding Enterprise tenant
Feature-broker Share data selectively with other tenants feature-broker Enterprise tenant
Feature-user-hierarchy Reflect independent organizational entities in Cumulocity IoT that share the same database feature-user-hierarchy Enterprise tenant
Info
All applications listed here are of the type “Feature”.

Other features may show up, depending on the individual subscriptions of your tenant.

Managing and monitoring microservices

Click Microservices in the Ecosystem menu in the navigator to display a list or grid of all microservices subscribed to your account.

Microservices list

A microservice is a specific type of application, that is a server-side application used to develop further functionality on top of Cumulocity IoT. As web applications, microservices can either be subscribed to your tenant by the platform or by a service provider, or they can be owned by you as custom applications, see Custom microservices.

Subscribed microservices

Cumulocity IoT provides a variety of microservice applications for different purposes. Depending on your installation and/or optional services your tenant will show a selection of the potentially available applications.

Below you find a list of all microservices which are by default subscribed in a Standard tenant and/or Enterprise tenant. In addition, numerous optional microservices might be subscribed to your tenant.

Microservices subscribed by default

Name in the UI Functionality Identification in the API Availability
Apama-ctrl-* Streaming Analytics microservices, including runtime for Analytics Builder, EPL apps and smart rules. Capabilities and resources vary depending on the microservice variant used apama-ctrl-* Standard tenant, Enterprise tenant
Device-simulator Simulate all aspects of IoT devices device-simulator Standard tenant, Enterprise tenant
Report agent Schedule data exports from within the Cockpit application report agent Standard tenant, Enterprise tenant
Smartrule Use the smart rules engine and create smart rules to perform actions based on realtime data. Requires a variant of the Apama-ctrl microservice smartrule Standard tenant, Enterprise tenant
Sslmanagement Activate your own custom domain name by using an SSL certificate sslmanagement Enterprise tenant
Info
All applications listed here are of the type “Microservice”.

Custom microservices

To add a microservice as custom application

  1. Click Add microservice at the top right.
  2. In the resulting dialog box, drop a ZIP file or browse for it in your file system. Note that the size limit of the file to be uploaded is 500 MB.
  3. The microservice application is created once the ZIP file has been successfully uploaded.
Important
The ZIP file must contain the application manifest and the Docker image of the microservice. Refer to General aspects in the Microservice SDK guide for information on preparing and deploying the microservice package. You can provide the name of the microservice in its manifest file. If no name is provided in the file, the platform will derive it from the ZIP file name by removing the recognized version suffix. In any case the length of the resulting name must not exceed 23 characters.

Microservice properties

To display further details on a microservice, click it to open its Properties tab.

Microservice properties

In the Properties tab, each microservice will show the following information:

Field Description Comment
ID Unique ID to identify the microservice Automatically provided
Name Application name; will be shown as title of the microservice application in the top bar Automatically inferred from the ZIP file name (recognized version number is dropped), unless provided in the microservice's manifest file
Application key Used to identify the microservice application and to make it available for subscription, see the Concepts guide Automatically created, based on the ZIP file name
Type Application type Microservice
Path Part of the URL invoking the application Automatically created as /service/<microservice-name>

Below, you will additionally find information on the microservice version, as well as on its isolation level and billing mode, see Enterprise tenant > Usage statistics and billing > Microservice usage for details on these parameters.

Microservice subscription

At the top right of the Properties tab, you find a toggle to subscribe to or unsubcribe from a microservice.

Changing the subscription is only possible for custom microservices, that is microservices being owned by you.

Microservice permissions

In the Permissions tab you can view the permissions required for the respective microservice, and the roles provided for it.

Monitoring microservices

You can monitor microservices hosted by Cumulocity IoT in two ways.

Status information

The status of the microservice can be checked in the Status tab of the respective microservice application.

Microservice status

To view the status you need the following permissions: role Application management READ and role Inventory READ.

The following information is provided on the Status tab:

Alarms and events

Most of the alarms and events visible in the Status tab are strictly technical descriptions of what’s going on with the microservice.

There are two user-friendly alarm types:

User-friendly alarms are created for the microservice owner tenant only. They are also automatically cleared when the situation gets back to normal, that is all the microservice instances are working properly.

User-friendly alarms can be used to create smart rules. For details on creating smart rules of various types, see Smart rules.

For example, to send an email, if a microservice is down, create an “On alarm send email” smart rule.

In the On alarm matching section, use c8y_Application_Down as an alarm type. As a target asset select the microservice which you would like to monitor, for example “echo-agent-server”.

Log files

Cumulocity IoT offers viewing logs which provide more details on the status of microservices owned by the tenant.

To view logs, open the Logs tab of the respective microservice.

At the top of the page, you can select the instance of the microservice, for which you want to view the logs.

Info
If your microservice was re-scaled into two instances you should be able to switch between them, but it is not possible to see the logs from both instances at once.

Next to the instance dropdown you can select the time range for the log entries to be shown by selecting a date from the calendar and entering a time.

Info
The time entered here may differ from the server time due to different time zones.

At the top right, additional functionality is provided:

Initially, the Logs tab shows the latest logs of the microservice instance.

At the bottom right you find navigation buttons:

If no logs are available in the selected time range, a message is shown accordingly:

Microservice log
Info

There is no possibility to see the logs from the previously running instances or from previously rotated logs exceeding 35 MB. However, inside the instance there is a Docker container running, and if only this one was restarted (not the whole instance) you should see the logs from the currently running and also lately terminated Docker container.

Logs are always loaded from the Docker container using both stdout and stderr sources, and there is no possibility to distinguish/filter by the source.

Managing business rules

Alarm mapping

Alarm mapping enables you to change the severity and text of alarms to adapt them to your business priorities. For example, a loss of the connection to a device is by default a MAJOR alarm but may be critical to you. To change this, add an alarm mapping to change alarms related to connection losses to CRITICAL.

Requirements

ROLES & PERMISSIONS:

  • To view alarm mappings: READ permission for the permission type “Option management”.
  • To manage (create, edit, or delete) alarm mappings: ADMIN permission for the permission type “Option management”.

For easier user access management, the above permissions are included in the global role created by default in every new tenant:

  • Tenant Manager - manages tenant-wide configurations like applications, tenant options and business rules.

To view alarm mappings

Click Alarm mapping in the Business Rules menu to see a list of all alarm mappings.

Alarm mapping

For each alarm mapping, the alarm severity, the alarm type and a description (optional) are shown.

To add alarm mapping

  1. Click Add alarm mapping in the top menu bar.
  2. Enter the alarm type to be modified.
  3. In the New description field, optionally enter a new description for the alarm. If you leave this field empty, the original text from the alarm will be kept.
  4. Select the desired new severity, or select “Drop” to not show the alarm at all.
  5. Click Save to save your settings.
Info
The alarm type provided as an alarm mapping is interpreted as alarm type prefix: "<type-prefix>*". If you create, for example, an alarm mapping to address alarms of type "crit-alarm", the mapping is effective for any type of alarm that starts with this value e.g. "crit-alarm-1", "crit-alarm-2", or "crit-alarm-xyz".

To edit an alarm mapping

Expand an alarm mapping to edit it. You may modify the description and the alarm severity. The alarm type is not editable.

Info
Refresh the list to discard any changes without saving.

To delete an alarm mapping

To delete an alarm mapping, hover over it and click the delete icon which appears on hovering over the row.

Managing data

Retention rules

Retention rules give you control on how long data is stored in your account. By default, all historical data is deleted after 60 days (configurable in the system settings by the platform administrator). You might however want to store measurements for 90 days for example, but delete alarms already after 10 days.

Info
Retention rules are usually run during the night. When you edit a retention rule, you will not see an immediate effect in the Usage section on the Home screen of the Administration application.

To view retention rules

Click Retention rules in the Management menu to view a list of retention rules configured for your account.

Retention rules

For each rule, the rule name, details on the data to be deleted (fragment type, type and source, see below) and the maximum age in days is provided.

The asterisk ("*") indicates that data with any value will be cleaned up.

Data types

The following data types are covered under retention rules:

Info
Retention rules do not apply to files stored in the files repository.

To add a retention rule

  1. Click Add rule in the top menu bar.
  2. In the resulting dialog box, select the type of data to be cleaned up (alarms, measurements, events, operations, audit logs or all).
  3. Enter a fragment type if you want to be more specific about the data to be cleaned up. To clean up all connection loss alarms with this rule, select “Alarm” and enter “c8y_UnavailabilityAlarm” as property into the Type field.
  4. If you want to remove data only from a specific device, enter the device ID into the Source field.
  5. Enter the Maximum age in days (max. allowed value is 10 years in days).
  6. Click Save to save your settings.

The retention rule will be added to the list.

Info
Per default, an asterisk ("*") is set in all fields except the Maximum age field, to include all values. Alarms are only removed if they have a status of CLEARED.

To edit a retention rule

Simply click the row of the rule you want to edit.

For details on the fields, see To add a retention rule.

To delete a retention rule

Hover over the row with the rule you want to delete and click the delete icon that appears on the right.

All retention rules are executed sequentially and independent of each other. So if we have two retention rules, a more specific one with a greater maximum age that defines a subset of the documents that are defined by a more common rule with a lower maximum age, then effectively it will work as if we had a single, more common rule.

For example given the two following rules:

Data type Fragment type Type Source Maximum age
MEASUREMENT * c8y_Temperature * 30 days
MEASUREMENT * c8y_Temperature 12345 60 days

All measurements with the type c8y_Temperature which are older than 30 days will be removed, including those where the source equals 12345.

On the other hand when we have the following retention rules defined:

Data type Fragment type Type Source Maximum age
MEASUREMENT * c8y_Temperature * 30 days
MEASUREMENT * * * 60 days

The retention process removes the measurements with the type c8y_Temperature which are older than 30 days, all other measurements will be removed when they are older than 60 days.

Info
The source parameter is the ID of the device. When it is defined, the retention process only removes the documents directly related to the device represented by the source, not its children or groups it belongs to.

Managing files in the file repository

The file repository provides an overview of the files stored in your account.

Click Files repository in the Management menu to see a list of files.

The files listed can come from various sources. They can be software images, configuration snapshots taken from devices, log files from devices or web applications uploaded from the All applications page.

For each file, the name of the file, its owner, the file type (for example, image/bmp, text/csv), its size and the date when it was last updated is provided.

Files Repository

To upload a file from your file system

Click Upload file in the top menu bar. In the resulting dialog box, select a file to be uploaded. If you want to upload more than one file, click Add file to select another file. You may also delete a file before uploading by clicking the delete icon on the right of the file field.

To download a file from your account

Click the menu icon at the right of the respective row and then click Download.

To delete a file from your account

Click the menu icon at the right of the respective row and then click Delete.

Info
If the file corresponds to an active application, it cannot be deleted. You must first remove or upgrade the application to be able to delete it.

Changing settings

From the Settings menu, administrators can manage various settings for the account:

Requirements

ROLES & PERMISSIONS:

To see the Authentication menu item, you must have ADMIN permission for the “Tenant management” permission type or be the first admin user created in the tenant.

For easier user access management, the above permission(s) are/is included in the global role(s) created by default in every new tenant:

  • Tenant manager - manages tenant-wide configurations like applications, tenant options and retention rules.

Changing authentication settings

Click Authentication in the Settings menu if you want to view or change the Login or TFA settings.

Authentication settings

Login settings

In the Preferred login mode field, you can select one of the following options:

This login mode will be used by the platform’s applications as the default method to authenticate users. Device authentication stays unchanged.

Important
Each time you change the login mode you will be forced to log out. Other users will need to log out and log in again so that the change is applied.

In the field Password validity limit, you can limit the validity of user passwords by specifying the number of days after which users must change their passwords. If you do not want to force your users to change passwords, use “0” for unlimited validity of passwords (default value).

Info
The password validity limit is not imposed on users with a “devices” role. This prevents device passwords from expiring.

By default, users can use any password with eight characters or more. If you select Enforce that all password are “strong” (green), users must provide strong passwords as described in Getting Started > User options and settings > To change your password.

Info
The password validity limit and the password strength may not be editable, if configured by the platform administrator.

Basic Auth restrictions

Even if OAI-Secure authentication is configured for users, basic authentication remains available for devices and microservices using the platform. To provide a higher security level the basic authentication can be restricted.

Use the Forbidden for web browsers toggle to disallow the usage of basic authentication for web browsers. Moreover you can specify the following parameters:

Info
If the user agent is not found in the list of trusted or forbidden user agents then Cumulocity IoT will try to verify if it is a web browser using an external library.

OAI-Secure

OAI-Secure is a more secure alternative to the Basic Auth mode that also supports username and password login. In OAI-Secure mode the credentials in the initial request are exchanged for a JWT token that is set as a cookie in the web browser or returned in the response body. Based on the configuration OAI-Secure can support full session management or work as a standard JWT authentication where the user session lifetime is limited by the token expiration time.

When there is no configuration related to the session, OAI-Secure issues a JWT token with a certain lifetime. If the token expires then the user is forced to re-login because token refresh is not supported. This behavior is very inconvenient for the user if the token lifetime is short because the user is forced to re-login frequently.

OAI-Secure with the configuration of the session management (session configuration turned on)

Using OAI-Secure with session configuration is more convenient and secure, and can be used to achieve a behavior which is similar to the authentication based on HTTP sessions.

The OAI-Secure token acts as a session identifier on the client side (web browser). Such a token identifier which is stored in the cookie can have a preconfigured short lifetime. Then, the Cumulocity IoT platform is responsible for renewing the session identifier without any user interaction. It is sufficient that the user’s action causes the web browser to send a request to Cumulocity IoT. Then, Cumulocity IoT can examine if the renewing of the session identifier should be executed and perform the operation if necessary. Cumulocity IoT offers extensive configuration related to this behavior so that tenant administrators can adjust the configuration to their needs.

If the Use session configuration option is enabled, the following settings can be configured on tenant level by a tenant administrator:

Field Description Default
User agent validation required If turned on, the user agent sent in headers of consecutive requests in the scope of one session will be compared and a request with changed user agent will not be authorized. false
Session absolute timeout Defines the maximum period of time that the user can use Cumulocity IoT without having to re-authenticate. 14 days
Session renewal timeout Expected to be much shorter than the absolute timeout. Defines the time after which Cumulocity IoT tries to provide a new token (session identifier). The renewal may take place only when Cumulocity IoT receives an HTTP request from a client with a non-expired token and the period of time between obtaining the token and the execution of the request is greater than the renewal timeout. 1 day
Maximum parallel sessions per user Defines the maximum number of sessions which can be started by each user (for example on different machines or browsers). When a user exceeds this limit, then the oldest session will be terminated and the user will be logged out on this particular device. 5 sessions
Token lifespan Defines the time for which a token is active. The user is only able to access Cumulocity IoT with a valid token. This configuration option is always available, it does not depend on session configuration. See Token generation with OAI-Secure below. 2 days
Info

The time parameters should depend on each other in the following manner: renewal timeout < token lifespan < absolute timeout. Moreover, the renewal timeout should be approximately half of the token lifespan.

Therefore, the recommended settings for a standard use case for OAI-Secure are the following:

  • Session absolute timeout: 28 800 seconds (8 hours)
  • Session renewal timeout: 2700 seconds (45 minutes)
  • Token lifespan: 5400 seconds (90 minutes)

In such configurations, the idle timeout is in the range of 45 to 90 minutes, depending on when the last activity for the session was performed.

During the session token renewal the previous token is revoked and a new one is provided. The parameter renewal token delay defines the delay used to make this process smooth and not disturbing for the user. The old token is still valid for this period (1 minute by default). This way both tokens, old and new, are accepted by Cumulocity IoT. This parameter is only configurable on platform level and cannot be modified by the tenant administrator.

Token generation with OAI-Secure

OAI-Secure is primarily based on JWT stored in a browser cookie. It can be also used to generate JWT in the response body. The lifespan of the tokens and the cookie is configurable by tenant options belonging to the category oauth.internal.

JWT tokens stored in the browser cookie have a default validity time of two weeks. This can be changed with tenant options:

The minimum allowed value is 5 minutes.

Lifespan configuration of cookies

Cookies used to store a JWT token in a browser have their own validity time that can be changed with tenant options:

The default value is two weeks. To have the cookie deleted when the user closes the browser, set it to any negative value.

Lifespan configuration of JWT in response body

The lifespan of JWT tokens generated in the response body is configured with the following tenant options:

Refer to the Tenant API in the Cumulocity IoT OpenAPI Specification for more details.

Info
If external communication to the Management tenant has been blocked, then it is only possible to access the tenant in a secure way (for example via SSH tunnel). This means that you can just as well use basic authentication. Additionally, it is not possible to use single sign-on since the communication from the external authorization server is also blocked. Therefore, the authentication method is automatically set to “Basic authentication” if the Management tenant is configured to block external communication.

TFA settings

Select the checkbox Allow two-factor authentication if you want to allow TFA in your tenant (only possible for administrators).

You may select one of the following options:

Info
The TOTP method is only available with the login mode “OAI-Secure”.

Click Save TFA settings to apply your settings.

Important
Each time you change the TFA method you will be forced to log out. User TFA settings are cleared and must be configured again.
Info
Users with a “devices” role are excluded from TFA and TOTP. This is also true when TOTP is enforced for all users.

Changing application settings

Click Application in the Settings menu to change applications settings.

Application settings

Under Default application, you can select a default application from the list which will apply to all users within the tenant. Whenever the platform is accessed, for example, by domain name only, without mentioning a specific application, the application selected as default application is used as default landing page.

Info
All users must have access to this application.

Under Access control, administrators can enable cross-origin resource sharing or “CORS” on the Cumulocity IoT API.

The Allowed Domain setting will enable your JavaScript web applications to directly communicate with REST APIs.

For further information, see http://enable-cors.org.

Managing the properties library

Click Properties library in the Settings menu, to add custom properties to inventory objects, alarms, events and tenants.

Properties library

With custom properties, you can extend the data model of Cumulocity IoT built-in objects. You may create the following custom values:

Info
Custom properties are visible to all authenticated users of the tenant, regardless of their inventory role permission.

To add a custom property

  1. Select the tab for the desired property and click Add property.

  2. In the resulting dialog box, provide a unique name as identifier and a label for the property and select its data type from the dropdown list.

  3. Additionally, select validation rules for the new property:

Checkbox Description
Required If selected, the property needs to be provided, for example, during alarm creation. Not available if the property type is "Boolean".
Default Value Provide a default value to be automatically filled in the custom property field. Only available for properties with type "string".
Minimum Enter a minimum integer value.
Maximum Enter a maximum integer value.
Minimum length Enter the minimum length required for the string.
Maximum length Enter the maximum length required for the string.
Regular expression Add a regular expression which will be required in order to fill the custom property field.
  1. Click Save to create the new property.

To edit a custom property

  1. Click on the name of a property in the list to open it.
  2. Do your edits. For details on the fields see To add a custom property.
  3. Click Save to save your settings.

To remove a custom property

  1. Click on the name of a property in the list to open it.
  2. Click Remove to delete the property.

Providing SMS provider credentials

SMS are used throughout the platform for various features like two-factor authentication and user notifications, for example, on alarms.

By providing your credentials you enable platform features that utilize SMS services.

To enter SMS provider credentials

  1. Click SMS provider in the Settings menu.
Info
To see the SMS provider configuration, you must have the permission SMS READ. To modify the SMS provider configuration, you must have the permission SMS ADMIN.
  1. In the SMS provider page, select one of the available SMS providers from the SMS provider dropdown field. You can start typing to filter items and more easily find your preferred provider.

  2. In the resulting dialog, enter the required credentials and properties or specify optional settings, which differ depending on the provider you selected.

  3. Click Save to save your settings.

Info
OpenIT does not serve new customers anymore and is in the process of shutting down their SMS provider business. We therefore recommend you to select one of the other SMS providers.

Managing the connectivity settings

In the Connectivity page, you can manage credentials for different providers. In order to add or replace credentials ADMIN permissions are required.

The following provider settings may currently be specified:

To provide or replace credentials

  1. Switch to the tab of your desired provider.
  2. Enter the URL of the provider.
  3. Enter the credentials of your provider platform. Depending on the provider, these credentials will be either the credentials of your account in the provider platform or the credentials with which you can register in the Cumulocity IoT connectivity page, will be displayed in your account in the provider platform.
  4. Finally, click Save to save your settings.

Depending on the provider you have selected, there may be additional fields, which will be explained in the respective agent documentation, see Protocol integration guide.

Two-factor authentication

The two-factor authentication (TFA) is an extra layer of security that only completes authentication with a combination of two different factors: something the users know (username and password) and something they have (for example, smartphone) or something they are (for example, fingerprint). You can read more on how to configure TFA in the authentication settings section.

There are two possible TFA strategies: Short Message Service (SMS) and Time-based One-Time Password (TOTP). Only one of them can be active at a time.

To check whether TFA is enabled for a certain user, go to the Users page and see the TFA status column right from the password strength column. A key icon indicates that TFA is enabled and by hovering over it you can see the strategy that is being used.

TFA status

SMS

Requirements
When adding a user and TFA is enabled, a mobile phone number must be specified. Without a valid phone number a login is impossible.

How to enable a specific user

  1. In the Administration application, navigate to Accounts > Users and select a user in the Users page.
  2. Select the checkbox next to Enable two-factor authentication.
  3. Click Save.

Enable TFA

Info
This process can only be executed in the Administration application and is not available under User settings.

TOTP

Requirements
Users must install a TOTP application on their smartphone (Google Authenticator is recommended), freely available both on App Store and Play Store.

Setup

Opposed to the SMS strategy TOTP must be set up by each user. By opening User settings in the top right corner and then clicking Set up two-factor authentication they can start the setup process. Trigger TOTP setup

IF TFA is enabled, the user will be presented a QR code at login, that needs to be scanned with the previously installed TOTP mobile application.

Alternatively, the secret can also be inserted manually in case scanning the QR code is not an option.

TOTP setup process

After this process the mobile application will generate a new code every 30 seconds that can be used to complete the authentication process.

Revoking the secret

If a user loses access to the TFA code, for example, if a user loses the phone or uninstalls the application, and needs to set it up again, the secret must be revoked. TOTP must be set up by each user individually.

Requirements

Users can not revoke their own TOTP secret. The secret of a user is only revoked by their respective parent user. See Enterprise tenant > Managing user hierarchies in the User guide for detailed information on user hierarchies.

ROLES & PERMISSIONS:

  • To revoke a secret: ADMIN or CREATE permission for permission type “User management”
  1. In the Administration application, navigate to Accounts > Users and select a user in the Users page.
  2. Scroll down to Login options.
  3. Click Revoke TOTP secret.
  4. Confirm by clicking Revoke.

TOTP secret revoke

Disabling TOTP for a user

If a user wants to turn off the use of TOTP (and thus TFA) completely, the secret must be revoked and TOTP enforcement must be disabled. TOTP must be set up by each user individually.

Requirements

ROLES & PERMISSIONS:

  • To revoke a secret: ADMIN or CREATE permission for permission type “User management”
  • To disable TOTP enforcement: ADMIN permission for permission type “User management”

To disable TOTP for a user follow these steps:

  1. In the Administration application, navigate to Accounts > Users and select the user in the Users page.
  2. Scroll down to Login options.
  3. Clear the Enforce TOTP for the user checkbox.
  4. Click Revoke TOTP secret.
  5. Confirm by clicking Revoke.
  6. Click Save to save your changes.

TOTP disable user

Configuring single sign-on

Cumulocity IoT provides single sign-on (SSO) functionality, that allows a user to login with a single 3rd-party authorization server using the OAuth2 protocol, for example Azure Active Directory (AAD). Currently authorization code grant is supported only with access tokens in form of JWT. SAML is not supported. On top of standard SSO, Cumulocity IoT also allows you to access the platform resources using access tokens from your authorization server directly as a Bearer token. For details refer to Configuring authentication with OAuth2 access tokens from authorization servers.

Requirements

To use the SSO feature the following requirements must be met:

  • The authorization server you use supports OAuth2 authorization code grant.
  • The access token is issued as JWT and you know what goes into the token content.
  • The JWT must consist of a unique user identifier, “iss” (issuer), “aud” (audience) and “exp” (expiration time) fields.
  • All microservices are built with Microservice Java SDK version 10.4.6 but preferably higher. For custom-built microservices, refer to General aspects > Security in the Microservice SDK guide.
  • For on premises installation the domain-based tenant resolution is configured properly.
  • For Enterprise tenants, the enterprise domain must be set up as redirect URI in the basic configurations. If SSO providers have a list of allowed domains, the enterprise domain should be added to that list.
  • You must assign a role to the user with at least READ permission for “Own user management”, otherwise the user cannot log in.
  • Users must have cookies enabled in the browser settings, as the SSO feature is built on top of cookies technology.

Configuration settings

To enable the SSO feature, the administrator must configure a connection with the authorization server. This is done in the Administration application.

Configuration access

SSO configurations can be configured to be exclusively accessible by the Management tenant, thus preventing other tenants from accessing the configurations. Users of such tenants are unable to update the configuration. This removes the risk of an incorrectly configured SSO, which can prevent other users from logging in via SSO. The Management tenant can grant or restrict access to SSO configurations for specific tenants. For more information about configuration access, refer to the Login options API in the Cumulocity IoT OpenAPI Specification.

Configuration view

Click the Single sign-on tab in the Authentication page. Note that the tab is only visible for tenants which have access to the SSO configuration.

At the top left, you can select a template. The selected option has an effect on the look of the panel. The default template is “Custom” which allows for a very detailed configuration with virtually any authorization server using OAuth2 authorization code grant. Other templates provide simplified views for well known and supported authorization servers. In the next steps there will first be a definition of how to use the “Custom” template followed by a view dedicated to Azure Active directory.

Custom template

Custom authorization request

As the OAuth protocol is based on the execution of HTTP requests and redirects, a generic request configuration is provided.

The first part of the Single sign-on page consists of the request configuration. Here you can configure the HTTP request address, request parameters, headers and body in case of token and refresh requests. The authorize method is executed as a GET, token and refresh method by POST requests.

Info
Be aware that the body field of each request, after filling placeholders with values, is sent in the request ‘as is’. This means it is not encoded by Cumulocity IoT. Many authorization servers require values inside the body to be URL-encoded (x-form-urlencoded). This can be achieved by entering already encoded values in a body field.

Specifying a logout request is optional. It performs front-channel single logout. If configured, the user is redirected to the defined authorization server logout URL after logging out from Cumulocity IoT.

Custom logout request

The Basic section of the Single sign-on page consists of the following configuration settings:

Custom basic configuration

Field Description
Redirect URI Redirect parameter. Can be used in request definitions as a ${redirectUri} placeholder
Client ID OAuth connection client ID. Can be used in request definitions as a ${clientId} placeholder
Token issuer OAuth token issuer
Button name Name displayed on the button on the Login page
Provider name Name of the provider
Audience Expected aud parameter of JWT
Visible on Login page Indicates whether the login option is enabled or not

Each time a user logs in, the content of the access token is verified and is a base for user access to the Cumulocity IoT platform. The following section provides the mapping between JWT claims and access to the platform.

Custom access mapping

In the example above, if a user tries to login a decoded JWT claims look like:

{
...
"user": "john.wick",
...
}

The user will be granted access to the global role “business”, the default application “cockpit” and the inventory roles “Manager” and “Reader” for the device group named “region north”.

If no access mapping matches the user access token, the user will get an “access denied” message when trying to log in. This will also happen if there is no access mapping defined causing all users to be unable to log in using SSO.

New rules can be added by clicking Add access mapping or Add inventory roles at the bottom. An access mapping statement can consist of multiple checks like in the image below. You can add a rule to an existing statement by clicking and. Click the Minus button to remove a rule.

New roles are added to the user from every matching access mapping. If one access mapping statement assigns the role “admin” and a second one assigns the role “business” and both meet the defined conditions, then the user will be granted access to the global roles “business” and “admin”."

When using “=” as operator you may use wildcards in the Value field. The supported wildcard is asterisk (*) and it matches zero or more characters. For example, if you enter “cur*” this matches “cur”, “curiosity”, “cursor” and anything that starts with “cur”. “f*n” matches “fn”, “fission”, “falcon”, and anything that begins with an “f” and ends with an “n”.

In case the asterisk character should be matched literally it must be escaped by adding a backslash (\). For example, to match exactly the string “Lorem*ipsum” the value must be “Lorem\*ipsum”.

Custom access mapping

In this case the following claim will match the condition:

{
...
"user": {
   "type": "human"
},
"role": [
   "ADMIN"
],
...
}

There is an option to verify that a value exists in a list via the “in” operator. Values can also be embedded in other objects. In this case a dot in the key implies looking into an embedded object.

The user access mapping configuration provides the following options:

Custom access mapping

Selecting one of the two options mentioned above will also enable admins to edit roles of SSO users in the user management. For details, refer to Administration > Managing permissions in the User guide.

When a user logs in with an access token, the username can be derived from a JWT claim. The claim name can be configured in the User ID configuration window. The user ID can be set to any top-level field of the authorization token payload sent from the authorization server to the platform during the login process. We recommend you inspect the authorization token in the audit logs to make sure the correct field is used (see Troubleshooting).

User ID configuration

If the Use constant value checkbox is selected, a constant user ID is used for all users who log in to the Cumulocity IoT platform via SSO. This means that all users who log in via SSO share the same user account in the Cumulocity IoT platform. Usage of this option is not recommended.

Next, the User data mappings can be configured:

User data mappings

On user login, user data like first name, last name, email and phone number can also be derived from JWT claims. Each field represents the claim name that is used to retrieve the data from JWT. The user data mapping configuration is optional and as admin manager you can only use the required fields. If the configuration is empty or the claim name cannot be found in the JWT token then the values in the user data are set as empty.

Mapping for alias is not available because it is not used in the context of SSO login.

Each access token is signed by a signing certificate. The following options are available to configure the signing certificates.

  1. By specifying the Azure AD certificate discovery address.

Signature verification Azure

  1. By specifying the ADFS manifest address (for ADFS 3.0).

Signature verification ADFS

  1. By providing the public key of a certificate manually to Cumulocity IoT. A certificate definition requires an algorithm information, public key value and validity period.

Signature verification Custom

  1. By specifying the JWKS (JSON Web Key Set) URI. JWKS is a set of JWK objects containing a public key used to verify tokens issued by the authorization server.

Signature verification JWKS

Info
Cumulocity IoT only supports certificates with RSA key, either as a (“n”, “e”) parameters pair or “x5c” certificate chain. Other key types (for example Elliptic-curves) are not supported.

Placeholders

Inside some fields you can use placeholders that are resolved by Cumulocity IoT at runtime. Available placeholders are:

Placeholder Description
clientId Value of the Client ID field
redirectUri Value of the Redirect URI field
code Code returned by the authorization server in response to authorization request
refreshToken Refresh token returned by the authorization server after token request

These placeholders can be used in authorization requests, token requests, refresh requests and logout request in the fields:

To use a placeholder in a field, put it inside two curly brackets preceded with a dollar sign: Placeholder standalone

Placeholders can also be used as a part of text: Placeholder text

Info
Placeholders are not validated for correctness. Any not recognized or misspelled placeholder will be left in text unprocessed.

Configuring authentication with OAuth2 access tokens from authorization servers

You can directly request Cumulocity IoT to use access tokens from your authorization server. This way, your applications or users can access resources without logging in to the platform or using Basic authentication. This leverages your authorization server to get access tokens for your applications which you can send in subsequent request to Cumulocity IoT.

Requirements

This feature requires the following on top of the above requirements:

  • Your authorization server must support the OAuth2 client credentials grant type.
  • All microservices are built with Microservice Java SDK version 1018.6.0 or higher. For custom-built microservices, refer to General aspects > Security in the Microservice SDK guide.

Enable or disable this authentication option in the External token configuration section. External token disabled

If enabled, this authentication takes precedence over the standard JWT token authentication, which means, for example, that an HTTP request to Cumulocity IoT with the header Authorization: Bearer {{access token}} assumes that the source of the access token is your authorization server instead of the token being issued by Cumulocity IoT. Configure the user ID or the application ID to any top-level claim in the access token.

External token user id

Cumulocity IoT creates a user which gets assigned the configured user ID or application ID. Additionally, this user is granted the roles to access to the applications defined in the Access mapping section.

Info
If it is set, the configuration allows you to create a Cumulocity IoT user representing your applications (the access tokens are obtained via the client credentials flow), or the users of your authorization server (the access tokens are obtained with the password grant type).

By default, Cumulocity IoT verifies that the token is not expired and its signature matches the signature you have configured earlier. You can strengthen the validation of the token by configuring either an introspection or a user info validation with the necessary credentials. This way, the platform knows if the access tokens were intentionally invalidated or expired. You cannot access Cumulocity IoT resources with an invalidated access token.

Introspection endpoint

Cumulocity IoT uses token introspection to verify the validity of the access tokens of your applications. In general, this endpoint can be used for access tokens obtained via the client credentials flow or any other OAuth2 flow.

To configure the introspection, provide an introspection endpoint and a URL-encoded (x-form-urlencoded) body containing the access token, the client ID and the client secret, and an “Authorization” request header.
Cumulocity IoT requests the introspection endpoint of your authorization server to query the status of the access token. If the token is active, proceed with verifying the token signature.

External token introspection validation

You can configure the Access token validation frequency to set how often the introspection is performed as it may be costly to always call the authorization server for the same access token. The validation status of the token is cached internally for the specified time. If the token is revoked in the meantime, Cumulocity IoT will only be aware during the next validation, that is, the token is still considered until the next validation. To avoid this, use a frequency. The default value is one minute.

External token validation interval

User info endpoint

The user info request can also be used to check the validity of the access token of your users. Unlike introspection, a user info request requires a user context. This means you cannot use it to validate access tokens obtained with the client credentials flow.

External token userinfo validation

Caution
If you use one of the two validation methods, make sure that your authorization server exposes the introspection or the user info endpoint.

Integration with Azure AD

The integration was successfully verified against Azure AD using OAuth2 and OpenID Connect (SAML is not supported). The configuration steps are available in https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code.

The following steps illustrate how to use Azure AD (Azure Active Directory) for SSO in Cumulocity IoT.

Requirements
You need administrative access to your Azure AD.

Configuring Azure AD

To connect Cumulocity IoT to Azure AD, you must create an App registration in Azure AD.

  1. Select App Registrations under Manage on the left and at the top click New Registration.
  2. In the resulting window, provide a name for the new App registration.
  3. As Redirect URI type select “Web” and enter the URL to your tenant OAuth endpoint, for example “https://documentation.cumulocity.com/tenant/oauth”*". You can derive this value from your Cumulocity IoT tenant. Navigate to Administration > Settings > Authentication > Single sign-on. The redirect URL is prefilled by the platform.
  4. Click Register to create the App registration.

The overview in the details page of your App registration contains several IDs and endpoints that you need later on, like the Application (client) ID and the Directory (tenant) ID (for your tenant in Cumulocity IoT).

App registration overview

Moreover, the App registration requires a secret which is used by Cumulocity IoT for the authentication.

  1. In the details page of your App registration, click Certificates & secrets under Manage on the left.
  2. Select New client secret.
  3. Enter a description and select an expiry time.
  4. Click Add to add the secret.
Caution
  • Copy the value of the new secret to another location. It will no longer be visible once you have left the page.
  • The secret string must not include a “=” character as this may conflict with the later usage in a URL. If it does, create a new one.

Optionally, create a user in Azure AD that you would like to use with Cumulocity IoT.

Configuring SSO for Azure AD in Cumulocity IoT

Navigate to Settings > Authentication in the Administration application and switch to the Single sign-on tab.

Retrieve the relevant information by a GET request to:

https://login.microsoftonline.com/&lt;Directory tenant ID>/.well-known/openid-configuration

The response will look like this:

  {
      "token_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/oauth2/token",
      "token_endpoint_auth_methods_supported": [
          "client_secret_post",
          "private_key_jwt",
          "client_secret_basic"
      ],
      "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys",
      "response_modes_supported": [
          "query",
          "fragment",
          "form_post"
      ],
      "subject_types_supported": [
          "pairwise"
      ],
      "id_token_signing_alg_values_supported": [
          "RS256"
      ],
      "response_types_supported": [
          "code",
          "id_token",
          "code id_token",
          "token id_token",
          "token"
      ],
      "scopes_supported": [
          "openid"
      ],
      "issuer": "https://sts.windows.net/4d17551b-e234-4e18-9593-3fe717102dfa/",
      "microsoft_multi_refresh_token": true,
      "authorization_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/oauth2/authorize",
      "device_authorization_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/oauth2/devicecode",
      "http_logout_supported": true,
      "frontchannel_logout_supported": true,
      "end_session_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/oauth2/logout",
      "claims_supported": [
          "sub",
          "iss",
          "cloud_instance_name",
          "cloud_instance_host_name",
          "cloud_graph_host_name",
          "msgraph_host",
          "aud",
          "exp",
          "iat",
          "auth_time",
          "acr",
          "amr",
          "nonce",
          "email",
          "given_name",
          "family_name",
          "nickname"
      ],
      "check_session_iframe": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/oauth2/checksession",
      "userinfo_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/openid/userinfo",
      "kerberos_endpoint": "https://login.microsoftonline.com/4d17551b-e234-4e18-9593-3fe717102dfa/kerberos",
      "tenant_region_scope": "EU",
      "cloud_instance_name": "microsoftonline.com",
      "cloud_graph_host_name": "graph.windows.net",
      "msgraph_host": "graph.microsoft.com",
      "rbac_url": "https://pas.windows.net"
  }

Now enter the following values in the configuration:

Azure Cumulocity IoT Value
Login URL; OpenID config; Beginning of token endpoint Azure AD address Address of your Azure AD tenant, for example “https://login.microsoftonline.com”
Home > Overview > Primary Domain Tenant <directoryName>.onmicrosoft.com, for example “admtest.onmicrosoft.com”
OpenID config “issuer” Token issuer Token issuer value in form of a HTTP address: “https://sts.windows.net/<Directory tenant ID>/”. Note that this won´t work without the tailing slash.
App registration > <app> > Application (client) ID Application ID for example “7fd1ed48-f4b6-4362-b0af-2b753bb1af2b”
Redirect URI Address of your Cumulocity IoT tenant followed by /tenant/oauth
App registration - <app> > Certificates & secrets > Value Client secret Azure AD client secret, for example “hE68Q~uC1.BlSzGJSDC3_UEFvvyIZvRcCxbvV345”
From OpenID config Public key discovery URL “https://login.microsoftonline.com/common/discovery/keys” or “https://login.microsoftonline.com//discovery/keys”

Optionally single logout can be configured:

Field Description
Redirect after logout Activates single logout by redirecting the user, after logout, to the authorization server logout endpoint
Redirect URL Address to redirect the user to after successful logout from the authorization server

After configuring SSO in Cumulocity IoT, you can try to login. You might get an “access denied” error, if this user has no access mapping yet. But you should see a “User login” event and a JSON web token in the audit logs (Administration > Accounts > Audit logs).

The content looks like this:

{
    "typ": "JWT",
    "alg": "RS256",
    "x5t": "2ZQpJ3UpbjAYXYGaXEJl8lV0TOI",
    "kid": "2ZQpJ3UpbjAYXYGaXEJl8lV0TOI"
} {
    "aud": "7fd1ed48-f4b6-4362-b0af-2b753bb1af2b",
    "iss": "https://sts.windows.net/4d17551b-e234-4e18-9593-3fe717102dfa/",
    "iat": 1660815959,
    "nbf": 1660815959,
    "exp": 1660820080,
    "acr": "1",
    "aio": "ASQA2/8TAAAAg0xPUeu6HKAlgK3vZJsW8TdejlNB3BGSz4XFmJLzPt0=",
    "amr": [
        "pwd"
    ],
    "appid": "7fd1ed48-f4b6-4362-b0af-2b753bb1af2b",
    "appidacr": "1",
    "family_name": "Doe",
    "given_name": "Jane",
    "ipaddr": "51.116.186.93",
    "name": "Jane Doe",
    "oid": "afbff765-592e-4ae1-9334-b968dad59c84",
    "rh": "0.AXkAG1UXTTTiGE6Vkz_nFxAt-kjt0X-29GJDsK8rdTuxryuUAAw.",
    "scp": "openid User.Read User.Read.All User.ReadBasic.All",
    "sub": "zRTnTukAjU11ME1aqiPMOdwk9jVNmInXbeuoUr_3cYk",
    "tid": "4d17551b-e234-4e18-9593-3fe717102dfa",
    "unique_name": "jane@admtest.onmicrosoft.com",
    "upn": "jane@admtest.onmicrosoft.com",
    "uti": "IcTqpKPIA0G_P1Lyw6xBAA",
    "ver": "1.0"
} [
    256 crypto bytes
]

You can now use the claims to map user attributes and give permissions in the same way as described in the section on the custom template.

Integration with Keycloak

Global logout feature (available for Keycloak in version 12.0.0 and higher)

Integration with Keycloak allows administrators to use a global logout feature based on OpenId Connect. An event from the Keycloak authorization server is sent to all applications (including the Cumulocity IoT platform) with a logout token that is verified in the same way as the token used in the login process. This feature allows ending sessions on both sides, applications and Keycloak, for the particular user.

To configure the global logout feature follow these steps:

  1. Go to the administrator console.
  2. Select the realm used in the SSO configuration for the tenant.
  3. Navigate to Clients in the Configure section.
  4. Select the client used in the SSO configuration.
  5. Set the Backchannel Logout URL field to “https://mytenant.cumulocity.com/user/logout/oidc”.

To use the global logout feature follow these steps:

  1. Go to the administrator console.
  2. Select the realm used in the SSO configuration for the tenant.
  3. Navigate to Users in the Manage section.
  4. Select the particular user.
  5. Navigate to the Sessions tab in the Manage section and click Logout.

Logout all users feature

Keycloak also provides a feature which allows administrators to logout all SSO users.

To configure the logout all users feature follow these steps:

  1. Go to the administrator console.
  2. Select the realm used in the SSO configuration for the tenant.
  3. Navigate to Clients in the Configure section.
  4. Select the client used in the SSO configuration.
  5. Set the Admin URL to “https://mytenant.cumulocity.com/user/keycloak”

To use the logout all users feature follow these steps:

  1. Go to the administrator console.
  2. Select the realm used in the SSO configuration for the tenant.
  3. Navigate to the Sessions tab in the Manage section and click Logout all.

Note that the logout event for all users is only performed in the scope of one Keycloak realm. Moreover, it is only sent for those tenants where the client being used as a configuration for the SSO feature has the correct Admin URL value.

In the Session tab, the Keycloak administrator can also check how many active sessions exist on the respective client and estimate how many tenants and users will be affected by the logout event.

To confirm if the logout event for all users or a single user has been received by the tenant, the Cumulocity IoT administrator can verify if there is information about the logout event in the audit logs. The audit logs are available in the Administration application under Accounts in the Audit Logs tab.

Troubleshooting

It can be particularly helpful to inspect the content of the authorization token sent to the platform as some of its fields contain the information required for the correct configuration described above.

In Administration application, after clicking on Accounts > Audit logs you can filter by the category “Single sign-on” and look for entries “Json web token claims”.

The contexts of the token will be presented in JSON format.

Audit token content

Platform configuration settings

From the Management tenant, you can configure properties which apply globally to the whole Cumulocity IoT deployment.

Click Configuration in the Settings menu, to access the Configuration page.

Configuration settings

Most of the settings you can configure here are also available in the Enterprise tenant. For details, refer to Enterprise tenant > Customizing your platform.

In addition, the following settings can be configured in the Management tenant only.

Passwords

In the Passwords section, you can specify password settings like default strength, length or validity for the users in your tenant.

Select the checkbox Enforce “green” passwords for all users to enforce the users in your tenant to use passwords that meet the conditions for “green” passwords, see also Getting started > User options and settings.

Support user

In the Support user section you can configure the parameters for the support user access for subtenant users.

This feature enables Cumulocity IoT platform providers (Software AG in case of the public cloud instances or service providers with on-prem installations) to support their customers by accessing their users using a support user. A support user is a user in the Management tenant that has specific permissions, that is, to access subtenant users in case of any issues. Refer to Enterprise tenant > Support user access for more information.

In the field Activate support user, specify if support user access is activated for subtenant users. Possible values you can enter here are:

In the Validity limit field, you can optionally specify the support duration, that means, for how many hours support user access will be prolonged after each support user request from a subtenant user. Enter a number specifying the number of hours. The default value is 24 hours.

The expiry date-time will be updated based on the duration specified in the Validity limit field, for example, if the current expiry date-time is 01/09/2018 15:00 and duration has been kept at 24 hours, the enabling support user will update the expiry date to 01/10/2018 15:00.

Details on the status of support requests and support user access for a tenant can be found in the Properties tab of the tenant, see Enterprise tenant > Managing tenants.

Configuring a support user

A support user is a user in the Management tenant with specific permissions. This user can log in to the target tenant and impersonate the target user.

To configure a user in the Management tenant as support user, you must assign the relevant roles to the user. This can either be done by using a global role or by inventory roles.

Using a global role

  1. Create a role “Support” with “Support READ” and “Support ADMIN” permission.
  2. Assign the role “Support” to the respective user and remove all other roles for the user.

Using inventory roles

Using inventory roles, you can selectively assign a support user for specific subtenants.

  1. Create an inventory role called “Support” with type = “*” and permission = “All”.
  2. Create a group of all subtenants which you want to be supported by the user.
  3. Assign the “Support” inventory role to above group as described in Administration > Managing permissions > Assigning inventory roles to users.
Info
The support user feature does not work when the support user has two-factor authentication enabled, but no phone number is provided. The phone number must be provided first, in order to login as a support user.