.. _user/user_management: ############### 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 :ref:`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``. .. figure:: ../resources/user_mgmt/navigation_panel_user.png :width: 600px .. _user/user_management/users: Users ===== Overview -------- This gives a quick overview about users, their roles, and permissions. .. figure:: ../resources/user_mgmt/users_and_roles_view.png :width: 750px Adding a New User ----------------- 1. To add a user, click ``+ Add User``. .. figure:: ../resources/user_mgmt/users_add.png :width: 750px 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. .. figure:: ../resources/user_mgmt/users_create.png :width: 600px (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. .. figure:: ../resources/user_mgmt/users_create_advanced_mode.png :width: 600px 3. Here you can additionally add individual permissions to the new user. To do so, click the + in the toolbar. .. figure:: ../resources/user_mgmt/users_create_advanced_add_permission.png :width: 600px 4. In the `Add Permissions` dialog select the type of permission you want to add. .. figure:: ../resources/user_mgmt/users_create_advanced_add_permission_modal.png :width: 600px 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". .. figure:: ../resources/user_mgmt/users_add_permission.png :width: 260px 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 :ref:`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. .. figure:: ../resources/user_mgmt/users_create_advanced_create.png :width: 600px Editing Users ------------- 1. On the navigation panel, click ``User``. .. figure:: ../resources/user_mgmt/navigation_panel_user.png :width: 600px 2. Click on the table row of the user you would like to edit. .. figure:: ../resources/user_mgmt/users_select.png :width: 750px Changing Passwords ~~~~~~~~~~~~~~~~~~ 1. Click on the ``Change Password`` button in the user detail view. .. figure:: ../resources/user_mgmt/users_update_password_button.png :width: 600px 2. Type in the new password twice and click the ``UPDATE`` button in the dialog. .. figure:: ../resources/user_mgmt/users_update_password_dialog.png :width: 600px Adding Roles to Users ~~~~~~~~~~~~~~~~~~~~~ 1. Click on the roles dropdown to open the options list. .. figure:: ../resources/user_mgmt/users_update_add_role.png :width: 600px 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. .. figure:: ../resources/user_mgmt/users_update_add_role_dropdown_options.png :width: 600px 3. Save the changes by clicking the ``UPDATE`` button in the bottom right. .. figure:: ../resources/user_mgmt/users_update_add_role_confirm.png :width: 600px Deleting Roles from Users ~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Click on the ``x`` right next to the role name in the roles field to remove this role. .. figure:: ../resources/user_mgmt/users_update_remove_role.png :width: 600px 2. Save the changes by clicking the ``UPDATE`` button in the bottom right. .. figure:: ../resources/user_mgmt/users_update_remove_role_confirm.png :width: 600px Adding Individual Permissions to Users ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Toggle the ``Advanced mode`` switch in the top right of the dialog. .. figure:: ../resources/user_mgmt/users_update_advanced_mode.png :width: 600px This will extend the dialog with an ``Additional permissions`` section. .. figure:: ../resources/user_mgmt/users_update_advanced_view.png :width: 600px 2. Click the + in the new section to add individual permissions to the user. .. figure:: ../resources/user_mgmt/users_update_advanced_add_permission.png :width: 600px 3. In the `Add Permissions` dialog, select the type of permission you want to add. .. figure:: ../resources/user_mgmt/users_update_advanced_add_permission_modal.png :width: 600px 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. .. figure:: ../resources/user_mgmt/users_update_advanced_create.png :width: 600px Deleting Permissions from User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Toggle the ``Advanced mode`` switch in the top right of the dialog. .. figure:: ../resources/user_mgmt/users_update_advanced_mode.png :width: 600px This will extend the dialog with an ``Additional permissions`` section. .. figure:: ../resources/user_mgmt/users_update_advanced_view_2.png :width: 600px 2. Click the ``Remove`` button in the action column for the permission you want to remove. .. figure:: ../resources/user_mgmt/users_update_advanced_remove_permission.png :width: 600px 3. The permission does no longer show in the Additional permissions section. Confirm the changes by clicking the ``UPDATE`` button. .. figure:: ../resources/user_mgmt/users_update_advanced_remove_permission_confirm.png :width: 600px .. _user/user_management/users/delete: Deleting Users -------------- 1. Click on the table row of the user you would like to delete. .. figure:: ../resources/user_mgmt/users_select.png :width: 750px 2. Click the ``DELETE`` button in the top right of the user edit dialog. .. figure:: ../resources/user_mgmt/users_update_delete.png :width: 600px 3. Click the delete button in the dialog. .. figure:: ../resources/user_mgmt/users_delete_dialog.png :width: 750px .. _user/user_management/roles: Roles ===== Overview -------- This gives a quick overview about the roles and their permissions. .. figure:: ../resources/user_mgmt/roles_overview.png :width: 750px Creating New Roles ------------------ 1. Click the + button in the top right toolbar to add a role. .. figure:: ../resources/user_mgmt/roles_add.png :width: 750px 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. .. figure:: ../resources/user_mgmt/roles_add_dialog.png :width: 600px 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. .. figure:: ../resources/user_mgmt/roles_edit.png :width: 600px 2. Change the name accordingly and confirm the changes by clicking the ``UPDATE`` button. .. figure:: ../resources/user_mgmt/roles_edit_change_name.png :width: 600px Deleting Roles -------------- 1. Open the edit dialog by clicking on one of the rows in the overview. .. figure:: ../resources/user_mgmt/roles_edit.png :width: 750px 2. Delete the Role by clicking the ``DELETE`` button in the top right of the dialog. .. figure:: ../resources/user_mgmt/roles_edit_delete.png :width: 600px 3. Click the delete button in the dialog. .. figure:: ../resources/user_mgmt/roles_edit_delete_confirm.png :width: 750px .. _user/user_management/permissions: Permissions =========== Overview -------- This gives an overview of all Permissions. .. figure:: ../resources/user_mgmt/permissions_overview.png :width: 750px Details ------- Permissions can not be edited by itself, only from roles or users. Clicking on a permission opens a dialog with detailed information. .. figure:: ../resources/user_mgmt/permissions_details.png :width: 750px .. figure:: ../resources/user_mgmt/permissions_details_dialog.png :width: 320px .. _user/user_management/password_policy: Password Policy Rules ===================== Connectware allows defining specific password policy rules by setting an environment variable ``CYBUS_AUTH_PASSWORD_POLICY_RULES`` before startup (see :ref:`user/configuration/env`). 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. .. _user/user_management/initial: 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 :ref:`user/configuration/env`). If there is a non-default :ref:`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 :ref:`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*. .. _user/user_management/mqtt_prefix: 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/``, 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. .. figure:: ../resources/user_mgmt/users_update_advanced_mode.png :width: 600px This will extend the dialog with an ``Additional permissions`` section. .. figure:: ../resources/user_mgmt/users_update_advanced_view.png :width: 600px 2. Edit the MQTT Publish Prefix .. figure:: ../resources/user_mgmt/users_update_mqtt_prefix.png :width: 600px .. 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: .. code:: bash mosquitto_sub -h 127.0.0.1 -p 1883 -u admin -P \ -t 'route-to-downstream/my-topic' 4. Publish a message on the topic ``my-topic`` with the following command: .. code:: bash mosquitto_pub -h 127.0.0.1 -p 1883 -u newuser -P \ -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: a. Scan the QR code. b. 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**. .. _user/user_management/web_tokens: 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. .. code:: bash curl -X 'POST' \ 'https:///api/login' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -k \ -d '{ "username": "", "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. .. code:: bash curl -k --location --request GET https:///api/users?apiToken= .. _user/user_management/web_tokens/browser: Browser Authentication ---------------------- In order to authenticate users on the browser using the aforementioned token, simply enter the following address: .. code:: text https:///admin?apiToken= And if you wish the browser to redirect elsewhere with-in Connectware once authenticated (useful for :ref:`Cybus::IngressRoute ` resources) use: .. code:: text https:///admin?redirect=&apiToken= Example: .. code:: text https:///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. .. _user/user_management/access: 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: .. include:: ./minimum-access-role.rst 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. .. toctree:: :maxdepth: 10 ui-access.rst API Definition ============== :download:`Auth Server Swagger <../swagger/auth.yaml>`