For the complete documentation index, see llms.txt. This page is also available as Markdown.

Users

Create and manage users, their roles, and permissions.

In Connectware, a user is a known identity — a person, or a software or hardware agent — that authenticates and is granted data permissions, administrative access, or both.

Each permission represents a specific access right to a resource, whether it is an MQTT topic or an HTTP endpoint, with clearly defined read and/or write capabilities.

Before creating individual users, establish a clear role-based access control strategy by defining roles that correspond to job functions within your organization. This approach simplifies user management and ensures consistent application of security policies.

During installation, Connectware creates a default administrator user to ensure immediate system access. This user is named admin and has the connectware-admin role assigned to provide comprehensive permissions. For more information, see Default Admin User.

Users View

The Users View shows all users in Connectware, including their assigned roles and permissions.

  • To open the Users View, click Users in the top bar.

Users and roles view with the Users tab open

Adding New Users

  1. In the Users View, click New user to open the Create user dialog.

Users tab with the New user button highlighted
  1. Do one of the following:

    • To add users with pre-defined roles quickly, use the default mode.

    • To define roles and permissions more granularly, use the advanced mode.

Default Mode

  1. In the Create user dialog, enter the username, password, and password confirmation.

  2. Optional: To assign a set of pre-defined roles to the user, click the Roles field and select a role. You can repeat this step to assign multiple roles.

  3. Click Create. The dialog closes, and the new user appears in the overview table.

Advanced Mode

In the advanced mode, you can assign a set of pre-defined roles to the user and/or individual permissions.

We recommend managing permissions through roles rather than individual user permissions for easier maintenance. For more information, see Roles.

  1. In the Create user dialog, enter the username, password, and password confirmation.

  2. Activate Advanced mode.

