rbac

pkg/rbac

This package computes effective authority inside UNI after authentication and identity propagation have already happened.

Intent

The package is the platform's effective-authority engine.

It takes authenticated actor context and delegated identity context, resolves roles and group membership from identity storage, and produces ACLs that the rest of the system can enforce.

Its main responsibilities are:

• resolve permissions for users, service accounts, and system accounts
• apply global, organization, and project scope
• prevent confused-deputy behaviour when a service acts as an impersonated principal
• constrain administrative delegation so callers cannot grant authority they do not themselves hold

This package is not just a convenience layer for handler checks. It is part of the security model.

Security Model

The package enforces several important security rules:

• authority is derived from roles via group membership and actor type
• permissions are additive within the allowed role set
• protected roles are internal-only roles and are never user-facing
• a caller may only grant a role if the caller already holds all permissions contained in that role
• when a system service acts as an impersonated principal, the effective ACL is the intersection of the principal's ACL and the service's ACL

Those rules prevent several different forms of privilege escalation:

• user-facing exposure of internal platform roles
• granting permissions the caller does not personally hold
• confused-deputy expansion through service-to-service calls

Scope Model

The package works with the same three logical scope levels defined by identity roles:

• global
• organization
• project

ACL construction and handler enforcement both follow that structure. Global permissions can satisfy organization and project checks, organization permissions can satisfy some project checks, and project permissions remain the narrowest scope.

This scoped structure is used both for direct authorization decisions and for query limiting in list operations.

Actor Model

The package distinguishes three important actor classes:

• users
• service accounts
• system accounts

Users derive access from organization membership, groups, and roles.

Service accounts derive access from their bound organization and group membership.

System accounts derive access from configured platform roles mapped from their authenticated service identity, typically an mTLS certificate common name.

When a system account carries an impersonated principal, RBAC does not simply switch to the principal's ACL. Instead, it intersects the principal ACL with the system account ACL so the service cannot exercise permissions that either side lacks.

Invariants

• Effective authority is computed from stored identity state, not invented ad hoc in handlers.
• Protected roles are not part of normal user-facing role administration.
• Role grantability is bounded by the caller's own effective permissions.
• ACL intersection for impersonated system-account calls is deliberate least-privilege behaviour.
• Service accounts are organization-bound and their scoped access must remain consistent with that binding.
• Group membership is the main route from actors to roles.
• The ACL output is both an enforcement artifact and a visibility artifact, so incorrect ACL construction affects both authorization and UX.

Caveats

• The package is tightly coupled to the identity storage and scoping model, including groups, projects, organization mappings, and label-based queries.
• Some migration-era behaviour is still present, especially compatibility with the deprecated Group.UserIDs field alongside the newer Subjects model.
• The package contains a mix of ACL construction, scope filtering, and handler-facing convenience checks, so it is broader than a pure policy-definition layer.
• Some pragmatic compatibility behaviour exists around scoped lookups and transition paths, so security-sensitive changes here should be reviewed in terms of end-to-end actor behaviour rather than local code shape alone.

TODO

• Re-check places where globally scoped callers are allowed to skip existence verification for user-supplied scoped resource identifiers, especially create paths that accept project IDs in the request body.

Relationship To Other Packages

• pkg/oauth2 establishes actor identity and session/token validity
• pkg/principal carries delegated identity and impersonation signals
• pkg/rbac converts those inputs into effective local authority
• middleware and handlers consume the resulting ACLs to enforce access and shape responses

Related Documentation

• pkg/oauth2, which establishes actor identity, session validity, and local admission before RBAC resolution
• pkg/userdb, which shields RBAC from the raw local identity storage model when resolving users, organization memberships, and service accounts
• pkg/principal, which carries delegated identity and impersonation signals consumed here
• pkg/apis/unikorn/v1alpha1, which defines the stored role, group, organization, project, user, and service-account resources this package resolves