RBAC & Scoping

Authorization has independent mandatory axes. Roles decide what a human principal may do through five coarse permissions and, for selected high-impact mutations, a closed typed operation capability. Scopes decide where the principal may do it along two axes: site and environment. A request must pass every applicable axis. Human routes publish their exact current permission or functional-capability requirement; protocol entry points use separate public, agent, or webhook classes. These access values are enforcement metadata, not roles.

Boundary convergence

This page documents the current RBAC vocabulary and scope behavior. Production acceptance additionally requires the Platform Security Boundary Specification: all human and non-human authenticators normalize to one verified principal; every route and internal operation maps to a typed action; the decisive policy check evaluates the final canonical resource; and approval, transition, and audit obligations are enforced atomically. The current path/permission and handler-local checks are migration inputs, not the final control ownership model.

Roles and permissions

The current entra-id implementation uses twelve fixed Entra app-role values. Each maps to one or more permissions; coarse authorization checks permissions, while approval workflows additionally use canonical role names for approval routing and quorum bookkeeping. This provider-specific mapping is transitional; the target accepts allowlisted claims from any configured authenticator and normalizes them before policy evaluation. See Entra App Registration for the full role matrix and how the roles claim is issued.

The coarse execute tier is not authority for every functional domain. The server evaluates these typed capability identifiers before dispatch and repeats the check in the protected handler:

PlatformAdmin and BreakGlassAdmin satisfy these capabilities through the explicit admin superuser rule. A capability never substitutes for object ownership, site/environment scope, approval, state-transition, or audit checks.

The current roles: PlatformAdmin, BreakGlassAdmin, DatacenterApprover, VMwareOperator, HyperVOperator, ProxmoxOperator, WintelLinuxOperator, BackupOperator, MonitoringOperator, ServiceDesk, Auditor, and Requester.

In current Entra mode, role assignment for people happens in the Entra enterprise application, not in Ryuki. Unknown roles on a token mint are rejected. Future providers must use an explicit, provider-qualified claim mapping; role strings never select a verifier or link identities.

The current BreakGlassAdmin mapping grants standing admin and is transitional. In the target model the external role establishes eligibility only: a separate, stepped-up, audited, short-lived activation grants emergency authority, and the role claim by itself grants none.

Route access classes

The API Reference's Access value for a human route is its exact current request, audit, execute, or admin tier. Safe reads do not inherit one generic read class: the router owns a closed requester-readable manifest and new or unclassified reads default to audit.

The former generated read label is retired because it hid the difference between requester-owned/static reads and audit-only data. Protocol classes explain why the complete surface still cannot be described using only human permissions. Scope and resource predicates continue after the route tier; the tier alone never proves ownership or final-resource authorization.

Scopes

A principal's current session representation carries a site scope and an environment scope, each a list of allowed values. The current implementation interprets an empty list as unrestricted on that axis. That is a migration encoding, not the production target: unrestricted, unknown/unresolved, not-applicable, and explicitly empty authority must be distinct validated states, so a missing or malformed claim cannot widen access.

Today, scopes are carried by API tokens: interactive sessions (Entra ID or local auth) are unscoped, and the development auth modes run as an unscoped admin. Preserve that behavior only to operate current development/migration deployments. To give a current integration a narrower blast radius, mint it a scoped token; production acceptance requires explicit effective scope on every actor kind under the canonical security context.

Enforcement semantics

The same rules apply across all scoped domains:

Platform-wide rows and nullable axes

Some resources have optional site or environment columns. A NULL axis means "no value on that axis," not "visible to everyone":

• A row is platform-wide, and visible to any scoped principal, only when both site and environment are NULL.
• A row with a concrete site and NULL environment is invisible to an environment-scoped principal, and vice versa. The rule is symmetric.
• For by-id reads of single-axis resources, a platform-wide row is reachable only by unrestricted principals.

Managing API tokens

Tokens are create-and-revoke: there is no edit. To change a token's roles or scope, mint a replacement and revoke the old one.

This is the current role-based compatibility-token model. The production target uses a credential-family id and version, an exact Ryuki audience, a closed action allowlist (or role ceiling translated to actions), explicit site/environment scope state, mandatory short TTL, and audited last-use/revocation metadata. Rotation shows the replacement once, permits only a bounded overlap, then revokes the prior version. Service tokens cannot satisfy interactive, step-up, or break-glass obligations. See service credentials and API tokens.

Authentication modes

In the current compatibility implementation, RYUKI_AUTH_MODE selects how sessions are established; it never enables live provider calls (that is a separate, operator-gated setting). The target registry and explicit deployment profile replace this switch; a missing profile or simultaneous legacy and registry authority selection fails before binding unless a time-bounded, non-authorizing migration overlay names the single source of truth.

A note on the portal

The portal filters navigation and actions by role for usability, but that is convenience, not security: every rule above is enforced server-side, and the API answers the same regardless of which client asks.