vitepress-template

Appearance

Role-Based Access Control (RBAC) ​

**Referenced Files in This Document** - [[rbac.go]](file/bi-common/auth/rbac.go) - [[middleware.go]](file/bi-common/auth/middleware.go) - [[claims.go]](file/bi-common/auth/claims.go) - [[context.go]](file/bi-common/auth/context.go) - [[auth.proto]](file/bi-common/api/auth/v1/auth.proto) - [[client.go]](file/bi-common/auth/client.go) - [[rbac.go]](file/bi-sys/internal/middleware/rbac.go) - [[rbac.go]](file/bi-sys/internal/server/rbac.go) - [[rbac.go]](file/bi-tenant/internal/server/rbac.go) - [[role_grpc.pb.go]](file/bi-tenant/api/tenant/v1/role-grpc.pb.go)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document describes the Role-Based Access Control (RBAC) system across the platform. It explains how roles and permissions are modeled, how permissions are evaluated at runtime, and how the system integrates with authentication middleware and RPC-based providers. It also documents the APIs for role management and permission checking, and outlines patterns for dynamic UI rendering (menus, feature toggles) based on permissions.

Project Structure ​

The RBAC system spans shared authentication utilities, service-specific middleware, and RPC contracts:

  • Shared authentication utilities define JWT claims, middleware composition, permission evaluation, and RPC client/provider abstractions.
  • System service (bi-sys) provides centralized RBAC enforcement and permission retrieval.
  • Tenant service (bi-tenant) provides client-side permission retrieval and a combined provider that routes management requests to bi-sys via RPC.
  • Role management APIs are exposed via gRPC in the tenant service.

Diagram sources

Section sources

Core Components ​

  • PermissionProvider: Abstraction for retrieving a user’s permission set by user ID.
  • PermissionCache: Optional caching layer for user permissions.
  • RBACConfig: Holds whitelist, providers, management path pattern, cache, and optional path-to-permission function.
  • RBACMiddleware: Enforces access control by path classification (-m for management), skipping checks for super/admin, and delegating to providers for permission lookup and evaluation.
  • Permission evaluation supports exact match, wildcard suffix (module:), and wildcard prefix (module:resource:).
  • AuthMiddlewares: Composes JWT authentication followed by RBAC middleware when configured.

Key behaviors:

  • Management APIs (paths containing -m) route to bi-sys RPC for permission checks.
  • Client APIs use either local provider or bi-tenant RPC depending on configuration.
  • Super/admin users bypass permission checks.

Section sources

Architecture Overview ​

The RBAC enforcement pipeline:

  • JWTAuthMiddleware validates tokens and injects user info into context and metadata.
  • RBACMiddleware inspects the request path to decide whether to use management or client provider.
  • Providers resolve permissions (directly or via RPC), cache results, and evaluate against required permission.

Diagram sources

Detailed Component Analysis ​

Shared RBAC Utilities (bi-common/auth) ​

  • PermissionProvider and PermissionCache define the contract for permission retrieval and caching.
  • RBACMiddleware orchestrates:
    • Whitelist checks
    • User extraction from context
    • Management path detection
    • Super/admin bypass
    • Provider invocation with caching fallback
    • Required permission derivation (default path-to-permission rules)
    • Permission evaluation with wildcards
  • Path-to-permission helpers support method-aware mapping (GET list/get, POST create, PUT/PATCH update, DELETE delete).

Diagram sources

Section sources

Authentication Middleware Composition ​

  • AuthMiddlewares composes JWTAuthMiddleware followed by RBACMiddleware when providers are configured.
  • SimpleAuthMiddleware provides JWT-only mode for endpoints that do not require permission checks.

Section sources

JWT Claims and Context Helpers ​

  • Claims carries user identity, tenant/dept/org scopes, role IDs, and admin flags.
  • UserInfo is derived from Claims and injected into context and Kratos metadata for cross-service propagation.
  • HeaderAuthMiddleware enables trust-mode where downstream services read user info from headers.

Section sources

System Service RBAC (bi-sys) ​

  • Provides a dedicated RBAC middleware for internal enforcement.
  • Uses a PermissionChecker to fetch permissions and caches them via a Cache instance.
  • Computes required permission from path and enforces access.

Section sources

Tenant Service RBAC (bi-tenant) ​

  • Implements a PermissionProvider that resolves user role IDs and aggregates role permissions.
  • Provides a CombinedPermissionProvider that:
    • Routes management APIs to bi-sys via RPC client.
    • Uses local provider for client APIs.
  • Exposes IsManagementAPI helper to detect management endpoints.

