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

  • Tenant name: mytenant
  • Application name: timeseriesviewer

Procedure

  1. Open the Developer Cockpit and select the application.
  2. Switch to the Authorization Management tab. The app roles mdsp:mytenant:timeseriesviewer.admin and mdsp:mytenant:timeseriesviewer.user have automatically been generated for the application. The Developer Cockpit simply displays them as ADMIN and USER.
  3. Define an application scope timeseriesviewer.all that grants access to every endpoint.
  4. Assign the 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 and 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 Time Series User role and 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 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 appEdge 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

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