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

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:

   Template

   mdsp:{tenant_name}:{application_name}.{role_name}
   

   Example

   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.

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.

mdsp:core:agm.readonly¶

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

Agent Access Token¶

Scops of the role mdsp:core:DefaultAgent are described below:

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

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.

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

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

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

mdsp:core:assetmanagement.reporter¶

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

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.

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

mdsp:core:dwf.readonly¶

Role granting read-only access to Deployment Workflow Service

Device Configuration¶

Definition of roles and permissions for the Device Configuration

mdsp:core:deviceconfiguration.fullaccess¶

Role granting all read/write access to DeviceConfiguration APIs

mdsp:core:deviceconfiguration.readonly¶

Role granting read-only access to DeviceConfiguration APIs

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

mdsp:core:devicemanagement.deviceadmin¶

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

mdsp:core:devicemanagement.devicetypereadonly¶

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

mdsp:core:devicemanagement.devicereadonly¶

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

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

mdsp:core:devicestatus.readonly¶

Role granting read-only access to Device Status APIs

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

mdsp:core:eadplymng.readonly¶

Role granting read-only access to Edge App Deployment

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

mdsp:core:eacfgmng.readonly¶

Role granting read-only access for Edge app configuration management

mdsp:core:ealmng.fullaccess¶

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

mdsp:core:ealmng.readonly¶

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

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

mdsp:core:em.eventmanager¶

Role granting access to manage everything in Event Management system

mdsp:core:em.eventviewer¶

Role granting access to read events and eventtypes in Event Management system

Firmware Deployment¶

Definition of roles and permissions for the Firmware Deployment

mdsp:core:frmdpylmnt.fullaccess¶

Role granting all read/write access to Firmware Deployment

scopes from mdsp:core:dvcinv.readonly

mdsp:core:frmdpylmnt.readonly¶

Role granting read-only access to Firmware Deployment

Identity Management¶

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

mdsp:core:im.meIamViewer¶

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

mdsp:core:im.userIamAdmin¶

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

mdsp:core:im.userIamViewer¶

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

Integrated Data Lake¶

Definition of roles and permissions for the Integrated Data Lake.

mdsp:core:dl.dsUser¶

This role grants read, write and delete access to the Integrated Data Lake API, comprising Data Object, Event and Time Series Import operations.

mdsp:core:dl.dsAdmin¶

This role grants full administrative access to the Integrated Data Lake API, including cross-account operations.

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.

mdsp:core:iot.filUser¶

Role granting read access to files.

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.

mdsp:core:iot.timUser¶

Role granting read access to time series.

IoT Time Series Aggregates¶

IoT Time Series Aggregates API roles.

mdsp:core:iot.tsaUser¶

Granting access to time series aggregates.

Job Manager Service¶

Definition of roles and permissions for Job Manager Service

mdsp:core:jobmgr.user¶

MindConnect API¶

Definition of roles and permissions for the MindConnect API

mdsp:core:mindconnect.fullaccess¶

Role granting all read/write access to MindConnect APIs.

mdsp:core:mindconnect.readonly¶

Role granting read-only access to Agent Management APIs.

Native MQTT API (Deprecated)¶

Definition of roles and permissions for the Native MQTT API

mdsp:core:nativemqtt.fullaccess¶

This role grants all read/write access to Native MQTT API.

mdsp:core:nativemqtt.readonly¶

This role grants read-only access to Native MQTT API.

MindConnect MQTT API¶

Definition of roles and permissions for the MindConnect MQTT API

mdsp:core:mindconnectmqtt.fullaccess¶

This role grants all read/write access to MindConnect MQTT API.

mdsp:core:mindconnectmqtt.readonly¶

This role grants read-only access to MindConnect MQTT API.

Commanding API¶

Definition of roles and permissions for the Commanding API.

mdsp:core:msg.fullaccess¶

Role granting all read/write access to Commanding APIs.

mdsp:core:msg.readonly¶

Role granting read-only access to Commanding APIs.

mdsp:core:msg.defaultagent¶

Internal role granting read and acknowledge access to the Commanding APIs for the default agent.

Model Management Service¶

Role granting user access level to Model Management APIs.

mdsp:core:amm.user¶

Notification Service¶

Definition of roles and permissions for the Notification Service.

mdsp:core:nose.mobileappuser¶

Role used for granting access to perform operations on mobile application instances

Rules¶

Definition of roles and permissions for the Rules Service

mdsp:core:oi.creator¶

mdsp:core:oi.viewer¶

Semantic Data Interconnect (SDI)¶

Definition of roles and permissions for the Semantic Data Interconnect (SDI) Service

mdsp:core:sdi.admin¶

This role entitles all read/write access, administrative access to SDI APIs.

mdsp:core:sdi.enduser¶

This role entitles end-user query access to SDI APIs.

mdsp:core:sdi.semanticuser¶

This role entitles access to semantic model and semantic core SDI APIs.

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

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.

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.

Resource Access Management Service¶

Definition of roles and permissions for the Resource Access Management Service

mdsp:core:ram.papAdmin¶

This role grants admin access to Resource Access Management (RAM) - Policy Administration API for managing policies, roles and policy assignments.

mdsp:core:ram.papViewer¶

This role grants read-only access to Resource Access Management (RAM) - Policy Administration API.

Work Order Management¶

Definition of roles and permissions for the Work Order Management Service

mdsp:core:oi.wom.creator¶

Role that can create work orders.

This is by default part of mdsp:core:TenantAdmin, mdsp:core:StandardUser, mdsp:core:oi.creator and mdsp:core:Admin3rdPartyTechUser.

mdsp:core:oi.wom.viewer¶

Role that can view work orders.

Any questions left?

Ask the community

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