Section sources

RPC Contract for Auth Services ​

  • AuthService defines VerifyToken, GetUserPermissions, CheckPermission, RefreshToken, and InvalidateToken.
  • AuthClient wraps RPC calls for clients to invoke bi-common auth services.

Section sources

Role Management APIs (gRPC) ​

  • RoleService exposes CRUD and operational endpoints for roles, including:
    • ListRole, GetRole, CreateRole, UpdateRole, DeleteRole, BatchDeleteRole
    • UpdateRoleMenus, UpdateRoleStatus
    • GetRoleTemplates, UpdateRoleTemplates
    • ListRoleOptions, GetAvailableMenus

These endpoints enable role creation, modification, deletion, and menu visibility updates.

Section sources

Dependency Analysis ​

  • bi-common/auth/rbac.go depends on:
    • apitypes/codes for standardized error codes
    • Kratos middleware/transport for request context and HTTP transport
  • bi-common/auth/middleware.go composes JWTAuthMiddleware and RBACMiddleware.
  • bi-sys RBAC middleware depends on:
    • Cache for permission caching
    • PermissionChecker for permission retrieval
  • bi-tenant CombinedPermissionProvider depends on:
    • AuthClient for bi-sys RPC
    • Local PermissionProvider for client APIs

Diagram sources

Section sources

Performance Considerations ​

  • Caching: RBACMiddleware supports PermissionCache to reduce provider/RPC calls. Prefer enabling cache for high-traffic endpoints.
  • Wildcard evaluation: Permission checks support wildcards; keep permission sets concise to minimize loop iterations.
  • Provider selection: Management APIs use bi-sys RPC; ensure low-latency connectivity and consider connection pooling.
  • Token propagation: Metadata injection avoids repeated decoding; maintain small payload sizes for role IDs.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common issues and resolutions:

  • Unauthorized: Occurs when Authorization header is missing or invalid, or when token is expired/blacklisted.
  • Forbidden:
    • Management endpoints return forbidden if TenantID is not zero or if required permission is missing.
    • Client endpoints return forbidden if required permission is missing.
  • Internal error: Returned when provider fails to fetch permissions.
  • Permission mismatch:
    • Verify path-to-permission mapping aligns with endpoint paths.
    • Confirm wildcard permissions are correctly formed (e.g., module:, module:resource:).

Operational checks:

  • Ensure JWTAuthMiddleware precedes RBACMiddleware in the chain.
  • Validate that PermissionProvider/ManagementProvider are configured appropriately for the service.
  • Confirm cache is initialized and functional to avoid repeated provider calls.

Section sources

Conclusion ​

The RBAC system provides a flexible, extensible framework for enforcing access control across services. It separates concerns between JWT authentication and permission evaluation, supports both local and RPC-based providers, and offers caching and wildcard permissions for scalability and expressiveness. Role management APIs in the tenant service enable administrators to manage roles and menus, while middleware ensures runtime enforcement consistently across endpoints.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​

RBAC Data Model ​

  • Users carry identity, tenant/dept/org scope, role IDs, and admin flags.
  • Roles are associated with permissions via role-to-permissions mapping.
  • Permissions are strings with module/resource/action semantics and wildcard support.

[No sources needed since this diagram shows conceptual model, not actual code structure]

Permission Evaluation Examples ​

  • Exact match: sys:user:list equals sys:user:list
  • Wildcard suffix: sys:* matches sys:user:list
  • Wildcard prefix: sys:user:* matches sys:user:get

Section sources

API Endpoints for Role Management ​

  • RoleService (tenant):
    • ListRole, GetRole, CreateRole, UpdateRole, DeleteRole, BatchDeleteRole
    • UpdateRoleMenus, UpdateRoleStatus
    • GetRoleTemplates, UpdateRoleTemplates
    • ListRoleOptions, GetAvailableMenus

Section sources

Dynamic UI Rendering Patterns ​

  • Menu visibility: Use GetAvailableMenus to filter visible menus per user.
  • Feature toggles: Gate features based on presence of specific permissions.
  • Conditional rendering: Evaluate permissions client-side using cached or fetched permission lists.

[No sources needed since this section provides general guidance]

Integration with Authentication Middleware ​

  • Compose JWTAuthMiddleware followed by RBACMiddleware.
  • Use SimpleAuthMiddleware for endpoints requiring only login.

Section sources

Audit Logging for Role Changes ​

  • Record role assignments and modifications with operator context.
  • Log permission changes and enforcement decisions for compliance.

[No sources needed since this section provides general guidance]