Skip to content

Roles & Scopes for Applications

This section describes the concepts of application-specific roles and scopes (permissions) for securing applications. In addition, all available roles that are required for calling the MindSphere APIs are listed here. MindSphere provides an integrated positive security concept based on oAuth (using oAuth Bearer Tokens [RFC 6750]) that eliminates the need for implementing your own user and access management.

Concept Overview

Every application and API on the platform is secured on an endpoint level. In order to access these endpoints a user must have the permission to access those. Users need to be explicitly granted access to an application by assigning a role to a user via the Settings. Otherwise the application does not appear on the Launchpad after logging in to MindSphere.

The same applies for your own developed applications. Therefore, every application must have at least one application-specific role and one application-specific scope to prevent unauthorized (but logged-in) users from accessing your application.

The MindSphere platform knows three entities for managing the access to applications and APIs:

  • Scopes
    A scope is the smallest entity that describes a single permission.

  • Roles
    A role is a collection of multiple scopes (permissions) that can be assigned to a user or another role.

  • Tokens
    A token contains all scopes for a particular authenticated user that can be used by an application for verifying if a user is allowed to access an endpoint.

Assign an application role

After registering an application via the Developer Cockpit your application specific roles appear in the Settings and can be assigned to a user. After the assignment the application is going to appear on the Launchpad and can be accessed.

Scopes

Scopes are essentially permissions, and are added as a named parameter in the access token. When accessing an endpoint or application within the MindSphere platform the MindSphere Identity and Access Management automatically takes care about the required and available scopes for the user and adds them into the token.

Scopes must follow the specific naming convention: {applicationName}.{scope}.

Roles

A role is a collection of scopes that can be either assigned to a user via the Settings for applications like the Asset Manager or be used in your application configuration to access a MindSphere API. For example, your application wants to read Time Series data which requires you to assign the role mdsp:core:iot.timUser to your own roles. This assignment ensures that all the scopes that are associated with this role are also available in your application specific role.

Securing your own Application

MindSphere helps developers by securing their application with the integrated Settings based on roles and scopes. Currently, MindSphere allows to use two specific roles for a developed application:

  • admin
  • user

These roles will be available after application registration in the Settings using the following scheme mdsp:{tenantName}:{applicationName}.{roleName}.

A developer can now define an application-specific scope (permission) to protect a functionality or endpoint and assign it to one of the available roles. Next, the developer has to implement a scope verification for the functionality or endpoint that verifies and decodes the token and checks, if the scope is present (see section in Authentication & Authorization).

Versioning

Keep in mind that application specific roles and scopes are not application version specific. They can only be managed on an application level.

Info

In future developers can define their own roles using different names.

Accessing MindSphere APIs

If your application uses a MindSphere API, you need to add the API-specific role to one of your application-specific roles. You can find the API-specific scopes that are required to call an API endpoint in the individual API specifications. Below we listed all API-specific scopes and roles, so that you know what to add to your application-specific roles in order to access an API.

Example

The following example shows how to enable reading access to Assets and Time Series data.

Prerequisites

  • Tenantname: mytenant
  • Application name: timeseriesviewer

Procedure

  1. Define an application-specific role called mdsp:mytenant:timeseriesviewer.user.
  2. Define an application-specific scope timeseriesviewer.all that grants access to every endpoint of your demo application.
  3. Assign the scope to the role via the Developer Cockpit.
  4. Assign the Asset Management-specific API role Reporter called mdsp:advanced:assetmanagement:reporter that grants read access to assets.
  5. Assign the Time Series-specific API role Time Series User called mdsp:core:iot.timUser that grants read access to Time Series data.

Available Roles of MindSphere APIs

This section describes all MindSphere API-specific roles and scopes that a developer must use in order to enable access to them for a custom developed application.

Agent Management

Definition of roles and permissions for the Agent Management

mdsp:core:agm.fullaccess

This role grants all read/write access to Agent Management APIs.

Scope Description
agm.c Permission to create agent resources.
agm.d Permission to delete agent resources.
agm.r Permission to read agent resources.
agm.u Permission to update agent resources.
dsc.r Permission to read data source configuration of an agent.
dsc.u Permission to update source configuration of an agent.
obc.r Permission to read onboarding status.
obc.sec Permission for offboarding and accessing onboarding material.

mdsp:core:agm.readonly

This role grants read-only access to Agent Management APIs.

Scope Description
agm.r Permission to read agent resources.
dsc.r Permission to read data source configuration of an agent.
obc.r Permission to read onboarding status.

Analytics Services

Definition of roles and permissions for analytics services:

  • Anomaly Detection
  • Event Analytics
  • KPI Calculation
  • Signal Calculation
  • Signal Validation
  • Trend Prediction

mdsp:core:analytics.user

Base role for all analytic services

