Skip to content

Using Subtenancy – Creating, using and developing applications for subtenants

Introduction

With the Subtenant functionality, MindSphere enables customers (Main Tenants) to easily bring their customers (Subtenants) to the platform and offer digital services to them based on platform capabilities. Subtenants reside inside the Main Tenant and can use the services and assets that are assigned to them by the Main Tenant.

Imagine a machine builder selling his machines to various customers. The machine builder gives guarantees for the machines and also supports his customers with setting up the machine and doing performance optimizations. Most of these services that are handled today mainly by support personnel being onsite at the customer, can be digitized by using MindSphere services. The machine builder becomes a MindSphere customer and his customers become Subtenants. Based on the digital representation of his machines, the machine builder can offer digital services like online support, predictive maintenance and remote performance optimization. He's able to see the collected data for his machines while they're residing at the customers plant. He can offer custom applications to his customers for doing visualizations, simple analytics or fleet management.

This "How To" describes in detail:

  • A new role mdsp:core:SubTenantUser is added per default to the tenant.
    This role needs to be assigned to every user of a subtenant to give access rights to core applications.
  • You'll be able to manage Subtenants using the Tenant Management Services (e.g., create, list, delete).
  • Assignments of users to Subtenants can be done using Identity Management.
    The subtenant assignment of a user restricts the data accessible to the user to the data assigned to the subtenant.

Both the assignment of the role mdsp:core:SubTenantUser and a concrete Subtenant is necessary, to allow the user to login and access the data restricted to the Subtenant.

Subtenancy for developer tenants

Subtenants and respective users can be created in developer tenants for testing purposes during application development.

Using subtenancy

Step 1: Create your provider information

Log into your tenant (role tenant administrator required) and open the User Management from the MindSphere Launchpad.

In the User Management, click on the tile 'Provider' on the left-hand side. This will initialize your provider information.

This feature gives you the possibility to insert tenant-specific legal information (a collection of links) to MindSphere. This process is referred to as legal info white-labeling (= legal info branding). It ensures that legal requirements of app operators and consumer tenants can be met by e.g., link to the localized imprint that platform users are facing. The links are displayed in all apps (in their MindSphere OS Bar), when clicking on the 'MindSphere' writing in the upper right corner.

The legal/branding information is sorted and ordered by languages and regions. There is always a global region with a default language which is set to English. More regions can be defined and country codes can be added to them. One country can always belong to one region only, but a region can have many countries. Different languages can set to a region but languages can be reused in different regions. A language can have many legal links which can be set as name-value pairs. A legal link can have different types such as www, phone and mail.

User Management Provider Information

These legal links will be displayed in the UI depending on the tenant's country and the language settings of the web browser. The legal information is visible between two different tenants and the region settings of one tenant described above will ensure that the right information will be shown depending on the other tenant's country information.

For more information, see the User Management documentation

Step 2: Request service credentials if necessary

To access the Subtenant management functionality via API, service credentials may be used.

In case you do not yet have service credentials, see the following description how to create service credentials.

If you don't want to use API calls to create Subtenants and assign respective users, you might as well use the User Management UI. Please see the User Management documentation (currently only available in german) on how to create and manage Subtenants.

Step 3: Use the Tenant Management API and service credentials to create a Subtenant

With the service credentials, you can request a token and call the Tenant Management API to create a new Subtenant.

Example:

This will create a new subtenant mycustomer, via Tenant Management API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST /api/tenantmanagement/v4/subtenants HTTP/1.1
Host: gateway.eu1.mindsphere.io
Content-Type: application/json
Accept: application/hal+json
Authorization: Bearer <token>
{
  "id": "mycustomer",
  "displayName": "MyCustomer Inc.",
  "description": "MyCustomer Incorporated"
}

Step 4: With this service credentials, create a new user with Subtenant type and assign to Subtenant

Use the service credentials to call the Identity Management API to create a new subtenant user.

Example:

This will create a new subtenant user in the subtenant \<mycustomer>, via Identity Management API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
POST /api/identitymanagement/v3/Users HTTP/1.1
Host: gateway.eu1.mindsphere.io
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
{
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "userName": "john.doe@example.com",
  "subtenants" : [
    {
      "id": "mycustomer"
    }
  ]
}

Info

Currently, an already existing user cannot be changed to a Subtenant user and vice versa. To achieve the same effect, please delete the user and create a new one.

Step 5: Assign the Subtenant role to the user

Log into your tenant as tenant administrator and open the User Management from the MindSphere Launchpad.

Add the mdsp:core:SubTenantUser role to the newly created Subtenant user.

Attention

You need to ensure that only the core role mdsp:core:SubTenantUser is assigned to a Subtenant user. Other core roles are not supported for Subtenant users and will lead to undefined behavior or access to more data than the Subtenant user is entitled to.

Step 6: Initial login as Subtenant user

Log into your tenant with your new Subtenant user. You'll only see the subset of MindSphere core applications a Subtenant user is entitled to see, such as Asset Manager and Fleet Manager. After opening the asset manager, you will see that the data shown to the user is restricted to the Subtenant mycustomer. Currently, no assets are shown for this Subtenant.

Asset Manager For Subtenant MyCustomer

Step 7: Assign an asset to the Subtenant via Asset Manager UI

Log into your tenant with a user being tenant administrator and open the Asset Manager from the MindSphere Launchpad.

