User Management

A user is a known identity with an associated set of data permissions and/or administrative access permissions, which are grouped as roles. The user can be a person or a software/hardware agent.

Users are managed using the web-based interface of Connectware. You can add or delete users, edit their permissions, and change their password. You can also create or modify roles which help you organize and share a set of permissions with multiple users.

For adding user accounts needed for hardware device access, in many cases the client registry is more suitable instead of manually adding users in the Admin-UI web-interface.

Note

Any Admin-UI user who desires to modify roles or users needs the admin role or corresponding permissions.

Users and Roles View

The Users and Roles view allows you to add users and manage their roles and permissions. You can assign roles to users, organize and share permission sets, and change passwords. For each endpoint or topic, you can individually assign permissions. Click a user or role for more information and settings.

Navigating to the Users and Roles View

• On the navigation panel, click User.

  

Users

Overview

This gives a quick overview about users, their roles, and permissions.

Adding a New User

1. To add a user, click + Add User.

   

Simple Mode

2. Enter the username, password and password confirmation in the Create User dialog. If needed, additional select any already existing Role in the Roles field if you want to assign the role to the user. Then click CREATE. The dialog will close and the new user will be visible in the overview table.

   

   (The username and password must fulfill the noted criteria.)

Advanced Mode

To activate advanced mode, toggle the switch in the top right of the dialog.

3. Here you can additionally add individual permissions to the new user. To do so, click the + in the toolbar.

