User Management

A user is a known identity with a 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 the 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.

Navigate to Users and Roles section

Once you have opened the entry screen of the Connectware Admin-UI web interface:

1. On the navigation panel click on User Management to expand the menu.

2. Click on Users and Roles.

Users

Overview

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

Create a new User

1. Press the + Add User button to add a 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 fulfil 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 permission 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.

   

Edit User

1. Go to the Users and Roles menu.

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

Change password

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.

Add Roles to User

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.

Delete Roles from User

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.

Add Individual Permissions to 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 + 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.

   

Delete Permission 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.

Delete User

1. Go to the Users and Roles menu.

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

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

4. Click the delete button in the dialog.

Roles

Overview

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

Create a new Role

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

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

Edit Role

A role can be edited in regards on 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.

Delete Role

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

The 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 fulfil this policy, otherwise the initial set-up of the 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 the 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 mqtts 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 posession of the certificate implies right to access the Broker.

The credentials of a User with grant type password can be used with an MQTT client to connect to the 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 a user

In the 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.

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 the 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 much permissions levels as required and not more.

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

Access Permissions for Admin-UI

The permission system of the 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 the 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

  • Info

  • Resources

  • Server

  • Servers

  • Service

  • Service Links

  • Services

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.

Note

Some of the operations can be performed by several different combinations of permissions like shown in the example here.

Service Deviations

Allows the listing of all service deviations through MQTT

Resource	Context	Operation
#	mqtt	readWrite

Alternatively: Allows the listing of all service deviations through HTTP

Resource	Context	Operation
/api/services/info	http	read

Note

For more examples take a look at the noted as “alternative” below.

• UI Access
• Backup and Restore
• Resources
  • Connections
    • Connection
  • Containers
    • Container
  • Endpoints
    • Endpoint
  • Mappings
    • Mapping
  • Servers
    • Server
  • Service Links
  • Volumes
    • Volume
• Service Catalog
• Services
  • Service
• System
  • Agents
  • Info
  • Metrics
  • Status
    • Status
• Tools
  • Data Explorer
  • Rule Sandbox
• User Management
  • Certificates
  • Client Registry
  • Users and Roles
• Workbench

API Definition

Auth Server Swagger