Agent Certificate from CA Certificate¶

This guide outlines the process of creating an agent or device certificate from a tenant CA certificate.

Agent Onboarding¶

The onboarding process differs depending on your environment:

• EU1
• Private Cloud

EU1¶

To onboard an agent in the EU1 environment, complete the following step:

Create an Agent Private Key and Certificates:

This step involves generating an agent private key, creating a Certificate Signing Request (CSR), issuing the agent certificate, and concatenating the agent and CA certificates.

**For LINUX**:

To get started, set the environment variables:

```cmd
export TENANT=<yourtenant>
export DEVICE_NAME=<yourdevicename>
export COUNTRY_CODE =<COUNTRY_CODE>
export CITY =<CITY>
export ORGANIZATION =<ORGANIZATION>
```

Then, execute the following commands:

1.**Generate Agent Private Key**: `openssl genrsa -out $DEVICE_NAME.key 2048`

2.**Create CSR**: `openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$DEVICE_NAME"`

(This command creates a CSR using the agent name as the certificate subject's Common Name, which is valid for 1 year.)

3.**Issue Agent Certificate**: `openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256`

(This uses the tenant's private key to issue the agent certificate.)

4.**Concatenate Certificates**: `cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem`

(This concatenates the agent certificate and CA certificate for later use.)

5.**To view the created certificate**: `openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout`

**WINDOWS:**

To get started, set the environment variables:

```cmd
set TENANT=<yourtenant>
set DEVICE_NAME=<yourdevicename>
set COUNTRY_CODE =<COUNTRY_CODE>
set CITY =<CITY>
set ORGANIZATION =<ORGANIZATION>
```

Then, execute the following commands:

1.Generate Agent Private Key: `openssl genrsa -out %DEVICE_NAME%.key 2048`

2.Create CSR: `openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%DEVICE_NAME%"`

(This command creates a CSR using the agent name as the certificate subject's Common Name, which is valid for 1 year.)

3.Issue Agent Certificate: `openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256`

4.Concatenate Certificates: `type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem`

5.To view the created certificate: `openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout`

Private Cloud¶

MindConnect MQTT supports two connection methods for agents in private cloud environments: credential-based authentication and certificate-based authentication. Select the method that best meets your security and operational requirements.

Credential-based connection¶

This method allows private cloud agents to connect using a username and password, offering an alternative to certificate-based authentication.

Create Connection Credentials using the MindConnect MQTT API:

Before connecting, you need to create a unique username and password for your agent using the MindConnect MQTT API.

Prerequisite:

Update the following fields with appropriate values before using the given sample:

• Replace <TOKEN> with a valid token.
• Use the format <tenantId>_<suffix> for the clientId.
• Specify a username. Do not use the reserved keyword _CertificateBearer (reserved keyword).
• Use a password that is at least 8 characters long and includes one uppercase letter, one lowercase letter, one digit, and one special character.

Sample HTTP request:

Use the following PUT request to create your credentials.

PUT /api/mindconnectmqtt/v3/credentials HTTP/1.1
Host: <customer_specific_url>
Content-Type: application/json
Authorization: Bearer <TOKEN>
{
    "clientId": "myTenant_mydevice01",
    "username": "myClientUser",
    "password": "SecureP@ss1"
}

Sample response:

A successful request returns a response similar to the following:

{
    "clientId": "myTenant_mydevice01",
    "username": "myClientUser"
}

Credential Management:

For comprehensive credential management, including listing, viewing details, or resetting credentials, please refer to the dedicated guide: Connecting with Username and Password Credentials using the MindConnect MQTT API.

MQTTX Agent Onboarding Example¶

Connection parameters are as follows:

• ClientId: <tenantId>_<suffix>
• Host: Customer specific MQTT broker URL. It should be started with "mindconnectmqtt"
• Port: Rancher: 8883 , Openshif: 30543
• CA File: Customer specific MQTT Root CA.
• Username: <username> (created via MindConnect MQTT API)
• Password: <password> (created via MindConnect MQTT API)

Initial Connection Attempt & Agent Provisioning:

At the first connection attempt, the broker will close the connection and start provisioning of the agent in the Insights Hub backend. Once completed, you can see your newly created agent asset in the Asset Manager application in the Launchpad.

After a couple of seconds, retry the connection attempt. This time connection will remain intact since provisioning is complete.

Once connected, clients can utilize the topics defined by applications available on MindConnect Connectivity. Refer to the async API specs of related services to learn about available topics and payload schemas.

Certificate-based connection¶

1. Create an agent private key

   The following commands create an agent private key (line 1) and create a CSR using the clientId as the certificate subject's Common Name, which is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using the created CSR (line 3). Finally, the client certificate and CA certificate are concatenated to use in later steps.

   LINUX:

   export TENANT=<yourtenant>
   export DEVICE_NAME=<yourdevicename>
   export COUNTRY_CODE =<COUNTRY_CODE>
   export CITY =<CITY>
   export ORGANIZATION =<ORGANIZATION>
   export CLIENT_ID="$TENANT"_"$DEVICE_NAME"
   

   1.openssl genrsa -out $DEVICE_NAME.key 2048

   2.openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$DEVICE_NAME"

   3.openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256

   4.cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem

   You can view the created certificate with the following command:

   openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

   WINDOWS:

   set TENANT=<yourtenant>
   set DEVICE_NAME=<yourdevicename>
   set COUNTRY_CODE =<COUNTRY_CODE>
   set CITY =<CITY>
   set ORGANIZATION =<ORGANIZATION>
   set CLIENT_ID="%TENANT%"_"%DEVICE_NAME%"
   

   1.openssl genrsa -out %DEVICE_NAME%.key 2048

   2.openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%DEVICE_NAME%"

   3.openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256

   4.type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem

   You can view the created certificate with the following command:

   openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout

2. Create X509 Client JWT

3. Required Headers

   Field	Description
   alg	value must be “RS256”
   x5c	Value of that claim must satisfy the following conditions:
   	- Contains Device Certificate and TenantCA Certificate sequentially
   	- Certificates must be in order (eg: [Device Certificate, TenantCA Certificate])
   	- All certificates must be valid (Please see Device Certificate Requirements & TenantCA and Intermediate Certificate Requirements for details below.)
   typ	value must be “JWT”

4. Required and Optional Claims

   Field	Description
   jti	Unique identifier for the token. The format is String in UUID with a maximum of 36 characters.
   iss	Issuer information of the token. The value must be MQTT Client id.
   sub	Subject information of the token. The value must be MQTT Client id (same as iss).
   aud	Audience claim identifies the recipients that the token is intended for. Value must be [“MQTTBroker”]
   iat	Time at which the token was issued. Format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC).
   nbf	Identifies the time before which the token must not be accepted for processing. Format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC). It is optional claim, if the token has that claim Insights Hub checks the notBefore time and validates the token.
   exp	Expiration time of the token. The format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC). Thetoken must be valid up to one hour. Therefore, the difference between iat and exp must be a maximum one hour.
   schemas	Defines the semantics of custom claims of the token. The value must be [“urn:siemens:mindsphere:v1”].
   ten	Any string value with a maximum of 36 characters.
   *	denotes optional claim.