4. In the Add Permissions dialog select the type of permission you want to add.

   

   Enter the resource path (both MQTT and HTTP follow MQTT topic conventions) and select the access type (read, write or both) the permission should be valid for. The specified topic can be either a single topic or a wildcard.

   The resource path on HTTP permissions follow an MQTT topic structure. This means wildcards ( “#” and “+”) can be used for valid expressions and paths should start with a leading “slash”.

   

   The assigned Additional Permissions can be either MQTT (for accessing the MQTT topics on the broker) or HTTP (for accessing the REST API using HTTP clients). Press the ADD button to add a permission.

   However, the suggested way of assigning permissions is not to assign individual permissions in this dialog, but rather using roles, see Add Role to User below. Nevertheless sometimes it is useful to assign individual permissions, so these steps will be explained in the following.

5. When all permissions have been added, create the new user by clicking the CREATE button.

   

Editing Users

1. On the navigation panel, click User.

2. Click on the table row of the user you would like to edit.

Changing Passwords

1. Click on the Change Password button in the user detail view.

2. Type in the new password twice and click the UPDATE button in the dialog.

Adding Roles to Users

1. Click on the roles dropdown to open the options list.

2. Select Roles you want to add to the user by clicking on the options in the dropdown. They will be shown in the text field next to each other.

3. Save the changes by clicking the UPDATE button in the bottom right.

Deleting Roles from Users

1. Click on the x right next to the role name in the roles field to remove this role.

2. Save the changes by clicking the UPDATE button in the bottom right.

Adding Individual Permissions to Users

1. Toggle the Advanced mode switch in the top right of the dialog.

This will extend the dialog with an Additional permissions section.

2. Click the + in the new section to add individual permissions to the user.

3. In the Add Permissions dialog, select the type of permission you want to add.

   

Enter the resource path (both HTTP and MQTT follow MQTT topic structures) and select the access type (read, write or read and write for both) the permission should be valid for. The specified topic can be either a single topic or a wildcard.

The resource path on HTTP permission follow an MQTT topic structure. This means both wildcards ( “#” and “+”) are valid expressions and paths should start with a leading “slash”.

4. When all permissions have been added, update the user by clicking the UPDATE button.

   

Deleting Permissions from User

1. Toggle the Advanced mode switch in the top right of the dialog.

This will extend the dialog with an Additional permissions section.

2. Click the Remove button in the action column for the permission you want to remove.

3. The permission does no longer show in the Additional permissions section. Confirm the changes by clicking the UPDATE button.

Deleting Users

1. Click on the table row of the user you would like to delete.

2. Click the DELETE button in the top right of the user edit dialog.

3. Click the delete button in the dialog.

Roles

Overview

This gives a quick overview about the roles and their permissions.

Creating New Roles

1. Click the + button in the top right toolbar to add a role.

2. Choose a name for the new role and either copy permissions from an already existing role or add specific permissions. Finish the creation by clicking the CREATE button in the bottom right.

Editing Roles

A role can be edited in regards to its name, adding and removing custom permissions as well as copying permissions from other roles.

1. Open the edit dialog by clicking on one of the rows in the overview.

2. Change the name accordingly and confirm the changes by clicking the UPDATE button.

Deleting Roles

1. Open the edit dialog by clicking on one of the rows in the overview.

2. Delete the Role by clicking the DELETE button in the top right of the dialog.

3. Click the delete button in the dialog.

Permissions

Overview

This gives an overview of all Permissions.

Details

Permissions can not be edited by itself, only from roles or users. Clicking on a permission opens a dialog with detailed information.

Password Policy Rules

Connectware allows defining specific password policy rules by setting an environment variable CYBUS_AUTH_PASSWORD_POLICY_RULES before startup (see Environment Variables). This variable must contain string defining a JSON object with the following properties:

• min - The minimum number of characters a password must contain.

• lower - The minimum number of lower-case letters a password must contain. (example: abcö)

• upper - The minimum number of upper-case letters a password must contain. (example: ABCDÜ)

• numeric - The minimum number of digit numbers a password must contain. (example: 123)

• symbol - The minimum number of symbol or punctuation characters a password must contain. (example: $#*?+~.)

Examples: {"min": 5} (default), {"min": 16}, {"min": 8, "upper": 2, "lower": 2, "numeric": 1}

Each of the properties can be set to one integer value. Each property is optional in the JSON object. If any value is zero, the respective rule is disabled and ignored. The character classes are checked using the “Unicode Regular Expression” category properties. For details on the exact definition of the character classes, see https://unicode.org/reports/tr18/#General_Category_Property .

The environment variable will be checked at start-up. If there is a misconfiguration, for example a syntax error in the JSON object, the auth-server container will not start and print a corresponding error message in its logs.

The default password policy rule is {"min": 5}, requiring a minimum length of 5 characters for each password.

Default Admin User

During the installation, Connectware creates a default admin user with user name admin and the connectware-admin role which contains all administrative permissions.

The initial password of a default admin user is defined by using an environment variable CYBUS_INITIAL_ADMIN_USER_PASSWORD which contains the initial password as base-64 encoded string. (In versions earlier than 1.0.80, the initial password was set directly as value of this environment variable, but starting with 1.0.80, it must be given as base-64 encoded string, to avoid any issues with potential variable substitutions.)

The default initial password is admin (see also Environment Variables). If there is a non-default password policy set, this initial password must fulfill this policy, otherwise the initial set-up of Connectware will fail. In any case it is strongly recommended to change the initial password after the first login.

If this default user is not wanted or needed, and there are enough permissions and roles added to other users, this default user can be disabled. To do so, the environment variable CYBUS_ADMIN_USER_ENABLED (default value: true) needs to be set to false before re-starting Connectware. If this environment variable is unset or has any value other than false, the user is enabled and the admin user can log in, given that suitable credentials are provided.

MQTT Users

There are two ways to authenticate MQTT clients depending on the configuration of the Broker’s environment variable CYBUS_BROKER_USE_MUTUAL_TLS. If set to no username and password need to be provided to the MQTT client; if set to yes then mutual TLS is activated in the Broker and MQTT clients need to provide an x.509 certificate that is valid for the CA cert installed for Connectware.

Mutual TLS works only over the MQTT connection scheme and needs a certificate created with a Common Name (CN) that matches a Connectware username with grant type certificate. When using Mutual TLS no username and password are required for authentication as the possession of the certificate implies the right to access the Broker.

The credentials of a User with grant type password can be used with an MQTT client to connect to Connectware and then subscribe topics and/or publish data on topics.

• Subscriptions are permitted on the topics with the read permission.

• Publishing is permitted on topics with the write permission.

• Topics with the readWrite permission are available for both subscribing and publishing.

Adding a MQTT Publish Prefix for Users

In Connectware it is possible to configure specific users so that every MQTT message published by this user gets an additional prefix added to its MQTT topic. That is, if a user UserA has a configured MQTT publish prefix topicA/, and once this user publishes a message to topic some/values, the message will actually be published on the topic topicA/some/values.

This feature simplifies the configuration for use cases where a fixed routing to a downstream application is required. This could be achieved just as well by using Mapping resources, but those would require an additional MQTT message transfer per topic mapping, which can be skipped by the prefix feature. Hence this feature is particularly suited for high-throughput installations with high performance in the MQTT message delivery.

Note: The required MQTT write permissions for this user must be specified including the MQTT prefix, because the permissions should specify the eventual locations on the global MQTT topic tree. In the above example, an UserA with prefix topicA/ would need the MQTT write permission for topicA/some/values in order to be allowed to write to that target topic. If it is needed to omit the prefix in the permission specification, MQTT wildcards might be a useful placeholder instead of the publish prefix, for example by specifying +/some/values.

The configuration of the MQTT prefix can be done either by HTTP requests at the REST endpoint /api/users/<userId>, or in the Admin-UI when editing users in the user management.

Admin-UI Configuration

In the Admin-UI, to add an MQTT prefix to an existing user, edit the MQTT Publish Prefix text field in the Edit User dialog.

1. Toggle the Advanced mode switch in the top right of the dialog.

This will extend the dialog with an Additional permissions section.

2. Edit the MQTT Publish Prefix

Note

The configured MQTT prefix should include the trailing topic level separator / at the end! The topic prefixing feature will not insert any separator automatically, hence the trailing separator must be part of the configuration here.

Example

As an example for setting up and validating a publishing prefix for user newuser:

1. Add the MQTT prefix route-to-downstream/ using the Edit User dialog as explained above.

2. Add an MQTT write permission for the topic ‘route-to-downstream/my-topic’ (i.e. including the prefix) for this user on the user’s management screen.

To validate that this setting works as expected, one can send some MQTT message with some MQTT client, for example the mosquitto_sub and mosquitto_pub command line tools (need to be installed before).

3. Subscribe for a topic route-to-downstream/my-topic with the following command:

mosquitto_sub -h 127.0.0.1 -p 1883 -u admin -P <ADMIN PASSWORD> \
-t 'route-to-downstream/my-topic'

4. Publish a message on the topic my-topic with the following command:

mosquitto_pub -h 127.0.0.1 -p 1883 -u newuser -P <PASSWORD NEW USER> \
-t 'my-topic' -m 'Hello World'

The subscribed client should then receive the published message ‘Hello World’ on the prefixed topic route-to-downstream/my-topic.

Multi-Factor Authentication

Multi-factor authentication (MFA), also known as 2-factor authentication, allows you to add an extra layer of security to your Connectware account. With MFA, you need a one-time code generated by an authentication app in addition to your main Connectware password to sign in.

If you do not have access to your authentication device, you can use backup codes to sign in or ask a Connectware admin to disable your MFA. Connectware admins can disable MFA for each user individually.

Prerequisites for Multi-Factor Authentication

• Your organization has enabled multi-factor authentication for your Connectware account.

Note: Depending on the Connectware settings of your organization, logging in via multi-factor authentication can be optional or required.

• You have an authentication app that supports the time-based one-time password (TOTP) protocol. We recommend the following apps:

  • Google Authenticator

  • Microsoft Authenticator

  • Authy

  • FreeOTP

Note: You do not need an Internet connection to use multi-factor authentication for logging in.

Setting up Multi-Factor Authentication

1. On the navigation panel, click Settings.

2. Click Enable Multi-Factor Authentication.

3. Open your authentication app and do one of the following:

1. Scan the QR code.

2. Enter your secret key.

The authentication app generates a one-time 6-digit code.

4. Enter the one-time 6-digit code in the Register Device fields and click Enable Multi-Factor Authentication. Connectware displays a list of backup codes. If you do not have access to your authentication device, you can use a backup code instead of a one-time 6-digit code. You can use each backup code only once. Alternatively, you can ask a Connectware admin to disable your MFA.

5. Copy and paste the backup codes to a safe location.

Signing in with Multi-Factor Authentication

1. On the Connectware login screen, enter your Username and Password.

2. Click Sign In.

3. Open the authentication app and select your Connectware account.

4. Enter the one-time 6-digit code displayed on the authentication app.

Signing in with Multi-Factor Authentication Backup Codes

If you have no access to your multi-factor authentication app, you can use backup codes instead of a one-time 6-digit code to sign in to Connectware. Backup codes are displayed when you set up multi-factor authentication.

This gives you access to Connectware in case you have misplaced your authentication device, uninstalled your authentication app or removed Connectware from your authentication app.

Note: You can use each backup code only once.

1. On the Connectware login screen, enter your Username and Password.

2. Click Sign In.

3. Click Use backup code.

4. In the Backup Code field, enter your backup code and click Sign In.

Disabling Multi-Factor Authentication (User)

You must have access to your authentication app to disable multi-factor authentication.

Note: If you do not have access to your authentication app, ask a Connectware admin to disable your multi-factor authentication.

1. On the navigation panel, click Settings.

2. In the Multi-Factor Authentication section, click Disable Multi-Factor Authentication.

3. Open the authentication app and select your Connectware account.

4. Enter the one-time 6-digit code displayed on the authentication app.

5. Click Disable Multi-Factor Authentication.

Disabling Multi-Factor Authentication (Admin)

As a Connectware admin, you can disable multi-factor authentication for each user individually.

1. On the navigation panel, select User Management > Users and Roles.

2. Click the user for which you want to disable the multi-factor authentication.

3. In the MFA row, click Disable.

4. Click Update.

Regenerate Backup Codes

You must have access to your authentication app to regenerate multi-factor authentication backup codes.

1. On the navigation panel, click Settings.

2. In the Multi-Factor Authentication section, click Regenerate Backup Codes.

3. Open the authentication app and select your Connectware account.

4. Enter the one-time 6-digit code displayed on the authentication app in the text field.

5. Click Regenerate Backup Codes.

Making Multi-Factor Authentication Mandatory for Individual Users (Admin)

As a Connectware admin, you can set multi-factor authentication to be the mandatory login method for individual users.

Note: For LDAP users, you can set a flag to make multi-factor authentication the mandatory login method for all new LDAP users (see configuration page).

1. On the navigation panel, select User Management > Users and Roles.

2. Click the user for which you want to make multi-factor authentication mandatory.

3. In the MFA (Required) row, click Enable.

4. Click Update.

Long lived JSON Web Tokens

The API allows the creation of long lived JSON Web Tokens (JWTs) which can be used to automate other tasks or for accessing other exposed APIs.

To generate this tokens it is required to:

1. Issue an HTTP request to obtain the token

2. Pass this token on the URL of the other requests through the apiToken query string parameter

Issue an HTTP request to obtain the token.

curl -X 'POST' \
'https://<CONNECTWARE HOST>/api/login' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-k \
-d '{
"username": "<A USERNAME>",
"password": "<A PASSWORD>",
"expireTimeInHours": 99999,
"label": "test-token"
}'

This will return a JSON response with a token property which contains the JWT holding the authentication claims for the user.

Pass this token on the URL of the other requests through the apiToken query string parameter.

curl -k --location --request GET https://<CONNECTWARE HOST>/api/users?apiToken=<TOKEN OBTAINED IN PREVIOUS STEP HERE>

Browser Authentication

In order to authenticate users on the browser using the aforementioned token, simply enter the following address:

https://<CONNECTWARE HOST>/admin?apiToken=<TOKEN>

And if you wish the browser to redirect elsewhere with-in Connectware once authenticated (useful for Cybus::IngressRoute resources) use:

https://<CONNECTWARE HOST>/admin?redirect=<REDIRECTION URL>&apiToken=<TOKEN>

Example:

https://<CONNECTWARE HOST>/admin?redirect=/services/foo/bar&apiToken=barFoo

Note on Security

A JWT provides access to Connectware with the same permissions as the user who generated it so it should be handled following good security practices. Ideally these tokens should be always generated by users with as many permission levels as required and not more.

In future Connectware versions the Admin-UI will add support for creating these tokens too.

Access Permissions for Admin-UI

The permission system of Connectware enables a fine-grained assignment of permissions per roles and users. In particular, if some users should be able to access only a limited set of features on the Admin-UI, it is possible to choose the particular features to see (read access) or to configure (write access).

• Users with the default administrative role connectware-admin have read and write access to any operation within Connectware.

• Users with the default role minimum-access can log into the Admin-UI and have read access for a limited set of features. The features are listed in the following permission sets:

  • Data Explorer

  • Internet Connectivity

  • License

  • Login

  • Server

  • Server

  • Servers

  • Service Details

  • Service Details

  • Service Links

  • Service Overview

  • Service Resources

  • System Information

  • System Status

It is always possible to grant additional read or write permissions to users and roles. To achieve this, the respective HTTP and MQTT paths need to be assigned to some roles, then assigning those roles to the users that should be allowed to access this information. The section below lists the various Admin-UI pages and operations, and shows which HTTP and MQTT permissions must be available so that users will be able to perform the listed operation.

• UI Access
  • Pages
    • Data
      • Data Explorer
    • Services
      • Rule Sandbox
      • Service Catalog
      • Service Logs
      • Service Overview
        • Edit template
        • Service Details
          • Connection
          • Container
          • Endpoint
          • Mapping
          • Server
          • Volume
      • Service Resources
        • Connections
          • Connection
        • Containers
          • Container
        • Endpoints
          • Endpoint
        • Mappings
          • Mapping
        • Servers
          • Server
        • Service Links
          • Service Details
        • Volumes
          • Volume
    • Settings
      • Login
    • System
      • Backup & Restore
      • System Status
        • Agents
        • Internet Connectivity
        • License
        • Metrics
        • System Container
          • Container
        • System Information
    • User
      • Client Registry
      • User Certificates
      • User Management
  • Permissions
    • Creating or updating services
    • Detecting deviations
    • Edit service templates
    • Loading agents
    • Loading connection’s details
    • Loading connections
    • Loading Connectware’s metrics
    • Loading Connectware’s system information
    • Loading Connectware’s topics metadata
    • Loading core container’s details
    • Loading core containers
    • Loading endpoint’s state
    • Loading endpoints
    • Loading endpont’s details
    • Loading logs
    • Loading mapping’s details
    • Loading mapping’s state
    • Loading mappings
    • Loading node’s state
    • Loading nodes
    • Loading server’s details
    • Loading servers
    • Loading service container’s details
    • Loading service containers
    • Loading service’s catalog metadata
    • Loading service’s details
    • Loading services
    • Loading volume’s details
    • Loading volumes
    • Managing agents
    • Managing certificates
    • Managing connections
    • Managing Connectware’s backups
    • Managing Connectware’s license
    • Managing Connectware’s metrics
    • Managing core containers
    • Managing endpoints
    • Managing mappings
    • Managing permissions
    • Managing roles
    • Managing servers
    • Managing service containers
    • Managing services
    • Managing the client registry
    • Managing users
    • Managing volumes
    • Subscribing to MQTT Topics
    • Use Multi-factor authentication
    • Using the Rule Engine
    • Using the workbench

API Definition

Auth Server Swagger