You will see assets of type 'core.basicsubtenant' for all Subtenants in the tenant. All assets below these types of assets will be visible to Subtenant users of the respective Subtenant.

You can use the normal create asset and move asset functionalities of Asset Manager to configure which subtenants can access which assets. Assets that are not inside an asset of type 'core.basicsubtenant' will be only visible to the main tenant.

For example below, you see that an asset MyCustomersAsset exists which is contained in the Subtenant asset named mycustomer.

Asset Manager -- Asset Assigned to Subtenant MyCustomer

For further information see Asset Manager documentation

Step 8: Login as Subtenant user to view the assigned Asset

Log into your tenant as the subtenant user of the tenant and open the Asset Manager from the MindSphere Launchpad.

You will now see the assets the tenant admin has previously assigned to you, for example MyCustomersAsset.

As a Subtenant User you're allowed to create your own Asset hierarchy and move the Assets assigned to you within this hierarchy. You may also edit limited meta information of the Asset.

Step 9: Delete Subtenant

After developing your application and conducting tests with subtenant users, you might delete the subtenants you created.

Use the service credentials to call the Tenant Management API to delete an existing subtenant.

1
2
3
4
5
DELETE /api/tenantmanagement/v4/subtenants/{id} HTTP/1.1
Host: gateway.eu1.mindsphere.io
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

Attention

If you delete a subtenant, all assigned users will also be deleted automatically to prevent inconsistent states for users. If you want to keep specific users assign them to your tenant or another subtenant before deleting the subtenant.

Please also be aware that after deleting a Subtenant from the Tenant Management that the associated Subtenant Root Asset (core.basicsubtenant) will still exist. This is by intention to avoid confusions when automatically deleting the Root Asset and moving Subtenant Assets to the main tenant hierarchy. The tenant administrator need to decide what happens to the Subtenant Assets. He might move the assets to another location in the asset hierarchy or delete them. As soon as there are no children below the Subtenant Root Asset, the Tenant Administrator can also remove the root asset via the Asset Management API using the DELETE endpoint for assets.

Developing applications that use subtenancy

To develop a Subtenant-enabled application, you must adhere to the following rules:

  • Each external service called by your services must be capable of handling Subtenants (Subtenant aware). The list of Subtenant-aware MindSphere services is provided below.
  • For each of your own services, you must interpret the Subtenant information within the call and perform operations and return information in a way so that your application becomes Subtenant aware.

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.

Services that are subtenant aware

For MindSphere services, the endpoints reachable via the following roles are currently capable of handling subtenancy. Unless stated otherwise, only calling APIs using the following MindSphere roles is allowed for Subtenant applications:

  • 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: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.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:tsm.read-only
    Role to view time series monitor configuration.

Over time additional MindSphere services might become Subtenant-aware.

Making your own service Subtenant aware

Interactive users

When developing an application that is hosted behind MindSphere Gateway, each call to your services will include a JWT token authenticating the principal calling your service. If the user belongs to a Subtenant, then the id of the Subtenant that the current user belongs to can be found in the 'subtenant' claim of the JWT token. If the user belongs to the main tenant, the token will not contain the 'subtenant' claim. For an example, how to extract a token, please see Token extraction. This token can be decoded, for example with the JWT library of the framework you are using (Spring, NodeJS, etc).

Example of decoded token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "scope": [ "iot.fil.r", ...],
  "cid": "myapp-mytenant",
  "user_name": "john.doe@example.com",
  "iss": "https://mytenant.piam.eu1.mindsphere/oauth/token",
  "ten": "mytenant",
  ...
  "subtenant" : "mycustomer",
  ...
}

It is the responsibility of the application/application developer to evaluate the subtenant claim and to design the application so that data protection of Subtenants is ensured in accordance with the intended application behavior.

Background activities

If your application needs to execute background jobs in the context of a Subtenant, it is possible to create or upgrade service credentials with the 'subtenant impersonation' capability. Please follow the manual how to create or upgrade service credentials

Service credentials with subtenant impersonation have the additional functionality to request tokens which are restricted to a specific Subtenant.

Call following endpoint https://<your tenant name>.piam.eu1.mindsphere.io/oauth/token with following header and body:

1
2
3
4
5
6
POST /oauth/token HTTP/1.1
Host: <your tenant name>.piam.eu1.mindsphere.io
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <ServiceCredentialID:ServiceCredentialSecret as Base64 encoded string>

grant_type=client_credentials&iam-action=client_credentials.subtenant-impersonation&subtenant=mycustomer

The returned token will include the additional claim 'subtenant'. All Subtenant-enabled services will evaluate this claim and return an appropriate response.

Example token returned:

1
2
3
4
5
6
7
8
9
{
  "scope": [ ... ]
  "cid": "myservicecredential-client",
  "iss": "https://mytenant.piam.eu1.mindsphere.io/oauth/token",
  "ten": "mytenant",
  ...
  "subtenant": "mycustomer",
  ...
}

Attention

When the subtenant impersonation capability is used, the same restrictions apply as for interactive user tokens above. In particular, it is only allowed to call subtenant-enabled MindSphere service endpoints that are reachable by the roles listed above. Other MindSphere services may not be called with a subtenant impersonated token.

Subtenancy for operator tenants

Subtenant support for operator tenants is available in the same way as for developer tenants, for all operator tenants with service credentials for their tenant.

Any questions left?

Ask the community


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