5. Signature JWT must be signed by the Device Certificate private key. For example, the JWT used by the device follows the structure as below:

   {
       "alg":"RS256", 
       "x5c": ["MIICYzCCAcygAwIBAgIBADANB...","MIIDCTCCAfGgAwIBAgIUU..."],
       "typ":"JWT"
   }
   

Creation Example¶

1. Open jwt.io. On jwt io, use the Decoded section to create JWT.8
   

2. Header should be like the following example.

   {
       "alg":"RS256",
       "x5c": ["MIICYzCCAcygAwIBAgIBADANB...","MIIDCTCCAfGgAwIBAgIUU..."],
       "typ":"JWT"
   }
   

   

3. Payload should be like the following example.

   {
   "jti": "anyId",
   "iss": "<yourclientid>",
   "sub": "<yourclientid>",
   "aud": ["MQTTBroker"],
   "iat": <currentepochdate>,
   "exp": <onehouraftercurrentepochdate>,
   "schemas": ["urn:siemens:mindsphere:v1"],
   "ten": "<tenant>"
   }
   

   

4. Add your device private key. You can find the private key in <yourdevicename>.key file.

   

5. MQTTX Agent Onboarding Example

   Connection parameters are as follows:

   • ClientId: <tenant>_<AgentCertificate.Subject.CommonName>
   • Host: Customer specific MQTT broker URL. It should be started with “mindconnectmqtt”
   • CA File: Customer specific MQTT Root CA.
   • Username: _CertificateBearer
   • Password: Created X509 Client JWT in above section.

At the first connection attempt, the broker will close the connection and start provisioning of the agent in the Insights Hub backend. Once completed, you can see your newly created agent asset in the Asset Manager application in the Launchpad.

After a couple of seconds, retry the connection attempt. This time connection will remain intact since provisioning is complete.

Once connected, clients can utilize the topics defined by applications available on MindConnect Connectivity. Refer to the async API specs of related services to learn about available topics and payload schemas.

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