Scope Description
as.ad.u Allows to use Anomaly Detection API.
as.ea.u Allows to use Event Analytics API.
as.kc.u Allows to use KPI Calculation API.
as.sc.u Allows to use Signal Calculation API.
as.sv.u Allows to use Signal Validation API.
as.tp.u Allows to use Trend Prediction API.

Asset Management

Definition of roles and permissions for the Asset Management

mdsp:core:assetmanagement.admin

Admin role allows users to create, read, update or delete assets, asset types, aspect types and images in Asset Management Service

Scope Description
asm.c Permission allows user to create assets.
asm.d Permission allows user to delete assets.
asm.h.d Permission allows user to delete hierarchy type assets.
asm.h.w Permission allows user to create or update hierarchy type assets.
asm.ia.d Permission allows user to delete image assignments.
asm.ia.w Permission allows user to assign images to assets.
asm.img.d Permission allows user to delete images.
asm.img.r Permission allows user to read images.
asm.img.w Permission allows user to create or update images.
asm.loc.d Permission allows user to delete locations.
asm.loc.w Permission allows user to create or update locations.
asm.m Permission allows user to move assets.
asm.r Permission allows user to read assets.
asm.rh.d Permission allows user to delete root assets.
asm.rh.w Permission allows user to create or update root assets.
asm.u Permission allows user to update assets.
atm.apt.d Permission allows user to delete aspect types.
atm.apt.r Permission allows user to read aspect types.
atm.apt.w Permission allows user to create or update aspect types.
atm.d Permission allows user to delete asset types.
atm.ia.d Permission allows user to delete image assignments.
atm.ia.w Permission allows user to assign images to asset types.
atm.r Permission allows user to read asset types.
atm.w Permission allows user to create or update asset types.

mdsp:core:assetmanagement.standarduser

Standard user role allows users to read or update assets and images, and to read asset types and aspect types in Asset Management Service

Scope Description
asm.h.d Permission allows user to delete hierarchy type assets.
asm.h.w Permission allows user to create or update hierarchy type assets.
asm.ia.d Permission allows user to delete image assignments.
asm.ia.w Permission allows user to assign images to assets.
asm.img.d Permission allows user to delete images.
asm.img.r Permission allows user to read images.
asm.img.w Permission allows user to create or update images.
asm.loc.d Permission allows user to delete locations.
asm.loc.w Permission allows user to create or update locations.
asm.m Permission allows user to move assets.
asm.r Permission allows user to read assets.
asm.u Permission allows user to update assets.
atm.apt.r Permission allows user to read aspect types.
atm.r Permission allows user to read asset types.

mdsp:core:assetmanagement.subtenantuser

SubTenant user role allows users to read asset ~ and aspect types, read or update assets, and read, update or delete images in Asset Management Service

Scope Description
asm.h.d Permission allows user to delete hierarchy type assets.
asm.h.w Permission allows user to create or update hierarchy type assets.
asm.ia.d Permission allows user to delete image assignments.
asm.ia.w Permission allows user to assign images to assets.
asm.img.d Permission allows user to delete images.
asm.img.r Permission allows user to read images.
asm.img.w Permission allows user to create or update images.
asm.loc.d Permission allows user to delete locations.
asm.loc.w Permission allows user to create or update locations.
asm.m Permission allows user to move assets.
asm.r Permission allows user to read assets.
asm.rh.d Permission allows user to delete root assets.
asm.rh.w Permission allows user to create or update root assets.
atm.apt.r Permission allows user to read aspect types.
atm.r Permission allows user to read asset types.

Data Exchange Service

Definition of roles and permissions for the Data Exchange Service

mdsp:core:dataexch.user

Role that tenants can upload, download and delete data.

Scope Description
pl.de.r Permission to list folder contents and download data
pl.de.w Permission to upload and delete data. It implies the pl.de.r

Data Flow Engine

Data Flow Engine roles.

mdsp:core:dataflowengine.standarduser

Data Flow Engine standard user role with all read scopes

Scope Description
dfs.amr Data Flow Engine System application management read scope
dfs.ras Data Flow Engine System runtime application status read scope
dfs.sm Data Flow Engine System stream management read/write scope

Event Management

Definition of roles and permissions for the Event Management

mdsp:core:em.eventcreator

Role granting access to create events (create, read and update) in Event Management system

Scope Description
em.c Permission required to create events in Event Management
em.et.r Permission required to read event types in Event Management
em.r Permission required to read events in Event Management
em.u Permission required to update events in Event Management
emds.ent.r Permission required to read entities via Entity Master Data Service

mdsp:core:em.eventmanager

Role granting access to manage everything in Event Management system

Scope Description
em.c Permission required to create events in Event Management
em.d Permission required to delete events in Event Management
em.et.c Permission required to create event types in Event Management
em.et.d Permission required to delete event types in Event Management
em.et.r Permission required to read event types in Event Management
em.et.u Permission required to update event types in Event Management
em.r Permission required to read events in Event Management
em.u Permission required to update events in Event Management
emds.ent.r Permission required to read entities via EntityMasterDataService

