Skip to content

delegated-administration.mdx

Latest commit

 

History

History
203 lines (167 loc) · 10.6 KB

delegated-administration.mdx

File metadata and controls

203 lines (167 loc) · 10.6 KB
Raw
title Delegated Administration
description Administration itself as a scoped grant — a business-unit subtree, an action set, and an assignable-set allowlist, with self-escalation structurally impossible (ADR-0090 D12).

Delegated Administration

A group with fifty subsidiaries cannot manage every grant from headquarters — but handing each subsidiary a full admin is worse. ADR-0090 D12's answer: administration itself becomes a scoped capability. A delegate can onboard their own staff and reshuffle their own positions, but can never grant anything outside an explicit allowlist — including to themselves — and can never touch tenant-level assets.

Because the scope lives on an ordinary permission set, it is distributed via positions, audited in the same tables, and explained by the same engine as every other grant. No parallel admin subsystem.

Authoring an admin scope

export const FieldOpsDelegate = definePermissionSet({
  name: 'field_ops_delegate',
  label: 'Field Ops Delegate Admin',
  // The scope authorizes WHAT may be administered…
  adminScope: {
    businessUnit: 'Field Operations',   // WHERE: this sys_business_unit subtree
    includeSubtree: true,               // default true
    manageAssignments: true,            // user ↔ position rows (sys_user_position)
    manageBindings: false,              // position ↔ set rows (sys_position_permission_set)
    authorEnvironmentSets: false,       // may they author environment-owned sets?
    assignablePermissionSets: ['showcase_contributor', 'showcase_manager'],
  },
  // …and plain CRUD on the RBAC link tables lets the requests through at all.
  // Both are required: table CRUD with NO scope is refused outright.
  objects: {
    sys_user_position: { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true },
    sys_position: { allowRead: true },
    sys_permission_set: { allowRead: true },
    sys_business_unit: { allowRead: true },
    sys_business_unit_member: { allowRead: true },
    sys_user: { allowRead: true },
  },
});

businessUnit names the subtree root by sys_business_unit.name; a misconfigured name resolves to an empty subtree and approves nothing (fail-closed).

What the runtime gate enforces

Writes to the governed tables (sys_user_position, sys_position_permission_set, sys_user_permission_set, sys_permission_set, sys_member) pass through the DelegatedAdminGate:

Rule Effect
Tenant admins pass through The superuser wildcard reaches the ordinary CRUD/RLS checks — delegation constrains delegates, not HQ
Subtree anchoring Assignments a delegate creates must be anchored (sys_user_position.business_unit_id) inside their subtree, and the target user must sit inside it
Allowlist, no self-escalation Every set reached by the write — bound to the assigned position, or granted directly — must be on assignablePermissionSets. Granting an un-allowlisted set is refused for anyone, including the delegate themselves
Action flags manageAssignments / manageBindings / authorEnvironmentSets gate their table classes independently; re-composing a position (manageBindings) additionally requires every current holder to sit inside the subtree
Strict containment Granting or authoring a set that itself carries an adminScope requires a held scope that strictly contains it — handing your own exact scope to a peer is refused (no lateral propagation)
Single-row writes Delegates write single rows by id only — a broad filter-write cannot be boundary-checked
Audit stamp Every assignment a delegate creates is granted_by-stamped automatically
Tenant-level assets stay tenant-level The everyone/guest audience anchors and security-domain publishes are untouchable from any delegated scope
Membership is not delegable sys_member writes are tenant-admin-only: no adminScope axis expresses org membership, and an admin-grade membership row is auto-elevated to organization_admin — writing one would mint a tenant admin. Adding people is delegable, through an invitation
No scope, no admin Holders of plain CRUD on the RBAC tables with no scope are refused: administration is a scoped capability now, not a side effect of table access

Every rule above is exercised end-to-end by the showcase permission zoo (packages/qa/dogfood/test/showcase-permission-zoo.dogfood.test.ts): the in-subtree allowlisted assignment passes with a granted_by stamp; the out-of-subtree anchor, the off-allowlist grant (to self), and the manageBindings: false binding write are each refused.

The assignment anchor

Positions never bind to a business unit at the definition level — that would recreate the position-per-department explosion. The assignment row may: sys_user_position.business_unit_id names the unit the person holds the position in ("张三 is sales_manager of 华东"). It does exactly three things: anchors that assignment's depth grants to the subtree, provides the delegation boundary check above, and makes "manager of what" an auditable fact. Capability bits are never BU-scoped.

