Dynamic Security REST API

This page describes how to use the Dynamic Security REST API that is provided by the Management Center for Eclipse Mosquitto.

info

Before sending command request make sure that you have been authenticated.

Sending command requests

The following command shows how to authenticate using curl. Please replace the <BASE_URL>, <BROKER_ID> and <JSON_COMMAND> placeholders accordingly.

• <BASE_URL>: The base URL where the installation of the Management Center is hosted.
• <BROKER_ID>: The id of the broker where the command should be send to (as defined via the Management Center).
• <JSON_COMMAND>: The JSON that should be send to the broker (see command documentation).

curl --cookie .cookies \
    --request POST <BASE_URL>/api/dynamic-security/<BROKER_ID>/command \
    -H 'Content-Type: application/json' \
    -d '<JSON_COMMAND>'

info

For the following command documentation, note that we assume that you store the JSON command that you send in a separate JSON file and reference it in the curl command as follows:

curl --cookie .cookies \
    --request POST <BASE_URL>/api/dynamic-security/<BROKER_ID>/command \
    -H 'Content-Type: application/json' \
    -d @command.json

We therefore only list the content of that JSON file in the following sections.

List clients

In order to send the listClients command to a broker with the id mosquitto-2.0 on the https://mosquitto.cedalo.com installation you would use the following command:

{
  "command": "listClients",
  "verbose": true
}

The response looks like the following (formatted into readable JSON):

{
  "command": "listClients",
  "data": {
    "totalCount": 1,
    "clients": [
      {
        "username": "admin",
        "textname": "MMC admin user",
        "roles": [
          {
            "rolename": "dynsec-admin"
          },
          {
            "rolename": "license-admin"
          },
          {
            "rolename": "sys-observe"
          },
          {
            "rolename": "topic-observe"
          }
        ],
        "groups": []
      }
    ]
  }
}

Get clients

Command:

{
  "command": "getClient",
  "username": "admin"
}

Response

{
  "command": "getClient",
  "data": {
    "client": {
      "username": "admin",
      "textname": "MMC admin user",
      "roles": [
        {
          "rolename": "dynsec-admin"
        },
        {
          "rolename": "license-admin"
        },
        {
          "rolename": "sys-observe"
        },
        {
          "rolename": "topic-observe"
        }
      ],
      "groups": []
    }
  }
}

Create clients

Command:

{
  "command": "createClient",
  "username": "max",
  "password": "5eCret",
  "clientid": "some-id",
  "rolename": "some-role",
  "textname": "Max Mustermann",
  "textdescription": "This is just a dummy user"
}

Response:

{
  "command": "createClient"
}

Delete clients

Commands:

{
  "command": "deleteClient",
  "username": "max"
}

Response:

{
  "command": "deleteClient"
}

List groups

Command:

{
  "command": "listGroups",
  "verbose": true
}

Response:

{
  "command": "listGroups",
  "data": {
    "totalCount": 0,
    "groups": []
  }
}

Get groups

Command:

{
  "command": "getGroup",
  "groupname": "example-group"
}

Response:

{
  "command": "getGroup",
  "data": {
    "group": {
      "groupname": "example-group",
      "textname": "Example Group",
      "textdescription": "An example group",
      "clients": [],
      "roles": []
    }
  }
}

Create groups

Command:

{
  "command": "createGroup",
  "groupname": "example-group",
  "rolename": "example-role",
  "textname": "Example Group",
  "textdescription": "An example group"
}

Response:

{
  "command": "createGroup"
}

Delete groups

Command:

{
  "command": "deleteGroup",
  "groupname": "example-group"
}

Response:

{
  "command": "deleteGroup"
}

Add clients to groups

Command:

{
  "command": "addGroupClient",
  "username": "max",
  "groupname": "example-group"
}

Response:

{
  "command": "addGroupClient"
}

Remove clients from groups

Command:

{
  "command": "removeGroupClient",
  "username": "max",
  "groupname": "example-group"
}

Response:

{
  "command": "removeGroupClient"
}

List roles

Command:

{
  "command": "listRoles",
  "verbose": true
}

Response:

