Skip to content

Agent Management

Idea

Agent Management is a service made available via its respective MindSphere APIs. This service is used to onboard, offboard, update and delete agents.

Agent Management API 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

Users can interact only with agents onboarded within their tenant. For full access to the service, a user needs the developer or administrator role. A standard user can list agents, view their data source configuration and get the boarding status.

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 needs to be provided during the onboarding step.

Agent needs "onboarded" to MindSphere prior using any services. Onboarding simply means registering an agent, so that MindSphere authorizes and authenticates the agent. During this "onboarding" step, 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 persistant storage. This secret returned to the agent in the onboarding response during the onboarding step.

RSA_3072 Security Profile

When onboarding, agent first sends its public key to MindSphere, MindSphere stores the public key in its persistant storage.

If onboarding is successfull MindSphere responds with a Registration Access Token (RAT), Which is used to renew registration to update credentials when agents credentials expired.

Access Token

After onboarding, agent needs 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 agent's self signed JWT.

If self signed JWT is valid, MindSphere responds with an access token. Access token is a time restricted jwt token that holds various information and agents scopes (access rights).

Agent can use the access token to consume the MindSphere services, till expiration. If expiration occurs agent needs to acquire a new access token to continue using MindSphere services.

DataSource Configuration

Data source configuration involves configuring data points per agent. This configuration is mandatory for Mindsphere to interpret uploaded data. Without this configuration Mindsphere has no way to guess what data agent is uploading. When the agent is first created; data source configuration is empty. This configuration later must be updated via update endpoint (/agents/{id}/dataSourceConfiguration)

DataPoint, 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

Boarding api provides following functionality

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

Boarding configuration consists of onboarding data, initial access token (IAT) and registration URL. Boarding configuration is required to be used by the agent to onboard to MindSphere.

MindSphere user can retrieve the agent boarding status. Boarding status contains three different status, namely NOT_ONBOARDED, ONBOARDED and ONBOARDING. Definitions of each status is 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 agent to trigger the onboarding process.
  • ONBOARDED: Agent is authorized to exchange data with MindSphere.

Boarding service also provides an api to offboard the agent. When agent is offboarded a brand-new IAT is generated by the MindSphere.

If agent wants to onboard again, this new IAT needs to be used by the agent during onboarding (Registration) process as explained in the latter sections

Register

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 the MindSphere.

In order to register, the agent needs to put Initial Access Token(IAT) from its boarding configuration in the request. The way request is constructed varies slightly depending on the Agent's Security Profile. IAT Key is valid for one week (7 days.

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

Agents credentials regardless of the security profile needs to be updated every 7 days, during the update process agent needs to provide the RAT instead of IAT to update its credentials, the process is the same as initial Registration but this time instead of IAT the RAT needs to be provided

After registration is completed for an agent, its boarding status is set to ONBOARDED. Key rotation process is done through /register/{id} endpoint, and enables agents to change its key(symmetric or asymmetric). RAT is required to be provided 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 the MindSphere. MindSphere grants access tokens to onboarded (registered) agents.

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

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

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 relation
  • Define agent 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.

Use the Agent Management Service to register and offboard the desired devices.

Requirements

  • MindConnect devices are connected to the internet using HTTPs.
  • New software uses administrator role.

API Specification

Download OpenAPI Specification

Any questions left?

Ask the community


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