Skip to content

Self-Hosted Application – Use MindSphere APIs from externally hosted infrastructure

This Getting Started will show you how to use MindSphere APIs from an application hosted outside of the MindSphere platform. This way you can utilize MindSphere services to enrich your own applications.

Use MindSphere Services from a self-hosted application

This Getting Started shows you how to use MindSphere services from a self-hosted application. The Getting Started includes a step by step guide to lead you through the basic setup.

Steps

Before you Begin

You need:

  • MindAccess DevOps Plan - this is your MindSphere account (tenant).
  • Outbound Traffic Upgrade

    Includes a data volume for consuming MindSphere services from outside of the MindSphere platform.

Attention

Because of the nature of this scenario and the increased amount of outbound traffic caused you may be required to increase your Outbound Traffic limit in the future.

Step 1: Create Service Credentials

In order to create new or update existig Service Credentials, you have to generate a service request to Siemens's Technical Support, known as GTAC (Global Technical Access Center), or via the MindSphere Support form accessible from your MindSphere Launchpad using the following template:

Note

Only users with the role mdsp:core:TenantAdmin can order Service Credentials!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Subject: Request for [new| updated] Service Credentials for self-hosted application

Dear MindSphere Support,

Please [create new| update existing] Service Credentials for the tenant with the following parameters:

Tenant name: <your mindsphere tenant>
Account type: <Developer (Dev) or Operator (Ops) depending on your account type>
Service Credentials ID: <name for the Service Credentials set>
Include subtenant impersonation: <yes/no. whether to include the capability to request tokens that are restricted to a specific subtenant>

Note

If you make the request via the MindSphere Support form on your MindSphere Launchpad, you do not need to include either the tenant name or the Soldto. Also remove any special characters from the template above. If you make the request via GTAC, your Soldto as well as the tenant name is identified on the Welcome Letter that the tenant admin received.

After verification, you will receive your Service Credentials in a secure manner.

Attention

The Service Credentials are created per account, if you follow our DevOps Application Lifecycle you will need one set of Service Credentials in your Dev Account and one set of Service Credentials in your Ops Account.

Attention

It is required to use a single set of Service Credentials for one Application Instance only. This will ensure that only one part of your system will be affected if the credentials are compromised.

Step 2: Authentication & Tokens

Call following endpoint: https://<your account id>.piam.eu1.mindsphere.io/oauth/token with following header and body ("grant_type=client_credentials"):

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

To get the token retrieve the content of access_token from the 200 response.

Info

The token issued is valid for 30 minutes and must be requested again after the 30 minutes have expired.

Step 3: Use Services via MindSphere APIs

Create another request to an API endpoint with following header keys:

1
2
Authorization: Bearer <token>
Content-Type: application/x-www-form-urlencoded

Example:

This will request a list of all users of your account through the Identity Management API.

1
2
3
GET /api/identitymanagement/v3/Users HTTP/1.1
Host: gateway.eu1.mindsphere.io
Authorization: Bearer <token>

Summary

In this Getting Started you enabled a self-hosted application to use services via MindSphere APIs.

To do so you

  1. Requested Service Credentials,
  2. Requested a token and
  3. Use the token to issue a request to the Identity Management API.

Success

You are now prepared to use services via MindSphere APIs in your applications!

Example (Python3)

We're going to use Python3 and the requests_oauthlib to connect to the MindSphere IAM API.

This example will get a token from the IAM service and will then use it to fetch all users and print all users with the role mdsp:core:StandardUser.

Attention

To complete this example, valid Service Credentials are required.

Info

You will need to install the dependencies via

1
pip install requests requests_oauthlib

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

# add your account name here
refresh_url = 'https://<your tenant name>.piam.eu1.mindsphere.io/oauth/token'

# enter your service user credentials here
credentials = {
    'client_id': '<ServiceCredentialID>',
    'client_secret': r'<ServiceCredentialSecret>',
}

# create a backend client and retrieve a token
oauthclient = BackendApplicationClient(client_id=credentials['client_id'])
oauthsession = OAuth2Session(client=oauthclient)
token = oauthsession.fetch_token(token_url=refresh_url, client_id=credentials['client_id'],
        client_secret=credentials['client_secret'])

# create session with token
client = OAuth2Session(client_id=credentials['client_id'], token=token)

# get a list of all users of your tenant
r = client.get('https://gateway.eu1.mindsphere.io/api/im/v3/Users')

# List users with mdsp:core:StandardUser role
users = r.json()['resources']
for user in users:
    roles = user['groups']
    for role in roles:
        if role['display'] == 'mdsp:core:StandardUser':
            print(user['userName'])

Any questions left?

Ask the community


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