Skip to main content

RBAC (Role-Based Access Control)

1. Overview (What does this do?)​

The RBAC (Role-Based Access Control) module provides a granular mechanism for restricting access to specific API endpoints or Service methods based on the permissions assigned to the currently authenticated user. It exposes the @require_roles decorator for declarative access control.

2. Philosophy (Why does it exist?)​

Hardcoding if user.role == "admin" statements inside controller logic leads to scattered, unmaintainable, and highly insecure code. The philosophy of this component is to extract access control entirely out of the business logic and enforce it at the pipeline boundary. If a user does not have the required role, the request is terminated before the domain logic is ever invoked.

3. Target Audience (Who is it for?)​

This module is for developers building multi-tenant SaaS applications, administrative dashboards, or any system where different users (e.g., standard users, editors, superadmins) require different levels of access to the system resources.

4. Architecture (How does it work?)​

When an HTTP or gRPC endpoint is called, the authorization token (JWT or PASETO) is validated at Layer 3 of the Onion Pipeline. The token payload contains the user's "claims", which include their list of roles. The @require_roles decorator operates at Layer 4. It intercepts the call before executing the controller, checks the local context for the extracted roles, and compares them against the required roles defined in the decorator.

5. Installation / Setup​

RBAC functionalities are automatically available when you install ferrox-py-auth. No additional database setup is required for basic RBAC, as the roles are inherently expected to be embedded directly within the cryptographic token payload.

6. Quickstart (Usage)​

from ferrox_py_auth.security.rbac import require_roles

class AdminController:
    
    # Restrict this endpoint to users who have at least one of these roles
    @require_roles("superadmin", "editor")
    async def delete_article(self, request, article_id: str):
        # Execution only reaches this point if the token contains a matching role
        return {"status": "Article deleted successfully"}

7. Ecosystem Integration​

The RBAC decorator is tightly integrated with the core Web & Transports Component. By operating entirely on the Request context generated by the Security Component's Auth Guards, it remains agnostic to the underlying web framework (e.g., FastAPI), allowing it to secure both HTTP REST endpoints and WebSocket connections uniformly.