{
  "command": "listRoles",
  "data": {
    "totalCount": 5,
    "roles": [
      {
        "rolename": "client",
        "textdescription": "Read/write access to the full application topic hierarchy (note: please create ACLs to restrict access as required by your application).",
        "allowwildcardsubs": true,
        "acls": [
          {
            "acltype": "publishClientSend",
            "topic": "#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "publishClientReceive",
            "topic": "#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "subscribePattern",
            "topic": "#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "unsubscribePattern",
            "topic": "#",
            "priority": 0,
            "allow": true
          }
        ]
      },
      {
        "rolename": "dynsec-admin",
        "textname": "",
        "textdescription": "Grants access to administer clients/groups/roles.",
        "allowwildcardsubs": true,
        "acls": [
          {
            "acltype": "publishClientSend",
            "topic": "$CONTROL/dynamic-security/#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "publishClientReceive",
            "topic": "$CONTROL/dynamic-security/#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "subscribePattern",
            "topic": "$CONTROL/dynamic-security/#",
            "priority": 0,
            "allow": true
          }
        ]
      },
      {
        "rolename": "license-admin",
        "textname": "",
        "textdescription": "Grants access to administer licenses.",
        "allowwildcardsubs": true,
        "acls": [
          {
            "acltype": "publishClientSend",
            "topic": "$CONTROL/cedalo/license/#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "publishClientReceive",
            "topic": "$CONTROL/cedalo/license/#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "subscribePattern",
            "topic": "$CONTROL/cedalo/license/#",
            "priority": 0,
            "allow": true
          }
        ]
      },
      {
        "rolename": "sys-observe",
        "textname": "",
        "textdescription": "Observe the $SYS topic hierarchy.",
        "allowwildcardsubs": true,
        "acls": [
          {
            "acltype": "publishClientReceive",
            "topic": "$SYS/#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "subscribePattern",
            "topic": "$SYS/#",
            "priority": 0,
            "allow": true
          }
        ]
      },
      {
        "rolename": "topic-observe",
        "textdescription": "Read only access to the full application topic hierarchy.",
        "allowwildcardsubs": true,
        "acls": [
          {
            "acltype": "publishClientReceive",
            "topic": "#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "subscribePattern",
            "topic": "#",
            "priority": 0,
            "allow": true
          },
          {
            "acltype": "unsubscribePattern",
            "topic": "#",
            "priority": 0,
            "allow": true
          }
        ]
      }
    ]
  }
}

Get roles

Command:

{
  "command": "getRole",
  "rolename": "example-role"
}

Response:

{
  "command": "getRole",
  "data": {
    "role": {
      "rolename": "example-role",
      "textname": "Example Role",
      "textdescription": "An example role",
      "allowwildcardsubs": true,
      "acls": []
    }
  }
}

Create roles

Command:

{
  "command": "createRole",
  "rolename": "example-role",
  "textname": "Example Role",
  "textdescription": "An example role"
}

Response:

{
  "command": "createRole"
}

Delete roles

Command:

{
  "command": "deleteRole",
  "rolename": "example-role"
}

Response:

{
  "command": "deleteRole"
}

Add roles to clients

Command:

{
  "command": "addClientRole",
  "username": "max",
  "rolename": "example-role"
}

Response:

{
  "command": "addClientRole"
}

Remove roles from clients

Command:

{
  "command": "removeClientRole",
  "username": "max",
  "rolename": "example-role"
}

Response:

{
  "command": "removeClientRole"
}

Add roles to groups

Command:

{
  "command": "addGroupRole",
  "username": "example-group",
  "rolename": "example-role",
  "priority": 5
}

Response:

{
  "command": "addGroupRole"
}

Remove roles from groups

Command:

{
  "command": "removeGroupRole",
  "username": "example-group",
  "rolename": "example-role"
}

Response:

{
  "command": "removeGroupRole"
}

Add ACLs to roles

info

See also the ACL documentation for a basic description of the different ACL types.

Command:

{
  "command": "addRoleACL",
  "rolename": "example-role",
  "acltype": "publishClientSend",
  "priority": 5,
  "topic": "/some/topic/structure",
  "allow": true
}

Response:

{
  "command": "addRoleACL"
}

Remove ACLs from roles

Command:

{
  "command": "removeRoleACL",
  "rolename": "example-role",
  "acltype": "publishClientSend",
  "topic": "/some/topic/structure"
}

Response:

{
  "command": "removeRoleACL"
}

Deauthenticate / Logout

To logout your client from the REST API you simply need to send the following request to the /logout endpoint:

curl --cookie .cookies \
    --request GET <BASE_URL>/logout