Agent Management Service¶

Idea¶

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

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 tenant.

Basics¶

Agents¶

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

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 MindSphere. MindSphere checks the signature of the IAT to validate the agent. After onboarding the agent is authorized and authenticated to communicate with MindSphere.

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

• SHARED_SECRET
• RSA_3072.

SHARED_SECRET Security Profile¶

MindSphere 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 MindSphere when onboarding. MindSphere stores the public key in its persistent storage.

Data Source Configuration¶

MindSphere needs a data source configuration for interpreting the data it receives from an agent. Without this configuration MindSphere 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, MindSphere 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 MindSphere, which allows to onboard the agent again.

Access Token¶

Agents need an access token to consume MindSphere 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, tenant name etc., and signs it with its shared secret or private key based on its security profile.
2. The agent sends an access token request with the self signed JWT to MindSphere.
3. MindSphere validates the signature of the JWT using the stored credentials of the agent.
4. If the self signed JWT is valid, MindSphere responds with an access token.

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

Related Links¶

• Onboarding an agent
• Acquiring an agent access token
• Uploading agent data
• MindConnect Service
• Authentication & Authorization

Any questions left?

Ask the community

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