.. _user/users: ############### 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 :ref:`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. .. figure:: ../resources/home/1_home_menubutton.png :width: 400px 2. On the navigation panel click on ``User Management`` to expand the menu. .. figure:: ../resources/user_mgmt/sidebar_1.png :width: 150px 3. Click on ``Users``. .. figure:: ../resources/user_mgmt/sidebar_2.png :width: 150px Create a user with permissions ============================== 1. Press the + button in the toolbar to add a user. .. figure:: ../resources/user_mgmt/users_add.png :width: 400px 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. .. figure:: ../resources/user_mgmt/users_create.png :width: 150px (The username must be at least 3 characters long, and the password at least 5 characters long.) .. note: the definition of the minimum length can be found in .. auth-server/src/models/user/index.js and auth-server/src/swagger/swagger.yaml 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. .. figure:: ../resources/user_mgmt/users_select.png :width: 400px 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 :ref:`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. .. figure:: ../resources/user_mgmt/users_select_type.png :width: 400px 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". .. figure:: ../resources/user_mgmt/users_add_permission.png :width: 200px 6. **Important:** Press the ``SAVE`` button to persist the changes to the user. .. figure:: ../resources/user_mgmt/users_save.png :width: 400px Delete a user ============= 1. Go to the `Users` menu. .. figure:: ../resources/user_mgmt/sidebar_2.png :width: 150px 2. Click on the table row of the user you would like to delete. .. figure:: ../resources/user_mgmt/users_select.png :width: 400px 3. Click the delete action in the user detail view. .. figure:: ../resources/user_mgmt/users_delete_button.png :width: 400px 4. Click the confirm button in the dialog. .. figure:: ../resources/user_mgmt/users_delete_dialog.png :width: 200px Change user password ==================== 1. Go to the `Users` menu. .. figure:: ../resources/user_mgmt/sidebar_2.png :width: 150px 2. Click on the table row of the user you would like to change password for. .. figure:: ../resources/user_mgmt/users_select.png :width: 400px 3. Click on the ``Change Password`` button in the user detail view. .. figure:: ../resources/user_mgmt/users_update_password_button.png :width: 400px 4. Type in the new password twice and click the ``CONFIRM`` button in the dialog. .. figure:: ../resources/user_mgmt/users_update_password_dialog.png :width: 150px 5. **Important:** Press the ``SAVE`` button to persist the changes to the user. .. figure:: ../resources/user_mgmt/users_save.png :width: 400px .. _user/users/roles: Add role to user ================ 1. Go to the `Users` menu. .. figure:: ../resources/user_mgmt/sidebar_2.png :width: 150px 2. Click on the table row of the user you would like update. .. figure:: ../resources/user_mgmt/users_select.png :width: 400px 3. Click on the `Roles` field. A list of available Roles should be displayed. .. figure:: ../resources/user_mgmt/user_roles.png :width: 400px 4. Click on the desired role name. .. figure:: ../resources/user_mgmt/users_roles_add.png :width: 400px 5. **Important:** Press the ``SAVE`` button to persist the changes to the user (as indicated by the remark *Unsaved changes, please save*). .. figure:: ../resources/user_mgmt/users_roles_save.png :width: 400px Remove role from user ===================== 1. Go to the `Users` menu. .. figure:: ../resources/user_mgmt/sidebar_2.png :width: 150px 2. Click on the table row of the user you would like update. .. figure:: ../resources/user_mgmt/users_select.png :width: 400px 3. Click on the `X` on the role you would like to remove. .. figure:: ../resources/user_mgmt/users_roles_remove.png :width: 400px 4. **Important:** Press the ``SAVE`` button to persist the changes to the user (as indicated by the remark *Unsaved changes, please save*). .. figure:: ../resources/user_mgmt/users_roles_save.png :width: 400px .. _user/users/permissions: Create a role with permissions ============================== 1. On the navigation panel click on ``User Management`` to expand the menu. .. figure:: ../resources/user_mgmt/sidebar_1.png :width: 150px 2. Go to the `Roles` menu. .. figure:: ../resources/user_mgmt/roles_menu.png :width: 150px 3. Press the + button in the toolbar to add a role. .. figure:: ../resources/user_mgmt/roles_add.png :width: 400px 4. Enter the role name in the `Create Role` dialog and click ``CREATE``. .. figure:: ../resources/user_mgmt/roles_add_dialog.png :width: 150px 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. .. figure:: ../resources/user_mgmt/roles_select.png :width: 400px 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. .. figure:: ../resources/user_mgmt/roles_add_permission.png :width: 400px 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. .. list-table:: * - .. figure:: ../resources/user_mgmt/roles_add_permission_dialog.png :width: 220px Example for a MQTT Topic - .. figure:: ../resources/user_mgmt/roles_add_permission_dialog_http.png :width: 270px 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*). .. figure:: ../resources/user_mgmt/roles_save.png :width: 400px Delete role =========== 1. Go to the `Roles` menu. .. figure:: ../resources/user_mgmt/roles_menu.png :width: 150px 2. Click on the table row of the role you would like to delete. .. figure:: ../resources/user_mgmt/roles_select.png :width: 400px 3. Click the delete action in the role detail view. .. figure:: ../resources/user_mgmt/roles_delete_button.png :width: 400px 4. Click the confirm button in the dialog. .. figure:: ../resources/user_mgmt/roles_delete_dialog.png :width: 150px .. _user/users/policy: 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. .. _user/users/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`` (default value: `admin`). If there is a non-default :ref:`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*. .. _user/users/mqtt_prefix: 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: .. code:: bash curl -X 'PUT' \ 'https:///api/users/' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -u admin -k \ -d '{ "mqttPublishPrefix": "", }' The user id can be found in the user management URL path as shown below: .. figure:: ../resources/user_mgmt/users_get_id.png :width: 400px .. 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: .. code:: bash curl -X 'PUT' \ 'https:///api/users/' \ -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: .. 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' 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. .. _user/users/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/users/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 the 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 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 ============== :download:`Auth Server Swagger <../swagger/auth.yaml>`