Skip to content

Onboarding an Agent

For onboarding an agent the following steps have to be performed:

  1. Provisioning an agent.
  2. Getting the boarding configuration of an agent.
  3. Registering an agent.

Provisioning an agent

In order to create an agent, an "asset type" and an "asset" needs to be created beforehand. An asset type to asset relationship can be considered analog to the relationship between a class and an object. An object is an instance of a class, a class is a blueprint for an object. The same applies to asset type and asset.

After creating the new entity, we can create an agent that will be bound to this entity using the agents endpoint of the Agent Management Service:

POST {{ _gateway_url }}/api/agentmanagement/v3/agents HTTP1/1
Content-Type: application/json
...
{
    "entityId": "3b27818ea09a46b48c7eb3fbd878349f",
    "name": "Nanobox Agent",
    "securityProfile": "SHARED_SECRET"
}
Parameter Description Remarks
entityId Id of the entity that is created for the agent beforehand. Each agent needs an entity.
name Name of the agent Different from the Id. Expected to be unique per tenant.
securityProfile Defines the method the agent will provide its credentials to Insights Hub:

Shared Secret
Symmetric Cryptography (a password that is known by both agent and Insights Hub)

RSA
Asymmetric Cryptography (public, private key pair where Insights Hub only knows the public key and the agent holds the private key)		 SHARED_SECRET or RSA_3072

The Agent Management Service runs the logic below when the agent is created:

Agent Management: Create agent checks and workflow

If all checks are passed, the Agent Management creates the agent. Initially, the boarding status of the newly created agent is NOT_ONBOARDED. The Agent Management creates the onboarding configuration for the related agent and sets the boarding status to ONBOARDING. This is an automatic process and no user involvement is required.

Upon successful creation, Insights Hub returns an HTTP response 201 Created with a JSON body holding additional data about the newly provisioned agent:

HTTP/1.1 201 Created
Content-Type: Application/Json
...
{
    "id": "3b27818ea09a46b48c7eb3fbd878349f",
    "eTag": "2",
    "entityId": "3b27818ea09a46b48c7eb3fbd878349f",
    "name": "Nanobox Agent",
    "securityProfile": "SHARED_SECRET"
}
Parameter Description Remarks
id Id of the created agent The agent Id is identical to the entity Id. There is a one-to-one relation.
eTag eTag version Used for synchronization purposes during agent creation, has no practical implications.
entityId Id of the entity this agent is created from.
name Name of the agent
securityProfile Security profile of the agent SHARED_SECRET or RSA_3072

Getting the boarding configuration

After agent creation, the agent needs to acquire the boarding configuration in order to board to Insights Hub. If an agent is not onboarded, it cannot use any of the services offered.

Boarding functionality is provided by the boarding endpoint of the Agent Management Service. Sending a GET {{ _gateway_url }}/api/agentmanagement/v3/agents/{{ agent_id }}/boarding/configuration HTTP request with the agent Id as the path parameter returns following sample boarding response body:

{
    "content": {
        "baseUrl": "https://southgate.eu1.mindsphere.io",
        "iat": "yJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJ0ZXN0LWFnZW50IiwiYXVkIjpbIkFJQU0iXSwiaWF0IjoxNTEzNjA3NjQ3LCJuYmYiOjE1MTM2MDc2NDcsImV4cCI6MTUxNDIxMjQ0NywianRpIjoiODBkNGViYTAtZTQwMC0xMWU3LTlmMDYtM2QzOTg3NTQ1MjNjIiwic2NvcGUiOlsiSUFUIl0sInRlbmFudCI6InRlc3QtdGVuYW50IiwiY2xpZW50X2NyZWRlbnRpYWxzX3Byb2ZpbGUiOlsiUlNBXzMwNzIiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.F/C44dH0orAVrKXDxcdGTgDFGsYzxOLR84j49S1qQMcX4GKq0HGfN7mm9N2tAUo8+z9ISRIW+D/n81uioF4ro+cyjGFbstatsRVH8hFFbZe4WcSChBHpwmA9IBOL0iFo/8C/7FppjhmHnlJNTQrfdkPJbtgQljtlY46BqW2pKp3wPUPJb21nLhVwMv1AiAbISg17FazhzuV7n12pJxdtpEB+mYZZe16P9amW217iyaDyRZ0+UhldHyKYwX0in5SpvJ1gzFlhMNwYWhG8zk6EJ8OYY49OhTYLHtvoEm8IIxarPWWmMztwrEXvNvQi6svZ1NCcgbkuSTwdEyJDzPqmbw==",
        "clientCredentialProfile": [
            "SHARED_SECRET"
        ],
        "clientId": "5fa51b64-dce2-11e7-9296-cec278b6b50a",
        "tenant": "6e70640a-dce2-11e7-9296-cec278b6b50a"
    },
    "expiration": "2017-12-18T14:04:01.076Z"
}
Parameter Description Remarks
baseUrl Southgate URL
iat Initial Access Token (IAT)
A JSON Web Token that is being signed by the Agent Management, required to do initial registration.		 IATs are subject to expiration and by default have 7 days of validity. If IAT is expired, an agent needs to call this endpoint to acquire a new configuration.
clientCredentialProfile The security profile of the agent set during provisioning. SHARED_SECRET or RSA_3072
clientId Agent Id
tenant Tenant of the agent
expiration Holds the expiration time of the IAT Default value is 7 days.

