Skip to content

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

In this section you will learn how to use MindSphere APIs from an application hosted outside of MindSphere platform (self-hosted). This way you can utilize MindSphere services to enrich your own applications.

This Getting Started includes a step by step guide, which leads you through the basic setup.

Prerequisites

For this Getting Started you need:

  • MindAccess DevOps Plan - this is your MindSphere account (tenant)
  • mdsp:core:TenantAdmin role
  • Outbound Traffic Upgrade - this 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 existing service credentials, you have to make a service request. Contact the GTAC (Global Technical Access Center) or fill out the MindSphere Support form accessible from your MindSphere Launchpad using the following template:

 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: {yourTenant}
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 the tenant name and the Soldto. Also, remove any special characters from the template above.

If you make the request via GTAC, find your Soldto and the tenant name are on the Welcome Letter that the tenant admin has received.

After verification, you receive your requested service credentials in a secure manner.

Attention

The service credentials are created per account. If you follow our DevOps Application Lifecycle you 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

This section shows you how to generate a token using service credentials.

Call following endpoint: https://{yourTenant}.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: {yourTenant}.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 success response.

The following example shows how to request an access_token using curl and jq:

1
2
3
4
5
curl -s \
  -H "Authorization: Basic $(echo -n {ServiceCredentialID}:{ServiceCredentialSecret} | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -X POST https://{yourTenant}.piam.eu1.mindsphere.io/oauth/token | jq -r .access_token

Info

The issued token is valid for 30 minutes. You have to be request a new token after the 30 minutes have expired.

Step 3: Use Services via MindSphere APIs

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

1
2
Authorization: Bearer {token}
Content-Type: application/x-www-form-urlencoded

Example:

This example shows how to request a list of all users of your account from the Identity Management API.

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

Info

You will only receive a success response, if you pass a valid token to Bearer {token}. In the same way you can use all MindpShere APIs.

Summary

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

  1. You requested service credentials.
  2. You requested a token.
  3. You used 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 use Python3 and the requests_oauthlib to connect to the MindSphere IAM API.

In this example you get a token from the IAM service and use it to fetch all users and print those with the role mdsp:core:StandardUser.

Attention

To complete this example, valid Service Credentials are required.

Info

You need to install the dependencies via the following command:

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://{yourTenant}.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.