Create user dialog with the Advanced mode switch highlighted
Advanced mode in the Create user dialog
  1. Optional: To assign a set of pre-defined roles to the user, click the Roles field and select one or more roles.

  2. Optional: To assign individual permissions, click the + button to open the Add permission dialog.

    • Select the permission type: HTTP for accessing the REST API using HTTP clients or MQTT for accessing MQTT topics on CybusMQ.

    • In the Endpoint field, enter the resource path. Wildcards (+ and #) are supported. For syntax details, see Permissions.

    • Select Read, Write, or both.

    • Click Add to add the permission.

Create user dialog with the add permission button highlighted
Add permission button
Create user dialog with the Add permission form highlighted
Add permission form
  1. Optional: Under Authentication methods, select how the user can authenticate. Password and Token are selected by default. For more information, see Authentication Methods.

  2. Click Create. The dialog closes, and the new user appears in the overview table.

Authentication Methods

Authentication methods control how a user proves their identity to Connectware. A user can have more than one. The following methods are available:

  • Password: The user authenticates with their username and password, for example when calling POST /api/login or connecting an MQTT client.

  • Token: The user authenticates with a JSON Web Token (JWT), for example a script that calls the API. For more information, see JSON Web Tokens.

  • Certificate: The user authenticates with a client certificate whose Common Name (CN) matches the username. For more information, see Client Certificates.

Users that you create in the Admin UI have Password and Token by default. The Authentication methods column in the Users View shows the methods of each user. A user without any method shows Cannot authenticate and cannot access Connectware.

Without Token, a user still receives a token from POST /api/login, but every request that uses the token fails with 401 Unauthorized.

In the API, authentication methods are called grant types. You set them in the grantTypes property of a user, with the values password, token, and certificate.

Changing Authentication Methods

  1. In the top bar, click Users.

  2. In the Users View, click the user whose authentication methods you want to change. This opens the Edit user dialog.

  3. In the Edit user dialog, activate Advanced mode.

  4. Under Authentication methods, select or clear the methods.

  5. Click Update. The dialog closes, and the user is updated.

You cannot clear Token for the admin user.

Deleting Users

You can delete users that are no longer needed.

  1. In the top bar, click Users.

  2. In the Users View, click the user that you want to delete. This opens the Edit user dialog.

Users tab with a user row highlighted
  1. Click the Delete button in the top right of the Edit user dialog.

Edit user dialog with the Delete button highlighted
Delete button
  1. Click Delete again to confirm. The user is deleted.

Changing Usernames

  1. In the Users View, click the user that you want to edit. This opens the Edit user dialog.

  2. In the Edit user dialog, enter a new username in the Username field.

  3. Click Update to apply the changes. The dialog closes, and the username is updated.

Adding Roles to Users

Roles provide a convenient way to assign multiple permissions at once. By adding roles to users, you can quickly grant them access to specific system functions without configuring individual permissions.

Assign roles based on job functions or responsibilities rather than individual users to maintain consistent access control across your organization.

  1. In the top bar, click Users.

  2. In the Users View, click the user to whom you want to add roles. This opens the Edit user dialog.

  3. In the Edit user dialog, click the Roles field to open the list of available roles.

Edit user dialog with the Roles list open
Options of the Roles field
  1. Click the Roles field and select a role. You can repeat this step to assign multiple roles.

  2. Click Update. The dialog closes, and the user is updated with the selected roles.

Removing Roles from Users

When a user's responsibilities change, you may need to remove roles from them to adjust their access permissions.

  1. In the top bar, click Users.

  2. In the Users View, click the user from whom you want to remove roles. This opens the Edit user dialog.

  3. In the Edit user dialog, click the x next to the role name in the Roles field to remove the role.

Edit user dialog with the remove icon of a role highlighted
Remove role from user
  1. Click Update. The dialog closes, and the user is updated.

Assigning Permissions to Users

While roles are the recommended way to manage permissions, there may be cases where you need to grant specific permissions to individual users without creating a new role.

  1. In the top bar, click Users.

  2. In the Users View, click the user to whom you want to assign individual permissions. This opens the Edit user dialog.

  3. In the Edit user dialog, activate Advanced mode.

Edit user dialog with the Advanced mode switch highlighted
Turning on Advanced mode in the Edit user dialog
  1. To assign individual permissions, click the + button to open the Add permission dialog.

    • Select the permission type: HTTP for accessing the REST API using HTTP clients or MQTT for accessing MQTT topics on CybusMQ.

    • In the Endpoint field, enter the resource path. Wildcards (+ and #) are supported. For syntax details, see Permissions.

    • Select Read, Write, or both.

    • Click Add to add the permission.

Edit user dialog with the add permission button highlighted
Add permission button
Edit user dialog with the Add permission form highlighted
Add permission form
  1. Click Update. The dialog closes, and the user is updated with the new permissions.

Removing Permissions from Users

When specific permissions are no longer needed, you can remove them while keeping other permissions intact.

  1. In the top bar, click Users.

  2. In the Users View, click the user from whom you want to remove individual permissions. This opens the Edit user dialog.

  3. In the Edit user dialog, activate Advanced mode.

Edit user dialog with the Advanced mode switch highlighted
Turning on Advanced mode in the Edit user dialog
  1. To remove a permission, click its Remove button in the Actions column of the permissions list.

Edit user dialog with the Remove button of a permission highlighted
Remove permission from user
  1. Click Update. The dialog closes, and the user is updated.

Changing User Passwords

Regularly updating passwords is an important security practice.

  1. In the top bar, click Users.

  2. In the Users View, click the user for whom you want to change the password. This opens the Edit user dialog.

  3. In the Edit user dialog, click Change password.

Edit user dialog with the Change password button highlighted
Change password button
  1. In the Password field, enter the new password and confirm it in the Confirm password field.

  2. To apply the changes, click Update. The dialog closes, and the password is updated.

Edit user dialog with the Password field highlighted
Password field in the Edit user dialog

Last updated

Was this helpful?