Single Sign-On (SSO) & Security

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/SSOController.java
• zheng-upms/zheng-upms-client/src/main/java/com/zheng/upms/client/shiro/realm/UpmsRealm.java
• zheng-upms/zheng-upms-client/src/main/resources/applicationContext-shiro.xml
• zheng-upms/zheng-upms-client/src/main/java/com/zheng/upms/client/shiro/session/UpmsSessionDao.java
• zheng-upms/README.md
• zheng-cms/zheng-cms-admin/pom.xml

The zheng-upms (User Permission Management System) module provides a centralized security solution for the entire zheng project. It is founded on a Role-Based Access Control (RBAC) model, offering fine-grained permission control. Its key features include Single Sign-On (SSO) for unified user authentication, distributed session management backed by Redis, and comprehensive logging.

This architecture allows various subsystems, such as zheng-cms-admin, to integrate seamlessly and delegate all security concerns to the central zheng-upms-server. Each subsystem can define its own roles and permissions, which are then managed and enforced by the UPMS.

Sources: zheng-upms/README.md

Architecture Overview

The SSO and security architecture is composed of two primary components: a central server and a client library, which together provide authentication, authorization, and session management.

• zheng-upms-server: Acts as the central authentication server. It hosts the login page, manages global user sessions, and exposes RPC services for accessing user, role, and permission data.
• zheng-upms-client: A library integrated into all other applications that require security (e.g., zheng-cms-admin, zheng-oss-admin). This client uses Apache Shiro to protect resources, communicate with the SSO server, and manage local sessions that are synchronized with the global session store in Redis.

The following diagram illustrates the high-level interaction between these components.

SSO Authentication Flow

The authentication process is initiated when a user attempts to access a protected resource in a client application. The flow relies on redirects and a one-time code to establish a trusted session between the client application and the central SSO server.

This sequence diagram details the complete login flow.

Security Framework: Apache Shiro

The zheng-upms-client module provides a robust integration with Apache Shiro to secure client applications. This is achieved through custom configuration, a specialized realm, and a distributed session DAO.

Shiro Configuration

Client applications configure Shiro via the applicationContext-shiro.xml file. This file defines the core security components as Spring beans.

Bean ID	Class	Description
securityManager	org.apache.shiro.web.mgt.DefaultWebSecurityManager	The central component of Shiro. It manages authentication, authorization, and session management.
sessionManager	org.apache.shiro.web.session.mgt.DefaultWebSessionManager	Manages the lifecycle of user sessions, configured to use the custom UpmsSessionDao.
sessionDAO	com.zheng.upms.client.shiro.session.UpmsSessionDao	A custom DAO that persists Shiro sessions in Redis, enabling distributed sessions.
upmsRealm	com.zheng.upms.client.shiro.realm.UpmsRealm	A custom realm responsible for fetching a user's roles and permissions from the UPMS RPC service.
shiroFilter	org.apache.shiro.spring.web.ShiroFilterFactoryBean	The main servlet filter that intercepts all requests and applies security rules.

Sources: zheng-upms/zheng-upms-client/src/main/resources/applicationContext-shiro.xml

Custom Realm: UpmsRealm

The UpmsRealm class extends Shiro's AuthorizingRealm and is responsible for providing authorization data after a user has been authenticated by the SSO server.

• doGetAuthorizationInfo(PrincipalCollection principals): This is the core method for authorization. When a permission check is required, Shiro invokes this method. It retrieves the username, then calls the upmsApiService (via RPC) to fetch all roles and permissions associated with that user. This information is then used by Shiro to grant or deny access.
• doGetAuthenticationInfo(AuthenticationToken token): In this SSO setup, this method's role is minimal. It confirms the user's identity based on the principal provided after the SSO flow is complete. The actual password validation occurs on the zheng-upms-server.

Sources: zheng-upms/zheng-upms-client/src/main/java/com/zheng/upms/client/shiro/realm/UpmsRealm.java:31-60

Distributed Session Management: UpmsSessionDao

To support horizontal scaling and failover, user sessions are not stored in memory but are persisted in Redis. The UpmsSessionDao class implements Shiro's SessionDAO interface to manage this.

• doCreate(Session session): Serializes and stores a new session in Redis.
• doReadSession(Serializable sessionId): Retrieves a session from Redis by its ID and deserializes it.
• update(Session session): Updates an existing session in Redis. This is crucial for keeping session data (like last access time) current and for propagating status changes (e.g., force_logout).
• delete(Session session): Removes a session from Redis, effectively logging the user out.

Sources: zheng-upms/zheng-upms-client/src/main/java/com/zheng/upms/client/shiro/session/UpmsSessionDao.java

SSO Server Components

The zheng-upms-server contains the central logic for handling SSO requests.

SSOController

This Spring MVC controller is the heart of the SSO server, defining the endpoints that manage the authentication lifecycle.

Method	Path	Description
GET	/sso/index	Entry point for authentication. Validates the client appid and redirects to the login page.
GET	/sso/login	Displays the login page. If the user is already logged in (global session exists), it generates a code and redirects back to the client.
POST	/sso/login	Processes login credentials. Authenticates via Shiro, creates a global session, generates and stores a code in Redis, and returns the backurl for redirection.
POST	/sso/code	Validates a one-time code provided by a client application to complete the login process.
GET	/sso/logout	Logs the user out of the global session by invalidating the Shiro subject's session.

Sources: zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java

Redis Key Schema

The SSO process relies on several key patterns in Redis to manage state.

Key Pattern	Description	Expiration
zheng-upms-server-session-id_{sessionId}	Stores the one-time code associated with a global session ID.	Same as session timeout.
zheng-upms-server-session-ids	A Redis list containing all active global session IDs, used for administrative session management.	N/A
zheng-upms-server-code_{code}	Stores the code itself as a validation token. The client's code must match this value.	Same as session timeout.

Sources: zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java:44-48