In this lesson you will learn the basics about creating and managing users and their permissions. To understand the basic concepts of the Connectware, please check out the Technical Overview lesson. To follow along with the example, you will also need a running instance of the Connectware. If you don't have that, learn How to install the Connectware. You should also be familiar with MQTT. If in doubt, head over to our MQTT Basics lesson.
This article will enable you to
In the following we will take a look at the first steps of user management: How to define a set of permissions, create a user and make him/her a useful member of the team. We will do this two times, first manually and then with a Commissioning File.
This lesson will guide you through the very basics of user management in a casual way. If you need any detailed instruction take a look at the User Management section in the Reference docs.
The Commissioning Files used in this lesson are made available in the Example Files Repository on GitHub.
First go ahead and log in to the Connectware using your admin account. Once you are successfully logged in you have all the tools available you need to manage users and permissions directly from the Connectware Admin User Interface (Admin UI).
Expand the section User Management on the menu bar by clicking on it. It will present three options to you:
If you want to learn more about Client Registry check out the How to MQTT lesson, which includes a hands-on example of self registration.
Now we will start right away with the definition of a Role.
To create a set of permissions switch to the section Roles. Here you can see all the roles that are available on your Connectware. To create a new role click the plus-button in the upper right corner of the UI. A dialog opens which demands you to define a name. We choose the name "UserManagement" and click Create. The newly created role does now appear in the list. Clicking on this entry will open the permissions view. Here you can switch between MQTT, the data interface, and HTTP, the application programming interface.
We start with an MQTT permission by selecting the MQTT tab and clicking the plus-button in the upper right corner of the permissions list. An MQTT permission is easily to define and requires just two parts of information:
For the resource we define the MQTT topic located under
users/# (with the
# indicating that this is valid for the topic
users as well as
every topic under it) with
readWrite access and confirm by clicking Add.
Now we switch to the HTTP tab and again click the plus-button in the upper right
corner. The second permission shall grant access to the HTTP API on path
/api/users/# (again utilizing the wildcard
#) which includes the interface
for user management. In result assigning a user the role UserManagement will
grant him rights to manage users via the HTTP API. Please note, that this does
not grant access to the Admin UI nor its User Management section!
After creating both permissions click Save and Back. This role is now ready to use.
Go ahead and open the Users view. Unless you have not already configured any users yourself or installed any services, there is only a single user in the list: the admin. We will start off by creating a new user. To do so you only need to press the plus-button located in the upper right corner of the UI. Once you pressed the button a small dialog appears in which you can set the username and the initial password.
For this lesson we will create a simple user called
user. Enter the username
and a password. We will delete the user in the end of the lesson so the password
doesn't have to be particularly complex. Accept the new user by clicking
Create. The menu will close and you will see that your new user appears in
Right now our new user has no permissions to access the API or read data. To make the user a bit more useful we will go ahead and add a few permissions by assigning a role. Open the user configuration by clicking the entry of our user in the list. This view provides the following options:
We want to assign the earlier created role to this user, so we type "UserManagement" to the input line Roles and select it from the list. Since we created the set of permissions for this user as a role, which by the way is considered good practice, we don't need to grant additional permissions. But if we wanted to, it would work just like assigning permissions to a role, by clicking the plus-button.
Great! Our newly created user is now able to read and write data on the
topic and access the user management API.
Sometimes a good member of the team has to leave and you might be in charge of
delivering the bad news. Luckily the Connectware makes this task a piece of
cake! Just go to the Users view, choose the poor candidate's entry in the list
and click it. In the user configuration click Delete in the upper right corner
and confirm if you are certain about it. Proceed like this for our
continue with the lesson.
Instead of adding users utilizing the User Management section of the Admin UI, you can also define users in a Commissioning File and create them as part of a service installation. You would probably do that in the process of integrating a device that connects to the Connectware API, to have a user directly associated with the service which would reduce the required user management effort because you do not have to create, manage and remove users manually when installing or deleting services.
The Commissioning File contains all information which is required for a
Service installation. It
defines all kinds of resources needed, like connections, mappings or also users.
To understand the file's anatomy in detail, please consult to the
To get started, open a text editor and create a new file, e.g.
users-example-commissioning-file.yml. The Commissioning File is in the YAML
format, perfectly readable for human and machine! We will now go through the
process of defining the required sections for this example:
These sections contain more general information about the commissioning file. You can give a short description and add a stack of metadata. Regarding the metadata, only the name is required while the rest is optional. We will just use the following set of information for this lesson:
description: > User Management Example Commissioning File Cybus Learn - User Management Basics https://learn.cybus.io/lessons/user-management-basics/ metadata: name: User Management Example version: 0.0.1 icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg provider: cybus homepage: https://www.cybus.io
Parameters allow the user to customize Commissioning Files for multiple use cases by referring to them from within the Commissioning File. Each time a Commissioning File is applied or reconfigured in the Connectware, the user is asked to enter custom values for the parameters or to confirm the default values.
parameters: userPassword: type: string description: Password for user
We are defining the user's password as a parameter without any default, so it has to be set during the installation of the service.
In the resources section we declare every resource that is needed for our service. Besides resources like connections, endpoints or volumes, the user we want to create is also a resource which has to be defined in this section. And even the role we want to assign to our new user is a resource and that is what we start with.
The name of the role that will be created, will match the name of the resource
we define, so we just name the resource
resources: UserManagement: type: Cybus::Role properties: permissions: - resource: users/# operation: readWrite context: mqtt - resource: /api/users/# operation: readWrite context: http
This resource is of the type
Cybus::Role which provides the single property
permissions. Permissions are defined by the resource, which in this case is
not a resource of those defined in the Commissioning File, but a resource path
in the context of data interface (
mqtt) or application programming interface
We define two permissions here. The first is the permission to access data on
MQTT topics located under
users/# (with the wildcard
# indicating that this
is valid for the topic
users as well as every topic under it). The second
permission grants access to the API on path
/api/users/# (also utilizing the
#) which includes the interface for user management. In result
assigning a user the role UserManagement will grant him rights to manage users
via the HTTP API. Please note, that this does not grant access to the Admin UI
nor its User Management section!
Again the name of the user that will be created, will be equal to the name of
the resource we define, so we just name the resource
user, like we did before.
user: type: Cybus::User properties: password: !ref userPassword roles: ['UserManagement']
Although the name of our resource already implies that it should be a user, we
still have to define it explicitly by setting the property type to
Cybus:User. This brings us to the next, type-specific properties: For the
definition of the password we reference the parameter
userPassword we declared
earlier by using
!ref and for the roles we assign the previously created role
We could also define additional permissions in the same way we did for the role but it is considered advisable to organize sets of permissions as roles and just assign those to users.
You now have the Commissioning File ready for installation. Head over to the
Services tab in the Connectware Admin UI and hit the plus-button to select and
upload the Commissioning File. You will be asked to specify values for the
service ID and each member of the section
parameters, in our case the password
for the user. Once the service was installed successfully click its entry in the
list and enable it from the service details view. You can now head back to the
User Management and find the freshly created user and role. But they look a bit
different as we might have expected: The names of our user and role come with
the service ID of the associated service as a prefix. This prefix is also part
of the credentials you will need for authorization of your client!
Furthermore we recognize that there are an additional user and role called
<prefix>.defaultRole which are created by any
service being enabled. Those do mainly serve its service's concerns and you
should just not care too much about them.
Since the user and role we defined in the Commissioning File are associated with the service, you should avoid to simply delete them from the lists. Doing this will be detected by the service and cause a deviation warning! The cleanest way of deleting them is to disable the service and if not needed anymore to delete the service too. Of course in most cases this would be the way to go anyhow because normally the created users become obsolete when the service is not needed anymore so you would delete the service and with it automatically the user and role.
After completing this lesson you should now have a better understanding of how user and permission management of the Connectware works. Keep in mind that service users should be created in their respective commissioning file.
The Connectware offers powerful features to build and deploy applications for gathering, filtering, forwarding, monitoring, displaying, buffering, and all kinds of processing data... why not build a dashboard for instance? For guides check out more of Cybus Learn.