Step 12: Advanced Access Control & Auditing

Master fine-grained permissions, understand the authorization model, and track who changed what.

Docker
Run
Access
Architecture
Explore
Connect
Automate
Alarms
Users
10
Access+
11
Scripts
12
Logs
13
Dashboards
14
Builders
15
Kiosks
16
Themes
17
Config
18
Audio
19
Email

In the previous step, you learned how to manage users and assign roles. This step goes deeper into ControlBird's permission system: how to create fine-grained access rules, understand the authorization model, assign areas of responsibility, and audit every change in your system.

Understanding the Authorization Model

ControlBird uses a hybrid RBAC + ABAC model. This combines the simplicity of role-based access control with the flexibility of attribute-based conditions.

RBAC
Role-Based Access ControlUsers are assigned to Roles. Roles grant permissions.
+
ABAC
Attribute-Based Access ControlPermissions can include conditions based on user or resource attributes.
=
Hybrid
Best of Both WorldsSimple role management with conditional fine-tuning when needed.

Subjects vs Resources

Every permission rule has two sides: a subject (who is requesting access) and a resource (what they're trying to access).

Subject

  • A user account
  • Has one or more assigned roles
  • Has feature permissions
  • Has areas of responsibility
  • Has attributes such as whether the account is active
requests access to

Resource

  • Any item in your system
  • Targeted by type or by a specific item
  • Access can be limited to individual fields
  • Scoped: Read Only or Read and Write

Two Permission Layers

ControlBird separates data access from feature visibility. This allows you to control both what data users can see and which UI features they can use.

Data Permissions

Control access to the data in your system.

You choose:
  • What: a type of equipment or a specific item
  • Which fields: all fields, or a single field
  • Scope: Read Only, or Read and Write
  • Condition: an optional rule that narrows when the permission applies

Feature Permissions

Control which apps, tabs, or actions are visible in the interface.

Feature permissions:
  • Are named for the feature they grant (for example, viewing dashboards)
  • Are granted through roles
  • Can be turned on or off for a session
  • Determine which features appear in the interface

Permission Resolution

Data permissions apply to every read and write. Add permission rules to define exactly which users can see and change which parts of your system.

Creating Conditional Permissions

A permission can include an optional condition that narrows when it applies. Conditions are evaluated against the requesting user's attributes, so the same rule can behave differently depending on who is asking.

Example Conditions

Grant access only while the user account is active.
Grant access only to users in a particular department.
Grant access only to users who hold a specific role, such as Supervisor.
Leave the condition empty to grant the permission unconditionally.

Role Hierarchy

Roles can inherit from other roles. This creates a hierarchy where a parent role automatically includes all permissions from the roles beneath it.

AdministratorFull access
inherits from
EngineerConfigure + Operate
AuditViewerRead audit logs
OperatorMonitor + Control
ViewerRead-only access

Permissions flow down the role hierarchy. If you assign a user the Administrator role, they automatically receive all permissions from the Engineer, Operator, and Viewer roles.

Duties: Areas of Responsibility

Responsibilities define the domains, zones, or functional areas a user is accountable for. Unlike permissions, which control access, responsibilities indicate what a user is accountable for.

Example Responsibilities

Building A - HVACResponsible for all HVAC equipment in Building A
Night Shift OperationsOn-call for after-hours monitoring
Safety SystemsAlarm acknowledgment authority for safety alarms
Production Line 3Primary operator for production line equipment

Responsibilities are assigned through roles, or directly to a user for session-specific duties. A user's effective responsibilities combine both their role-based and session-selected responsibilities.

Comprehensive Auditing

ControlBird provides multiple audit mechanisms to track who did what, when, and where. This is essential for compliance, troubleshooting, and security investigations.

Change History

Every change is recorded with full context:

Who made the change (the user account)
Timestamp: when the change occurred
The entity that was modified
The field that was changed
The new value written

Alarm History

Alarm events capture operator actions for compliance:

Who acknowledged the alarm, and when
Who shelved the alarm, and the reason they gave
The event type: state change, acknowledged, shelved, and so on

Historian

Time-series history with configurable retention:

Record on every value change, or on every write
Capture related values alongside each record
Set how long recent and archived history are kept

User Access Tracking

Login activity and account security:

The most recent successful login is recorded for each account
Repeated failed sign-in attempts temporarily lock an account to protect against guessing

Viewing Audit Data

You can inspect audit data with the cb-cli command-line tool, or by reading fields directly in the Database Browser.

bashQuery with cb-cli
# Read a field with metadata (shows the last writer and timestamp)
cb-cli read "/Devices/Thermostat" "Temperature" --metadata

# Output includes:
# Value: 72.5
# Timestamp: 2024-01-15T14:32:01Z
# WriterId: User:admin

Real-Time Notifications Include Writer ID

When you subscribe to field changes, each notification also carries the identity of whoever made the change. Your UI or scripts can use this to show who modified a value in real time.

Best Practices

Use Role Hierarchy

Create a base "Viewer" role and build up from it. Changes to the base propagate automatically.

Separate Data from Features

Use data permissions to control access to your system's data, and feature permissions to control app features. Don't conflate the two.

Assign Responsibilities Meaningfully

Responsibilities should reflect actual job functions, not just copy permissions.

Configure History Retention

Set how much change history is kept to match your compliance requirements.

Troubleshooting

Permission is denied but the user has the right role

Check these in order:

  • Session refresh: the user may need to log out and back in after role changes
  • Condition: if the permission has a condition, confirm the user's attributes satisfy it
  • Field coverage: verify the permission covers the specific field, not just the type
  • Target match: a permission can target a type of item or a specific item, so make sure it matches what the user is accessing
How do I see who made a specific change?

Use cb-cli read with the --metadata flag to see who last changed a field, or read the field in the Database Browser. For alarm actions, the alarm itself records who acknowledged or shelved it.

Responsibilities aren't showing for a user
  • Verify the role includes the responsibility
  • Check that the user has selected that role as their active role
  • Confirm the user's effective responsibilities, which combine their role-based and session-selected responsibilities
A condition never grants access
  • Attribute names and text values are case-sensitive, so match them exactly
  • Use cb-cli to check the user's actual attribute values
  • Test with an empty condition first to confirm the base permission works

Coming Up Next

Now that you understand advanced access control, learn how to extend ControlBird's capabilities with custom JavaScript scripts for business logic beyond visual automations.