Roles, Teams & Owners

Overview — what it does

Roles and Teams are informational labels for classifying people. The one and only thing that opens access to screens and actions is the level (user_level). What a user can see, and what they may save or delete, is decided 100% by level; roles ("DBA", "DevOps", "Security") and teams ("Infra Team", "Security Team") are display/organization tags that grant no permissions whatsoever.

This keeps the permission model simple. To give someone admin power you raise their level — you do not change their role. Tagging a user "Security" does not open the security screens; their level must be Staff (5) or higher.

This article covers three things:

1. Roles (infr_role) — six job labels (DBA, DevOps, Security, Admin, Staff, Developer).
2. Teams (infr_team) — organizational units, used for user membership and asset ownership.
3. The Owner picker — a combined dropdown that lets you assign either a user or a team, with App\Support\Owners as its single source of truth. The "owner" field on Instances, Hardware and Storage uses it.

Access control = level (user_level) only. Roles and teams open no permissions programmatically. See Understanding levels (RBAC) for the level system.

When to use

• Onboarding a new person and tagging their job (role) and membership (team).
• Reorganizing — creating a team or changing its lead.
• Assigning an owner (a person or a team) to server, hardware or storage assets so "who is responsible for this" is explicit.
• Auditing / handover: looking up "who owns this asset".

Layout

/admin/users (Administration ▸ Users & Roles) has two tabs.

The user edit modal has level / role / team selectors, followed by this hint:

Level decides access — Demo (read) · Staff (operate) · Admin (everything). Roles are for display.

How to use

Roles — job labels

The role master is six entries, upserted idempotently by key by InfrRoleSeeder.

• A user has at most one role (users.role_id, nullable). It may be unset.
• Roles appear only as a label/color in the top-bar user dropdown and list badges.
• The display label is resolved by App\Support\RolePolicy::roleLabel($roleId) with a 60-second cache (call RolePolicy::flush() after changes).

The role admin (label "Admin") has nothing to do with the admin level (10). A role is just a label, so a user whose role is "Admin" but whose level is Demo (1) can save nothing. Conversely, a level-10 admin has full administration even with an empty role.

Teams — organizational units

Teams are freely CRUD-managed in the Teams tab. The four seed teams:

Team edit fields:

• A user belongs to at most one team (users.team_id, nullable).
• On team delete: the team_id of that team's members is set to null (the users remain, now unassigned). Assets that referenced the team via owner_type='team' are a separate concern, so the assets themselves are not deleted.

The Owner picker — users + teams combined

Assets (server instances, hardware, storage) have an "owner" field that may be either a person or a team. The rules for this combined picker live in App\Support\Owners (the SOT).

Storage shape = two columns

The asset table stores the owner in two columns.

Front-end exchange shape = a single ref string

The browser (forms, filters) exchanges owner_type and owner_id as one string.

user:5     → user id 5
team:3     → team id 3

The bootstrap options (Owners::options()) return the two groups for optgroup rendering (20-second cache). Closed users (is_close=1) and inactive teams (is_active=0) are excluded.

{
  "users": [ { "ref": "user:5", "id": 5, "name": "Jane Doe" } ],
  "teams": [ { "ref": "team:3", "id": 3, "name": "Infra Team" } ]
}

Server-side split / rebuild

For example, the instance save controller does this:

// owner ref ("user:5"/"team:3") → owner_id + owner_type
[$ownerType, $ownerId] = Owners::split($request->input('owner_ref'));
$payload['owner_id']   = $ownerId ?: null;
$payload['owner_type'] = $ownerId ? $ownerType : 'user';   // default 'user' when unset

The same ref is used when filtering by owner — the list query splits the owner parameter (user:5/team:3) with split() and narrows to WHERE owner_id = ? AND owner_type = ?.

The Owner picker is reused identically on the Instances, Hardware and Storage & Files asset screens. Assigning a team as owner puts the whole team on the responsibility line (robust to any one person leaving).

Avatar · initials · color

The avatar shown next to a label is generated from the name by RolePolicy.

• Initials (initials): CJK/Korean → first character; Latin names → first letter of the first and last word (2 chars).
• Hue (hue): crc32(name) % 360 for a stable HSL background.
• Level tone (tierTone): admin (≥10) = crit · staff/operate (≥2) = accent · demo = muted.

Data sources

SOT helpers:

• App\Support\Owners — combined owner picker (options/split/ref/resolveName/flush).
• App\Support\RolePolicy — level labels/tones, role labels (60-second cache), avatar initials/color.

Access

• Entry to the whole screen is admin-only. /admin/* is protected by the group middleware infr.level:10, and UserController / TeamController re-check the session user_level >= 10 (RolePolicy::ADMIN) themselves. Demo (1) and Staff (5) get a 403.
• Level thresholds (reference): write ≥ 2 (RolePolicy::WRITE, blocks demo) · administer ≥ 10 (ADMIN) · development/observability ≥ 9 (DEV, includes admin 10).
• On user save, user_level is restricted to one of 1,5,10.
• Every user/team change is audited to infr_audit_log (team.create / team.update / team.delete, user save/delete, etc.).

Safeguards (last-admin protection)

Troubleshooting & FAQ

Q. I gave someone the "Security" role but the security screens won't open. Roles are labels; they open no permissions. The security screens (mostly read) need a level — raise them to Staff (5) or higher. See RBAC levels.

Q. Some user/team is missing from the owner dropdown. Closed users (is_close=1) and inactive teams (is_active=0) are excluded from the picker. Re-activate the user/team, or if the list is stale wait for the 20-second cache to expire (Owners::flush() invalidates it immediately).

Q. If I delete a team, do its people disappear? No. The users remain; only their team_id becomes null (unassigned). An asset's owner_type='team' reference is separate, so the asset is not deleted either (its owner display just becomes empty).

Q. I saved an owner but no name shows. resolveName() is a 20-second cache. If you just renamed something it refreshes shortly. Also confirm the ref format is user:5/team:3 — a broken format is treated by split() as unassigned (user:0).

Q. Can a user have two roles? No. role_id is a single (nullable) value. If you need organizational grouping too, use a team (also a single value).

Related

• Understanding levels (RBAC) — the only axis that actually decides access
• Users & Teams console — /admin/users CRUD details
• Instances — the flagship asset screen that uses the Owner picker
• Hardware — physical asset owners
• Storage & Files — storage asset owners
• Audit log — history of user/team/owner changes