Advanced Role-Based Access Control (RBAC) for IoT devices and applications

• Overview
• ThingsBoard CE vs PE security features comparison
  • ThingsBoard Community Edition
  • ThingsBoard Professional Edition
• Glossary
• Roles
  • Creating a new role
  • Generic roles
    • Example
    • Permissions
  • Group roles
    • Example
• Solution example for smart buildings: separate user groups per facility
• Video tutorial
• Next steps

Overview

Identity access and management (IAM) is essential for today’s business security strategy. Many IAM systems use a method known as role-based access control (RBAC) to assign permissions for who can do what within specified IT resources.

Role-Based Access Control (RBAC) allows to create and grant advanced access by assigning a set of permissions. RBAC roles refer to the levels of access that users may have. Access to resources can be limited to specific operations, such as viewing, creating, writing, or deleting data. Similarly, you can restrict access to sensitive information, increasing business security.

ThingsBoard CE vs PE security features comparison

ThingsBoard Community Edition

ThingsBoard Community Edition supports a straight-forward security model with three main roles: System administrator, Tenant administrator, and Customer user. A system administrator is able to manage tenants, while a tenant administrator manages devices, dashboards, customers, and other entities that belong to a particular tenant. Customer user is able to view dashboards and control devices that are assigned to a specific customer. ThingsBoard Community Edition functionality is sufficient for a lot of simple use cases, especially building real-time end-user dashboards.

ThingsBoard Professional Edition

ThingsBoard Professional Edition brings much more flexibility in terms of user, customer, and role management. It is designed to cover use cases for businesses and enterprises with multiple user groups that have different permissions but may interact with the same devices and assets.

ThingsBoard supports the “recursive” customer hierarchy with tens of thousands of sub-customers. The root-level Owner is Tenant. Each Owner may have multiple Entity Groups, User Groups, and Customer Groups.

Since Customer Groups can contain multiple Customers, each Customer can also own his Entity Groups, User Groups, and Customer Groups (i.e. sub-customer groups).

Note: Each Entity has only one owner. However, Entities can belong to multiple Entity Groups that belong to the same owner.

The ThingsBoard Professional Edition security model support advanced RBAC for IoT applications and includes security features such as:

• ability to create a hierarchy of customers with multiple levels of sub-customers, independent users, and devices;
• ability to create roles with a flexible set of permissions;
• ability to assign roles to exact user groups;
• ability to grant specific permissions to particular user groups over precise device groups.

This document covers features that are exclusive to ThingsBoard Professional Edition. We will start with a glossary and will provide step-by-step examples of how to configure the most popular use cases.

Glossary

Tenant

A Tenant is a separate business-entity: an individual, or an organization that owns or produces devices and assets. A tenant can have multiple tenant administrator users and millions of customers.

Customer

A Customer can be a separate business-entity: an individual, or an organization that purchases or uses tenant devices and/or assets. Customer can also be a division within the Tenant organization. Customer can have multiple users, inner customers, and millions of devices and/or assets.

Customer Group

The Customer group is also an Entity Group. It has the same features as regular Entity Group, but we have a separate term for Customer Group to be able to easily distinct Customer Groups and all other Entity Groups.

User

Users are able to login to the ThingsBoard web interface, execute REST API calls, access devices, and assets if it’s allowed. The User is also an Entity in ThingsBoard.

User Group

A User group is also an Entity Group. It has the same features as regular Entity Group, but we have a separate term for User Group to be able to easily distinct User Groups and all other Entity Groups.

Entity

An Entity can be a device, asset, user, dashboard, entity view, etc. Any entity is managed by ThingsBoard. See entities and relations guide for more details.

Entity Group

Entity Groups are groups of entities of the same type, for example, Device Group or Asset Group. A single entity can simultaneously belong to multiple entity groups. For example, a thermostat device might belong to group “Thermostats”, which contains all devices, and a more specific group like “Thermostats with FW v1.2.3”.

Owner

Each Entity Group belongs to one owner. This can be either Tenant or Customer. Also, each Customer has only one owner. If the Customer Owner is a Tenant, it means that this is a top-level Customer. If the Customer owner is another Customer, it means that this is a sub-customer. There might be multiple levels of Customers in ThingsBoard.

Resource

Anything that has the secure APIs or represents a ThingsBoard Entity is a resource. Examples of Entities are listed in the Entity definition above. Groups of entities are also resources, for example, Device Group, Asset Group, Dashboard Group. Additional resources are white-labeling, audit logs, and admin settings.

Operation

Operations represent actions that you might perform over Resources. There are generic actions like “create”, “read”, “write”, “delete”, “add to group”, “remove from group”. There are also specific actions like “read/write credentials”.

Role

A Role contains a list of Resources and a list of allowed Operations for each of those resources. There are two Role types: Generic and Group. There is a special resource “All” which is a shortcut to all available resource types. There is also a special operation “All” that is a shortcut to all possible operations.
We will explain the differences between them later in this article.

