RBAC Configuration Guide

Detailed Guide to Role Permission Configuration

Basic Concepts · Configuration Steps · Best Practices

🎯 Overview

RBAC (Role-Based Access Control) is NextJS Base's permission management system, managing user access permissions through roles.

Core Concepts

User
   │
   └─── Has Role ───► Role
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
    Permission        Menu        Inherit Menu Permissions
   (Permission)     (Menu)     (inheritMenuPermissions)
         │               │
         ▼               ▼
    Server Actions    Page Access

📚 Basic Concepts

Permission

Permissions define operations users can perform:

Field	Description	Example
`name`	Permission name	View Post, Create Post
`parentId`	Parent ID (supports tree)	null / Parent permission ID
`crudCategory`	CRUD category	post, user, role
`actions`	Associated Server Actions	['sysGetPostList', 'sysCreatePost']
`apis`	Associated API paths	['/api/v1/posts']

Menus define admin sidebar display:

Field	Description	Example
`name`	Menu name	Post Management
`parentId`	Parent ID (supports tree)	null / Parent menu ID
`url`	Page path	/admin/content/posts
`icon`	Icon	FileTextOutlined
`permission`	Associated permission ID array	['perm_id_1', 'perm_id_2']

Role

Roles are collections of permissions and menus:

Field	Description	Example
`name`	Role name	admin, editor
`permission`	Permission ID array	['perm_id_1', 'perm_id_2']
`menu`	Menu ID array	['menu_id_1', 'menu_id_2']
`inheritMenuPermissions`	Whether to inherit menu permissions	true / false

📝 Configuration Steps

Step 1: Create Permissions

Create permissions in the "Permission Management" page:

Post Management (Parent Permission)
├── View Post
│   └── actions: ['sysGetPostList', 'sysGetPostDetail']
├── Create Post
│   └── actions: ['sysCreatePost']
├── Edit Post
│   └── actions: ['sysUpdatePost']
└── Delete Post
    └── actions: ['sysDeletePost', 'sysBatchDeletePost']

Configuration Example:

Field	Parent Permission	Child Permission (View Post)
Name	Post Management	View Post
Parent	-	Post Management
CRUD Category	post	post
Actions	[]	['sysGetPostList', 'sysGetPostDetail']

Step 2: Create Menus

Create menus in the "Menu Management" page:

Content Management (Parent Menu)
├── Post Management
│   ├── URL: /admin/content/posts
│   ├── Icon: FileTextOutlined
│   └── Associated Permissions: [View Post, Create Post, Edit Post, Delete Post]
└── Category Management
    ├── URL: /admin/content/categories
    └── Associated Permissions: [View Category, Create Category, ...]

Step 3: Create Roles

Create roles in the "Role Management" page:

Admin Role:

Field	Value
Name	admin
Permissions	[] (can be empty)
Menus	[All menus]
Inherit Menu Permissions	✅ Yes

Editor Role:

Field	Value
Name	editor
Permissions	[View Post, Create Post, Edit Post]
Menus	[Post Management]
Inherit Menu Permissions	❌ No

Step 4: Assign Roles to Users

Assign roles to users in the "User Management" page:

Find target user
Click "Edit"
Select role in "Role" field
Ensure "Backend Access" is enabled
Save

🔐 Permission Check Flow

Action Permission Check

// 1. Call Server Action
sysGetPostListAction()

// 2. wrapAction parses Action name
//    - Prefix: sys → requires admin permission
//    - Operation: GetPostList

// 3. Check if user has admin access permission
if (!user.hasBackendAccess) {
  throw new Error('No admin access permission')
}

// 4. Get all permissions of user's roles
const permissions = await getUserPermissions(user.roles)

// 5. Check if Action is in permission list
const allowedActions = permissions.flatMap(p => p.actions)
if (!allowedActions.includes('sysGetPostList')) {
  throw new Error('No permission to perform this operation')
}

// 6. Execute business logic

