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.

Create a user with permissions

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

    ../_images/users_add.png
  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.

    ../_images/users_create.png

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

  1. 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.

../_images/users_select.png
  1. 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.

../_images/users_select_type.png
  1. 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”.

../_images/users_add_permission.png
  1. Important: Press the SAVE button to persist the changes to the user.

../_images/users_save.png

Delete a user

  1. Go to the Users menu.

../_images/sidebar_2.png
  1. Click on the table row of the user you would like to delete.

../_images/users_select.png
  1. Click the delete action in the user detail view.

../_images/users_delete_button.png
  1. Click the confirm button in the dialog.

../_images/users_delete_dialog.png

Change user password

  1. Go to the Users menu.

../_images/sidebar_2.png
  1. Click on the table row of the user you would like to change password for.

../_images/users_select.png
  1. Click on the Change Password button in the user detail view.

../_images/users_update_password_button.png
  1. Type in the new password twice and click the CONFIRM button in the dialog.

../_images/users_update_password_dialog.png
  1. Important: Press the SAVE button to persist the changes to the user.

../_images/users_save.png

Add role to user

  1. Go to the Users menu.

../_images/sidebar_2.png
  1. Click on the table row of the user you would like update.

../_images/users_select.png
  1. Click on the Roles field. A list of available Roles should be displayed.

../_images/user_roles.png
  1. Click on the desired role name.

../_images/users_roles_add.png
  1. Important: Press the SAVE button to persist the changes to the user (as indicated by the remark Unsaved changes, please save).

../_images/users_roles_save.png

Remove role from user

  1. Go to the Users menu.

../_images/sidebar_2.png
  1. Click on the table row of the user you would like update.

../_images/users_select.png
  1. Click on the X on the role you would like to remove.

../_images/users_roles_remove.png
  1. Important: Press the SAVE button to persist the changes to the user (as indicated by the remark Unsaved changes, please save).

../_images/users_roles_save.png

Create a role with permissions

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

../_images/sidebar_1.png
  1. Go to the Roles menu.

../_images/roles_menu.png
  1. Press the + button in the toolbar to add a role.

    ../_images/roles_add.png
  2. Enter the role name in the Create Role dialog and click CREATE.

    ../_images/roles_add_dialog.png
  3. 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.

../_images/roles_select.png
  1. 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.

../_images/roles_add_permission.png
  1. 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.

    ../_images/roles_add_permission_dialog.png

    Example for a MQTT Topic

    ../_images/roles_add_permission_dialog_http.png

    Example for a URL Path

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

../_images/roles_save.png

Delete role

  1. Go to the Roles menu.

../_images/roles_menu.png
  1. Click on the table row of the role you would like to delete.

../_images/roles_select.png
  1. Click the delete action in the role detail view.

../_images/roles_delete_button.png
  1. Click the confirm button in the dialog.

../_images/roles_delete_dialog.png

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.

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. In a docker-compose installation, this environment variable is recommended to be set in the .env file in the same directory as the docker-compose.yml file. 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.

API Definition

Auth Server Swagger