Registering an agent

After acquiring the Initial Access Token (IAT), the agent needs to register with Insights Hub. This registration process takes place in accordance with the OAuth 2.0 authorization protocol. Therefore, the agent sends an HTTP POST request to Insights Hub. The way this request is constructed varies slightly depending on the security profile of the agent.

Agents with a Shared Secret security profile

Registering an agent is provided by the register endpoint of the Agent Management Service. The agent sends an HTTP POST request with an empty body:

POST /api/agentmanagement/v3/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJ0ZXN0LWFnZW50IiwiYXVkIjpbIkFJQU0iXSwiaWF0IjoxNTEzNjA3NzI1LCJuYmYiOjE1MTM2MDc3MjUsImV4cCI6MTUxNDIxMjUyNSwianRpIjoiYWY2YzkwMzAtZTQwMC0xMWU3LTk4MjQtMTEwNzBjODYyZmRiIiwic2NvcGUiOlsiSUFUIl0sInRlbmFudCI6InRlc3QtdGVuYW50IiwiY2xpZW50X2NyZWRlbnRpYWxzX3Byb2ZpbGUiOlsiU0hBUkVEX1NFQ1JFVCJdLCJzY2hlbWFzIjpbInVybjpzaWVtZW5zOm1pbmRzcGhlcmU6djEiXX0=.Re1be4kiDfIs+tqZ+CEZ1/3UoBrHZ4azy3Lesse8bK6LvFtUIU626+g4JDjRdJV9gCstqfYsj15cPC+PJLOfxZFBMnoBY451RLDVJOJOtAncLPdvnPHXvvTu3VbU5Qpx0SCLY/VoDRva1a1/vMy/6S2lpOJ4dYcOMq1madzyf4iXGwmTMiKmfZEHAJuxmFRNosaEo+SkIm//OQ2SCGlWvAr1iM9QHIo8kpjYukOSt+5ubpXqlmeX7Gu5ouVABaC3T03uTzK620wNDTxhbPpNjG1RMzkUHfNcQJT0K5UuSJaMjSc1tolETAlzCz4fFevzS8UcfcUVR1Wre8qilt3khg==
Host: southgate.{region}-{env}.{mindsphere-domain}
{} //empty JSON Object

Info

{region}, {env} and {mindsphere-domain} are placeholders for the region, environment and domain. A valid URL for the RC environment in eu1 would be southgate.eu1-rc.mindsphere.io.

Insights Hub receives the request and validates it (IAT validation, mandatory header validation, etc.). If the validation succeeds, Insights Hub creates a shared secret (password) and stores it in its database with a predefined shared secret expiration time (7 days by default).

At the same time, Insights Hub creates another token called Registration Access Token (RAT) for the client. When the shared secret expiration occurs, the client is expected to send a registration update request using the created RAT instead of the IAT so the registration and password can be renewed.

