Skip to content

Industrial IoT SDK for Node.js Token Handling

Token Handling in Industrial IoT SDK for Node.js provides access token fetching using service credentials, caching them and re-fetching them on expiry. This provides an easy authorization handling mechanism for developers. Developers can configure user authorization tokens or service credentials. Service credentials can be set up programmatically or using environment variables.

Features

Token handling in the Industrial IoT SDK for Node.js provides the following features:

  • Handling of user tokens
  • Fetching and handling of technical tokens
    • Fetching using app specific service credentials
    • Fetching using tenant specific service credentials
    • Fetching using tenant specific service credentials with subtenant impersonation
  • Token validation using issuer, issuing time, expiry time, token algorithm and token type before making API calls.
  • Reuse of technical tokens until they expire and automatic refresh when the expiry time is less than 5 minutes to reduce traffic.

Technical Token handling mechanism

Token Fetching

The Industrial IoT SDK for Node.js uses the client ID, client secret and other configured parameters when fetching technical tokens to make Industrial IoT API calls. Refer to Required Environment Variables for Fetching Technical Tokens for more information on parameters to be configured.

The Industrial IoT SDK for Node.js uses app service credentials if available and otherwise looks for tenant service credentials.

Token Validation

API calls are only executed by the Industrial IoT SDK if the technical token is valid. The validation uses the issuer, valid issuer, issued at, expiry, token algorithm, and token type in the check.

Token Caching and Re-Fetching

After fetching a valid token, the token is cached in a AppCredentials or TenantCredentials object. Every technical token has validity for 30 minutes. A new token is automatically fetched 5 minutes before the expiry.

Required Environment Variables for Fetching Technical Tokens

The Industrial IoT SDK for Node.js only uses environment variables for fetching tokens if neither user token nor service credentials are set programmatically.

Environment Variables for App Specific Technical Token

Environment Variable Description
MDSP_KEY_STORE_CLIENT_ID Client ID displayed as service credentials in Developer Cockpit or Operator Cockpit
MDSP_KEY_STORE_CLIENT_SECRET Client secret displayed as service credentials in Developer Cockpit or Operator Cockpit
MDSP_OS_VM_APP_NAME The application name as stored by the version management of the Operator Services
MDSP_OS_VM_APP_VERSION The application version as stored by the version management of the Operator Services
MDSP_HOST_TENANT Host Tenant
MDSP_USER_TENANT User Tenant
HOST_BASEDOMAIN(optional) The basedomain url for domains other than '*.mindsphere.io'

Environment Variables for Tenant Specific Technical Token

Environment Variable Description
MINDSPHERE_CLIENT_ID Client ID of the service credentials
MINDSPHERE_CLIENT_SECRET Client secret of the service credentials
MINDSPHERE_TENANT Tenant name
HOST_BASEDOMAIN(optional) The basedomain url only for domains other than '*.mindsphere.io'

Environment Variables for Tenant Specific Technical Tokens with Subtenant Impersonation

Environmental Variable Name Description
MINDSPHERE_CLIENT_ID Client ID of the service credentials
MINDSPHERE_CLIENT_SECRET Client secret of the service credentials
MINDSPHERE_TENANT Tenant name
MINDSPHERE_SUB_TENANT Subtenant name
HOST_BASEDOMAIN(optional) The basedomain url only for domains other than '*.mindsphere.io'

Here are some examples of how you can also pass these variables as parameters for authentication and token handling.

NOTE

hostBasedomain is set to 'mindsphere.io' by default

eu1 domain
let config = new ClientConfig({
    hostEnvironment: 'eu1'
});
let credentials = new AppCredentials({
    appName: 'myapp',
    appVersion: 'v1.0.0',
    keyStoreClientId: 'tenant1-myapp-v1.0.0',
    keyStoreClientSecret: 'abcdefghijklmnopqrstuvw123',
    hostTenant: 'tenant1',
    userTenant: 'tenant1'
});
let assets_client = new AssetsClient(config, credentials);
eu2 domain
let config = new ClientConfig({
    hostEnvironment: 'eu2'
});
let credentials = new AppCredentials({
    appName: 'myapp',
    appVersion: 'v1.0.0',
    keyStoreClientId: 'tenant1-myapp-v1.0.0',
    keyStoreClientSecret: 'abcdefghijklmnopqrstuvw123',
    hostTenant: 'tenant1',
    userTenant: 'tenant1'
});
let assets_client = new AssetsClient(config, credentials);
private cloud domain

For domain "tenant1.abc.basedomain.xyz"

let config = new ClientConfig({
    hostEnvironment: 'abc',
    hostBasedomain: 'basedomain.xyz'
});
let credentials = new AppCredentials({
    appName: 'myapp',
    appVersion: 'v1.0.0',
    keyStoreClientId: 'tenant1-myapp-v1.0.0',
    keyStoreClientSecret: 'abcdefghijklmnopqrstuvw123',
    hostTenant: 'tenant1',
    userTenant: 'tenant1'
});
let assets_client = new AssetsClient(config, credentials);

Last update: February 23, 2024

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