Roles & Permissions

FerrisKey uses a bitwise permission system where each permission is a single bit in a 64-bit integer. Roles are named bundles of permissions. Authorization checks reduce to fast bitwise AND operations.

How It Works

Each permission maps to a unique power of two:

CreateClient        = 0b0000...0001  (bit 0)
ManageAuthorization = 0b0000...0010  (bit 1)
ManageClients       = 0b0000...0100  (bit 2)
...

A role stores its permissions as a single u64 bitmask — the OR of all included permission bits. Checking whether a user has a permission is a single AND operation:

fn has_permission(user_permissions: u64, required: u64) -> bool {
    user_permissions & required == required
}

Permissions Reference

Manage Permissions

Query Permissions

View Permissions

Role Mappings

Roles are assigned to users (or service account users) through role mappings. A user’s effective permissions are the union (bitwise OR) of all assigned role bitmasks.

For example, if a user has two roles:

• Viewer with permissions ViewUsers | ViewClients = 0b...10100
• User Manager with permissions ManageUsers | QueryUsers = 0b...01010

Their effective bitmask is 0b...11110 — they can view and manage users, view clients, and query users.

Realm-Scoped Roles

Roles are defined within a realm and apply to all clients in that realm. When a user authenticates, their roles are resolved and included in the access token as claims (via protocol mappers), allowing resource servers to make authorization decisions without calling back to FerrisKey.