This is a successful register HTTP response for a shared secret security profile:

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "client_id": "008ceaf9dff443ee94205f903aa545c4",
    "token_endpoint_auth_method": "client_secret_jwt",
    "grant_types": [
        "client_credentials"
    ],
    "client_secret": "ly7zmXbz0Izla6B82xlAYRVBcKDcCFatwmnHQmR8Ycw",
    "client_secret_expires_at": 1514206768,
    "registration_access_token": "eyJraWQiOiJrZXktaWQtMSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJTQ0kiLCJzdWIiOiIwMDhjZWFmOWRmZjQ0M2VlOTQyMDVmOTAzYWE1NDVjNCIsImF1ZCI6IkFJQU0iLCJpYXQiOjE1MTM2MDE5NjgsIm5iZiI6MTUxMzYwMTk2OCwiZXhwIjoxNTE0MjA2NzY4LCJqdGkiOiIwMTNiNzU2Zi02YWZhLTRiZjYtYjY2Yi1jZTU3NWUwYmIyNzMiLCJzY29wZSI6IlJBVCIsInRlbiI6ImNvbm50ZW5hbnRvbmVxYSIsImNsaWVudF9jcmVkZW50aWFsc19wcm9maWxlIjpbIlNIQVJFRF9TRUNSRVQiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.KFERGKzl5YKhEnNptKYHvZWngAs07iZLR_F2DoPAuAW_rowGk3ykooztfHJoEtWvi1HlWAbtn5MX7QOE0EYyNJN-4K3PEStKLeRc6Ony9vAIzdAUhn-aP5c0fKvKeSRNpd8pxXPtMbEOIwKWUa9XmpbOwem6qkD3bvnGzqnHMiYN4dXluNNBM1uhK8rCKafW3QwOKZVYkfJgyyvAlnr978hbEHzK28g5mBZWOjx7inDmAdiD0woI39S4NoeU031bYQ8N7gnDBrqo8ZE5C_VtigRmWCFbnz_6-Qna8akW_MkhobEjmF7v74E3orb2Dfj-FosxkX0J4VhJEgD3hAwPOQ",
    "registration_client_uri": "https://southgate.eu1-rc.mindsphere.io/api/agentmanagement/v3/register/008ceaf9dff443ee94205f903aa545c4"
}
Parameter Description Remarks
client_id Agent Id
token_endpoint_auth_method String indicator of the requested authentication method for the token endpoint Defined in RFC 7591
grant_types OAuth 2.0 access token flow type to be used when requesting access token.
client_secret Generated client secret, the client will use when requesting access token.
client_secret_expires_at Time, the generated client secret will expire. Client needs to re-register with RAT, if expiration occurs.
registration_access_token Registration Access Token (RAT). The client needs RAT to renew its registration.
registration_client_uri URI to use when client renews its registration.

Agents with an RSA 3072 security profile

Registering an agent is provided by the register endpoint of the Agent Management Service. The agent sends an HTTP POST request with its public key in the request body:

POST /api/agentmanagement/v3/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer ey...{yourIAT}
Host: authorizationserver.mindsphere.com
{
    "jwks": {"keys": [
        { // RSA key created by client
        "e": "AQAB",
        "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
        HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
        lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
        RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
        2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
        qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
        "kty": "RSA",
        "kid": "key-1"
        }
    ]}
}
Parameter Description Remarks
jwks JSON Web Key Set of the client, document value Defined in RFC 7517
e Public exponent e See RSA algorithm for details.
n Modulus n See RSA algorithm for details.
kty Key type Identifies the cryptographic algorithm family used by the key.
kid Key ID to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover.

Insights Hub receives the request and validates it (IAT validation, mandatory header validation, etc.). If the validation succeeds, Insights Hub stores the agents public key in its database.

At the same time, Insights Hub creates another token called Registration Access Token (RAT) for the client. When the client secret expiration occurs, the client is expected to send a registration update request using the created RAT instead of the IAT so the registration can be renewed.

This is a successful register HTTP response for an RSA 3072 security profile:

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "client_id": "s6BhdRkqt3", //Client ID - equals value of "sub" claim in IAT
    "token_endpoint_auth_method": "private_key_jwt",
    "grant_types": ["client_credentials"],
    "client_secret_expires_at": 1234545 // 7 days after created.
    "registration_access_token": "ey..."
    "registration_client_uri": "https://authorizationserver.mindsphere.com/register/s6BhdRkqt3"
}
Parameter Description Remarks
client_id Agent Id
token_endpoint_auth_method String indicator of the requested authentication method for the token endpoint. Insights Hub uses two types of JWT authentication, depending on the key used to secure the assertion:

client_secret_jwt
The JWT is secured with a Hash-based Message Authentication Code (HMAC) computed with the client secret.

private_key_jwt
The JWT is signed with an asymmetric key (RSA or EC) that belongs to the client.		 For details see RFC 7591, Section 2 "Client Metadata".
grant_types OAuth 2.0 access token flow type to be used when requesting access token.
client_secret Generated client secret, the client will use when requesting access token.
client_secret_expires_at Time, the generated client secret will expire. Client needs to re-register with RAT, if expiration occurs.
registration_access_token Registration Access Token (RAT) The client needs RAT to renew its registration.
registration_client_uri URI to use when client renews its registration.

Refreshing a registration

