Skip to content

Agent Management Service

Idea

The Agent Management Service is used to onboard, offboard, update and delete agents. It provides connectivity functions to enable communication with the MindSphere Platform.

The Agent Management Service is typically used by application developers or machine builders (OEMs). Agent Management API provides agent provisioning and configuration functionality.

Access

For accessing this service you need to have the respective roles listed in Agent Management roles and scopes.

Users can interact only with agents onboarded within their tenant.

Basics

Agents

An agent is the primary actor within the MindSphere environment. Every action is directly or indirectly related with an agent. As an example an agent uploads data, retrieves its events, changes its configuration etc. The very first step to use MindSphere APIs is to create an agent.

When the agent is created, an initial access token is generated (IAT). This IAT is a JSON Web Token (JWT) that holds various information about the agent. This token needs to be downloaded to the agent and provided during the onboarding step.

Agents need to "onboard" to MindSphere prior to using any services. Onboarding simply means registering an agent, so that MindSphere authorizes and authenticates the agent. During this onboarding step, the agent needs to provide the IAT to MindSphere to validate its identity. MindSphere validates the agent by checking the signature of the IAT.

The agent communicates its credentials based on one of the following security profiles:

  • SHARED_SECRET
  • RSA_3072.

SHARED_SECRET Security Profile

For agents with this security profile, MindSphere generates a secret for the agent and stores it in its persistent storage. This secret is returned to the agent in the onboarding response during the onboarding step.

RSA_3072 Security Profile

Agents with this security profile first send their public key to MindSphere when onboarding. MindSphere stores the public key in its persistent storage.

If onboarding is successful, MindSphere responds with a Registration Access Token (RAT), which is used to renew registration to update credentials when the agent's credentials are expired.

Access Token

After onboarding, agents need to acquire an access token. Acquiring an access token involves creating a self signed JWT, and sending this self signed JWT to MindSphere. Upon receiving the access token request MindSphere validates the signature of the JWT with the stored credential of the agent. Based on the security profile either shared secret or public key will be used to validate the agent's self signed JWT.

If the self signed JWT is valid, MindSphere responds with an access token. An access token is a time restricted JWT token that holds various information and the agent's scopes (access rights).

Agents can use the access token to consume the MindSphere services until expiration. After expiration, the agent needs to acquire a new access token to continue using MindSphere services.

Data Source Configuration

Data Source configuration involves configuring Data Points for an agent. This configuration is mandatory for MindSphere to interpret uploaded data. Without this configuration MindSphere does not understand the data an agent uploads. When the agent is first created, its Data Source configuration is empty. This configuration must be updated via the update endpoint.(/agents/{id}/dataSourceConfiguration).

A Data Point represents measurements done by either a sensor or a device. For example, "Temperature" and "Torque" can be Data Points for a Data Source configuration.

Boarding

The Boarding API provides the following functionality:

  • retrieve onboarding configuration
  • get boarding status of an agent
  • offboard and agent.

The boarding configuration consists of onboarding data, the Initial Access Token (IAT) and a registration URL. The boarding configuration is used by the agent to onboard to MindSphere.

MindSphere users can retrieve an agent's boarding status. The boarding status contains three different statuses, namely NOT_ONBOARDED, ONBOARDED and ONBOARDING. They are defined as follows:

  • NOT_ONBOARDED: Agent is not authorized to exchange data with MindSphere.
  • ONBOARDING: Onboarding configuration for the agent is ready and MindSphere is waiting for the agent to trigger the onboarding process.
  • ONBOARDED: Agent is authorized to exchange data with MindSphere.

The Boarding API also provides an interface to offboard the agent. When the agent is offboarded, a brand-new IAT is generated by MindSphere.

Using this new IAT the agent can be onboarded again.

Register

The registration process takes place in accordance with the OAuth 2.0 Authorization protocol (RFC 6749). The boarding configuration retrieved from the /agents/{id}/boarding/configuration is required to register (onboard) the agent to MindSphere.

In order to be registered, the agent needs to send a request with the Initial Access Token (IAT) from its boarding configuration. The structure of a request varies slightly depending on the Agent's Security Profile. The IAT Key is valid for one week (7 days).

The /register endpoint returns a Registration Access Token (RAT), which is valid indefinitely and required for key rotation.

Agent credentials have to be updated every 7 days, regardless of the security profile. In the update process the agent has to provide the RAT instead of IAT to update its credentials, otherwise the process is the same as for initial registration.

After the registration is completed for an agent, its boarding status is set to ONBOARDED. The key rotation process is performed via the /register/{id} endpoint, and enables agents to change their key (symmetric or asymmetric). The RAT is required in the request.

Token

Each registered (onboarded) agent is required to get an access token in order to use any of the services offered by MindSphere. MindSphere grants access tokens to onboarded (registered) agents.

Note

Token generation and grants comply to the rules stated by Oauth2.0 authorization framework.

In order to get an access token, the agent needs to create a Json Web Token (JWT) which holds information such as agent ID, tenant name etc., and sign it with its shared_secret/private_key based on its security profile.

Note

An access token is valid for one hour.

The /OAuth/token_key endpoint which returns the public key of the server, is provided to the agents in order to enable them to verify any access token granted by MindSphere.

Features

  • Create, edit, remove agents
  • Onboard and offboard agents
  • Acquire agent onboarding configuration
  • Define asset - agent relations
  • Define an agent's Data Sources
  • Acquire access tokens to consume Connectivity Services

Example Scenario

The application developer of a brewery wants to programmatically on- and offboard MindConnect devices connected to the production lines.

The developer uses the Agent Management Service to register and offboard the desired devices.

Any questions left?

Ask the community


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