Accessing Industrial IoT or external APIs during Local Development¶
This section describes two options to access Industrial IoT APIs during local development and demonstrates how to configure the API development environment Postman for this purpose.
Applications must send their app credentials to the Token Management Service in order to request a token. For more information, refer Application credentials.
Accessing Industrial IoT APIs using Application credentials¶
Application credentials are valid for 365 days. They can be used to create access tokens in Insights Hub without having to log into your tenant and capture session cookies. However, access tokens generated using application credentials have admin scope, which means it is not suitable for testing applications with different user types. For more information, refer Token Management Service.
Prerequisites¶
- Insights Hub user account on a developer environment.
- The admin role for your Insights Hub environment
mdsp:core:TenantAdmin
Create Application credentials¶
- Create your application credentials as described here.
-
Encode the combination of the application credentials in Base64 format.
-
Combine credentials ID and password as shown below.
{client_id}:{client_secret}
-
Encode the resulting string in Base64 format.
-
Generate the Access Token¶
-
Send an HTTP request to the Technical Token Manager Service:
POST /api/technicaltokenmanager/v3/oauth/token HTTP/1.1 Host: gateway.{region}.{mindsphere.domain} X-SPACE-AUTH-KEY: Bearer {ServiceCredentialID: ServiceCredentialSecret as Base64 encoded string} Content-Type: application/json { "grant_type": "client_credentials", "appName": "application name", "appVersion": "version", "hostTenant": "TenantName", "userTenant": "Tenantname" }
-
Extract the access token from the
access_token
field in the response and send it as Bearer token in the Authorization header of HTTP requests.
For more information refer Token Management Service.
Postman Example¶
The below postman collection should be imported in the postman. After successful import, you can replace the values in body, pre-request scripts, etc.
Postman
{
"info": {
"_postman_id": "8b0ad76a-9f63-4946-9597-2443252645a0",
"name": "Application Credential Token Generation with Example",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Generate App Credential Bearer Token",
"event": [
{
"listen": "prerequest",
"script": {
"id": "7ed5b9aa-8e45-4d05-b1b4-6324300e6e8a",
"exec": [
"var id = '{Application Credential ID}';\r",
"var secret = '{ Application Credential Secret}';\r",
"pm.environment.set(\"base64token\", btoa(id + ':' + secret));"
],
"type": "text/javascript"
}
},
{
"listen": "test",
"script": {
"id": "93b90d1f-2f5e-4487-a3f8-caac49b55cec",
"exec": [
"var jsonData = pm.response.json();\r",
"pm.globals.set(\"BearerToken\", 'Bearer ' + jsonData.access_token);"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "X-SPACE-AUTH-KEY",
"value": "Bearer {{ base64token }}",
"type": "text"
},
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"body": {
"mode": "raw",
"raw": "{\r\n\t\"grant_type\": \"client_credentials\",\r\n\t\"appName\":\t\"{Application Name}\",\r\n\t\"appVersion\": \"{Application Version }\",\r\n\t\"hostTenant\": \"{Host Tenant Name}\",\r\n\t\"userTenant\": \"{User Tenant Name}\"\r\n} "
},
"url": {
"raw": "https://gateway.eu1.mindsphere.io/api/technicaltokenmanager/v3/oauth/token",
"protocol": "https",
"host": [
"gateway",
"eu1",
"mindsphere",
"io"
],
"path": [
"api",
"technicaltokenmanager",
"v3",
"oauth",
"token"
]
}
},
"response": []
},
{
"name": "Get Tenant Users ( IAM )",
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "{{ BearerToken }}",
"type": "text"
}
],
"url": {
"raw": "https://gateway.eu1-int.mindsphere.io/api/im/v3/Users",
"protocol": "https",
"host": [
"gateway",
"eu1-int",
"mindsphere",
"io"
],
"path": [
"api",
"im",
"v3",
"Users"
]
},
"description": "This API lists all the users of specific tenant"
},
"response": []
}
],
"protocolProfileBehavior": {}
}
Accessing Industrial IoT APIs using Session Cookies¶
Session cookies are only valid for up to 12 hours and expire after 30 minutes of inactivity. However, by assigning your user specific application roles, it is possible to test your application's behaviour for users other than admin.
Prerequisites¶
- Insights Hub user account on a developer environment.
- A Insights Hub developer role, either
mdsp:core:Developer
ormdsp:core:DeveloperAdmin
. - A simple application to be registered at Insights Hub.
Deploy and Register the Application¶
- Deploy the application to Cloud Foundry and configure it in the "Developer Cockpit" as described here.
-
Configure the application roles and scopes.
Info
Make sure to add the Core roles required to access the respective Industrial IoT APIs.
-
Register the application.
- Assign an application role to your user.
Generate User Credentials¶
- Log into the application using a web browser.
- Open the developer tools of your browser (press F12).
- Navigate into the cookies section.
Chrome: Application > Cookies
Firefox: Storage > Cookies. -
Copy the
SESSION
andXSRF-TOKEN
cookies.Info
These credentials will be valid for up to 12 hours and expire after 30 minutes of inactivity. Avoid timeouts by implementing a ping functionality into your application.
cURL Example¶
The following code block shows an example script for setting the user credentials in a cURL command - placeholders are indicated using angular brackets <>
.
#!/bin/bash
TOKEN="<token-copied-from-browser>"
SESSION="<session-cookie-copied-from-browser>"
curl -vv \
-G \
--cookie "SESSION=${SESSION}; X-XSRF-TOKEN=${TOKEN}" \
--data 'filter=dir*' \
-X GET \
https://<tenantId>-<appId>-<tenantId>.<regionId>.mindsphere.io/api/dataexchange/v3/directories/_PRIVATE_ROOT_ID
Postman Example¶
- Enter the HTTP request to be executed. Follow the schema below:
https://{appName}.{region}.{mindsphere-domain}/{MindSphere-API}
https://my-app.eu1.mindsphere.io/api/iottimeseries/v3/assets
2.Click the "Cookies" link under the "Send" button.
3.Enter the application domain, e.g. my-tenant.eu1.mindsphere.io
, and click "Add".
4.Add two cookies:
Key | Value |
---|---|
Cookie | SESSION=Y2YyYWJiM2YtYWMzZS00NjQyLWI1NTUtMGNhYWMxYzczOTJh; XSRF-TOKEN=d06e1798-51f1-4a1d-9484-46b28d23e11c; path=/; domain=.my-app.eu1.mindsphere.io; |
X-XSRF-TOKEN | d06e1798-51f1-4a1d-9484-46b28d23e11c |
5.Send the HTTP request.
Accessing Industrial IoT /Token APIs¶
Prerequisites¶
The following are the prerequisites to use the Advanced Token Exchange (ATE) functionality (/token API):
- the application that calls the 3rd party API must be enabled with custom application credentials
- the application must be configured with UI to API mapping in "Developer Cockpit"
Procedure¶
After the above prerequisites are met, the first step is to get a token that enables to call the Advanced Token Exchange. This section describes the procedure to get a token.
- Send an HTTP request to the Technical Token Manager service to call ATE /token endpoint:
To call the Technical Token Manager, an application credential issued on the developer or operator tenant is required. The token fetched using this endpoint will have the sufficient permissions for performing Advance Token Exchange. The upcoming JWT token should have the rolemdsp:core:ATE3rdPartyTechUser
. This can be fetched as below. Encode the following combination of Client ID and Client Secret using Base64<client_id>
:<client_secret>
Build the <X-SPACE-AUTH-KEY>
using the word Basic, followed by a space and the encoded result. For example,
X-SPACE-AUTH-KEY : Basic <ZGlvcDEtaGVybWlvbmUtaGVybWlvbmU6c2RqaGZhc2RqaGZqYXNkaGZqa2FzZGhmams=>
POST /api/technicaltokenmanager/v3/oauth/token HTTP/1.1
Host: gateway.{region}.{mindsphere.domain}
X-SPACE-AUTH-KEY: Basic <ZGlvcDEtaGVybWlvbmUtaGVybWlvbmU6c2RqaGZhc2RqaGZqYXNkaGZqa2FzZGhmams=>
Content-Type: application/json
{
"appName": "application_x",
"appVersion": "1.0.0",
"hostTenant": "host_tenant",
"userTenant": "core"
}
2.In order to access the ATE /token
endpoint, extract the access token from the access_token
field in the response from the above Technical Token Manager request and send it as Bearer token in the Authorization header of HTTP requests. The subject_token
is provided through the technical token.
POST /api/ate/v3/token HTTP/1.1
Host: gateway.{region}.{mindsphere.domain}
Authorization: Bearer <access_token>
Content-Type: application/json
{
"subject_token": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbmZybGFiaC5waWFtLmV1MS1pbnQubWluZHNwaGVyZS5pby90b2tlbl9
rZXlzIiwia2lkIjoia2V5LWlkLTYiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIwNTE4ZWYzZTNlZmY0ZWQ4YjdlMjlhMjEyMWJkODQ2MCIsInN1YiI6I
m5mcmxhYmgtcGVyZmluLXYxIiwic2NvcGUiOlsicGVyZmluLmMiLCJtZHNwOmNvcmU6QVRFM3JkUGFydHlUZWNoVXNlciJdLCJjbGllbnRfaWQiOi
JuZnJsYWJoLXBlcmZpbi12MSIsImNpZCI6Im5mcmxhYmgtcGVyZmluLXYxIiwiYXpwIjoibmZybGFiaC1wZXJmaW4tdjEiLCJncmFudF90eXBlIjo
iY2xpZW50X2NyZWRlbnRpYWxzIiwicmV2X3NpZyI6IjliNTI0ZjE0IiwiaWF0IjoxNjEyMTcyNzYzLCJleHAiOjE2MTIxNzQ1NjMsImlzcyI6Imh0
dHBzOi8vbmZybGFiaC5waWFtLmV1MS1pbnQubWluZHNwaGVyZS5pby9vYXV0aC90b2tlbiIsInppZCI6Im5mcmxhYmgiLCJhdWQiOlsibmZybGFia
C1wZXJmaW4tdjEiLCJwZXJmaW4iXSwidGVuIjoibmZybGFiaCIsInNjaGVtYXMiOlsidXJuOnNpZW1lbnM6bWluZHNwaGVyZTppYW06djEiXSwiY2
F0IjoiY2xpZW50LXRva2VuOnYxIn0.Ndo14t-XENpEKtfGJug2nNcHUiDMiPkI29ePazpbFfJO8wXs6sda00No3XhU42Ng8zzF9QM_kovVm1dfuR9
QxLoBYhU6pVtUKV6trOZpCYGgXVG3OYJhORJBzuHnQ4uC5SRDAlVW1AUQ5_wjqRUFDHoe6433UiKSl0xnZjtGFHBphtV1Prfn0m9VXrNsF_Su_QEe
YaTIWi3x6vrfptsHjoK0FYSuhGl9VTMINXixAN9iiCsZWeyK12D-z7TppSiXIQB-TfcKlLfcV_66tCMSqRXTtC4nkM8f5-rkHdeeCcUCBhdfaxqlA
llNenZbx-xIlgZM1usQqLQx1ggNBuV6HA",
"subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"resource": "https://gateway.eu1.mindsphere.io/api/<app_name>_<tenant_name>/<version>"
}
With the authorization Token received in response, it is possible to access the endpoints of the API application hosted on another tenant. The API cannot access any Industrial IoT APIs.
Note
As a UI application developer, please note that you should not handover your UI application to the same tenant that is hosting the API that you externally depend on. This use case is currently not supported and your UI will not be able to reach the API.
Info
Token issued by ATE will expire in 30 minutes. Therefore, the consumer service is responsible for caching the token issued by the ATE. The token should be refreshed 5 minutes before token expires.
Except where otherwise noted, content on this site is licensed under the Development License Agreement.