Security & Access Control

Overview

ControlBird implements a hierarchical role-based access control (RBAC) system. Users authenticate through one of several methods, are granted one or more roles, and those roles resolve into an effective set of permissions and responsibilities. The model separates two concerns: UI-layer security (which apps and functional areas a user can see and act on) and data-plane authorization (which entity fields a user can read or write).

Security configuration (users, roles, and permission rules) is managed in the product like any other configuration. When a user signs in, their credentials are validated and the session is resolved into an effective permission set.

Authentication Methods

Each user is configured with an authentication method that determines how their identity is verified at sign-in. Three methods are supported.

Native Authentication

Native passwords are protected with strong password hashing. The password policy is configurable and enforced at sign-in. By default it requires a minimum of 8 characters with at least one uppercase letter, one lowercase letter, one digit, and one symbol.

LDAP Authentication

An LDAP provider, configured in the Permissions Manager, connects ControlBird to an LDAP or Active Directory server. You provide the directory host and port, the connection security, the bind method, and where to find users and groups:

• Connection security must be LDAPS or StartTLS. Sign-in through a provider set to None is refused, because the user's password would cross the network unencrypted.
• Search Then Bind uses a service account to look the user up under the user search base with the user search filter, such as (sAMAccountName={}) for Active Directory or (uid={}) for OpenLDAP. Bind As User builds the user's distinguished name from a template such as uid={},ou=users,dc=example,dc=com and needs no service account.
• Groups are found by searching the group search base with the group search filter when a base is set, and otherwise from the user's memberOf attribute.

An LDAP user signs in with their directory username and directory password. The ControlBird user's name must be that directory username; an LDAP user cannot sign in with an email address, and changes their password in the directory, not in ControlBird. Failed directory sign-ins count toward account lockout like any other.

The first successful sign-in pins the ControlBird user to the directory account it matched. Later sign-ins bind to that same account, and if the username ever resolves to a different directory account, sign-in is refused.

Where an LDAP User's Roles Come From

Each LDAP provider has a Role Source:

• Assigned by hand: the directory only verifies the password. An administrator assigns roles in the Permissions Manager, as for any other user.
• Directory group mappings: the provider's group mappings decide the roles. Each mapping pairs a group's distinguished name with one ControlBird role. At every sign-in, the user's roles are replaced by exactly the roles their groups map to, and the session starts in the least privileged of them. A user whose groups map to no role is refused and their open sessions are ended. The Permissions Manager does not let an administrator edit these users' roles by hand.

Group mappings follow these rules:

• Only groups the user belongs to directly count. Membership inherited through a nested group does not grant a role.
• A mapping can only grant a role that stays within the Administrator role's authority. It can never grant Owner, Playing With Fire, a role that includes either of them, or a role with privilege level 0.
• A user who holds the Owner or Playing With Fire role keeps the roles assigned by hand; group mappings never change them, so the Owner can always sign in.
• Sessions of group-mapped users end after the provider's Directory Session Lifetime and cannot be extended past it. A change to a user's groups in the directory takes effect at their next sign-in, so a shorter lifetime makes group changes apply sooner.

OAuth / OpenID Connect

OAuth / OpenID Connect registers an external identity provider for single sign-on. You can choose a built-in provider type (Google, Microsoft, or GitHub) or configure a generic provider by supplying its authorization, token, and user-info endpoints along with the client ID, client secret, redirect URI, and requested scopes.

API Keys

The command-line tools and AI assistants connect to a node with an API key instead of a password. Any user can create keys from API Keys in the start menu, each with a name and an expiry of 1 to 365 days, and sees each key only once, when it is created. A key acts as the user who created it, with exactly that user's permissions. Each user can hold at most 20 active keys. Revoking a key in the same window disconnects any tool using it within seconds, changing the user's password or deactivating the user disables every key they created before, and Owners can see and revoke every user's keys. See CLI Tools for how to use a key.

Roles, Permissions & Responsibilities

A role bundles UI capabilities and can inherit from other roles. Each role combines two distinct kinds of capability plus inheritance from other roles:

• Permissions: actions a user is allowed to perform, such as opening a specific app.
• Responsibilities: functional areas a user can view and access, such as Security, Design, Debug, Infrastructure, and AI/Development.
• Inherited roles: other roles whose capabilities are inherited.

The distinction matters: permissions control what a user can do, while responsibilities control what a user can see. Permissions and responsibilities are kept separate so that visibility and action capability can be governed independently.

Per-App Permissions

Permissions are named capabilities, and each app requires a specific permission to launch. For example, the Device Manager app requires app.device-manager, and the Permissions Manager app requires app.permissions-manager. A user can launch an app only if their effective permission set contains every permission the app requires.

Role Hierarchy Resolution

When a session is created, the user's assigned roles are resolved recursively: the union of all permissions and responsibilities reachable through role inheritance becomes the session's effective permission and responsibility set.

A user may be assigned multiple roles. The session tracks which role is currently active, and switching the active role recomputes the effective permission and responsibility set dynamically.

Data-Plane Authorization

UI permissions govern the interface, but field-level access is governed separately by permission rules. Each rule matches a resource type and field, grants a scope, and optionally narrows applicability with a CEL condition.

Authorization Scopes

CEL Conditions

The condition accepts a CEL (Common Expression Language) expression that is evaluated at authorization time. This enables attribute-based access control: a rule can grant access only when runtime attributes of the user, the resource, or the request context satisfy the expression. Wildcard matching on the resource type and field combines with conditions to express broad rules that are narrowed precisely.

Sessions

An authenticated session represents the signed-in user, their active role, and the effective permissions and responsibilities that role grants. Sessions have a bounded lifetime and expire automatically.

Session Settings

Session behavior is governed by configurable settings: the password policy (minimum length and the required character classes) and the account-lockout settings. Sessions expire automatically.

Account Lockout

Accounts lock automatically after repeated failed sign-ins. Both the number of attempts that triggers a lock and how long the lock lasts are configurable.

Authentication Flow

The end-to-end flow from credentials to an authorized request proceeds as follows:

1. A user is created (or registers) with an authentication method of Native, LDAP, or OAuth.
2. The user signs in with a password, their directory username and password, or an OAuth provider redirect.
3. The credentials are validated and a session is created. For an LDAP user whose provider maps directory groups to roles, the user's roles are first replaced by the roles their groups grant.
4. The user's assigned roles are resolved into effective UI permissions and responsibilities for the session.
5. The user may switch to any other assigned role; the effective permissions are recomputed dynamically.
6. Data-plane requests are checked against the permission rules by matching resource type, field, and scope, with any CEL condition evaluated for context.

Managing Security

The Permissions Manager app (gated by the app.permissions-manager permission) is the central place to manage users, roles, and permission rules. Because it manages the security model itself, access is restricted to users whose roles grant that permission.

Edition Differences

First-time setup and initial user provisioning differ between editions. For a full comparison, see Editions: Cloud vs CE.

• Community Edition (CE) enforces a first-time setup step: the setup wizard claims the Owner with a password, an OpenID Connect provider, or the Owner's own directory account over LDAP before the system becomes available.
• Cloud deployments auto-create an initial Owner user with all four default roles assigned (Owner, Administrator, Engineer, Operator) and single sign-on enabled.

Cloud Single Sign-On

For cloud deployments, single sign-on is configured automatically: the initial user is signed in without a separate setup step, and the per-deployment domain is provisioned for you.