Model authorization rules

Authorization Modeling

When to Use

Use when designing, reviewing, or refactoring roles, permissions, access policies, ownership rules, or approval requirements in an application.

The Six-Question Authorization Decision Tuple

Never model authorization as a flat user.role === 'admin' check. Every policy rule must answer six questions explicitly:

1. Who is the Initiating Principal (Subject)? Human user, API key, webhook principal, or AI agent (plus the delegating user if acting on behalf of someone).
2. In Which Organizational Scope & Capacity? Active tenant/workspace membership, department/team assignment, and active role(s).
3. Which Action (Verb) on Which Target Resource (Object)? E.g., quote:create, quote:edit, quote:submit, quote:approve, quote:export.
4. Which Resource State, Ownership, Relationship, or Value Threshold Applies?
   • State: A draft quote is editable by its owner; an approved or invoiced quote is immutable even by its owner.
   • Relationship: Account owner, department manager, project collaborator, or direct report.
   • Threshold: Discounts > 15% or orders > 10,000 EUR require manager approval.
5. Is Delegation or Explicit Approval Required? Does the action execute immediately (ALLOW), require a co-signer (REQUIRE_APPROVAL), or rely on a time-bounded delegation grant?
6. What Happens When Conditions Change Later? What if the resource owner changes, the quote total is edited after approval, or the user's role is revoked while a job is queued?

Choosing the Right Paradigm (Without Over-Engineering)

Adapt to the project's existing policy/gate layer and combine models only where warranted:

• RBAC (Role-Based Access Control): Map roles (sales_rep, sales_manager, finance_approver, auditor) to explicit permission capabilities (quote:approve), never scattering raw role names across controllers. Apply role hierarchy only where business rules genuinely state a higher role inherits all lower permissions (often false under Separation of Duties—e.g., an engineering_lead or system_admin must not automatically have permission to approve their own expense report!).
• ABAC (Attribute-Based Access Control): Evaluate subject attributes (user.departmentId), resource attributes (quote.status === 'draft', quote.discountPct <= 15), and environment constraints.
• ReBAC (Relationship-Based Access Control): Derive permissions from domain graph edges (user -> owner_of -> account -> parent_of -> opportunity).

Build an Explicit Authorization Matrix First

Before writing enforcement code, document a concrete Subject $\times$ Resource State $\times$ Action Matrix with real examples, highlighting edge cases, exceptions, and conflicting rules (deny-overrides vs. explicit exception grants).