Group Permissions Entity (GPE)

Group Permissions Entity is basically a mapping between User Group, Role, and optional Entity Group. See Generic roles and Group roles for more details.

Roles

Roles represent a set of rights and permissions that determine what actions a user or group of users can perform within the system. Generally, roles help to simplify permission management by allowing administrators to assign and modify permissions for a group of users and for each user individually.

Role maps resource type to a list of allowed operations. A list of all available resources is here

Let’s examine the diagram below to better understand how roles work.

• User Group 1 with the role assigned to them as “Read device only” has access only to devices (can view, but cannot delete, edit or add new devices). This user group has access only to devices and does not have access to any other entities.

• User Group 2 has been assigned two roles: “Device Read Only” and “Dashboards and Widgets Administrator”. The “Dashboards and Widgets Administrator” role allows users to create, delete, and edit widgets and dashboards. Additionally, the users have access to data from the devices available to them due to the “Device Read Only” role, and can visualize this data in their dashboards.

• User Group 3 has been assigned the role of “Access to all resources”. This role grants permissions for creating, editing, and deleting all entities such as devices, dashboards, assets, and customers.

In ThingsBoard Professional Edition, there are two types of roles: Generic and Group. Each role type has its own permissions.

Creating a new role

To create a new Role, navigate to the Security section -> Roles page then click the “plus” button in the top right corner.

Please specify the name and choose type of the role: Generic or Group, as well as the necessary permissions. The Generic Role automatically grants User Group access to all resources with all permissions.

Now let’s look at each type of role separately.

Generic roles

The Generic Role consists of the set of permissions that are applied to all entities of the Tenant or Customer or Sub-customer recursively.

ThingsBoard use special “connection” called Group Permission Entity (GPE) which grants permissions of Generic Role for User Group.

Example

Let’s consider an example to better understand how a generic role works.

The “Device Admins” user group of Tenant A, which includes the user Bob, is assigned the Generic Role (Resource: All, Operation: All). User Bob can perform any operations over any entity that belongs to his Tenant A or Customer B and all its sub-customers.

The user Alice from the “Device Admins” user group of Customer B, is assigned the Generic Role (Resource: All, Operation: All). User Alice can perform any operations on any entity that belongs only to her Customer B and all of its sub-customers.

So, Alice and Bob have access to Device B1, but only Bob has access to Device A1.

Let’s check this. Login as user Bob.

User Bob has access to two devices: “Device A1” and “Device B1”.

Now login as user Alice.

User Alice has access to only one device “Device B1”.

Permissions

Please check out resource types and corresponding operations listed below.

Group roles

The Group Role defines a set of permissions for a specific group of users in relation to a specific group of entities.

We use special “connection” called Group Permission Entity (GPE) to make a connection between User Group, Entity Group and Group Role.

Example

Let’s consider an example to better understand how a group role works.

Let’s assume you have two user groups: “Building A Admins” and “Building B Admins”, and each user group is responsible for monitoring the status of different devices in Building A and Building B respectively.

You want User Bob (user group “Building B Admins”) to have reading/writing access to all devices in the device group “Building B”, but not be able to view or alter the state of devices in device group “Building A”. Similarly, User Alice (user group “Building A Admins”) should have reading/writing access to all devices in the device group “Building A”, but not be able to view or alter the state of devices in device group “Building B”.

You can achieve this by creating Group role with reading/writing operations.

Now, assign this role to the device group “Building A”.

Assign the same group role to the device group “Building B”.

So, user Alice and all users in the group “Building A Admins” only have access to Device A1. Login as user Alice to verify this.

Same thing with user Bob. User Bob and all users in the group “Building B Admins” only have access to Device B1.

In this way, group roles allow you to flexibly manage access to resources at the group level, rather than at the level of individual users or individual devices.

Note:
Since Entity Group has only one Owner, you can assign Group Role to any User Group that belongs to the same Owner or any parents of the Owner.

Solution example for smart buildings: separate user groups per facility

Let’s assume your solution manages commercial buildings. Your main customer is a Building Manager that wants to monitor HVAC systems, electricity consumption, and other smart devices in the building.
The Building Manager may want to design and share some dashboards with the end-users - office workers. Besides, your engineers responsible for the maintenance are interested in supervising the device’s state, for example, receive alerts when the battery level forgoes below certain thresholds.

To summarize those requirements in ThingsBoard terms, we should implement the following roles:

• Supervisors - read-only access to all devices’ telemetry in all the buildings, and the ability to create their custom dashboards, but no access to dashboards created by users from different user groups.
• Facility Managers - allows provisioning new devices for each facility, setup thresholds, manage users, and configure dashboards.
• End Users - allows having read-only access to the state of the facility where this user belongs to.

Let’s configure ThingsBoard to support this use case. The instructions below assume that you have logged in as a Tenant Administrator.

