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 (MMC).
Before sending command request make sure that you have been authenticated.
Enable Dynamic Security REST API
To enable the Dynamic Security REST API, make sure you are using the Pro Edition of Mosquitto and that you have the feature enabled in your license. Also, ensure that your config file (specified with CEDALO_MC_PROXY_CONFIG environmental variable or by default saved in management-center/config/config.json) contains the following entry inside of the plugins array:
{
"name": "dynamic-security-rest-api"
}
On start-up, the Management Center will print a message that the dynamic-security-rest-api plugin is enabled and loaded into the console:
Loaded plugin: "cedalo_dynamic_security_rest_api" (Cedalo Dynamic Security REST API)
Authenticate / Login
In order to use the REST API you first need to authenticate. Note that after a successful login a cookie is created that contains the session id. This cookie needs to be passed to any further request to the API. For example when using the curl command you can use the --cookie-jar option for storing that cookie automatically and the --cookie option for further requests to automatically read that cookie and pass it with the request.
The following command shows how to authenticate using curl. Please replace the <BASE_URL>, <USERNAME> and <PASSWORD> placeholders accordingly:
<BASE_URL>: The base URL where the installation of the Management Center is hosted (including the protocol and base path, e.g., https://mosquitto.cedalo.com).<USERNAME>: The name of the user which has access to the REST API.<PASSWORD>: The password of the user which has access to the REST API.
curl --cookie-jar .cookies \
--request POST <BASE_URL>/auth \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d "username=<USERNAME>&password=<PASSWORD>"
You can check if authentication worked by issuing the following request:
curl --cookie .cookies \
--request GET http://localhost:8088/api/profile \
-H 'Content-Type: application/json'
Sending command requests
The following command shows how to send command requests 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>'
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
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