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.
Users¶
Create a new User¶
Press the
+ Add User
button to add a user.
Simple mode¶
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.
Here you can additionally add individual permissions to the new user. To do so, click the + in the toolbar.
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.
When all permissions have been added, create the new user by clicking the
CREATE
button.
Edit User¶
Go to the Users and Roles menu.
Click on the table row of the user you would like to edit.
Change password¶
Click on the
Change Password
button in the user detail view.
Type in the new password twice and click the
UPDATE
button in the dialog.
Add Roles to User¶
Click on the roles dropdown to open the options list.
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.
Save the changes by clicking the
UPDATE
button in the bottom right.
Delete Roles from User¶
Click on the
x
right next to the role name in the roles field to remove this role.
Save the changes by clicking the
UPDATE
button in the bottom right.
Add Individual Permissions to User¶
Toggle the
Advanced mode
switch in the top right of the dialog.
Click the + in the new section to add individual permissions to the user.
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
orread 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”.
When all permissions have been added, update the user by clicking the
UPDATE
button.
Delete Permission from User¶
Toggle the
Advanced mode
switch in the top right of the dialog.
Click the
Remove
button in the action column for the permission you want to remove.
The permission does no longer show in the Additional permissions section. Confirm the changes by clicking the
UPDATE
button.
Delete User¶
Go to the Users and Roles menu.
Click on the table row of the user you would like to delete.
Click the
DELETE
button in the top right of the user edit dialog.
Click the delete button in the dialog.
Roles¶
Create a new Role¶
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.
Open the edit dialog by clicking on one of the rows in the overview.
Change the name accordingly and confirm the changes by clicking the
UPDATE
button.
Delete Role¶
Open the edit dialog by clicking on one of the rows in the overview.
Delete the Role by clicking the
DELETE
button in the top right of the dialog.
Click the delete button in the dialog.
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.
Toggle the
Advanced mode
switch in the top right of the dialog.
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
:
Add the MQTT prefix
route-to-downstream/
using the Edit User dialog as explained above.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).
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'
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:
Issue an HTTP request to obtain the token
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:
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 |
|
|
|
Alternatively: Allows the listing of all service deviations through HTTP
Resource |
Context |
Operation |
|
|
|
Note
For more examples take a look at the noted as “alternative” below.