Skip to content

Roles & Scopes for Applications

This section describes the concepts of application specific roles and scopes (permissions) for securing applications. In addition it lists all available roles that are required for calling the MindSphere APIs. 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. Users must have respective permission in order to access these endpoints. They must explicitly be granted access by assigning a role to them via the Settings application. Otherwise, the application does not appear on their Launchpad after logging into MindSphere or they cannot access the API.

The same security concept applies for custom applications on MindSphere. Therefore, every application must provide at least one application specific role and one application specific scope to prevent unauthorized (but logged-in) users from accessing it.

The concept by which MindSphere manages access to applications and APIs is based on three entities:

  • Scopes
    A scope is the smallest entity that describes a single permission.
  • Roles
    A role is a collection of multiple scopes. It can be assigned to a user or included in another role.
  • Tokens
    A token contains all scopes for a particular authenticated user. It can be used by applications for verifying if a user is allowed to access an endpoint.

Scopes

Scopes describe permissions which are listed in the access token as named parameters. When accessing an endpoint or application within MindSphere, the MindSphere Identity and Access Management automatically adds the required scopes to the access token if the respective user has access permission.

Scopes must adhere to the following naming convention: {application_name}.{scope}.

Roles

A role is a collection of scopes. It can either be assigned to a user via the Settings application or added to an application role to grant access to MindSphere APIs. For example, add the Core role mdsp:core:iot.timUser to your application role so the application can read time series data. This assignment makes all the scopes of the Core role available in your application role.

Securing your own Application

MindSphere provides the security concept using roles, scopes and tokens to every application. The most important aspects when developing custom applications are listed below:

  • Every application can have 1-5 application roles.
  • MindSphere automatically generates two application roles for custom applications:
    • admin
    • user
  • Developers can replace or remove default roles and add custom application roles (within the aforementioned limits).
  • Application roles and scopes are not version specific and can only be managed on application level.
  • When handing an application over to an operator tenant, the currently available application roles and scopes are applied.

Access Control

MindSphere does not restrict access to custom applications. It only provides the access token with application specific scopes available for the current user. If you define application specific scopes to protect a functionality or endpoint, you also have to implement a verification to check if the scope is present in the provided token. Refer to Authentication & Authorization.

Creating a Custom Application Role

  1. Open the Developer Cockpit from the Launchpad and select the Authorization Management tab.
  2. Switch to the App Roles sub tab.
  3. Select the application.
  4. Select the Roles tab.
  5. Enter at least a role name and description.

    Hint

    The following restrictions apply:

    • Role names are limited to up to 30 lowercase letters.
    • Descriptions are limited to up to 255 characters.

    Custom application roles are created using the following scheme:

    1
    mdsp:{tenant_name}:{application_name}.{role_name}
    
    1
    mdsp:my_tenant:my_app.tester
    
  6. Click on Save.

Changes or removal of application roles are only reflected in the Settings application if the application is in the state Registered.

Assigning an application role

The application roles only appear in the Settings application after registering the application in the Developer Cockpit. If a role is assigned to a user, the application will be available on their Launchpad the next time they log in.

Accessing MindSphere APIs

If your application requires access to a MindSphere API, the respective Core role must be added to one of your application roles. The scopes required to call a specific endpoint are documented in the respective API specification. A list of all MindSphere Core roles and the scopes they provide is given below.

Example

