Agent Management Service - Developer Documentation - Developer Documentation
Skip to content

Agent Management Service

Idea

The Agent Management Service is typically used by application developers or machine builders (OEMs). It provides APIs to onboard, offboard, update and delete agents. Connectivity functions are used to enable communication with Industrial IoT.

Access

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

Users can only interact with agents onboarded within their environment.

Basics

Agents

Agents are the primary actors within the environment. For example, they upload data, retrieve events, changes their configuration etc. The very first step for using Industrial IoT APIs is to create an agent in Insights Hub.

When the agent is created, an initial access token (IAT) is generated. The IAT is a JSON Web Token (JWT) that holds various information about the agent and must be downloaded to the agent. The IAT is valid for one week (7 days). It required for onboarding the agent to Insights Hub. Insights Hub checks the signature of the IAT to validate the agent. After onboarding the agent is authorized and authenticated to communicate with Insights Hub.

Agents provide their credentials using one of the following security profiles:

  • SHARED_SECRET
  • RSA_3072.

SHARED_SECRET Security Profile

Insights Hub creates a secret for agents with this security profile and stores it in its persistent storage. This secret is returned to the agent in the onboarding response.

RSA_3072 Security Profile

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

Data Source Configuration

Insights Hub needs a data source configuration for interpreting the data it receives from an agent. Without this configuration Insights Hub cannot understand the data. The data source configuration contains data sources and data points. Data sources are logical groups, e.g. a sensor or a machine, which contain one or more measurable data points, e.g. temperature or pressure.

When an agent is first created, its data source configuration is empty and must be updated using this service.

Onboarding

Agents are onboarded using the Register endpoints of this service. The onboarding process follows the OAuth 2.0 Authorization protocol (RFC 6749):

  1. The agent retrieves the Initial Access Token (IAT) from its boarding configuration.
  2. It sends an onboarding request singed with the IAT according to its security profile.
  3. If onboarding is successful, Insights Hub responds with a Registration Access Token (RAT), which is valid indefinitely.

Agent credentials have to be updated using the /register/{id} endpoint 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.

Agents are offboarded using the /agents/{id}/boarding/offboard endpoint. When an agent is offboarded, a new IAT is generated by Insights Hub, which allows to onboard the agent again.

Access Token

Agents need an access token to consume Industrial IoT services. This is a time restricted JSON Web Token (JWT) that holds the agent's scopes (access rights) among other information. Agents must be onboarded before they can acquire an access token, which requires the following steps:

  1. The agent creates a self-signed JWT, which holds information such as agent ID, environment name etc., and signs it with its shared secret or private key based on chosen security profile.
  2. The agent sends an access token request with the self signed JWT to Insights Hub.
  3. Insights Hub validates the signature of the JWT using the stored credentials of the agent.
  4. If the self signed JWT is valid, Insights Hub responds with an access token.

Note

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

Note

Access tokens are valid for one hour. After its expiration, agents need to acquire a new access token to continue using Industrial IoT services.

Agent Access token will have the role mdsp:core:DefaultAgent which has the scopes listed in Agent Access Token roles and scopes.

Features

  • Create, edit, remove agents
  • Onboard and offboard agents
  • Define an agent's data sources
  • Acquire access tokens to consume Insights Hub 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.

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

Last update: April 13, 2023