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. For adding users for hardware devices, in many cases the client registry is more suitable than manually adding users in the web-interface.

You can also create or modify roles which help you organize and share a set of permissions with multiple users.

Note

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

Navigate to user section

Once you have opened the entry screen of the Connectware interface:

1. If the navigation panel is not displayed on the left side click the menu icon in the upper left corner.

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

3. Click on Users.

Create a user with permissions

1. Press the + button in the toolbar to add a user.

   

2. Enter the username and password in the Create User dialog and click CREATE. A message confirming that the user was successfully created will be shown.

   

   (The username must be at least 3 characters long, and the password at least 5 characters long.)

3. Important: Continue the setup of the new user by adding permissions in the user detail view: Click on the table row for the newly created user.

4. In the Additional Permissions section select the type of permission you want to add.

   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.

   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 + button to add a permission.

5. In the Add Permission dialog enter the resource path (both data and api follow MQTT topic structures) and select the access type (read, write or readWrite for both) the permission should be valid for. The specified topic can be either a single topic or a wildcard.

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

6. Important: Press the SAVE button to persist the changes to the user.

Delete a user

1. Go to the Users menu.

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

3. Click the delete action in the user detail view.

4. Click the confirm button in the dialog.

Change user password

1. Go to the Users menu.

2. Click on the table row of the user you would like to change password for.

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

4. Type in the new password twice and click the CONFIRM button in the dialog.

5. Important: Press the SAVE button to persist the changes to the user.

Add role to user

1. Go to the Users menu.

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

3. Click on the Roles field. A list of available Roles should be displayed.

4. Click on the desired role name.

5. Important: Press the SAVE button to persist the changes to the user (as indicated by the remark Unsaved changes, please save).

Remove role from user

1. Go to the Users menu.

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

3. Click on the X on the role you would like to remove.

4. Important: Press the SAVE button to persist the changes to the user (as indicated by the remark Unsaved changes, please save).

Create a role with permissions

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

2. Go to the Roles menu.

3. Press the + button in the toolbar to add a role.

   

4. Enter the role name in the Create Role dialog and click CREATE.

   

5. Continue the setup of the new role by adding permissions in the role detail view: Click on the table row for the newly created role.

6. In the Permissions section select the type of permission you want to add. The assigned 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 + button to add a permission.

7. In the Add Permission dialog enter the resource path (both data and api follow MQTT topic structures) and select the access type (read, write or readWrite for both) the permission should be valid for. The specified topic can be either a single topic or a wildcard.

   Example for a MQTT Topic

   Example for a URL Path

8. Important: Press the SAVE button to persist the changes to the user (as indicated by the remark Unsaved changes, please save).

Delete role

1. Go to the Roles menu.

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

3. Click the delete action in the role detail view.

4. Click the confirm button in the dialog.

Password policy rules

The Connectware allows defining specific password policy rules by setting an environment variable CYBUS_AUTH_PASSWORD_POLICY_RULES before startup. 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 (default value: admin). 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 prefix for MQTT publishing user

In Connectware it is possible to modify a topic by adding a prefix during the authorization of a publishing user.

This feature simplifies the configuration for use cases where a fixed routing to a downstream application is required. This could just as well be achieved 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 performancein the MQTT message delivery.

The configuration has to be done using HTTP requests at the user management REST endpoints (currently). To add an MQTT prefix to an existing user, issue following HTTP request as an admin user:

curl -X 'PUT' \
'https://<CONNECTWARE HOST>/api/users/<A USER ID>' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-u admin
-k \
-d '{
"mqttPublishPrefix": "<A PREFIX>",
}'

The user id can be found in the user management URL path as shown below:

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 it must be part of the configuration here.

Example for the setting and the validation of a prefix for MQTT publishing user newuser:

1. Add an MQTT write permission for the topic ‘my-topic’ for this user on the user’s management screen.

2. Add an MQTT prefix route-to-downstream/ to this user with the following HTTP request:

curl -X 'PUT' \
'https://<CONNECTWARE HOST>/api/users/<A USER ID>' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-u admin
-k \
-d '{
"mqttPublishPrefix": "route-to-downstream/",
}'

A validation if the setting works as expected can be done by using any mqtt clients, for example mosquitto_sub and mosquitto_pub (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'

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

The configuration of these prefixes in the Admin-UI is scheduled for some future Connectware releases.

The setting of the environment

For a docker-compose installation, we recommend defining the values of all environment variables in the file .env file in the same directory as the docker-compose.yml file.

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.

API Definition

Auth Server Swagger