Token Management Service¶

Idea¶

Use the Token Management Service to grant your application access to data of tenants, who use the application. This is relevant if your application frequently performs data processing on multiple tenants without user interaction, e.g. pre-calculating KPIs for a dashboard. If an application has access to the Token Management Service, it can request tokens to access IoT data of other tenants. The access to the Token Management Service must be explicitly granted for each version of an application.

Access¶

For accessing the Token Management Service, your application must explicitly be granted access using the Developer Cockpit during development and the Operator Cockpit for productive use.

Basics¶

Whenever IoT data is accessed, a valid token is required to get access permission. If an application requires to access IoT data without human interaction, it needs a technical token. The Token Management Service generates these tokens. In order to issue a token, the application sends a request to the Token Management Service, which contains its own credentials and specifies which data it needs to access. If the application has permission to access this data, the Token Management Service returns a valid token, which grants the requested access permission.

Architecture¶

The figure below shows the basic interactions between Token Management Service and the Developer Cockpit, the Operator Cockpit, and an application.

When application developers upload their applications for testing to the Developer Cockpit, it is not possible to access data on other tenants. However, the communication between the application and the Token Management Service can be tested. [1]

An application requests a token from the Token Management API, if it needs to access IoT data. In its request, it provides its application credentials as well as the location it wants to access. If the application has permission to access this data, the Token Management Service returns a valid token for this action. [2]

The application uses the token in order to access the requested data. [3]

When an application is registered in the Operator Cockpit, it can be assigned read/write, limited, Data Contextualization read/write or custom access. Read/Write access grants full access to all available Insights Hub APIs. Limited access allows the application to manage assets and files and create events, but not to write time series data. Data Contextualization read/write access grants permission for only Data Contextualization APIs. Custom access grants access to the user selected Insights Hub APIs. If a customer purchases an application, they must confirm that the application may access their data. [4]

Application Credentials¶

Applications must send their application credentials to the Token Management Service in order to request a token. Application credentials consist of a client ID and a client secret. They are created after uploading an application to the Developer Cockpit or Operator Cockpit and must be provided as environment variables of the application.
Access for an application must be issued manually in the Authorization Management in order to create application credentials. For Cloud Foundry applications, the Operator Cockpit automatically provides the application credentials as environment variables of the application.

Application credentials are version specific and must be updated, if a new version of an application is uploaded. This also means, that the application credentials issued in the Developer Cockpit are not valid anymore, once the application has been transferred to the operator tenant.

In order to revoke the credentials, de-register the application.

Features¶

Token Management Service exposes its API for the following task:

• Issuing tokens in the name of user tenants for a specific application version.
• Providing a list of user tenants authorized to access an application with pagination support.

Limitations¶

• This service does not issue more than 5 access tokens per request.

Example Scenario¶

An operator wants to offer an application on the Insights Hub Store, which automatically pre-calculates KPIs and schedules data processing for tenants who buy the application. They register their application to use the Token Management Service in order to get access to the tenants' data without requiring user action.