Supervisors

We will create a separate user group named “Supervisors”, a separate dashboard group “Supervisor Dashboards” and one dashboard. Our goal is to allow supervisors to manage dashboards in the “Supervisor Dashboards” group, but for all other entities in the system, they should have read-only access.

Let’s start by creating a “Supervisor Dashboards” group:

1. Navigate to the “Groups” tab in the “Dashboards” page and click “plus” button to create new entity group;
2. Input the name of your dashboard group. In our case, it’s “Supervisor Dashboards”. Click on the “Add” button;
3. New dashboard group “Supervisor Dashboards” has been created.

Next we should create two roles to implement this use case:

• “All Entities Read-only” - the generic role that will allow access to all entities’ data except device credentials.
  1. Navigate to the “Security” section -> “Roles” page and click on the “+” sign at the top right of the screen;
  2. Input the role name - “All Entities Read-only”;
  3. Select role type - “Generic”;
  4. In the “Permissions” section select “All” for the “Resources”;
  5. select operations: “Read”, “Read Attributes” and “Read Telemetry”;
  6. Click on the lowest “Add” button, the one without a “+” sign.

• “Entity Group Administrator” - the group role that allows all operations for the group.
  1. Again, click the “plus” icon in the upper right corner of the “Roles” page screen;
  2. Input the role name - “Entity Group Administrator”;
  3. Select role type - “Group”;
  4. In the “Permissions” section select “All” operations;
  5. Click on the “Add” button.

Now let’s assign those roles to the “Supervisors” group.

1. Navigate to the “Users” page -> “Groups” tab and click on the “+” sign (Add entity group) at the top right of the screen;
2. Input the name - “Supervisors”, then click on the “Add” button. The “Supervisors” user group is created. Click on it;
3. Click on the “pencil” icon to open entity group details;
4. Navigate to the “Roles” tab and click on the “plus” icon at the right top of the opened menu;
5. Select role type - “Generic” and select previously created role - “All Entities Read-only”. Then, click “Add”;
6. Again press the “+” sign. This time select role type - “Group” and select role - “Entity Group Administrator”. For a group owner select “Tenant”, for a entity type select “Dashboard”, and select entity group - “Supervisor Dashboard”. Click “Add”. We have assigned these roles to the Supervisors group.

Facility Managers

We will create a separate customer entity for each building or group of buildings. We will add the Facility Manager user account to the default “Customer Administrators” user group which is automatically created for each customer. Now, as Facility Manager, we can log in, design dashboards, provision devices, and end-users.

1. Navigate to the “Customers” page and click on the “+” sign (Add customer) at the top right of the screen;
2. Input the title “Building A” and click “Add”;
3. Click on the “Manage customer users” icon opposite the “Building A” customer;
4. Navigate to the “Groups” tab and click on the “Customer Administrators” user group;
5. Click on the “+” sign at the top right of the screen. Input email address, for instance, we can use [email protected], and click “Add”;
6. In the opened window you can see the user activation link, click “OK”;
7. Customer user Jane has been created.

End Users

Let’s log in as customer user Jane Smith (created in a previous guide), Building A administrator, and create a dashboard.

1. Login as customer user Jane Smith;
2. Go to the “Dashboards” page, and click on the “plus” icon in the top right corner. Select “Create new dashboard”;
3. Input dashboard name. For example, “End User Dashboard”. Click “Add” to create the dashboard;
4. Open created dashboard and enter edit mode;
5. Click “Add new widget” and select “Simple card” widget in “Cards” widgets bundle;
6. In this example, we will generate random temperature values in the widget. In the “Datasources” section select the type as “Function” and the key as “Random”. Click “Add”;
7. The widget has been created. Save the dashboard.

Now, let’s create a Read-only User. Let’s assume we want to assign “End User Dashboard” to him and make sure that this Dashboard will open full screen once the user is logged in. So, our read-only user will not have access to the administration panel to the left, since they are still not allowed to perform any server-side API calls, except read-only browsing the data.

1. Select “Customer Users” on the “Groups” tab of the “Users” page;
2. Click “+” at the top right of the screen to add new user;
3. Input email address, for example, we will use [email protected], then click “Add”;
4. In the opened window you can see the user activation link, click “OK”;
5. Now, click on the created user;
6. At the right top of the screen you shall see the “pen” icon. Click on it to enter edit mode;
7. Check the box “Always fullscreen” and choose “End User Dashboard” in the “Default dashboard” line. Then save changes;
8. Login as customer user Bob. Dashboard will open full screen. User Bob will not have access to the administration panel to the left. Bob is not allowed to perform any server-side API calls, only browsing the data.

Video tutorial

You can watch the video tutorial for step-by-step instructions on role-based access control.

Next steps

• Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.

• Data processing & actions - Learn how to use ThingsBoard Rule Engine.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.