Module: User Permission Management (UPMS)
Relevant source files
The following files were used as context for generating this wiki page:- zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/manage/UpmsUserController.java
- zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/manage/UpmsRoleController.java
- zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/manage/UpmsPermissionController.java
- project-datamodel/zheng.sql
- zheng-upms/README.md
- zheng-upms/zheng-upms-rpc-api/src/main/java/com/zheng/upms/rpc/api/UpmsApiService.java
- zheng-upms/pom.xml
The User Permission Management (UPMS) module is a universal platform for fine-grained permission control. It is built on a foundation of both Role-Based Access Control (RBAC) and direct user-based authorization. The module provides core functionalities including single sign-on (SSO), centralized session management, and comprehensive logging. It is designed to be extensible, allowing consuming systems to define their own structures for organizations, roles, permissions, and resources.
Key features of the UPMS module include management of systems, organizations, users, roles, and permissions, as well as a robust permission assignment system. It serves as the central authority for authentication and authorization across various integrated systems.
Sources: zheng-upms/README.md:5-9
Architecture Overview
The UPMS module is a multi-layered system composed of several sub-modules that handle specific responsibilities, from data access to client-side integration.
The following diagram illustrates the high-level architecture of the UPMS module and its components.
- zheng-upms-server: The main server application containing the RESTful API controllers for managing users, roles, permissions, etc. It also hosts the user interface.
- zheng-upms-rpc-service: Implements the business logic and exposes it via RPC.
- zheng-upms-rpc-api: Contains the service interface definitions (
UpmsApiService) used by both the server and client modules. - zheng-upms-dao: The data access layer, responsible for all database interactions using MyBatis.
- zheng-upms-client: A client library that can be included in other microservices to interact with the UPMS for tasks like authentication and permission checking.
Sources: zheng-upms/pom.xml:18-23, zheng-upms/zheng-upms-client/pom.xml:28-32, zheng-upms/zheng-upms-dao/pom.xml:19-23
Database Schema
The UPMS database schema is designed to support a flexible permission model, including users, roles, permissions, organizations, and the systems they belong to. The core of the model is a set of tables that define these entities and their many-to-many relationships.
The following Entity-Relationship diagram shows the key tables in the UPMS schema and their relationships.
Sources: project-datamodel/zheng.sql:705-998
Key Tables
| Table Name | Description | Source File |
|---|---|---|
upms_user | Stores user account information, including credentials and personal details. | project-datamodel/zheng.sql:896-910 |
upms_role | Defines roles that can be assigned to users. | project-datamodel/zheng.sql:814-823 |
upms_permission | Contains all permissions, which can be directories, menus, or buttons. | project-datamodel/zheng.sql:746-760 |
upms_system | Manages different systems that are integrated with UPMS. | project-datamodel/zheng.sql:867-880 |
upms_organization | Defines the organizational structure (e.g., departments, branches). | project-datamodel/zheng.sql:734-741 |
upms_user_role | A join table linking users to their assigned roles. | project-datamodel/zheng.sql:987-993 |
upms_role_permission | A join table linking roles to their granted permissions. | project-datamodel/zheng.sql:828-835 |
upms_user_permission | A join table for assigning or revoking specific permissions directly to a user, bypassing roles. | project-datamodel/zheng.sql:968-975 |
upms_user_organization | A join table linking users to their organizations. | project-datamodel/zheng.sql:956-963 |
Permission Models
The UPMS module supports two complementary models for managing user permissions, providing both broad and fine-grained control.
Role-Based Access Control (RBAC)
The primary model is RBAC. Permissions are granted to roles, and users inherit permissions by being assigned to one or more roles. This simplifies management for large numbers of users.
This relationship is managed through the upms_user_role and upms_role_permission tables. The UpmsRoleController handles assigning permissions to roles via the /manage/role/permission/{id} endpoint.
Sources: project-datamodel/zheng.sql:828-835, 987-993, zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/manage/UpmsRoleController.java:62-69
User-Based Permissions (Fine-Grained Control)
For exceptional cases, permissions can be directly assigned to a user. The upms_user_permission table facilitates this. This model is particularly powerful because it supports both adding and subtracting permissions.
type = 1: Grants the user an additional permission they might not have from their roles.type = -1: Revokes a permission from a user, even if one of their roles grants it. This is considered a "subtractive" permission.
This logic is handled in the UpmsUserController at the /manage/user/permission/{id} endpoint, which processes a JSON array of permission changes.
Sources: project-datamodel/zheng.sql:968-975, zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/manage/UpmsUserController.java:140-146
Management API Endpoints
The zheng-upms-server exposes a set of RESTful endpoints for managing all aspects of the UPMS. These endpoints are secured using Apache Shiro annotations (@RequiresPermissions).
User Management (/manage/user)
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /index | upms:user:read | Returns the main user management page. |
GET | /list | upms:user:read | Retrieves a paginated list of users. |
POST | /create | upms:user:create | Creates a new user. Password is encrypted with MD5 and a salt. |
GET | /delete/{ids} | upms:user:delete | Deletes one or more users by their IDs. |
POST | /update/{id} | upms:user:update | Updates an existing user's details (password cannot be changed here). |
POST | /organization/{id} | upms:user:organization | Assigns a user to one or more organizations. |
POST | /role/{id} | upms:user:role | Assigns one or more roles to a user. |
POST | /permission/{id} | upms:user:permission | Manages a user's direct (additive/subtractive) permissions. |
Role Management (/manage/role)
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /index | upms:role:read | Returns the main role management page. |
GET | /list | upms:role:read | Retrieves a paginated list of roles. |
POST | /create | upms:role:create | Creates a new role. |
GET | /delete/{ids} | upms:role:delete | Deletes one or more roles by their IDs. |
POST | /update/{id} | upms:role:update | Updates an existing role's details. |
POST | /permission/{id} | upms:role:permission | Assigns permissions to a role. |
Permission Management (/manage/permission)
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /index | upms:permission:read | Returns the main permission management page. |
GET | /list | upms:permission:read | Retrieves a paginated list of permissions, filterable by type and system. |
POST | /create | upms:permission:create | Creates a new permission (directory, menu, or button). |
GET | /delete/{ids} | upms:permission:delete | Deletes one or more permissions by their IDs. |
POST | /update/{id} | upms:permission:update | Updates an existing permission. |
POST | /role/{id} | upms:permission:read | Returns a tree of permissions for a given role ID. |
POST | /user/{id} | upms:permission:read | Returns a tree of permissions for a given user ID. |
RPC Service API
The UpmsApiService interface defines the contract for other microservices to retrieve permission and user data from the UPMS module. This enables a decoupled architecture where other services can query for authorization information without directly accessing the UPMS database.
Key UpmsApiService Methods
| Method | Description |
|---|---|
selectUpmsPermissionByUpmsUserId(Integer upmsUserId) | Retrieves all permissions for a user, combining their direct and role-based permissions. |
selectUpmsRoleByUpmsUserId(Integer upmsUserId) | Retrieves all roles assigned to a user. |
selectUpmsRolePermisstionByUpmsRoleId(Integer upmsRoleId) | Retrieves all permissions granted to a specific role. |
selectUpmsUserPermissionByUpmsUserId(Integer upmsUserId) | Retrieves only the direct user-permission associations (additive/subtractive). |
selectUpmsUserByUsername(String username) | Fetches a user's details by their username. |
insertUpmsLogSelective(UpmsLog record) | Allows other services to write to the central UPMS log. |
Sources: zheng-upms/zheng-upms-rpc-api/src/main/java/com/zheng/upms/rpc/api/UpmsApiService.java:13-55
Summary
The UPMS module is a comprehensive and flexible user permission management system. It provides a solid foundation for securing a microservices-based application by centralizing user, role, and permission data. Its dual-mode permission model (RBAC and direct user-based) offers both ease of management and the ability for fine-grained overrides. The combination of a RESTful management API and an RPC data-access API makes it a well-structured and integral part of the zheng project.
Sources: zheng-upms/README.md