Skip to content

Developing Subtenancy-Aware Applications

With the subtenant functionality, Insights Hub enables customers to easily offer digital services based on platform capabilities to their customers (subtenants). Subtenants can use the services and assets that are assigned to them by the main tenant.

Using Subtenant Impersonation

Subtenant Impersonation via User Tokens

Applications registered at the Gateway receive a JSON Web Token (JWT) with every call. The JWT authenticates the principal calling your service. If the user belongs to a subtenant, the JWT contains the subtenant claim which specifies the subtenant's ID.

Extract this token as described in Calling APIs from Backend and use it for API calls. The token can be decoded using the JWT library of the used framework (Spring, NodeJS, etc.). Example of a decoded token:

{
  "scope": [ "iot.fil.r", ...],
  "cid": "myApp-myTenant",
  "user_name": "john.doe@example.com",
  "iss": "https://myTenant.piam.myRegion.mindsphere/oauth/token",
  "ten": "myTenant",
  ...
  "subtenant" : "myCustomer",
  ...
}

Subtenant Impersonation via Application or Service Credentials

If your application needs to execute background jobs in the context of a subtenant without an active user session, you have two options:

  • Use the Token Management Service to generate a token for accessing the required endpoints and filter the results for data related to the desired subtenant. This is the preferred approach.
  • Use the service credentials of your tenant obtained from the technical support team and create a token with subtenant impersonation using the OAuth Authorization Server. For subtenant impersonation you have to provide the iam-action parameter and subtenant=<subtenant_id> in the body of the API call to https://{tenant_name}.piam.{region}.mindsphere.io/oauth/token:

    POST /oauth/token HTTP/1.1
    Host: <tenantName>.piam.<region>.mindsphere.io
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic <service_credential_id:secret_as_Base64_encoded_string>
    
    grant_type=client_credentials&iam-action=client_credentials.subtenant-impersonation&subtenant=mycustomer
    

    The returned token contains the subtenant claim, which is evaluated by all subtenant-aware services to return an appropriate response:

    {
      "scope": [ ... ]
      "cid": "my_service_credential-client",
      "iss": "https://my_tenant.piam.my_region.mindsphere.io/oauth/token",
      "ten": "my_tenant",
      ...
      "subtenant": "my_customer",
      ...
    }
    

Guidelines

To develop a subtenancy-aware application, you must adhere to the following rules:

  • Every service called by your application must be capable of handling subtenants (subtenancy-aware). A list of subtenancy-aware Industrial IoT services is provided below.
  • Your own services must evaluate the subtenant claim in the call. They must be designed so that data protection of subtenants is ensured in accordance with the intended application behavior.

Attention

Failure to adhere to the above rules may result in information disclosure across subtenants or operations executed in context of unintended subtenants. You are responsible for ensuring that your application respects separation of information, with respect to your intended application functionality.

Subtenancy-Aware Industrial IoT Services

Subtenancy-aware applications may only call Industrial IoT APIs capable of handling subtenancy. Unless stated otherwise, this is complied by endpoints reachable via the following roles:

  • mdsp:core:amm.user
    Role granting access to Model Management Services.
  • mdsp:core:analytics.adb.user
    Role granting access to Anomaly Detection Batch Services.
  • mdsp:core:analytics.user
    Role granting access to Analytics Services.
  • mdsp:core:assetmanagement.reporter
    Role allows users to read assets, asset types, aspect types and files in Asset Management Service.
  • mdsp:core:assetmanagement.subtenantuser
    Role allows users to read asset and aspect types, read or update assets, and read, update or delete files in Asset Management Service.
  • mdsp:core:dataexch.user
    Role granting access to Data Exchange Service.
  • mdsp:core:em.eventviewer
    Role granting access to read events and event types in Event Management Service.
  • mdsp:core:im.meIamViewer
    Role granting access to the current user's information including assigned roles in tenant's user Identity Management Service.
  • mdsp:core:iot.bulkTimUser
    Role granting read access to bulk time series.
  • mdsp:core:iot.filAdmin
    Role granting read, write and delete access to files.
  • mdsp:core:iot.filUser
    Role granting read access to files.
  • mdsp:core:iot.timUser
    Role granting read access to time series.
  • mdsp:core:iot.tsaUser
    Role granting access to time series aggregates.
  • mdsp:core:jobmgr.user
    Role granting access to Job Manager Services.
  • mdsp:core:tsm.read-only
    Role to view time series monitor configuration.

More Industrial IoT services might become subtenancy-aware in the future.


Last update: April 13, 2023

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