Authorization — Aquilia Documentation
Comprehensive guide and documentation for Authorization in the Aquilia framework. View API reference, examples, and implementation patterns.
Security & Auth / Authorization Authorization Engine Aquilia's authorization subsystem coordinates RBAC (Role-Based), ABAC (Attribute-Based), scope checks, and tenant isolation policies into a unified, high-performance evaluation coordinator named AuthzEngine . Decision Model Aquilia evaluates authorization requests using a tri-state decision model. This allows policies to explicitly permit access, explicitly deny access, or abstain to let downstream policies decide. , , , ].map((d, i) => ( ))} Context & Result Structures Authorization requests are represented by `AuthzContext`, which holds the security principal ( Identity ), resource ID, action, scopes, roles, attributes, and tenant ID. Evaluators produce `AuthzResult` objects: from aquilia.auth.authz import Decision, AuthzContext, AuthzResult # AuthzContext - Input parameters for evaluating policies ctx = AuthzContext( identity=current_identity, # The authenticated Identity object resource="orders:1234", # The resource being accessed action="delete", # Action name scopes=["orders:read", "orders:write"], # Scopes derived from JWT/Session roles=["editor"], # Roles attached to the principal tenant_id="tenant_company_a", # Tenant ID for isolation check attributes= , # Resource attributes for ABAC ) # AuthzResult - Output describing decision outcome result = AuthzResult( decision=Decision.ALLOW, reason="Identity is resource owner", policy_id="owner_only", ) Unified AuthzEngine The AuthzEngine aggregates all sub-engines. It provides explicit helper checks for scopes, roles, permissions, and tenant mismatches, as well as a sequential ABAC policy evaluation pipeline. Default Deny: If no policy explicitly returns ALLOW or DENY, the engine falls back to a secure default deny decision. from aquilia.auth.authz import AuthzEngine # Initialize with sub-engines engine = AuthzEngine(rbac=rbac_engine, abac=abac_engine) # Configure order of ABAC policy runs engine.set_policy_order(["owner_can_edit", "business_hours_only"]) # 1. Pipeline check: runs ABAC policies, returning first non-ABSTAIN result result = engine.check(ctx) # 2. Enforcement: raises AUTHZ_POLICY_DENIED on Decision.DENY engine.authorize(ctx, raise_on_deny=True) # 3. Direct checks (raise specific faults on authorization failure) engine.check_scope(ctx, required_scopes=["orders:write"]) # Raises AUTHZ_INSUFFICIENT_SCOPE engine.check_role(ctx, required_roles=["admin"]) # Raises AUTHZ_INSUFFICIENT_ROLE engine.check_permission(ctx, permission="orders:delete") # Raises AUTHZ_RESOURCE_FORBIDDEN engine.check_tenant(ctx, resource_tenant_id="tenant_b") # Raises AUTHZ_TENANT_MISMATCH # 4. Utilities: filter allowed actions for a resource permitted_actions = engine.list_permitted_actions( identity=current_user, resource="orders:1234", actions=["read", "write", "delete"] ) Guards Role-Based Access Control (RBAC) )
Go to Homepage