Permissions is a feature that can be used to give users in MIC granular access to different parts and capabilities of the MIC platform.
The foundation of user access management is the hierarchical domain tree where all Things reside. In this domain tree, a user has a home domain, and any access the user has applies to their home domain and all child domains. Access does not flow upward in the tree, nor does it extend to any sibling domains.
Permissions allows further capabilities to control user access.
- Fine-grained access control within domains, e.g. allowing access to things, but not to device management
- Cross-domain access, e.g. letting a user in one part of the domain tree access data in a different part of the domain tree
Privileges are given to users through Roles. MIC comes with predefined system roles, and beyond this Permissions gives you the ability to create and configure additional roles tailored to specific user needs. A user can have many different roles, and the privileges of these roles are applied in an additive method. For example, a user with the ReadWrite role in domain A can be given an additional Role that grants privileges in domain B (domain B being a sibling to A).
Each Role has one or more Privileges. The Privileges define what the Role allows a user to do. A Privilege applies to an object type, e.g. “Users”, “Thing Pub/Sub”, or “Observations" (historic Thing data). A Privilege can apply to either the user’s home domain or to any other specified domain.
A role can be given to any number of users. This makes updates to privileges for different user groups easy, as an update to a role affects all users with that specific role.
A role has the following properties:
id: The ID of the role
name: The name of the role
domainId: The domain that the role resides in
description: An optional description of the role
visibleInSubdomains: Boolean that determines whether the role should be visible in domains below the one it resides in (
createdAt: Epoch timestamp in milliseconds
updatedAt: Epoch timestamp in milliseconds
System Roles are predefined roles which cover common use cases in MIC. These roles provide a simple way to give users either read or read and write access in their home domains. The privileges for system roles cannot be modified, and the roles cannot be deleted. A user can have only one system role.
The following system roles are available:
Read: Gives read access to all entities in a users home domain
ReadWrite: Gives read and write access to all entities in a users home domain
Root: Is only available on root level and there it corresponds to the
A privilege gives access to specific operations on API endpoints, and the privilege object defines what API endpoints are in scope. A privilege has the following properties:
id: The ID of the privilege
roleId: The ID of the role that the privilege belongs to
objectName: The object name that the privilege applies to
domainId: The domain, if any, where the privilege applies
type: The type of the privilege. (
regularprivileges control access to different operations within the context of the specified
settingsprivileges control access to parts of MIC outside of the domain hierarchy. Hence, privileges with the type
settingsdo not allow a
domainIdto be set.
name: A user-defined field that can be used to store a human-readable description of the privilege
create: Whether the privilege gives create privilege or not. (
read: Whether the privilege gives read privilege or not. (
update: Whether the privilege gives update privilege or not. (
delete: Whether the privilege gives delete privilege or not. (
The values for
delete determines which operations are allowed,
1 for allowed,
0 for disallowed.
objectName determines which object the privilege gives access to. See further explanation below.
Each privilege with the type
regular requires a
domainId to be set. This represents the domain where the privilege applies. All domain privileges are recursive, which means that a privilege that applies to a domain will also apply to all subdomains under that domain.
Example: If a user tries to read a thing that belongs to the domain
A, that user needs a role with a privilege allowing the user to read things on domain
A or a domain above domain
In MIC, each user resides in a domain, referred to as the user’s home domain. A privilege can be applied to a user’s home domain by specifying the string
homeDomain as the
domainId when creating a privilege. This is useful when creating generic roles to be used across multiple domains.
Each Privilege Object in MIC is represented by the
objectName property in the privilege object. All supported object names are listed below.
Regular Privilege Objects
Regular objects are scoped to a specified domain and include the following:
Dashboards define the layouts of widgets in App Board. There are two types of Dashboards,
Personal Dashboard and
Domain Dashboard. Much like
Domain Dashboards are visible in the domain they reside, but also on the domains below assuming a
READ-privilege for Dashboards on that Domain has been granted. For
DELETE the privilege on the domain of the Dashboard has to be granted.
Personal Dashboards are only available for the logged in user and therefore only need
READ-privilege for creation.
Dashboards are uniquely designed for App Board, so any privileges assigned here only affect App Board-users.
DataExport allows you to export large data-sets from MIC. Creating a DataExport-job requires
CREATE, retrieving a job requires
READ, updating or canceling a job requires
UPDATE and deleting a job requires
Domains are a logical separation or grouping of entities in MIC, such as Things or ThingTypes. Creating a domain requires
CREATE in the parent domain of the domain, deleting requires
DELETE in the specified domain (the
root domain is required and cannot be deleted), and updating a domain requires
UPDATE in that domain.
Events are generated by the system as a result of a rule triggering. Certain events can be acknowledged to acknowledge that you have received the information displayed in the event. Acknowledging an event requires
Events in the domain the event originated from.
Files are either public, belong to ThingTypes, or belong to Things. Accessing or modifying public files requires the respective privilege in the user’s home-domain or
root if attempting to access a file on
root. If accessing a
ThingType, the privilege is required in the domain that the entity belongs in.
Observations are the historical data for a thing. Searching for observations requires
READ in the users home-domain.
Permissions control access to entities in MIC through roles and privileges. Accessing or modifying roles and privileges requires the correct privilege in the domain that the role belongs to. For accessing or modifying role-assignments, the correct privilege is required for
Rules allow you to automatically respond to changes to resource values. Accessing or modifying rules require the corresponding privilege on
Rules in the domain specified for the rule-filter. To create a rule, for example, you need
Rules in the domain for the rule filter.
Thing batches allow you to create several things in a single operation. Accessing or modifying thing batches requires the corresponding privilege on
ThingBatches in the domain you wish to create the things.
ThingBatches.CREATEshall be limited to as few users as possible, since it also gives permissions to download the batches with Thing credentials. We recommend only allowing
rootusers to have
Thing Groups allow you to logically group things based on arbitrary criteria, regardless of Thing Type. This is mainly used for executing jobs on a collection of things. Accessing and modifying thing groups requires the corresponding privilege on
ThingGroups in the domain the group belongs to.
Thing Jobs makes it possible to send data down to one or more things, such as a firmware upgrade. Jobs target either a number or things or a thing group. When creating a job, you need
CREATE in the domain the job should belong to, but also
Things for the things you want to add or alternatively,
ThingGroups on the domain that the thing group belongs to. For accessing or canceling a job, only the corresponding privilege for
ThingJobs on the domain in question is required.
ThingPubSub allows you to control access to publishing and subscribing to data for all things in a domain using the Thing API.
READ privileges gives access to subscribe to data while
UPDATE privileges gives access to publish data.
The system roles
ReadWrite implicitly include the ThingPubSub privilege for the home domain of the user assigned to the role. This means the ThingPubSub privilege will not be displayed for system roles in App Board. A user with the
Read role can subscribe to data in their home domain and any domain below it. A user with the
ReadWrite system role can subscribe to and publish data in their home domain and any domain below it.
A ThingPubSub privilege created on a custom role cannot be applied to
Once a role with a ThingPubSub privilege has been assigned or updated, it will only apply when the assigned users have reauthenticated using the Auth API.
ThingTypes are visible in the domain they reside and the domains below. To
DELETE, the privilege on the
thing type has to be granted on the domain where the
thing type reside. For example, given the following domain structure:
If a thing type resides in
domain1A and a user has a role with a privilege that allows reading thing types on
domain2A, the user will have access to the thing type. However, to be able to update a thing type, the user needs to have
ThingTypes.UPDATE Privilege on
Things report observations on resources, most commonly in the form of physical devices. Accessing or modifying things require the corresponding privilege on
Things in the domain the thing belongs to.
Things.CREATEshall be limited to as few users as possible, since it also gives permissions to download Thing credentials.
Thingsdoes not give access to data reported from the things, this is done by the privilege objects
Units are a special type of regular object in MIC. Since units only exist in the
root domain, a privilege for
Units must specify
root as the
Units to a Role gives all users of the Role access to Units, regardless of the users home domain. It works similar to like a Settings Privilege. For a user to be able to use Units, e.g. see them in App Board, the user needs a role with
Users are users of the system. Accessing or modifying users require the corresponding privilege on
Users in the domain the user belongs to.
Settings Privilege Objects
Settings objects control access to parts of MIC that exist outside of the domain tree. Adding these Privileges to a Role give all Users of that Role the capabilities of the Privilege, regardless of the users home domain. The available settings objects are:
AppBoardcontrols access to the MIC App Board. Setting
0denies access to the App Board. Therefore, if a role allows App Board access, the Privilege is not shown in the Privilege list on the Role.
StorageRetentioncontrols the access to modify the storage retention policy for observation data.
ThingPubSubprivilege relies on a policy document to work. The policy document has a strict size limitation. If a created or updated privilege results in a policy document that exceeds the size limit, the action will throw a
POLICY_DOCUMENT_LIMIT_EXCEEDEDerror. You then have to adjust one of the following three factors to achieve a successful result:
- The length of the domain ID specified in the privilege
- The depth of each domain in the domain tree
- A user can have max 7 roles with a
In the currently released version, the following limitations apply. We aim to address these limitations and when resolving them we will communicate that in the release notes and update this page.
- A role can only have one privilege of each object type. If a user needs Privileges to the same object type (e.g. Things) in more than one domain, multiple roles will need to be used, each containing one Privilege of the desired object type.
- The ThingPubSub privilege created on a custom role cannot be applied to
- If a domain that is used in a
ThingPubSubprivilege is moved or the domain ID is changed, the privilege will be broken and will have to be removed and recreated.
- The user assigning a role which gives cross-domain access, need to have access to both branches of the domain tree (the users home domain and the domain you want to give cross-domain access to)
- The Event API REALTIME action may not work as expected for users without a System role assigned
- In App Board, the role detail page contains a list of users assigned to that role. This list is not loading properly and you might not see all users belonging to the role. If you are logged in with a user in a domain other than
root, this list may be empty on initial page load.
- If you need to see the roles assigned to a specific user, you may do so by editing the user from the Users page