BigRAE Workspaces¶
Account hierarchy and legacy organization/workspace tenancy above user-owned ranges.
Account scope introduced by ADR-066¶
An Account is the stable owner of customer resources. Its closed kinds are
individual, team, and enterprise. An individual account may own resources
directly. Team and enterprise accounts own one or more organizations, and each
organization owns one or more workspaces. New business account hierarchies have
exactly one default organization and one default workspace per organization.
The default workspace cannot be archived while it carries that designation.
Account memberships contain a principal UUID, not a role or an inherited grant.
They express account association only; authorization remains at the owning
resource or workspace boundary.
workspaces.services creates accounts and their default hierarchy, and resolves
a ResourceScope for new account-owned resources. The scope contract in
shared.identity_scope has an explicit installation or account kind, an
account UUID, and optional organization and workspace UUIDs. Owning domains store
these values as scalar columns and never take a cross-layer foreign key.
The read-only legacy mapping classifier in workspaces.identity_mapping accepts
explicit owner evidence and principal UUID mappings. It produces deterministic
individual or business-account mappings, or named blockers for ambiguous legacy
data. Existing personal-workspace rows and API behavior stay on the legacy path
until the S8 cutover; ambiguous rows must be resolved before that cutover.
The remainder of this page documents the current legacy workspace API.
Governing decision: ADR-046. Design guardrails: organization/workspace preflight, membership/roles preflight, range-scoping preflight, and administration-console preflight.
What this domain is for¶
A university, research lab, or hosting operator runs one BigRAE deployment as shared infrastructure. An organization owns workspaces, a workspace has members with roles, and a range is scoped to a workspace in addition to its individual owner. Multi-organization deployments use the same model, so no single-tenant assumption is baked into the schema.
An organization is only a grouping of workspaces and members. It is not an
OIDC issuer, a cloud account or project, a Django auth.Group, a CTF event, an
API-token audience, an SPA navigation area, a Terraform workspace, or a range
network boundary.
Models¶
| Model | Purpose |
|---|---|
Organization |
Tenancy grouping that owns workspaces; carries the editable profile (name, description, support_email, support_url) |
Workspace |
Scope that holds members and owns range scope; belongs to exactly one organization |
WorkspaceMembership |
One user's role in one workspace |
OrganizationMembership |
One user's organization-level role (ADR-048); the persisted organization authority seam |
Invariants enforced in the database:
- a workspace belongs to exactly one organization (non-null FK);
- a workspace name is unique within its organization;
- a user has at most one membership per workspace;
- membership role is one of
owner,admin, ormember; - a user has at most one personal workspace (
personal_for_useris unique); - a user has at most one organization membership per organization, and its role
is the closed
OrganizationRolevocabulary (initiallyadmin).
Both Organization and Workspace carry an internal integer primary key and an
immutable public uuid. Internal orchestration and the integer
shared.audit entity id use the primary key; public surfaces accept and emit
only the UUID, so callers cannot enumerate tenants by counting primary keys.
A workspace has no owner_user column. Ownership is a membership row, so there
is one place authority is recorded.
Service interface¶
workspaces.services is the only module other layers may import. They must not
import workspaces.models, and they must not hold a ForeignKey to a workspace
(ADR-001-R2 forbids cross-layer FKs).
| Function | Purpose |
|---|---|
resolve_personal_workspace(user) |
Return the user's personal workspace, creating it on first use |
authorize_workspace(actor, workspace_uuid, operation) |
Authorize against an untrusted, externally supplied workspace UUID |
authorize_bound_workspace(actor, workspace_id, operation) |
Authorize against a trusted, already-persisted internal binding |
authorize_launch_workspace_locked(actor, workspace_id, operation) |
Authorize a bound scope under the workspace mutex; run inside the reservation transaction so membership cannot be revoked mid-launch |
get_self_membership(actor, workspace_uuid) |
Return the actor's minimum membership projection |
list_workspace_memberships(actor, workspace_uuid) |
Return the roster to an owner or admin |
add_workspace_member(...) |
Add an existing active account with a closed role |
change_workspace_member_role(...) |
Change a role under the owner boundary |
remove_workspace_member(...) |
Remove another member while retaining an owner |
leave_workspace(...) |
Remove the actor's own non-personal membership |
get_organization_profile(actor, organization_uuid) |
Return the organization profile projection, authorized by org-admin membership or superuser (ADR-048) |
update_organization_profile(actor, organization_uuid, changes, *, audit) |
Atomically apply a partial profile update under the same authority, strict-audited |
Authorization functions return a frozen WorkspaceAuthorization (workspace
ID, public UUID, organization ID, role) and never an ORM instance. Membership
queries and commands return frozen minimum projections.
engine.services.rebind_range_workspace_by_request is the Engine half of the
rehoming operation; CMS owns the decision and calls it so the Engine range's
scope moves with the CMS projections.
Denials raise
WorkspaceAuthorizationError with a single message. A missing workspace, a
non-membership, and a role that does not permit the operation are deliberately
indistinguishable, because the difference is a tenant-enumeration oracle.
Membership commands lock the workspace as their transaction mutex and recheck the actor's live grant while locked. They retain at least one owner, reserve owner changes to owners, protect personal-workspace ownership, and write a strict audit record in the same transaction.
Role policy and API¶
The closed role policy is owned in workspaces.roles; callers ask the service
about an operation and do not compare role strings themselves. All roles can
act on their own workspace-bound resources, subject to the existing range
owner, source, lifecycle, CTF, and remote-access checks. Owners and admins can
manage the roster, but only owners can grant or revoke ownership.
Organization-level authority is a separate accepted model (ADR-048), not a
workspace role. OrganizationMembership holds an org-scoped admin role and is
the only source of organization authority; it is never derived from a workspace
role, Django staff/groups or model permissions, provider claims, API-token
scopes, or cloud roles (ADR-046-R8/R12). A Django is_superuser is the sole
platform-operator override—able to read/update any organization, audited
distinctly—while is_staff alone grants nothing. Each personal organization
seeds its personal-workspace owner as its bootstrap admin only on the legacy
compatibility path (at resolve_personal_workspace creation and by the #1939
backfill). ADR-066 supersedes that rule for the account hierarchy: individual
accounts have no organization/workspace, and creating a team or enterprise
default hierarchy grants no organization or workspace role. An organization may
have no administrator until a separately authorized grant operation creates an
explicit membership. See
org-workspace-admin-console.md for the
organization profile API and settings surface.
The DRF routes are mounted below /api/v1/workspaces/{workspace_uuid}/. Reads
require the exact workspaces:membership:read API-token scope and changes
require workspaces:membership:write. Session authentication and API-token
scope checks establish the actor but never replace the service-layer role
check. The API returns minimum projections and the shared sanitized error
envelope.
How ranges are scoped¶
cms.Request, cms.RangeInstance, and engine.Range each carry a scalar
workspace_id column. It is a soft reference, matching the existing
RangeInstance.range_id / user_id and UserProfile.active_ctf_event_id
convention, because cross-layer ForeignKeys are prohibited.
The CMS range-create facade resolves and authorizes the scope once, then carries
it beside the RequestSpec—the same shape as the backend_admission binding—so Engine persists it in the range's create transaction. Engine never resolves
or authorizes a workspace itself.
An interactive launch may select a workspace by supplying its public UUID
(workspace_uuid) on the launch command; omission binds the launcher's personal
compatibility workspace, so existing single-user clients are unchanged. Only the
public UUID is accepted—an internal integer, role, organization ID, or name is
never trusted from HTTP—and a malformed, unknown, unauthorized, or non-member
selection is denied with the single non-enumerating message rather than falling
back to the personal workspace. Because a shared-workspace membership can be
revoked concurrently, the reservation reauthorizes the resolved scope under the
workspace row mutex (authorize_launch_workspace_locked) and holds that lock
across the request/range insert, so a removal committing mid-launch cannot leave
a range scoped where its owner cannot reach it. A single pre-reservation
workspace launch-admission seam (admit_workspace_launch) that both the
cyberscript and RAES paths pass through is the one attachment point for a future
durable per-workspace quota or effective workspace egress policy; the initial
policy admits with no additional limit and does not change the
(user_id, range_source) active-range constraint. Engine idempotent create is
defense in depth: a create replay whose workspace_id differs from the persisted
range is refused as a binding conflict rather than silently reused.
Range.user, cms.Request.user, and cms.RangeInstance.user_id remain the
range's owner. Workspace membership is workspace-level authorization only: it
grants no SSH, RDP, VPN, Guacamole, or CTF access to another member's range.
Every interactive CMS operation on a persisted range binding also asks the
workspace service for read_range, manage_range, or access_range.
Collection reads omit ranges whose membership has been revoked; point and
mutation operations return a non-enumerating denial. Mission Control reaches
terminal, SSH, and RDP through CMS's authorized facade before Engine resolves
credentials. System-attributed expiry and provider callbacks bypass this human
role gate so cleanup cannot be stranded by membership removal.
Reassigning a range's owner requires the new owner to be a member of the range's
workspace, so a range is never left scoped to a tenant its owner cannot reach.
For a handover that legitimately crosses tenants—a pre-provisioned CTF spare
range being given to a participant—the caller asks for it explicitly with
reassign_range_owner(..., rehome=True), and the range's scope moves to the new
owner across all three projections inside the reassignment transaction.
Rehoming is never implicit.
The invariant is enforced in two places, not by convention:
- The database. All three columns are non-null with no default
(
cms.0040_workspace_binding_required,engine.0042_workspace_binding_required). An unscoped range is not a reachable state. A default would let a creation path persist a placeholder tenant, which is what the constraint exists to prevent. - The Engine creation boundary.
engine.services.create_rangeandcreate_raes_rangetakeworkspace_idas a required argument and refuse a missing one, so a caller that forgets it fails loudly at the seam rather than at an integrity error deep in a transaction.
The columns were introduced nullable so historical rows could be validated and backfilled without a default silently assigning one tenant to everyone, then made mandatory once that completed.
Compatibility¶
Before the S8 cut, every legacy user owns one personal workspace inside its own
personal organization. The 0002_backfill_personal_workspaces migration creates
them for existing accounts and the CMS/Engine backfills bind existing ranges to
their owner's workspace, so the current compatibility runtime behaves as before.
ADR-066 retires that model at the hard cut: an individual account then owns
resources directly and has no organization or workspace.
There is deliberately no shared deployment-wide "Default" organization. A global default would make every install single-tenant by construction and would have to be unpicked before a second tenant could exist.
The backfill proves historical ownership evidence is consistent before it writes anything: if a range projection disagrees with its request, or CMS and Engine disagree about who owns a range, the migration stops with a diagnostic naming the row (never an email or credential) rather than guessing a tenant. The non-null migrations run after it, so an upgrade that could not resolve a row fails there instead of silently leaving it unscoped.
The upgrade is tested against the real historical schema
(tests/workspaces/test_backfill_migration_schema.py): it migrates the database
back to the nullable state, seeds genuinely unbound rows, and migrates forward.
That is the only way to exercise the path, since the current models can no longer
express an unbound row.
What stays deployment-global¶
Tenancy scopes principals and range ownership. It does not scope platform configuration or catalog. These remain deployment-global and do not acquire a workspace binding as a side effect of this layer (ADR-046-R7):
- the scenario catalog and RAES package sources;
- the agent, operating-system, instance-type, and app catalogs;
- NGFW instances and platform network/infrastructure;
- cloud provider, range-backend, and deployment settings, including the environment manifest;
- identity-provider configuration and the API-token scope registry;
- the durable audit store;
- feature flags;
- CTF events, teams, and participants, which stay a separate membership model.
Each of these carries platform-operator authority rather than tenant authority, so scoping any of them to a workspace needs its own decision. A workspace-level policy surface—the zero-egress range posture in issue #1171, for example—is added by an explicit decision on that surface, never inherited from here.
Identity provider integration¶
Not implemented. The integration point is decided: provider group and claim
mapping happens after the existing config.oidc / config.identity_platform
adapters have verified issuer, audience, authorized party, subject, and verified
email and bound the Django user—the same position config.organizer_authority
occupies for CTF organizer authority. Any future mapping must be an allowlisted,
deployment-configured adapter with membership provenance, revocation, and strict
audit, writing through the workspace service. A provider group name is external
evidence, never a workspace UUID or a role code, and auth.Group /
UserProfile.cognito_groups are never the membership store.