Undore RBAC

RBAC made easy for Ascender Framework

UndoreRBAC is a lightweight, configurable role-based access control (RBAC) system designed for seamless integration with the Ascender Framework.

Its goal is to separate permission-evaluation logic and priority rules from data storage, provide a flexible manager interface for fetching permissions/roles, and offer an easy-to-configure permission map.

---

Core concepts

• RBAC Map - a YAML file that declares all available permissions and their configuration (default, explicit, children).
• RBAC Manager - the user-implemented bridge between your database and UndoreRBAC. You implement methods for authentication and for fetching roles/permissions.
• RBACGate - You will use this the most: an object that represents a single user’s access state; it performs all the comparison, inheritance, and override logic.
• Permissions carry a boolean value (True/False). This allows both granting and explicit denial of permissions.

---

Basic behavior rules

1. Priority (from lower to higher; later items win in conflicts):

   • children permissions
   • roles (shared permissions) - roles with higher priority take precedence
   • scoped permissions (permissions assigned directly to the user)
   • wildcards (regardless of which hierarchy level they are assigned to)

2. Wildcard (*), e.g. users.*, means “everything under users.” - but a wildcard can be overridden by a permission marked explicit in the RBAC Map.

3. explicit: true - a permission marked explicit ignores wildcard/override propagation. Use with caution.

Important note on Wildcard priority

Wildcards are the highest in priority. Even if a wildcard permission is assigned to a lower priority role or children permission, it CANNOT be overwritten by a higher priority permission (if it is not a wildcard itself)

For example, if user has scoped permission users.manage on value True and also has a role, which has a wildcard permission users.* on value False, access will be denied, regardless of the fact that scoped permissions are higher in the hierarchy

---

Quick start

1) Implement BaseRBACManager

BaseRBACManager is an abstract class. You must implement:

• authorize(token: str, request: Request | None = None, custom_meta: dict | None = None) -> user_id
• fetch_user_access(user_id: Any, custom_meta: dict | None = None) -> Access

where Access contains:

{
  "permissions": list[IRBACPermission],
  "roles": list[IRBACRole],
  "user": Any | None
}

Note

• Make sure fetch_user_access returns data in a predictable order if your logic depends on creation time or role priority.
• The library can enforce require_sorted_permissions in RBACConfig by default, so it’s best if the manager returns sorted data.

---

2) Create rbac_map.yml

Permissions can be declared in two styles: nested YAML or dot-notation. Example:

users:
  delete:
  view:
    other:

auth.login:

audit.export:
  _config:
    default: false
    explicit: true
    children:
      - users.view: true
      - users.delete: false

_config options:

• default - the default boolean value for this permission when the user has no record for it.
• explicit - if true, this permission cannot be obtained only via wildcard/children inheritance.
• children - a list of permission:value pairs that are applied automatically when this permission is present.

---

3) Initialization in Ascender Framework

In your bootstrap.py:

from undore_rbac.interfaces.config import RBACConfig
from undore_rbac.rbac_module import RbacModule
from shared.custom_rbac_manager import CustomRBACManager
import os

appBootstrap: IBootstrap = {
    "providers": [
      RbacModule.for_root(
          RBACConfig(
              rbac_manager=CustomRBACManager(),
              rbac_map_path=os.path.join(BASE_PATH, "rbac_map.yml"),
              require_sorted_permissions=True
          )
      )
   ]
}

Notes

• rbac_map_path should point to the YAML file you prepared.
• require_sorted_permissions=True tells the library to expect manager-provided permission records in created_at order

---

4) Guard - usage examples

Simple Guard

---

Note: Refer to official Ascender Framework docs for Guard and ParamGuard endpoint usage examples

---

class RBACGuard(Guard):
   def __init__(self, *permissions: str):
      self.permissions = permissions

   def __post_init__(self, rbac: RbacService):
      self.rbac = rbac
      self.manager = rbac.manager

   async def can_activate(self, request: Request, token: HTTPAuthorizationCredentials = Security(HTTPBearer())):
      user_id = await self.manager.authorize(token.credentials, request=request, custom_meta={"org_id": 123})

      gate = await RBACGate.from_user_id(user_id, custom_meta={"org_id": 123})
      status, reason = gate.check_access(self.permissions)
      if status is False:
         raise InsufficientPermissions(request_url=request.url.path, required_permission=reason)

ParamGuard (recommended to avoid duplicated DB calls)

class RBACParamGuard(ParamGuard):
    def __init__(self, *permissions: str):
        self.permissions = permissions

    def __post_init__(self, rbac: RbacService):
        self.rbac = rbac
        self.manager = rbac.manager

    async def credentials_guard(self, request: Request, token: HTTPAuthorizationCredentials = Security(HTTPBearer())):
        user_id = await self.manager.authorize(token.credentials, request=request)
        
        if self.permissions:
           gate = await RBACGate.from_user_id(user_id, custom_meta={"org_id": 123})
           status, reason = gate.check_access(self.permissions)
           if status is False:
               raise InsufficientPermissions(request_url=request.url.path, required_permission=reason)
            
           user = gate.user
        else:  # Save performance if permission check is not needed
           user = ... # Your user GET logic
          
        # Your pydantic model for creds kwarg in endpoint
        return AuthCredentials(
            user=user  # You can also pass the gate here to reuse it later
        )

Note: gate.user is not populated automatically by the library. If you want gate.user available, your fetch_user_access implementation must return a user field inside the Access object.

---

Detailed priority and override logic

1. Collect all permission records (scoped + shared) and roles for the user.
2. RBACGate calculates children (using the RBAC Map) for every permission.
3. Permissions are then applied in this order:
   • Children (applied first),
   • Roles (applied next - consider role.priority and assignment created_at),
   • Scoped permissions assigned directly to the user (applied last - strongest).
   • Wildcards
4. When conflicting permissions have the same effective priority, the most recent record (by created_at, or the order provided by the manager) wins.
   • If you rely on DB timestamps or insertion order, ensure fetch_user_access returns results in the expected order (Enabling require_sorted_permissions rises an exception if the sorting is wrong).

---

Best practices & recommendations

• Log concise check summaries at debug level (do not log tokens or sensitive data).
• Avoid overusing explicit: true - it can silently block wildcard inheritance causing confusing denials.
• Cache Access per-request (e.g., in request.state) or use ParamGuard to prevent multiple DB hits in the same request.
• Be careful with wildcards: Always keep in mind that wildcards override EVERYTHING and they don't care about higher-priority roles and permissions

---

---

Common pitfalls and how to avoid them

1. Wildcard permissions not taking effect - check if the target permission has _config.explicit: true in the RBAC Map.
2. Permissions must be sorted by created_at Exception - ensure permissions are sorted as exception suggests or turn of this requirement in RBACConfig (not recommended)
3. Heavy DB workload - cache Access for the lifetime of the request or use ParamGuard to do a single fetch.

---

Thank you for using UndoreRBAC.

Undore <github.com/Undore>