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

LDAP authentication configures the connection to a directory server and the rules for translating directory groups into ControlBird roles. You provide the directory host and port, the connection security (none, LDAPS, or StartTLS), the bind method, the service account and search bases used to locate users and groups, and the mapping from directory groups to ControlBird roles.

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.

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 Shell app requires app.shell, 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 via credentials, an LDAP bind, or an OAuth provider redirect.
3. The credentials are validated and a session is created.
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 Owner user must complete password setup 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.