Dynamic Security

Manage the dynamic security functionality of brokers

Available API Paths

• /api/dynamic-security/{brokerId}/command
  
• /api/dynamic-security/{brokerId}/export
  

---

Path: /api/dynamic-security/{brokerId}/command

Methods

POST

Executes a command on the specified broker. Must be editor to access

Parameters

Name	Location	Type	Required	Description
brokerId	path	string	true	ID of the broker where the command will be executed

Parameters

Name	Required	Type	Request Properties or Schema
body	true	object	Command object. For more information on commands refer to the dynamic security section of the official Mosquitto Cedalo documentation. Properties: { "command": { "type": "string", "description": "Command name" } } Optional properties: { "description": "Other command parameters. Refer to dynamic security documentation" }

Responses

Status	Description	Response Content or Scheme
200	Command execution result	{ "command": { "type": "string", "description": "Name of the executed command" }, "data": { "type": "object", "description": "Data (command execution result) returned by the broker" } }

Example

{
  "command": "listRoles",
  "data": {
    "totalCount": 8,
    "roles": [
      "client",
      "dynsec-admin",
      "inspect-admin",
      "license-admin",
      "streams-admin",
      "super-admin",
      "sys-observe",
      "topic-observe"
    ]
  }
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
409	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker connection does not exist" ], "description": "Message of the error" } }
500	An internal server error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred" ], "description": "Message of the error" } }

---

Path: /api/dynamic-security/{brokerId}/export

Methods

GET

Retrieves the dynamic security data for the specified broker. Must be editor to access

Parameters

Name	Location	Type	Required	Description
brokerId	path	string	true	ID of the broker you want to get the dynamic security data for

Responses

Status	Description	Response Content or Scheme
200	Dynamic security data (broker clients, groups, roles and their ACLs)	{ "clients": { "type": "object", "description": "Information about broker clients" }, "groups": { "type": "object", "description": "Information about broker groups" }, "roles": { "type": "object", "description": "Information about broker roles and their ACLs" } }

Example

{
  "clients": {
    "command": "listClients",
    "data": {
      "totalCount": 2,
      "clients": [
        {
          "username": "admin",
          "textname": "Admin user",
          "roles": [
            {
              "rolename": "super-admin"
            },
            {
              "rolename": "sys-observe"
            },
            {
              "rolename": "topic-observe"
            }
          ],
          "groups": [],
          "connections": [
            {
              "address": "111.111.111.111"
            }
          ]
        },
        {
          "username": "democlient",
          "textname": "Demonstration client with full read/write access to the '#' topic hierarchy.",
          "roles": [
            {
              "rolename": "client"
            }
          ],
          "groups": [],
          "connections": []
        }
      ]
    }
  },
  "groups": {
    "command": "listGroups",
    "data": {
      "totalCount": 2,
      "groups": [
        {
          "groupname": "test",
          "textname": "test",
          "textdescription": "",
          "clients": [],
          "roles": []
        },
        {
          "groupname": "unauthenticated",
          "textname": "Unauthenticated group",
          "textdescription": "If unauthenticated access is allowed, this group can be used to define roles for clients that connect without a password.",
          "clients": [],
          "roles": []
        }
      ]
    }
  },
  "roles": {
    "command": "listRoles",
    "data": {
      "totalCount": 4,
      "roles": [
        {
          "rolename": "client",
          "textdescription": "Read/write access to the full application topic hierarchy.",
          "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": "super-admin",
          "textdescription": "Grants access to administer all kind of broker controls",
          "allowwildcardsubs": true,
          "acls": [
            {
              "acltype": "publishClientSend",
              "topic": "$CONTROL/#",
              "priority": 0,
              "allow": true
            },
            {
              "acltype": "publishClientReceive",
              "topic": "$CONTROL/#",
              "priority": 0,
              "allow": true
            },
            {
              "acltype": "subscribePattern",
              "topic": "$CONTROL/#",
              "priority": 0,
              "allow": true
            },
            {
              "acltype": "unsubscribePattern",
              "topic": "$CONTROL/#",
              "priority": 0,
              "allow": true
            }
          ]
        },
        {
          "rolename": "sys-observe",
          "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
            }
          ]
        }
      ]
    }
  }
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
409	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker connection does not exist" ], "description": "Message of the error" } }
500	Broker is unavailable or some other error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred", "There was a problem accesing the broker" ], "description": "Message of the error" } }

---