Permissions

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

Roles

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 ( true | false )
  • createdAt: Epoch timestamp in milliseconds
  • updatedAt: Epoch timestamp in milliseconds

System Roles

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 ReadWrite system role

Privileges

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. ( regular | settings)
    • regular privileges control access to different operations within the context of the specified domainId
    • settings privileges control access to parts of MIC outside of the domain hierarchy. Hence, privileges with the type settings do not allow a domainId to 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. ( 0 | 1)
  • read: Whether the privilege gives read privilege or not. ( 0 | 1)
  • update: Whether the privilege gives update privilege or not. ( 0 | 1)
  • delete: Whether the privilege gives delete privilege or not. ( 0 | 1)

The values for create, read, update and delete determines which operations are allowed, 1 for allowed, 0 for disallowed.

The objectName determines which object the privilege gives access to. See further explanation below.

Domains

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 A.

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.

Privilege Objects

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
  • DataExport
  • Domains
  • Events
  • Files
  • Observations
  • Permissions
  • Rules
  • ThingBatches
  • ThingGroups
  • ThingJobs
  • ThingPubSub
  • ThingTypes
  • Things
  • Units
  • Users

Dashboards

Dashboards define the layouts of widgets in App Board. There are two types of Dashboards, Personal Dashboard and Domain Dashboard. Much like ThingTypes, 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 CREATE,UPDATE and 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

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 DELETE.

Domains

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

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 UPDATE on Events in the domain the event originated from.

Files

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 Thing or ThingType, the privilege is required in the domain that the entity belongs in.

Observations

Observations are the historical data for a thing. Searching for observations requires READ in the users home-domain.

Permissions

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 Users.

Rules

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 CREATE on Rules in the domain for the rule filter.

ThingBatches

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.

Note! ThingBatches.CREATE shall be limited to as few users as possible, since it also gives permissions to download the batches with Thing credentials. We recommend only allowing root users to have ThingBatches.CREATE.

ThingGroups

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.

ThingJobs

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 READ on Things for the things you want to add or alternatively, READ in 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

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 Read and 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 homeDomain.

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

ThingTypes are visible in the domain they reside and the domains below. To CREATE,UPDATE and 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:

  • root
    • domain1A
      • domain2A

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 domain1A.

Things

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.

Note!

Things.CREATE shall be limited to as few users as possible, since it also gives permissions to download Thing credentials.

Things does not give access to data reported from the things, this is done by the privilege objects ThingPubSub and Observations.

Units

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 domainId. Adding 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 Units.READ.

Users

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:

  • AppBoard controls access to the MIC App Board. Setting create, read, update and delete to 0 denies 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.
  • StorageRetention controls the access to modify the storage retention policy for observation data.

Restrictions

  • The ThingPubSub privilege 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_EXCEEDED error. 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 ThingPubSub privilege.

Known limitations

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 homeDomain.
  • If a domain that is used in a ThingPubSub privilege 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