User permissions = Union of role's explicit permission and all "inherit menu permissions" roles' menu-associated permissions. Implementation location: app/(admin)/actions/dao/sys.js#getUserPermissionIds.
Inheritance logic: If role inheritMenuPermissions === true, add each menu's permission from the role's menu together, then deduplicate.
Action matching: Permissions' actions (supports wildcards like sysCreateExample*) are extracted and matched against current Server Action by checkUserHasActionPermission.
Example: Menu "with permissions" associates permission "example write(no delete)" whose actions include sysCreateExample*/sysUpdateExample*/sysBatchUpdateExample*/sysActivateExample*/sysDeactivateExample*. After granting this menu to a role and checking "Inherit Menu Permissions", then granting the role to a user, the user ultimately has the above action permissions.

// 1. Get user roles
const roles = await getRoles(user.roles)

// 2. Aggregate all menu IDs
const menuIds = roles.flatMap(r => r.menu)

// 3. Get menu details
const menus = await getMenus(menuIds)

// 4. Filter enabled and non-hidden menus
const visibleMenus = menus.filter(m => m.enable && !m.hidden)

// 5. Build menu tree and render sidebar

🎨 Configuration Examples

Example: E-commerce System Permissions

Product Management
├── View Product [sysGetProductList, sysGetProductDetail]
├── Create Product [sysCreateProduct]
├── Edit Product [sysUpdateProduct]
├── Delete Product [sysDeleteProduct]
└── Toggle Product Status [sysToggleProductStatus]

Order Management
├── View Order [sysGetOrderList, sysGetOrderDetail]
├── Process Order [sysUpdateOrder]
├── Cancel Order [sysCancelOrder]
└── Export Order [sysExportOrder]

User Management
├── View User [sysGetUserList, sysGetUserDetail]
├── Edit User [sysUpdateUser]
├── Ban User [sysBanUser]
└── Reset Password [sysResetUserPassword]

Example: Role Configuration

Super Admin:

{
  name: 'super_admin',
  permission: [],  // Empty, use menu inheritance
  menu: ['All menu IDs'],
  inheritMenuPermissions: true,
}

Operator:

{
  name: 'operator',
  permission: [
    'View Product', 'Edit Product', 'Toggle Product Status',
    'View Order', 'Process Order',
  ],
  menu: ['Product Management', 'Order Management'],
  inheritMenuPermissions: false,
}

Customer Service:

{
  name: 'customer_service',
  permission: [
    'View Order',
    'View User',
  ],
  menu: ['Order Management', 'User Management'],
  inheritMenuPermissions: false,
}

✅ Best Practices

1. Permission Granularity

✅ Recommended: Fine-grained permissions
├── View Post
├── Create Post
├── Edit Post
└── Delete Post

❌ Not Recommended: Coarse-grained permissions
└── Post Management (includes all operations)

2. Use CRUD Category

// ✅ Recommended: Use crudCategory for grouping
{
  name: 'View Post',
  crudCategory: 'post',  // Easy to filter and manage
  actions: ['sysGetPostList'],
}

// ✅ Admin: Use inheritance to simplify configuration
{
  name: 'admin',
  menu: ['All menus'],
  inheritMenuPermissions: true,  // Automatically get menu-associated permissions
}

// ✅ Regular Role: Explicitly assign permissions
{
  name: 'editor',
  permission: ['Specific permissions'],
  menu: ['Edit-related menus'],
  inheritMenuPermissions: false,  // Precise permission control
}

4. Permission Naming Convention

{Module Name} - {Operation}

Examples:
- Post Management - View
- Post Management - Create
- Post Management - Edit
- Post Management - Delete

5. Regular Auditing

Regularly check role permission configuration
Remove unused permissions
Check if user role assignments are reasonable
Review operation logs for anomalies

Permission Model

RBAC architecture design and data model

Menu Management

Mapping relationship between sidebar navigation and permissions

wrapAction API

Reuse authentication and logging in Actions

Permission Configuration Template

Permission configuration standards ready to use

Server Actions Development

Backend implementation combined with RBAC