Documentation › ACL Groups

ACL Groups

Groups are collections of MQTT clients that share a common set of permissions. Assign roles to a group and every client in that group automatically inherits those permissions. This makes it easy to manage access for large device fleets without configuring each client individually.

What Groups Are

A group is a logical container for clients. Its primary purpose is permission inheritance: any role assigned to a group is automatically applied to every client that belongs to that group.

Groups work alongside direct role assignments. A client's effective permissions are the union of:

  1. Roles assigned directly to the client
  2. Roles assigned to each group the client belongs to

This gives you flexible layering: use groups for broad, shared policies and direct role assignments for client-specific exceptions.

Creating a Group

  1. Navigate to ACL > Groups in the sidebar.
  2. Click Add Group.
  3. Enter a Group Name - use something descriptive like sensors, actuators, or monitoring-tools.
  4. Click Save.

The group is created empty with no members and no roles.

Adding Clients to a Group

There are two ways to add a client to a group:

From the Group page

  1. Open the group in ACL > Groups.
  2. Click Add Client.
  3. Select the client from the dropdown.
  4. Click Save.

From the Client page

  1. Open the client in ACL > Clients.
  2. Click Add to Group.
  3. Select the group and click Save.

Both approaches produce the same result. The client immediately inherits all roles assigned to the group.

Assigning Roles to a Group

  1. Open the group in ACL > Groups.
  2. Click Add Role.
  3. Select the role from the dropdown.
  4. Optionally set a priority for this role assignment.
  5. Click Save.

All clients currently in the group immediately gain the permissions defined in that role. Any clients added to the group in the future also inherit this role automatically.

Removing Clients from a Group

  1. Open the group and find the client in the Members list.
  2. Click the Remove button next to the client.
  3. Confirm the action.

The client immediately loses any permissions it was inheriting from this group, unless it has those same permissions through another group or a direct role assignment.

Deleting a Group

  1. Find the group and click Delete.
  2. Confirm the deletion.

Deleting a group removes all its role assignments and removes all clients from it. The clients themselves are not deleted - they remain in your ACL client list but lose the permissions that came from this group.

Permission Inheritance Model

A client's full permission set combines all sources:

Client Effective Permissions =
    (Direct roles assigned to client)
    + (Roles from Group A)
    + (Roles from Group B)
    + (Roles from any other group)
    ...

Example: client sensor-01 belongs to group sensors (role: publish to sensor/#) and group beta-testers (role: publish to beta/#), and also has role alert-publisher (publish to alerts/#) assigned directly. The client can publish to all three topic namespaces.

Practical Use Cases

IoT sensor fleet

Create a sensors group with a sensor-publish role (publish to sensor/#). Add all your sensor clients to this group. When you provision a new sensor device, just create a client and add it to the group - no per-device role configuration needed.

Actuator group

Create an actuators group with an actuator-command role that allows subscribing to actuator/#/command and publishing to actuator/#/status. All actuator devices get their permissions from this group.

Monitoring dashboards

Create a monitoring group with a read-all role (subscribe to #). Add all dashboard clients and monitoring tools to this group. They can observe all traffic without being able to publish.

Environment separation

Create separate groups for production-clients and staging-clients with different topic namespaces. Production clients publish to prod/# and staging clients publish to staging/#. Clean separation, same role structure.

← ACL Roles Connected Clients →