The following example shows how to enable reading access to assets and time series data for an application time_series_viewer on a tenant with name my_tenant.

  1. Open the Developer Cockpit from the Launchpad and select the Authorization Management tab.
  2. Select the application. The app roles mdsp:my_tenant:time_series_viewer.admin and mdsp:my_tenant:time_series_viewer.user have automatically been generated for the application. They are displayed as ADMIN and USER.
  3. Define an application scope time_series_viewer.all that grants access to every endpoint (/**).
  4. Assign this scope to both roles.
  5. Add the Core role mdsp:core:assetmanagement:reporter for accessing the Asset Management API to both app roles. This is the Reporter role for the Asset Management which grants read access to assets.
  6. Add the Core role mdsp:core:iot.timUser for accessing the Time Series API to both app roles. This is the User role for the Time Series Services which grants read access to Time Series data.

Available Roles of MindSphere APIs

This section lists all Core roles for MindSphere APIs and the scopes they provide. Custom applications can only use MindSphere APIs if the respective scopes are provided. This is either achieved implicitly via technical users or by adding the Core roles to the application roles.

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 the following 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 - without batch endpoints.
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.

mdsp:core:analytics.adb.user

Base role for utilizing the batch mode of Anomaly Detection service. In order to fully utilize Anomaly Detection service, both this role and the mdsp:core:analytics.user role are required.

Scope Description
as.adb.u Allows to use Anomaly Detection Batch 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.f.d Permission allows user to delete files.
asm.f.r Permission allows user to read files.
asm.f.w Permission allows user to create or update files.
asm.fa.d Permission allows user to delete files assignments.
asm.fa.w Permission allows user to assign files to 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.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.rep.r Permission allows user to read reports.
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.fa.d Permission allows user to delete file assignments.
atm.fa.w Permission allows user to assign files to assettypes.
atm.d Permission allows user to delete 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.f.d Permission allows user to delete files.
asm.f.r Permission allows user to read files.
asm.f.w Permission allows user to create or update files.
asm.fa.d Permission allows user to delete files assignments.
asm.fa.w Permission allows user to assign files to 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.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.f.d Permission allows user to delete files.
asm.f.r Permission allows user to read files.
asm.f.w Permission allows user to create or update files.
asm.fa.d Permission allows user to delete files assignments.
asm.fa.w Permission allows user to assign files to 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.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.

mdsp:core:assetmanagement.reporter

Reporter role allows users to read assets, asset types, aspect types and files in Asset Management Service

Scope Description
asm.f.r Permission allows user to read files.
asm.r Permission allows user to read 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

Deployment Workflow Service

Definition of roles and permissions for the Device Configuration

mdsp:core:dwf.fullaccess

Role granting all read/write access to Deployment Workflow Service

Scope Description
dinv.r Permission to read devices
dwf.cmd.c Permission to create new commands
dwf.wfinst.c Permission to create new workflow instances
dwf.wfinst.r Permission to read workflow instances
dwf.wfinst.u Permission to update workflow instances
dwf.wfmodels.c Permission to create new workflow models
dwf.wfmodels.d Permission to delete workflow models
dwf.wfmodels.r Permission to read workflow models

mdsp:core:dwf.readonly

Role granting read-only access to Deployment Workflow Service

Scope Description
dinv.r Permission to read devices
dwf.wfinst.r Permission to read workflow instances
dwf.wfmodels.r Permission to read workflow models

Device Configuration

Definition of roles and permissions for the Device Configuration

mdsp:core:deviceconfiguration.fullaccess

Role granting all read/write access to DeviceConfiguration APIs

Scope Description
dcfiles.c Permission to create device configuration files
dcfiles.d Permission to delete device configuration files / revisions
dcfiles.r Permission to read device configuration files / revisions
dcfiles.u Permission to update device configuration files / revisions
dvccfg.c Permission to create new device configuration jobs
dvccfg.d Permission to delete device configuration jobs and configuration status
dvccfg.r Permission to read device configuration jobs and configuration status
dvccfg.u Permission to update device configuration jobs and configuration status

mdsp:core:deviceconfiguration.readonly

Role granting read-only access to DeviceConfiguration APIs

Scope Description
dcfiles.r Permission to read device configuration files / revisions
dvccfg.r Permission to read device configuration jobs and configuration status

Device Management

Definition of roles and permissions for the Device Management

mdsp:core:devicemanagement.devicetypeadmin

Role granting all read/write access to Device Management APIs for Device Types

Scope Description
dvctyp.c Permission to create device types
dvctyp.d Permission to delete device types
dvctyp.r Permission to read device types
dvctyp.u Permission to update device types

mdsp:core:devicemanagement.deviceadmin

Role granting all read/write access to Device Management APIs for Device Instances

Scope Description
dinv.c Permission to create new devices
dinv.d Permission to delete devices
dinv.r Permission to read devices
dinv.u Permission to update devices
sinv.c Permission to create entries in the software inventory
sinv.d Permission to delete entries in the software inventory
sinv.r Permission to read entries in the software inventory
sinv.u Permission to update entries in the software inventory

mdsp:core:devicemanagement.devicetypereadonly

Role granting read-only access to Device Management APIs for Device Types

Scope Description
dvctyp.r Permission to read device types

mdsp:core:devicemanagement.devicereadonly

Role granting read-only access to Device Management APIs for Device Instances

Scope Description
dinv.r Permission to read devices
sinv.r Permission to read entries in the software inventory

Device Status

Definition of roles and permissions for the Device Status

mdsp:core:devicestatus.fullaccess

Role granting all read/write access to Device Status APIs

Scope Description
dhlt.c Permission to create device status information
dhlt.d Permission to delete device status information
dhlt.r Permission to read device status information
dhlt.u Permission to update device status information
sinv.c Permission to create entries in the software inventory
sinv.d Permission to delete entries in the software inventory
sinv.r Permission to read entries in the software inventory
sinv.u Permission to update entries in the software inventory

mdsp:core:devicestatus.readonly

Role granting read-only access to Device Status APIs

Scope Description
dhlt.r Permission to read device status information
sinv.r Permission to read entries in the software inventory

Edge App Deployment Service

Definition of roles and permissions for the MindConnect Open Edge App Deployment

mdsp:core:eadplymng.fullaccess

Role granting all read/write access to Edge App Deployment

Scope Description
apptrmsandcnd.c Permission to create new terms and conditions documents for Edge app deployment
apptrmsandcnd.d Permission to delete terms and conditions documents for Edge app deployment
apptrmsandcnd.r Permission to read terms and conditions documents for Edge app deployment
apptrmsandcnd.u Permission to update terms and conditions documents for Edge app deployment
docmng.r Permission to read document bundles and documents
edgeappdplymnt.c Permission to create new Edge app deployment jobs
edgeappdplymnt.d Permission to delete Edge app deployment jobs
edgeappdplymnt.r Permission to read Edge app deployment jobs
edgeappdplymnt.u Permission to update Edge app deployment jobs
edgerlsmng.r Permission to read Edge application products and releases
jbcntl.c Permission to create new Edge deployment jobs for devices
jbcntl.d Permission to delete Edge deployment jobs for devices
jbcntl.r Permission to read Edge deployment jobs for devices
jbcntl.u Permission to update Edge deployment jobs for devices

mdsp:core:eadplymng.readonly

Role granting read-only access to Edge App Deployment

Scope Description
apptrmsandcnd.r Permission to read terms and conditions documents for Edge app deployment
edgeappdplymnt.r Permission to read Edge app deployment jobs
jbcntl.r Permission to read Edge deployment jobs for devices

Edge App Instance Management Service

Definition of roles and permissions for the MindConnect Open Edge App Instance Management

mdsp:core:eacfgmng.fullaccess

Role granting all read/write access for Edge app configuration management

Scope Description
edgeconfmng.c Permission to create configurations of Edge app instances
edgeconfmng.d Permission to delete configurations of Edge app instances
edgeconfmng.r Permission to read configurations of Edge app instances
edgeconfmng.u Permission to update configurations of Edge app instances

mdsp:core:eacfgmng.readonly

Role granting read-only access for Edge app configuration management

Scope Description
docmng.r Permission to read document bundles and documents
edgeconfmng.r Permission to read configurations of Edge app instances

mdsp:core:ealmng.fullaccess

Role granting all read/write access for Edge app lifecycle management

Scope Description
edgelifecyclemng.c Permission to create Edge app instances
edgelifecyclemng.d Permission to delete Edge app instances
edgelifecyclemng.r Permission to read Edge app instances
edgelifecyclemng.u Permission to update Edge app instances

mdsp:core:ealmng.readonly

Role granting all read/write access for Edge app lifecycle management

Scope Description
docmng.r Permission to read document bundles and documents
edgerlsmng.r Permission to read application products and releases

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

Firmware Deployment

Definition of roles and permissions for the Firmware Deployment

mdsp:core:frmdpylmnt.fullaccess

Role granting all read/write access to Firmware Deployment

Scope Description
dinv.r Permission to read devices
docmng.r Permission to read document bundles and documents
dwf.wfinst.c Permission to create new workflow instances
dwf.wfinst.r Permission to read workflow instances
dwf.wfinst.u Permission to update workflow instances
fwdplymnt.c Permission to create new deployment jobs for firmware deployment
fwdplymnt.d Permission to delete deployment jobs for firmware deployment
fwdplymnt.r Permission to read deployment jobs for firmware deployment
fwdplymnt.u Permission to update deployment jobs for firmware deployment
fwmng.r Permission to read firmware for devices
jbcntl.c Permission to create new deployment jobs for devices
jbcntl.d Permission to delete deployment jobs for devices
jbcntl.r Permission to read deployment jobs for devices
jbcntl.u Permission to update deployment jobs for devices
trmsandcnd.c Permission to create terms and conditions documents for firmware deployment
trmsandcnd.d Permission to delete terms and conditions documents for firmware deployment
trmsandcnd.r Permission to read terms and conditions documents for firmware deployment
trmsandcnd.u Permission to update terms and conditions documents for firmware deployment

scopes from mdsp:core:dvcinv.readonly

mdsp:core:frmdpylmnt.readonly

Role granting read-only access to Firmware Deployment

Scope Description
dinv.r Permission to read devices
dwf.wfinst.r Permission to read workflow instances
fwdplymnt.r Permission to read deployment jobs for firmware deployment
fwmng.r Permission to read firmware for devices
jbcntl.r Permission to read deployment jobs for devices
trmsandcnd.r Permission to read terms and conditions documents for firmware deployment

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
iot.bi.r read bulk time series
iot.bi.w write bulk time series

mdsp:core:iot.timUser

Role granting read access to time series.

Scope Description
iot.tim.r read time series
iot.bts.r read bulk 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.

Note

Roles and scopes for the Notification Service are implicitly available to operator and developer tenants. Refer to 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.

Spectrum Analysis Service

Definition of roles and permissions for Spectrum Analysis service

mdsp:core:spectrumanalysis.fft.user

Base role for using the Spectrum Analysis service

Scope Description
as.sa.fft Permission required to use Spectrum Analysis API.

Tenant Management Service

Definition of roles and permissions for the Tenant Management Service

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 quota information
uts.rc Grants access to report console
uts.ri Grants user to request 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.