Industrial IoT SDK V2 for Java - Token Handling¶

Token Handling in Industrial IoT SDK V2 for Java 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 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 Mechanisms¶

Token Fetching¶

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

The Industrial IoT SDK V2 uses app specific service credentials if available and otherwise looks for tenant specific 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 MindsphereCredentials object. Every technical token is valid 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 V2 for Java only uses environment variables for fetching tokens if neither user token nor service credentials are available.

Environment Variables for App Specific Technical Tokens¶

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 Tokens¶

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 for Agentmanagement.

NOTE¶

hostBaseDomain is set to 'mindsphere.io' by default

For eu1 domain¶

RestClientConfig config = RestClientConfig.builder()
    .connectionTimeoutInSeconds(100)
    .hostEnvironment("eu1")
    .build();
MindsphereCredentials credentials = MindsphereCredentials.appCredentialsBuilder()
    .appName("myapp")
    .appVersion("v1.0.0")
    .keyStoreClientId("tenant1-myapp-v1.0.0")
    .keyStoreClientSecret("abcdefghijklmnopqrstuvw123")
    .userTenant("tenant1")
    .hostTenant("tenant1").build();
AssetsClient assets_client = AssetsClient.builder()
    .mindsphereCredentials(credentials)
    .restClientConfig(config)
    .build();

For eu2 domain¶

RestClientConfig config = RestClientConfig.builder()
    .connectionTimeoutInSeconds(100)
    .hostEnvironment("eu2")
    .build();
MindsphereCredentials credentials = MindsphereCredentials.appCredentialsBuilder()
    .appName("myapp")
    .appVersion("v1.0.0")
    .keyStoreClientId("tenant1-myapp-v1.0.0")
    .keyStoreClientSecret("abcdefghijklmnopqrstuvw123")
    .userTenant("tenant1")
    .hostTenant("tenant1").build();
AssetsClient assets_client = AssetsClient.builder()
    .mindsphereCredentials(credentials)
    .restClientConfig(config)
    .build();

For private cloud domain¶

For domain "tenant1.abc.basedomain.xyz"

RestClientConfig config = RestClientConfig.builder()
    .connectionTimeoutInSeconds(100)
    .hostEnvironment("abc")
    .hostBaseDomain("basedomain.xyz")
    .build();
MindsphereCredentials credentials = MindsphereCredentials.appCredentialsBuilder()
    .appName("myapp")
    .appVersion("v1.0.0")
    .keyStoreClientId("tenant1-myapp-v1.0.0")
    .keyStoreClientSecret("abcdefghijklmnopqrstuvw123")
    .userTenant("tenant1")
    .hostTenant("tenant1").build();
AssetsClient assets_client = AssetsClient.builder()
    .mindsphereCredentials(credentials)
    .restClientConfig(config)
    .build();