Authorization platform

Authorization does not ask whether a user signed in. It asks whether this trusted caller may perform this action on this resource, in this tenant, now. Several policies contribute evidence, and the result must remain auditable, invalidatable, and reproducible.

1. One capability, two source areas

The runtime is split between Framework and Platform code:

Platform owns policy facts; Framework evaluates them. A business module must not query Authorization tables or reproduce policy with local role checks.

2. Request-to-decision path

The authorization behavior executes before the transaction behavior. A denial returns Authorization.Denied, skips the handler, and must not start a transaction. AuthorizationPipelineBehaviorTests.Deny_Should_Prevent_Transaction_From_Starting fixes this ordering.

3. Evaluators are not independent gates

Every evaluator runs before the final merge. Any Deny rejects; otherwise one or more Allows permit; all Neutral yields NoMatchingPolicy. Registration order affects the first denial reason and obligation order, but placing Feature last is not what gives Deny priority.

See decision engine for the algorithm, cache key, DataScope, and audit behavior.

4. Management plane versus decision plane

The management plane changes roles, bindings, permissions, ABAC, Feature, field policy, classification, sharing, and delegated grants through owner-local stores. A workflow-approved access request is a separate, absolutely expiring authorization source. The decision plane reads trusted subjects, resource facts, policy stores, and caches; it never calls a management handler.

public sealed record ApproveInvoiceCommand(
    string InvoiceId,
    decimal Amount,
    string Status,
    string Sensitivity) : ICommand<Result>, IAuthorizedRequest
{
    // The same descriptor feeds the RBAC code, ABAC facts, and instance-level ReBAC.
    public ResourceDescriptor Resource => new(
        Module: "billing",
        ResourceType: "invoice",
        ResourceId: InvoiceId,
        TenantId: TrustedTenantId,
        Status: Status,
        Amount: Amount,
        Sensitivity: Sensitivity);

    // The action participates in permission derivation and policy filtering.
    public AuthorizationAction Action => AuthorizationAction.Approve;

    // Use the caller's trusted tenant accessor, never a tenant supplied in the body.
    private string TrustedTenantId => CurrentTenantAccessor.EffectiveTenantId;
}

This complete contract example uses CurrentTenantAccessor as a stand-in for the caller’s trusted tenant port. In production, load owner, status, amount, and sensitivity from server-side data rather than accepting self-declared facts.

5. The current model is not a Role aggregate

Earlier prose described a Role.Grant() aggregate, but the implementation uses explicit store records:

See RBAC management and role lifecycle for stable-key and write-path details.

6. Management endpoints

Grant and revoke commands now use AuthorizationAction.Grant and AuthorizationAction.Revoke, matching the public permission catalog. User-role assignment and revocation invalidate the target subject’s permission and menu caches rather than the actor’s.

7. Cache and event boundaries

• Role and role-permission changes publish events and invalidate the tenant Permission cache.
• ABAC CRUD invalidates the effective tenant’s Permission decision cache.
• Feature updates publish FeatureChangedIntegrationEvent; a global-default change invalidates all Feature entries, while an override targets one tenant.
• The decision cache key covers caller, claims, tenant, client, all resource facts, and action; Delegated callers bypass it.
• DataScope and ReBAC use independent caches and require independent invalidation.

Role changes use AuthorizationSubjectCacheInvalidation for the target subject and cross-instance menu synchronization. Group relationships, field policy, sharing rules, and temporary grants retain separate sources and invalidation paths; clearing the Permission cache does not refresh every derived catalog. See configuration, persistence, and caching.

8. Chapter map

9. Source review commands

Run from the BitzOrcasVNext root:

# Read both halves of the capability: runtime decisions and policy management.
rg -n "class AuthorizationDecisionService|class .*PolicyEvaluator|class .*Role" \
  src/Framework/BitzOrcas.Application/Authorization src/Platform/Authorization -g '*.cs'

# Grant and Revoke actions must remain isomorphic with the public catalog.
rg -n "AuthorizationAction\.(Grant|Revoke)|role-permission\.(grant|revoke)|user-role\.revoke" \
  src/Platform/Authorization -g '*.cs'

# Every invalidation must target the changed user, tenant, resource, or Feature.
rg -n "InvalidateBy(User|Tenant|Resource)Async" \
  src/Platform/Authorization src/Framework/BitzOrcas.Application/Authorization -g '*.cs'

10. Minimum GA evidence

1. Every request-derived permission exists in the catalog.
2. Assignment and revocation invalidate the target subject’s decisions and menu projection immediately.
3. ABAC, ReBAC, and Feature failures retain fail-closed behavior.
4. Consumers convert DataScope into query filters and prove tenant isolation.
5. Cache hits recompute DataScope and audit the call; delegated sessions never outlive their grant through cache.
6. Field security, sharing, delegation, and temporary grants have no unregistered owner execution surfaces.
7. Both ORM contracts, seed idempotency, and global permission/Feature uniqueness pass.

Next: decision engine · Back to module catalog