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.). An example of a decoded token is as shown below:
{
"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 the following 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 need to provide the
iam-action
parameter andsubtenant=<subtenant_id>
in the body of the API call tohttps://{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.
Related Links¶
Except where otherwise noted, content on this site is licensed under the Development License Agreement.