Roles and Scopes for Applications¶

This section describes the concepts of application specific roles and scopes (permissions) for securing applications. Additionally, it lists all available roles that are required for calling the Insights Hub APIs. Insights Hub 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 Insights Hub is secured at the endpoint level. Users need the respective permissions to access these endpoints. Access is granted by assigning roles via the Settings application. Without this access, the application will not appear on the user's Launchpad after logging into Insights Hub or they cannot access the API.

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

Insights Hub manages access to applications and APIs through three main 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 specific authenticated user. It can be used by applications to verify 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 Insights Hub, the Insights Hub Identity and Access Management automatically add 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 Insights Hub 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¶

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

• Every application can have 1-5 application roles.
• Insights Hub 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 at the 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 desired application.
4. Select the "Roles" tab.
5. Enter at least a role name and description.

Custom application roles are created using the following scheme:

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

mdsp:my_tenant:my_app.tester

6.Click "Save".

If the application is in the "Registered" state, the changes or removal of application roles are reflected only in the Settings application.

Accessing Insights Hub APIs¶

If your application requires access to the Insights Hub API, the respective core role must be added to one of your application roles. The required scopes for calling a specific endpoint are documented in the respective API specification. A list of all Insights Hub 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 the name my_tenant.

1. Open the "DevOps Cockpit" from the Launchpad and click "Application List" in the Quick Links section.
2. Select the application and choose the version of your choice.
3. Click "See Details" and select the "Access" tab. By default, the application scope with the "Admin" role (mdsp:my_tenant:time_series_viewer.admin) is automatically added to the application and this role is displayed as admin.
4. Define an application scope time_series_viewer.all that grants access to every endpoint (/**).
5. Assign this scope to the admin role.
6. Click "Add API Role" in the "API Roles" and add the mdsp:core:assetmanagement:reporter role for accessing the Asset Management API. This is the Reporter role for Asset Management, which grants read access to assets.
7. Click "Add API Role" in the "API Roles" and add the mdsp:core:iot.timUser role for accessing the Time Series API. This is the User role for the Time Series Services, which grants read access to Time Series data.
8. Click "Configure".

Available Roles of APIs¶

This section lists all the core roles of Insights Hub APIs and the scopes they provide. Custom applications can use Insights Hub APIs only if the respective scopes are provided. This can be achieved either implicitly via technical users or by adding the core roles to the application roles.

Agent Management¶

Definition of roles and permissions for Agent Management. The specific permissions for each role are explained below.

mdsp:core:agm.fullaccess¶

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

mdsp:core:agm.readonly¶

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

Agent Access Token¶

The "Scopes" of the role mdsp:core:DefaultAgent are described below:

Asset Management¶

Definition of roles and permissions for Asset Management. The specific permissions for each role are explained below.

mdsp:core:assetmanagement.admin¶

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

mdsp:core:assetmanagement.standarduser¶

The "Standard" user role allows users to read or update assets and images, as well as read asset types and aspect types in the Asset Management Service.

mdsp:core:assetmanagement.subtenantuser¶

The "SubTenant" user role allows users to read asset and aspect types, read or update assets, and also read, update or delete images in the Asset Management Service.

mdsp:core:assetmanagement.reporter¶

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

Data Exchange Service¶

Definition of roles and permissions for the Data Exchange Service.

mdsp:core:dataexch.user¶

The "Role" allows tenants to upload, download and delete data.

Deployment Workflow Service¶

Definition of roles and permissions for Device Configuration. The specific permissions for each role are explained below.

mdsp:core:dwf.fullaccess¶

This role grants all read and write access to the Deployment Workflow Service.

mdsp:core:dwf.readonly¶

This role grants read-only access to the Deployment Workflow Service.

Device Configuration¶

Definition of roles and permissions for Device Configuration.

mdsp:core:deviceconfiguration.fullaccess¶

This role grants all read and write access to the Device Configuration APIs.

mdsp:core:deviceconfiguration.readonly¶

This role grants read-only access to the Device Configuration APIs.

Device Management¶

Definition of roles and permissions for Device Management.

mdsp:core:devicemanagement.devicetypeadmin¶

This role grants all read and write access to the Device Management APIs for Device Types.

mdsp:core:devicemanagement.deviceadmin¶

This role grants all read and write access to the Device Management APIs for Device Instances.

mdsp:core:devicemanagement.devicetypereadonly¶

This role grants read-only access to the Device Management APIs for Device Types.

mdsp:core:devicemanagement.devicereadonly¶

This role grants read-only access to the Device Management APIs for Device Instances.

Device Status¶

Definition of roles and permissions for Device Status.

mdsp:core:devicestatus.fullaccess¶

This role grants all read and write access to the Device Status APIs.

mdsp:core:devicestatus.readonly¶

This role grants read-only access to the Device Status APIs.

Edge App Deployment Service¶

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

mdsp:core:eadplymng.fullaccess¶

This role grants all read and write access to Edge App Deployment.

mdsp:core:eadplymng.readonly¶

This role grants 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¶

This role grants all read and write access to Edge app configuration management.

mdsp:core:eacfgmng.readonly¶

This role grants read-only access to Edge app configuration management.

mdsp:core:ealmng.fullaccess¶

This role grants all read and write access to Edge app lifecycle management.

mdsp:core:ealmng.readonly¶

This role grants all read and write access for Edge app lifecycle management.

Event Management¶

Definition of roles and permissions for Event Management.

mdsp:core:em.eventcreator¶

This role grants access to create, read and update events in the Event Management system.

mdsp:core:em.eventmanager¶

This role grants access to manage everything in the Event Management system.

mdsp:core:em.eventviewer¶

This role grants access to read events and event types in the Event Management system.

Firmware Deployment¶

Definition of roles and permissions for Firmware Deployment.

mdsp:core:frmdpylmnt.fullaccess¶

This role grants all read and write access to Firmware Deployment.

scopes from mdsp:core:dvcinv.readonly

mdsp:core:frmdpylmnt.readonly¶

This role grants read-only access to Firmware Deployment.

Identity Management¶

The Identity Management service serves to manage all authorization-related functionality.

mdsp:core:im.meIamViewer¶

This role grants access to the current user's information, including assigned roles in the tenant's user IAM system.

mdsp:core:im.userIamAdmin¶

This role grants administrative access (read and write) to a tenant's user IAM system.

mdsp:core:im.userIamViewer¶

This role grants 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.

mdsp:core:idlmanager.readuser¶

This role grants read-only access to the Integrated Data Lake API.

IoT File Service¶

Definition of roles and permissions for the IoT File Service.

mdsp:core:iot.filAdmin¶

This role grants read, write and delete access to files.

mdsp:core:iot.filUser¶

This role grants read-only access to files.

IoT Time Series¶

Definition of roles and permissions for the IoT Time Series Services.

mdsp:core:iot.timAdmin¶

This role grants read, write and delete access to time series.

mdsp:core:iot.timUser¶

This role grants read-only access to time series.

IoT Time Series Bulk Service¶

Definition of roles and permissions for the IoT Time Series Bulk Services.

mdsp:core:iot.bulkTimUser¶

This role grants access to read bulk time series data and fetch the job status of bulk ingest jobs.

mdsp:core:iot.bulkTimAdmin¶

This role grants access to submitting bulk ingest jobs, reading bulk time series data and fetching the job status of bulk ingest jobs.

IoT Time Series Aggregates¶

Definition of roles and permissions for IoT Time Series Aggregates API roles.

mdsp:core:iot.tsaUser¶

This role grants 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¶

This role grants read and write access to the MindConnect APIs.

mdsp:core:mindconnect.readonly¶

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

Native MQTT API (Deprecated)¶

Definition of roles and permissions for the Native MQTT API.

mdsp:core:nativemqtt.fullaccess¶

This role grants read and write access to the Native MQTT API.

mdsp:core:nativemqtt.readonly¶

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

MindConnect MQTT API¶

Definition of roles and permissions for the MindConnect MQTT API.

mdsp:core:mindconnectmqtt.fullaccess¶

This role grants read and write access to the MindConnect MQTT API.

mdsp:core:mindconnectmqtt.readonly¶

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

Commanding API¶

Definition of roles and permissions for the Commanding API.

mdsp:core:msg.fullaccess¶

This role grants read and write access to the Commanding APIs.

mdsp:core:msg.readonly¶

This role grants read-only access to the Commanding APIs.

mdsp:core:msg.defaultagent¶

The internal role grants read and acknowledge access to the Commanding APIs for the default agent.

Model Management Service¶

This role grants users access to the Model Management APIs.

mdsp:core:amm.user¶

Notification Service¶

Definition of roles and permissions for the Notification Service.

mdsp:core:nose.mobileappuser¶

This role grants 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¶

Data Contextualization¶

Definition of roles and permissions for the Data Contextualization Service.

mdsp:core:sdi.admin¶

This role grants all (read and write) access and administrative access to Data Contextualization APIs.

mdsp:core:sdi.enduser¶

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

mdsp:core:sdi.semanticuser¶

This role grants access to semantic models and semantic core SDI APIs.

Spectrum Analysis Service¶

Definition of roles and permissions for the Spectrum Analysis service.

mdsp:core:spectrumanalysis.fft.user¶

This is the 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¶

This role grants full administrative access to the respective tenant.

mdsp:core:tm.tenantUser¶

This role grants permissions for standard tenant users.

Usage Transparency Service¶

Definition of roles and permissions for the Usage Transparency Service.

mdsp:core:uts.analyst¶

This role allows tenants to see 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 the 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 the Resource Access Management (RAM) Policy Administration API.

Case Management Service¶

Definition of roles and permissions for the Case Management Service.

mdsp:core:oi.wom.creator¶

This role allows for the creation of cases.

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¶

This role allows viewing of cases.

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