Explaining delegated decisions

The explain engine closes the loop twice:

  • explaining another user is authorized by manage_users or a delegated adminScope whose subtree covers that user — a delegate can diagnose their own people, and only their own people;
  • contributor attribution plus the granted_by stamp answer both who granted this and who could have.

Reading your own scope

The gate also answers the read question — what may I delegate? — so an admin surface can narrow its pickers instead of offering the whole tree and letting the user discover the boundary by being refused:

GET /api/v1/security/my-delegable-scope
const scope = await client.security.describeDelegableScope();
{
  "isTenantAdmin": false,
  "placeableBusinessUnitIds": ["bu_east", "bu_east_sales"],  // where you may place people
  "assignablePositions": ["sales_rep"],                      // positions you may hand out
  "scopes": [                                                // the scopes those derive from
    { "setName": "sub_admin", "businessUnit": "east", "manageAssignments": true,
      "assignablePermissionSets": ["sales_user"], "businessUnitIds": ["bu_east", "bu_east_sales"] }
  ]
}

Three properties worth knowing:

  • It narrows; it does not decide. The lists are computed by the same helpers the write gate enforces with, so an option here is one the gate accepts — but the gate still runs on the write. A UI that skipped it would be refused, not obeyed.
  • A position appears only if you may hand out every set it distributes. mixed_pos bundling an allowlisted set with a non-allowlisted one is withheld, exactly as the write gate would refuse it.
  • Strictly self-scoped — there is no target-user parameter, so it discloses nothing beyond the authority you already hold. A tenant-level admin comes back isTenantAdmin: true with everything enumerated, so consumers render one uniform picker rather than special-casing.

Scoped invitations (ADR-0105 D8) are the first consumer: the invitation form narrows its unit/position pickers with this, and the invitation's placement intent is then authorized against the issuer's scope at issuance time.

Letting a delegate invite (delegated_admin)

A scope is what you may administer; it does not by itself let you reach the invitation endpoint. The underlying organization plugin grants invitation: ["create"] to owner and admin only — and both of those are auto-elevated to organization_admin (a tenant admin), for whom the scope gate narrows nothing. So the scope-bounded issuance path needs a membership grade that is neither: delegated_admin.

// sys_member — the better-auth membership row
{ "user_id": "usr_plant_admin", "organization_id": "org_acme", "role": "delegated_admin" }

Two independent switches, and you need both:

Grants Without it
sys_member.role = delegated_admin May reach /organization/invite-member Refused by the org plugin before any framework hook runs
An adminScope-carrying permission set What the invitation may place (subtree + allowlist) The gate refuses every placement — the role alone administers nothing

The role carries no ObjectStack authority of its own: it passes through as a position name, and with no sys_position_permission_set binding it resolves to nothing. Role = can reach the endpoint. adminScope = what the endpoint permits. A default deployment is unaffected — nobody holds the role until you set it.

The invitation role cap

An invitation may add a person; it may never add authority above the issuer's own. The framework caps every invitation — placement-carrying or not — at issuance:

  • an invited role may not outrank the issuer's (owner > admin > everyone else);
  • an issuer below admin grade may invite as member only. Not just "not admin/owner": every value stored in sys_member.role projects into current_user.positions, so any tier above plain member is a capability channel too. A delegate's channel for capability is the invitation's placement intent, which this gate allowlists position-by-position — and since ADR-0108 that is the only way capability travels on an invitation, because the tier vocabulary is closed to four framework-owned names;
  • an issuer whose membership cannot be read confers nothing above a plain member (fail-closed).

Without the cap the role would be a ladder: invite an admin, and acceptance auto-elevates that membership to organization_admin → tenant admin — the grade the delegation exists to withhold. sys_member is not one of the gate's governed objects and the acceptance write runs outside the issuer's context, so the cap is the defense on that path.

Both halves are pinned end-to-end over the real HTTP route by packages/qa/dogfood/test/delegated-admin-invite.dogfood.test.ts: a delegated_admin issues a member invitation successfully, the same principal issuing admin is refused with no invitation row left behind, and a plain member still cannot invite at all — so it is demonstrably the role, not some unrelated loosening, that opened the endpoint.

See also