Privilege-based access control (PBAC) overview in Alphabet

Alphabet’s PBAC system lets you define fine-grained privileges, assign them to roles or users, and evaluate access at runtime via the API.

Alphabet extends ASP.NET Core Identity roles with a privilege-based access control (PBAC) layer. Instead of checking only whether a user belongs to a role, your API can check whether that user holds a specific named permission — such as report.export or user.delete. This gives you precise, auditable control over capabilities without restructuring your existing role hierarchy.

Key concepts

Privilege — A named permission that follows resource.action format, for example user.delete or report.export. Each privilege has a stable name that serves as its identifier across the lifetime of your application. You can attach metadata such as a display name, description, resource type, actions, dependencies on other privileges, and arbitrary key-value attributes.

Category — An organizational grouping for privileges. Categories can be nested to form a hierarchy, letting you browse and filter the permission catalog by domain (for example, Reporting > Analytics > Export). Categories are informational and do not affect evaluation.

Policy — A composite object that groups multiple privileges under a single named unit. When you assign a policy to a role or user, all privileges in the policy are evaluated together. You choose the evaluation condition:

• AllRequired — the user must hold every privilege in the policy.
• AnyRequired — the user must hold at least one privilege in the policy.

Assignment — The act of granting a privilege (or policy) to a role or directly to a user. Assignments can carry an optional expiresAt timestamp. Role assignments affect every member of that role. Direct user assignments are scoped to a single user.

Effective privileges — The resolved set of permissions for a user at evaluation time. Alphabet computes this as:

1. All privileges granted through the user’s roles (including via policies assigned to those roles).
2. All privileges granted directly to the user (including via policies assigned directly to the user).
3. Minus any privileges that are directly denied on the user.

A direct deny assignment on a user overrides any role-based allow for the same privilege. Use direct denies intentionally — they are designed for explicit exceptions, not routine access revocation.

How evaluation works

When Alphabet evaluates a privilege check, it resolves the user’s effective privileges using the union of role grants and direct user grants, then subtracts direct user denies. The result is cached per user for CacheDurationMinutes (default: 5 minutes). Direct user assignments invalidate that user’s cache immediately; role-level changes take effect after the cache TTL expires.

Configuration reference

The following settings in appsettings.json under PrivilegeSettings affect runtime behavior:

Setting	Default	Effect
CacheEnabled	true	Enables per-user caching of effective privilege snapshots.
CacheDurationMinutes	5	How long a cached privilege snapshot is considered fresh.
EnableAuditLogging	true	Logs all privilege creation, assignment, revocation, and evaluation events.
MaxPrivilegeRequestDurationDays	30	Maximum duration a user can request through self-service.
AdminRoles	["Admin", "PrivilegeManager"]	Roles that can manage the privilege catalog and assignments.

Privilege management endpoints require membership in one of the AdminRoles. End-user self-service endpoints require only a valid authenticated session.

Privilege naming

Name privileges using stable resource.action identifiers. Choose names that reflect business capabilities, not UI labels.

Good: report.export, invoice.approve, user.delete

Avoid: export-button-visible, admin-panel-access, can-click-delete

Privilege names are immutable after creation. They are used as the stable identifier in code ([PrivilegeAuthorize("report.export")]), authorization policies, and audit logs. Renaming a privilege requires creating a new one and migrating all assignments.

What’s in this section

Privilege catalog

Create and manage privileges, categories, and composite policies.

Roles and users

Assign privileges to roles or individual users, run bulk operations, and inspect effective access.

Self-service requests

Let users request temporary elevated access through an approval workflow.