By default, each registered agent (either RSA 3072 or Shared Secret security profile) has its credentials valid for 7 days. After this period, Insights Hub will not grant access tokens to the agent and it will render the agent credentials invalid. The agent needs to re-register to Insights Hub providing its Registration Access Token (RAT). The agent needs to perform this request to the URL value of registration_client_uri. This URL is provided in the JSON body of the HTTP response 201 Created to a successful registration (see section Registering an agent).

Registration access tokens have no practical expiration times (valid until 1000000000-12-31T23:59:59.999999999Z) but each time a client refreshes its registration, a new RAT is generated by Insights Hub. Agents are expected to refresh their registrations before their credentials expire.

Refreshing an agent registration is provided by the register endpoint of the Agent Management Service. Below is a sample refresh request of an agent with a shared secret security profile:

PUT /api/agentmanagement/v3/register/{agent-id} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer ey...{yourRAT}
Host: authorizationserver.mindsphere.com
{
    client_id: agentid
}

If the RAT is correct and the provided client Id matches, a new registration access token is returned to the client. The old registration access token must be discarded by the client, Insights Hub discards the old RAT automatically.

Insights Hub returns an HTTP response 200 OK. The structure of the JSON body is the same as for the initial registration of the agent:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    client_id: 'f1e45f31-0014-4e54-b58b-2065f965f7db',
    token_endpoint_auth_method: 'client_secret_jwt',
    grant_types: [ 'client_credentials' ],
    client_secret: 'usiRBejgh6XhOEYXpedDJZzhA4TTOw_nFmsKuyTl0NQ',
    client_secret_expires_at: 1516898093,
    registration_access_token: 'eyJraWQiOiJqd3QiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJTQ0kiLCJzdWIiOiJmMWU0NWYzMS0wMDE0LTRlNTQtYjU4Yi0yMDY1Zjk2NWY3ZGIiLCJhdWQiOiJBSUFNIiwiaWF0IjoxNTE2MjkzMjkzLCJuYmYiOjE1MTYyOTMyOTMsImV4cCI6MzE1NTY4ODk4NjQ0MDMxOTksImp0aSI6IjY0YmQxNTcyLTEyNmItNDI0My1hNWJmLWVjMzAxNTNmYTNmNCIsInNjb3BlIjoiUkFUIiwidGVuIjoibXlUZW5hbnRJZCIsImNsaWVudF9jcmVkZW50aWFsc19wcm9maWxlIjpbIlNIQVJFRF9TRUNSRVQiXSwic2NoZW1hcyI6WyJ1cm46c2llbWVuczptaW5kc3BoZXJlOnYxIl19.LOnsuClqKFMMf_5aE-y0al2cPIgrX8S92GBw_owVHPEfvPzVW_6ISffDy_Oa944dqHT0tmXg8VwR7PhnP0PQK4rQkFsuLOI_lf84xevVnmjbVov5Lqg4WTP9hxxIe9PFzQ8DdpTx4KSwEvUEftqv694sK4lY2EKAyuAQWfjPMifhUwpyCt9dQkcpHf87YygDThrj9AoBmC--LUnvYZzMGpS9IvnAZaq22AKuzv-B-j31L5vCO_J6GrqN7zS6goYewinFuKeS14rDCGE-bgdwyZMpkv4BdyUmnQgQIxlIrsWJH1X3j9ZIQKlFpN8F0eY1TlfpIJ4rqkqwnRbL_WsLUQ',
    registration_client_uri: 'https://southgate.eu1.mindsphere.io/api/agentmanagement/v3/register/f1e45f31-0014-4e54-b58b-2065f965f7db'
}
Parameter Description Remarks
client_id Agent Id
token_endpoint_auth_method String indicator of the requested authentication method for the token endpoint Defined in RFC 7591
grant_types OAuth 2.0 access token flow type to be used when requesting access token.
client_secret Generated client secret, the client will use when requesting access token.
client_secret_expires_at Time, the generated client secret will expire. Client needs to re-register with RAT, if expiration occurs.
registration_access_token Registration Access Token (RAT). The client needs RAT to renew its registration.
registration_client_uri URI to use when client renews its registration.

For agents with an RSA 3072 security profile, the registration refresh process is the same. Only the registration refresh requests HTTP body changes slightly:

PUT /api/agentmanagement/v3/register/{agent-id} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer ey...{yourRAT}
Host: authorizationserver.mindsphere.com
{
    "jwks": {"keys": [
        { // RSA key created by client
        "e": "AQAB",
        "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
        HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
        lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
        RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
        2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
        qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
        "kty": "RSA",
        "kid": "key-1"
        }
    ]}
}

Agent states and token handling

The following diagram illustrates the available agent states and the associated token handling:

Agent State Diagram

Last update: August 2, 2024

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