Overview
Tenants are physically separated data spaces with a separate URL, with a specific set of users, a separate application management and no data sharing by default. Users in a single tenant share the same URL and the same data space.
For many scenarios it is sufficient to manage multiple parties within a single tenant. In this case, you control the user access by assigning appropriate roles - to specify which devices a user can see - and this way separate and protect multiple parties from each other. This approach corresponds to a Standard tenant in Cumulocity IoT.
For other scenarios this approach might not be sufficient for various reasons and it might be relevant to manage a portfolio of tenants. This multi-tenancy approach is reflected by the concept of Enterprise tenants in Cumulocity IoT.
Multi-tenancy
With the Enterprise tenant concept, Cumulocity IoT supports full multi-tenancy. All data related to a tenant is stored in a dedicated data space. This includes user data, inventory, events, measurements, operations and alarms.
The Enterprise tenant can create subtenants that will then again function like Standard tenants in the platform and have their own tenant management.
This multi-tenancy approach has various advantages:
- User and permission management
Each tenant has full admin access to their user and permission management and can create its own roles. - Application management
Each tenant can manage their applications separately and extend the platform by adding applications. - Usage statistics and billing
Having separate tenants allows for cloud-based business models, which typically charge per API call and storage.
However, since every tenant has its dedicated database, only the IoT data of the tenant itself can be accessed within each tenant. While this has many advantages in terms of clear data separation it also means that, in order to share data between tenants it is required to copy the data over, which means that data is stored twice.
You can find a detailed discussion on the advantages and disadvantages of the role-based access control in a single tenant versus the multi-tenant approach in RBAC versus multi-tenancy approach.
Hierarchy levels
The Cumulocity IoT tenant concept builds a 3-level hierarchy, including the following levels from bottom to top:
These three levels differ in their scope, particularly with regards to administration, see below.
Info
Refer to the Cumulocity IoT Pricing page for details on our related commercial offering.
Refer to your contract for details on your individual subscriptions.
Standard tenant
At the bottom of the hierarchy you can find single tenants which are represented by the concept of Standard tenants in Cumulocity IoT.
A Standard tenant offers most of the device management and monitoring functionality of the Cumulocity IoT platform, but has certain limitations when it comes to administrative aspects.
In a Standard tenant, multiple parties are reflected by separate users. Since all users in a tenant share the same URL and data space they can only be separated from each other by assigning access rights based on the roles concept, that means, using roles you can give certain users only restricted visibility of the tenant (for example only the devices that belong to them).
Standard tenants, as direct subtenants of the Management tenant, provide fully standardized functionality.
Details on the administration of Standard tenants are described in the Administration section in the User guide.
Enterprise tenant
An Enterprise tenant offers additional administrative functionality compared to a Standard tenant, the major difference being multi-tenancy.
Using an Enterprise tenant, you can
- create and manage subtenants
- manage the subscribed applications/features of the subtenants
- invoice subtenants based on usage statistics
See also multi-tenancy approach.
Moreover, an Enterprise tenant includes the following additional features:
- Branding - To configure an individual look & feel
- Domain name - To provide an individual domain name
- Support user - To support users of other tenants
- User hierarchy - To reflect entities with limited permissions to subsets of shared data
Enterprise tenants offer standardized functionality combined with some individual customization.
Details on the usage of this additional features and on the additional administration options of the Enterprise tenant can be found in the Enterprise tenant section in the User guide.
Management tenant
The Management tenant builds the highest level of the Cumulocity IoT tenant hierarchy.
Every Cumulocity IoT deployment is delivered with a Management tenant. The Management tenant is used to administer all tenants within the same deployment on platform level and thus provides full control of the platform.
On the Cumulocity IoT cloud instances, the Management tenant can only be accessed by the Software AG cloud operations team.
You will only have access to the Management tenant, when you setup your own Cumulocity IoT instance either as a dedicated/hosted cloud deployment, an on-prem deployment, or the Cumulocity IoT Edge offering.
For detailed information on the configuration options of a Cumulocity IoT deployment on platform level, refer to the Cumulocity IoT Core - Operations guide available on the Software AG Empower Portal.
RBAC versus multi-tenancy approach
Introduction
When you think about offering your applications and services to your customers you need to think at some point about how to structure your customers within the platform. Cumulocity IoT can help you with that in two different ways.
The first is role-based access control (RBAC) that is part of every tenant in the Cumulocity IoT platform and lets you granularly define the rights of each user. This can be used to give certain users (like a customer) only partial visibility of the tenant (only the devices that belong to them).
On top of that the Cumulocity IoT platform in general is a multi-tenant platform which also gives you the ability to create your own subtenants, which function like any other tenant in the platform.
This will leave you with two options to organize your customers. You can either create a tenant for each of your customers or you can manage multiple customers within a single tenant and protect them from each other using RBAC.
In the following we will look at both approaches in more detail and run through some use cases explaining how to solve them in both ways. This should help you to decide which approach suits your business case better. Cumulocity IoT is designed to manage tenants using the tenant hierarchy. As a result, some aspects that must be handled in a customer environment are more challenging when using Role Based Access Control. Using a combination of both approaches will provide you and your customers with the most flexible approach.
Info
Starting with one approach and then switching to the other one will require some migration. It is easier to go from RBAC to multi-tenancy than vice versa.
General setup
Before going into detail with certain use cases we need to clarify the general setup for each approach and the underlying concepts.
Role-Based Access Control (RBAC)
Handling everything in a single tenant usually starts by creating an asset hierarchy in which you create separate folders for your customers. Details of the asset hierarchy can be customized but at some point you will probably end up with one folder for each customer. Your customers will then only have access to their folders and will not be able to see anything outside of that folder.
Multi-tenancy
Creating a tenant for each customer will separate your customers at the tenant level. Your customers will get access to their tenants only and can work in this tenant the same way you do in yours (with whatever specific access you want to grant them). In the use cases we will assume that the customer is the admin of his tenant and therefore has full access.
Info
The customer tenant is not different from your tenant unless you restrict your customer from certain functionality explicitly.
Comparison of various use cases
The following tasks should be covered by a platform solution:
- Onboarding new customers
- Registering new devices for a customer
- Managing access rights
- Creating additional users
- Granting access to applications
- Invoicing your customer
- Running analytics
The following sections discuss how these tasks are handled in both approaches.
Customer onboarding
| Role Based Access Control | Multi-tenancy |
|---|---|
| Adding a new customer is achieved by expanding your asset hierarchy and creating the respective user accounts for the customer with access to the newly created parts of the hierarchy. | Adding a new customer is achieved by creating a new subtenant from your own tenant. During tenant creation you can automatically create the first user for the customer which will get admin permissions. |
Comparison:
The creation of a new customer is equally simple. However, you must consider that in the multi-tenant approach you create a new empty tenant with nothing in it but the standard applications. You still might need to subscribe additional applications, create default dashboards, configure retention and others. These are already present in the RBAC approach as they are set up only once for everyone. On the other hand, this also means that you cannot have different setups for different customers, as certain settings (like retention) are configured at tenant level.
Device registration
| Role Based Access Control | Multi-tenancy |
|---|---|
| The common scenario in the RBAC setup is that the customer is not responsible for device registration, all devices are registered on the platform by the platform provider. However, it is still technically possible for a customer to register devices. The important detail in this case is that upon creating the registration entry the customer needs to specify the correct group to which the device belongs; otherwise the device would be created outside of any group and as customers can only see their groups they wouldn't be able to see the device. | As customers have full access to their tenants they are free to register devices without any further limitations. |
Comparison:
There is no technical limitation on who registers the device on the platform. However, care should be taken with the RBAC approach since customers can more easily make an incorrect configuration which registers the device without the customers being able to see it.
Access Rights
| Role Based Access Control | Multi-tenancy |
|---|---|
| There are two types of roles in Cumulocity IoT – global and inventory. Global roles are applied at the tenant level. In an RBAC approach you must use the inventory roles in order to have the correct level of separation. Apart from some global permissions (like "own user management") customer users will not be assigned any roles. Inventory roles must be created, or the default roles used, and then assigned to the user in combination with the assets the roles apply to. This needs to be done at least once for each customer. | As the tenant is completely separated from all other customers you do not necessarily need to be involved in setting up the access rights of the customer. If customers are given administration rights for their tenants they can set up permissions on their own. It is not possible for customers to have any sight or knowledge of other customers. |
Comparison:
In the RBAC approach, managing access is the most complicated part as a misconfiguration can potentially give customers access to data that they mustn’t see, like other customers' data. The inventory roles allow you to granularly define access for only certain parts of data but they don’t protect you from accidental misconfigurations. Another limitation here is that customers won’t be able to create their own roles.
For security aspects on access control see Security aspects > Access control.
User management
| Role Based Access Control | Multi-tenancy |
|---|---|
| Using the user hierarchy feature you can delegate the user management to the customers, so that they are able to create new users on their own. Using this feature they are only allowed to create users with the same roles that they have (or less). Therefore you must assign all roles that the customer needs in total to the first user so that he can delegate those. | Customers have full admin access to the user management and can also define their own roles. |
Comparison:
Having a separate tenant for each customer they will not be limited with respect to user management and can fully utilize all management functionality. In the RBAC approach you can delegate certain management functionality and the platform will make sure that users can never overstep their boundaries. However, certain functionality like creating roles will only be available to full user management admins.
Application management
| Role Based Access Control | Multi-tenancy |
|---|---|
| Application management can only be done by admins. Customers will still be able to grant their users access to available applications (of course only to those they can access themselves) but they won't be able to create own applications. | Customers are free to add applications into their tenant as they see fit. The microservice hosting feature is optional and therefore needs to be granted to the tenant by the Management tenant. This does not apply for UI applications. |
Comparison:
Application management is only available on tenant level. If you want to give customers the ability to extend the platform on their own you will need to go for a separate customer tenant. In the RBAC approach you need to take care of the application management but it is still possible to have different applications for different customers. This is easily doable for UI applications however if you add microservices you need to manage it via access rights as the microservice is generally available for the whole tenant.
Invoicing and usage data
| Role Based Access Control | Multi-tenancy |
|---|---|
| The platform automatically collects usage data like API requests, storage space, number of users and devices. However, this is always on tenant level. Resolving which customer has how much devices is still doable via the API but you will not be able to separate storage space and API requests. | If your customers are subtenants of your own tenant you will be able to see and export the usage data for each tenant from your own tenant without requiring any access to your customers´ data. You also have the ability to set limits for your customers, thus ensuring they stay under certain usage amounts. |
Comparison:
Choosing the RBAC approach limits you in the options for your business model as it will be impossible to get accurate usage data for the customers. A license based business model (for example per device) is far more feasible in the RBAC setup. Dealing with a multi-tenant setup gives you the option to select typical Cloud-based business models where you charge per API call and storage.
Analytics
| Role Based Access Control | Multi-tenancy |
|---|---|
| All data is available in a single database and therefore you can easily apply analytics on the data either using the Apama streaming analytics engine or external tools. Applying analytics to just one customer can be a bit more challenging as you must split the devices based on the customer group they belong to. | All data is split across multiple databases (one per tenant/customer) and you are not able to directly access all of them. You either need access to each tenant to extract the data or you are using features like data explorer to synchronize analytic-relevant data into a single tenant where you then can do your analytics. |
Comparison:
If you are dealing with a single tenant it will be easier to do analytics across all devices of all customers but it might be more complicated to do separate analytics for just one customer. Having the data spread across multiple tenants will take additional effort to collect the data in one place for such use cases. However, it will ease deployment of custom analytics solutions per customer.
Cumulocity IoT DataHub
Cumulocity IoT DataHub currently does not support RBAC. Users who have access to DataHub on the tenant can offload any measurements, events, alarms, and inventory details into the same data lake regardless of the permission in use. Although it might be possible to restrict the offloading job to just data for a user this would require careful and manual configuration. DataHub currently only supports one data lake folder connection per tenant. Also note that only one user is created to access the data lake from analytical tools, therefore enforcing security on the data in the data lake is also currently not possible.