Connecting with Username and Password Credentials using MindConnect MQTT API¶

Overview¶

MQTT agents that want to connect to a private cloud Insights Hub environment can authenticate using a username and password instead of X.509 certificates.

You create the credentials via the MindConnect MQTT API, and the agent provides them during the MQTT connection handshake.

Prerequisites¶

• Insights Hub environment: You need a Insights Hub environment. Within this document, the parameter $TENANT is the name of your Insights Hub environment.

• Service credentials: You need service credentials with the mcmq.cred.c scope to create or update client credentials.

Managing Client Credentials¶

1. Create or update client credentials
2. Get all client credentials
3. Get client credentials details
4. Reset client credentials
5. Delete client credentials
6. Connect the agent using the credentials

Create or update client credentials¶

To create a username and password for your agent, make a PUT request to the credentials endpoint with a JSON payload containing the clientId, username, and password.

Prerequisite: Update the following fields with appropriate values before using the given sample in this section:

• <TOKEN> header parameter needs to be replaced by an actual token.
• clientId payload parameter needs to be replaced by an actual client ID in the format <tenantId>_<suffix>.
• username payload parameter needs to be replaced by an actual username.
• password payload parameter needs to be replaced by an actual password.

Sample HTTP request body:

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"
}

If the clientId does not exist yet, new credentials are created and 201 Created is returned. If it already exists, the credentials are updated and 200 OK is returned.

Sample response (201 Created — new credentials):

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

Sample response (200 OK — existing credentials updated):

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

Get all client credentials¶

To retrieve a list of all client credentials for your tenant, make a GET request to the credentials endpoint.

Prerequisite: Update the following fields with appropriate values before using the given sample in this section:

• <TOKEN> header parameter needs to be replaced by an actual token.

Sample HTTP request:

GET /api/mindconnectmqtt/v3/credentials HTTP/1.1
Host: `Customer specific URL. `
Authorization: Bearer <TOKEN>

Sample response:

{
    "credentials": [
        {
            "clientId": "myTenant_mydevice01",
            "username": "myClientUser",
            "creationDate": "2024-01-15T10:00:00Z",
            "updatedDate": "2024-01-15T10:00:00Z"
        },
        {
            "clientId": "myTenant_mydevice02",
            "username": "anotherUser",
            "creationDate": "2024-01-16T08:30:00Z",
            "updatedDate": "2024-01-16T08:30:00Z"
        }
    ],
    "page": {
        "nextToken": "4fad62585def4d84a4c21481b209c116"
    }
}

Get client credentials details¶

To retrieve details for a specific client, make a GET request to the credentials/{clientId} endpoint.

Prerequisite: Update the following fields with appropriate values before using the given sample in this section:

• <TOKEN> header parameter needs to be replaced by an actual token.
• <clientId> path parameter needs to be replaced by an actual client ID.

Sample HTTP request:

GET /api/mindconnectmqtt/v3/credentials/<clientId> HTTP/1.1
Host: `Customer specific URL. `
Authorization: Bearer <TOKEN>

Sample response:

{
    "username": "myClientUser",
    "creationDate": "2024-01-15T10:00:00Z",
    "updatedDate": "2024-01-15T10:00:00Z"
}

Reset client credentials¶

To reset the password for a client, make a POST request to the credentials/{clientId}/reset endpoint. The response contains the URL of the PUT endpoint to use for setting a new username and password.

Prerequisite: Update the following fields with appropriate values before using the given sample in this section:

• <TOKEN> header parameter needs to be replaced by an actual token.
• <clientId> path parameter needs to be replaced by an actual client ID.

Sample HTTP request:

POST /api/mindconnectmqtt/v3/credentials/<clientId>/reset HTTP/1.1
Host: `Customer specific URL. `
Authorization: Bearer <TOKEN>

Sample response (200 OK):

No response body is returned. After resetting, call the PUT /credentials endpoint with a new username and password body to set the new credentials. See Create or update client credentials for the request format.

Delete client credentials¶

To delete the credentials for a specific client, make a DELETE request to the credentials/{clientId} endpoint.

Prerequisite: Update the following fields with appropriate values before using the given sample in this section:

• <TOKEN> header parameter needs to be replaced by an actual token.
• <clientId> path parameter needs to be replaced by an actual client ID.

Sample HTTP request:

DELETE /api/mindconnectmqtt/v3/credentials/<clientId> HTTP/1.1
Host: `Customer specific URL. `
Authorization: Bearer <TOKEN>

Sample response (204 No Content):

No response body is returned when the credentials are successfully deleted.

Connect the agent using the credentials¶

Once the credentials are created, connect your agent to the MindConnect MQTT broker using the following connection parameters:

• ClientId: <tenantId>_<suffix> (the clientId created in the previous steps)
• Host: Customer specific MQTT broker URL. It should be started with "mindconnectmqtt"
• Port: Rancher: 8883 , Openshift: 30543
• CA File: Customer specific MQTT Root CA.
• Username: <username> (the username created in the previous steps)
• Password: <password> (the password created in the previous steps)

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