Identity Management

The Identity Management service serves for managing all authorization-related functionality within MindSphere

mdsp:core:im.meIamViewer

Role granting access to the current user's information including assigned roles in tenant's user IAM system

Scope Description
im.usr.me Permission required to read the own user.

mdsp:core:im.userIamAdmin

Role granting administrative access (read and write) to a tenant's user IAM system

Scope Description
im.dg.c Permission required to create data groups.
im.dg.d Permission required to delete data groups.
im.g.c Permission required to create groups.
im.g.d Permission required to delete groups.
im.g.r Permission required to read groups.
im.g.u Permission required to update groups.
im.ug.c Permission required to create user groups (here: sub-tenants).
im.ug.d Permission required to delete user groups (here: sub-tenants).
im.ug.r Permission required to read user groups (here: sub-tenants).
im.usr.c Permission required to create users.
im.usr.d Permission required to delete users.
im.usr.me Permission required to read the own user.
im.usr.r Permission required to read users.
im.usr.u Permission required to update users.

mdsp:core:im.userIamViewer

Role granting read only access to a tenant's user IAM system

Scope Description
im.g.r Permission required to read groups.
im.ug.r Permission required to read user groups (here: sub-tenants).

IoT File Service

Definition of roles and permissions for the IoT File Service

mdsp:core:iot.filAdmin

Role granting read, write and delete access to files.

Scope Description
iot.fil.d delete file
iot.fil.r read file
iot.fil.w write file

mdsp:core:iot.filUser

Role granting read access to files.

Scope Description
iot.fil.r read file

IoT Time Series

Definition of roles and permissions for the IoT Time Series Services (Time Series, Aggregations, Subscription and Export)

mdsp:core:iot.timAdmin

Role granting read, write and delete access to time series.

Scope Description
iot.tim.d delete time series
iot.tim.r read time series
iot.tim.w write time series

mdsp:core:iot.timUser

Role granting read access to time series.

Scope Description
iot.tim.r read time series

IoT Time Series Aggregates

IoT Time Series Aggregates API roles.

mdsp:core:iot.tsaUser

Granting access to time series aggregates.

Scope Description
iot.tsa.r read time series aggregations

Job Manager Service

Definition of roles and permissions for Job Manager Service

mdsp:core:jobmgr.user

Scope Description
prl.jm.e Allows to execute, start, stop or schedule jobs in Job Manager API.
prl.jm.h Allows to query the history of executions in Job Manager API.

Mind Connect API

Definition of roles and permissions for the Mind Connect API

mdsp:core:mindconnect.fullaccess

Role granting all read/write access to MindConnect APIs.

Scope Description
da.c Permission to create diagnostic activation.
da.d Permission to delete diagnostic activation.
da.r Permission to read diagnostic activation info.
di.r Permission to read diagnostic data.
map.c Permission to create a mapping.
map.d Permission to delete a mapping.
map.r Permission to read a mapping.

mdsp:core:mindconnect.readonly

Role granting read-only access to Agent Management APIs.

Scope Description
da.r Permission to read diagnostic activation info.
di.r Permission to read diagnostic data.
map.r Permission to read a mapping.

Model Management Service

Role granting user access level to Model Management APIs. mdsp:core:amm.user

Scope Description
plr.amm.c Permission to create a model.
plr.amm.r Permission to read a model.
plr.amm.u Permission to update a model.
plr.amm.d Permission to delete a model.

Notification Service

Definition of roles and permissions for the Notification Service

mdsp:core:nose.admin

Role used for granting access to use the Notification Service administration APIs

Scope Description
nose.ac Grants access to administration console.

mdsp:core:nose.user

Role used for granting the user the permission to send message APIs

Scope Description
nose.se Grants user access to send e-mail message, Push Notification and SMS.

Tenant Management Service

Tenant management manages tenants and subtenants.

mdsp:core:tm.tenantAdmin

Role grants full administrative access to the respective tenant.

Scope Description
tm.li.c Permission required to create legal information.
tm.li.d Permission required to delete legal information.
tm.li.r Permission required to read legal information.
tm.li.u Permission required to update legal information.
tm.st.c Permission required to create subtenants.
tm.st.d Permission required to delete subtenants.
tm.st.r Permission required to read subtenants.
tm.st.u Permission required to update subtenant.

mdsp:core:tm.tenantUser

Role grants permissions for standard tenant users.

Usage Transparency Service

Definition of roles and permissions for the Usage Transparency Service

mdsp:core:uts.analyst

Role that tenants can see the usage data.

Scope Description
uts.qi Grants access to qutoa information
uts.rc Grants access to report console
uts.ri Grants user to requestion usage information
uts.su Grants access to send usage information

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.