From 9df37873ba9647970af88254f28dec63e0d440ed Mon Sep 17 00:00:00 2001
From: gitee-bot <no-reply@git.oschina.net>
Date: Sat, 27 Sep 2025 04:41:07 +0000
Subject: [PATCH] Add README.md

---
 README.en.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 328 insertions(+)
 create mode 100644 README.en.md
 create mode 100644 README.md

diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..6551ac4
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,164 @@
+# MaxKey Maven Project
+
+## Project Introduction
+
+MaxKey is an open-source identity authentication and access control solution that supports various authentication methods and protocols, including but not limited to OAuth2, JWT, SAML, LDAP, Kerberos, and WS-Federation. This project provides users with a flexible, secure, and extensible authentication framework suitable for enterprise application integration and single sign-on (SSO) scenarios.
+
+This repository contains the Maven project structure of MaxKey, including multiple modules such as authentication core, captcha support, social login, OTP (One-Time Password), and common utility classes. These modules together build a complete identity authentication system supporting various authentication mechanisms and security policies.
+
+## Main Modules
+
+### `maxkey-authentication-core`
+- **Function**: Authentication core module, providing basic authentication logic.
+- **Supported Authentication Methods**: Username and password, LDAP, Active Directory, JWT, Kerberos, WS-Federation, OAuth2, SMS verification code, Email verification code, etc.
+- **Key Classes**:
+  - `AbstractAuthenticationProvider`: Abstract base class for authentication providers.
+  - `RealmAuthenticationProvider`: Realm-based authentication implementation.
+  - `LoginCredential`: Encapsulates login credential information.
+  - `AuthenticationAutoConfiguration`: Spring Boot auto-configuration class for initializing authentication-related beans.
+
+### `maxkey-authentication-captcha`
+- **Function**: Captcha support module, providing graphical captcha functionality.
+- **Key Classes**:
+  - `KaptchaAutoConfiguration`: Captcha auto-configuration class.
+  - `ImageCaptchaEndpoint`: Controller for generating captcha images.
+
+### `maxkey-authentication-social`
+- **Function**: Social login module, supporting OAuth2 login for third-party platforms (e.g., WeChat, QQ, Weibo, etc.).
+- **Key Classes**:
+  - `SocialSignOnAutoConfiguration`: Social login auto-configuration class.
+  - `SocialSignOnProvider`: Social login provider.
+  - `SocialSignOnEndpoint`: Controller for social login.
+
+### `maxkey-authentication-otp`
+- **Function**: One-Time Password (OTP) module, supporting TOTP, HOTP, SMS verification code, Email verification code, etc.
+- **Key Classes**:
+  - `AbstractOtpAuthn`: Abstract base class for OTP authentication.
+  - `TimeBasedOtpAuthn`, `HotpOtpAuthn`: Time-based or counter-based OTP implementations.
+  - `SmsOtpAuthn`, `MailOtpAuthn`: Implementations for SMS and email verification codes.
+  - `OtpKeyUriFormat`: OTP key URI formatting utility.
+
+### `maxkey-common`
+- **Function**: Common utility module, including encryption, serialization, date handling, UUID generation, JSON utilities, etc.
+- **Key Classes**:
+  - `PasswordEncoder`: Password encoding interface.
+  - `JwtSigningAndValidationService`: JWT signing and validation service.
+  - `KeyPairUtil`, `RSAUtils`: Key pair generation and RSA encryption utilities.
+  - `DateUtils`, `StringUtils`: Common utility classes.
+  - `IdGenerator`, `SnowFlakeId`: ID generators.
+
+### `maxkey-core`
+- **Function**: Core business module, including user management, organizational structure, permission control, logging, etc.
+- **Key Classes**:
+  - `UserInfo`: User information entity class.
+  - `Organizations`: Organizational structure entity class.
+  - `Roles`, `Resources`: Permission and resource management.
+  - `HistoryLogin`: Login history record.
+  - `ApplicationConfig`: Application configuration class.
+  - `MvcAutoConfiguration`: Spring MVC auto-configuration.
+
+### `maxkey-web-*`
+- **Function**: Web layer module, including frontend resources, page controllers, security configuration, etc.
+- **Key Classes**:
+  - `AuthenticationAutoConfiguration`: Authentication auto-configuration.
+  - `SessionRedisAutoConfiguration`: Redis session support.
+  - `SwaggerConfig`: API documentation configuration.
+
+## Authentication Method Support
+
+MaxKey supports multiple authentication methods, including:
+
+- **Basic Authentication**: Username + password.
+- **Multi-Factor Authentication (MFA)**: Supports TOTP, HOTP, SMS verification code, email verification code, etc.
+- **Social Login**: Supports OAuth2 third-party login (e.g., WeChat, QQ, GitHub, etc.).
+- **Kerberos**: Supports Kerberos protocol authentication.
+- **JWT**: Supports stateless authentication based on JWT.
+- **SAML**: Supports SAML 2.0 protocol.
+- **WS-Federation**: Supports WS-Federation protocol.
+- **LDAP / Active Directory**: Supports LDAP and Active Directory authentication.
+
+## Security Features
+
+- **Password Policies**: Supports password complexity, password history, password expiration, etc.
+- **Login Restrictions**: Supports login failure limits, IP whitelisting, login time restrictions, etc.
+- **Session Management**: Supports session timeout, session concurrency control, and RememberMe functionality.
+- **Encryption Support**: Supports multiple encryption algorithms (e.g., RSA, AES, SM3, SM4).
+- **Certificate Management**: Supports signing and verification of X.509 certificates.
+
+## Data Storage Support
+
+- **JDBC**: Supports storing user, organization, and permission information based on databases.
+- **Redis**: Supports caching user sessions, verification codes, etc., using Redis.
+- **In-Memory**: Supports in-memory storage, suitable for testing or lightweight deployments.
+
+## Development and Deployment
+
+### Dependency Management
+
+The project is built using Maven, with dependencies managed through `pom.xml`. Core dependencies include:
+
+- Spring Boot
+- Spring Security
+- Spring Data JPA
+- Redis
+- JWT support (e.g., Nimbus JOSE+JWT)
+- Utility libraries such as Apache Commons, Jackson, and Java Util
+
+### Configuration Files
+
+- `application.properties` or `application.yml`: Spring Boot configuration files.
+- MaxKey-related configuration options:
+  - `maxkey.login.captcha`: Whether to enable captcha.
+  - `maxkey.login.rememberme`: Whether to enable RememberMe.
+  - `maxkey.server.persistence`: Persistence method (JDBC / Redis / In-Memory).
+  - `maxkey.saml.*`: SAML-related configurations.
+  - `maxkey.jwt.*`: JWT-related configurations.
+
+### Startup Methods
+
+Start the project using Spring Boot:
+
+```bash
+mvn spring-boot:run
+```
+
+Or build and run:
+
+```bash
+mvn package
+java -jar target/maxkey-*.jar
+```
+
+## Extensibility and Integration
+
+MaxKey provides excellent extensibility, supporting:
+
+- Custom authentication methods (by extending `AbstractAuthenticationProvider`).
+- Custom OTP implementations (by extending `AbstractOtpAuthn`).
+- Custom social login platforms (by implementing `SocialSignOnProvider`).
+- Custom password policies (via the `PasswordEncoder` interface).
+- Custom session storage (via the `OnlineTicketServices` interface).
+
+## Open Source License
+
+This project is licensed under the **Apache 2.0** license, allowing free use and modification in commercial environments.
+
+## Contributions and Feedback
+
+Code contributions, issue submissions, or pull requests are welcome. For technical support or commercial collaboration, please visit the [MaxKey Official Website](http://maxkey.top).
+
+## Reference Documentation
+
+- [MaxKey Official Documentation](http://maxkey.top)
+- [MaxKey GitHub Repository](https://github.com/dromara/maxkey)
+- [MaxKey Gitee Repository](https://gitee.com/dromara/maxkey)
+
+## Contact Information
+
+- Official Website: http://maxkey.top
+- Email: maxkey@163.com
+- QQ Group: 1033886520
+
+---
+
+**MaxKey** is a powerful, flexible, and extensible identity authentication platform suitable for enterprise SSO, OAuth2, JWT, SAML, and various other authentication scenarios. Welcome to join the community!
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d722c50
--- /dev/null
+++ b/README.md
@@ -0,0 +1,164 @@
+# MaxKey Maven 项目
+
+## 项目简介
+
+MaxKey 是一个开源的身份认证和访问控制解决方案，支持多种认证方式和协议，包括但不限于 OAuth2、JWT、SAML、LDAP、Kerberos、WS-Federation 等。该项目为用户提供了一个灵活、安全、可扩展的身份认证框架，适用于企业级应用集成和单点登录（SSO）场景。
+
+本仓库是 MaxKey 的 Maven 项目结构，包含多个模块，如认证核心、验证码支持、社交登录、OTP（一次性密码）、公共工具类等。这些模块共同构建了一个完整的身份认证系统，支持多种认证机制和安全策略。
+
+## 主要模块
+
+### `maxkey-authentication-core`
+- **功能**：认证核心模块，提供基础认证逻辑。
+- **支持的认证方式**：用户名密码、LDAP、Active Directory、JWT、Kerberos、WS-Federation、OAuth2、短信验证码、邮件验证码等。
+- **关键类**：
+  - `AbstractAuthenticationProvider`：认证提供者的抽象基类。
+  - `RealmAuthenticationProvider`：基于 Realm 的认证实现。
+  - `LoginCredential`：封装登录凭证信息。
+  - `AuthenticationAutoConfiguration`：Spring Boot 自动配置类，用于初始化认证相关 Bean。
+
+### `maxkey-authentication-captcha`
+- **功能**：验证码支持模块，提供图形验证码功能。
+- **关键类**：
+  - `KaptchaAutoConfiguration`：验证码自动配置类。
+  - `ImageCaptchaEndpoint`：验证码生成的控制器。
+
+### `maxkey-authentication-social`
+- **功能**：社交登录模块，支持第三方平台（如微信、QQ、微博等）的 OAuth2 登录。
+- **关键类**：
+  - `SocialSignOnAutoConfiguration`：社交登录自动配置类。
+  - `SocialSignOnProvider`：社交登录提供者。
+  - `SocialSignOnEndpoint`：社交登录的控制器。
+
+### `maxkey-authentication-otp`
+- **功能**：一次性密码（OTP）模块，支持 TOTP、HOTP、短信验证码、邮件验证码等。
+- **关键类**：
+  - `AbstractOtpAuthn`：OTP 认证的抽象基类。
+  - `TimeBasedOtpAuthn`、`HotpOtpAuthn`：基于时间或计数的 OTP 实现。
+  - `SmsOtpAuthn`、`MailOtpAuthn`：短信和邮件验证码实现。
+  - `OtpKeyUriFormat`：OTP 密钥 URI 格式化工具。
+
+### `maxkey-common`
+- **功能**：公共工具类模块，包含加密、序列化、日期处理、UUID 生成、JSON 工具等。
+- **关键类**：
+  - `PasswordEncoder`：密码编码接口。
+  - `JwtSigningAndValidationService`：JWT 签名与验证服务。
+  - `KeyPairUtil`、`RSAUtils`：密钥对生成与 RSA 加密工具。
+  - `DateUtils`、`StringUtils`：常用工具类。
+  - `IdGenerator`、`SnowFlakeId`：ID 生成器。
+
+### `maxkey-core`
+- **功能**：核心业务模块，包含用户管理、组织架构、权限控制、日志记录等功能。
+- **关键类**：
+  - `UserInfo`：用户信息实体类。
+  - `Organizations`：组织架构实体类。
+  - `Roles`、`Resources`：权限与资源管理。
+  - `HistoryLogin`：登录历史记录。
+  - `ApplicationConfig`：应用配置类。
+  - `MvcAutoConfiguration`：Spring MVC 自动配置。
+
+### `maxkey-web-*`
+- **功能**：Web 层模块，包含前端资源、页面控制器、安全配置等。
+- **关键类**：
+  - `AuthenticationAutoConfiguration`：认证自动配置。
+  - `SessionRedisAutoConfiguration`：Redis 会话支持。
+  - `SwaggerConfig`：API 文档配置。
+
+## 认证方式支持
+
+MaxKey 支持多种认证方式，包括：
+
+- **基础认证**：用户名 + 密码。
+- **多因素认证 (MFA)**：支持 TOTP、HOTP、短信验证码、邮件验证码等。
+- **社交登录**：支持 OAuth2 第三方登录（如微信、QQ、GitHub 等）。
+- **Kerberos**：支持 Kerberos 协议认证。
+- **JWT**：支持基于 JWT 的无状态认证。
+- **SAML**：支持 SAML 2.0 协议。
+- **WS-Federation**：支持 WS-Federation 协议。
+- **LDAP / Active Directory**：支持 LDAP 和 Active Directory 认证。
+
+## 安全特性
+
+- **密码策略**：支持密码复杂度、历史密码、密码过期等策略。
+- **登录限制**：支持登录失败次数限制、IP 白名单、登录时间限制等。
+- **会话管理**：支持会话超时、会话并发控制、RememberMe 功能。
+- **加密支持**：支持多种加密算法（如 RSA、AES、SM3、SM4）。
+- **证书管理**：支持 X.509 证书的签名与验证。
+
+## 数据存储支持
+
+- **JDBC**：支持基于数据库的用户、组织、权限等信息存储。
+- **Redis**：支持 Redis 缓存用户会话、验证码等信息。
+- **In-Memory**：支持内存存储，适用于测试或轻量级部署。
+
+## 开发与部署
+
+### 依赖管理
+
+使用 Maven 构建项目，各模块通过 `pom.xml` 管理依赖。核心依赖包括：
+
+- Spring Boot
+- Spring Security
+- Spring Data JPA
+- Redis
+- JWT 支持（如 Nimbus JOSE+JWT）
+- Apache Commons、Jackson、Java Util 等工具库
+
+### 配置文件
+
+- `application.properties` 或 `application.yml`：Spring Boot 配置文件。
+- `maxkey` 相关配置项：
+  - `maxkey.login.captcha`：是否启用验证码。
+  - `maxkey.login.remeberme`：是否启用 RememberMe。
+  - `maxkey.server.persistence`：持久化方式（JDBC / Redis / In-Memory）。
+  - `maxkey.saml.*`：SAML 相关配置。
+  - `maxkey.jwt.*`：JWT 相关配置。
+
+### 启动方式
+
+使用 Spring Boot 启动项目：
+
+```bash
+mvn spring-boot:run
+```
+
+或打包后运行：
+
+```bash
+mvn package
+java -jar target/maxkey-*.jar
+```
+
+## 扩展与集成
+
+MaxKey 提供了良好的扩展性，支持：
+
+- 自定义认证方式（通过继承 `AbstractAuthenticationProvider`）。
+- 自定义 OTP 实现（通过继承 `AbstractOtpAuthn`）。
+- 自定义社交登录平台（通过实现 `SocialSignOnProvider`）。
+- 自定义密码策略（通过 `PasswordEncoder` 接口）。
+- 自定义会话存储（通过 `OnlineTicketServices` 接口）。
+
+## 开源协议
+
+本项目采用 **Apache 2.0** 协议，允许在商业环境中自由使用和修改。
+
+## 贡献与反馈
+
+欢迎贡献代码、提交 Issue 或 Pull Request。如需技术支持或商业合作，请访问 [MaxKey 官方网站](http://maxkey.top)。
+
+## 参考文档
+
+- [MaxKey 官方文档](http://maxkey.top)
+- [MaxKey GitHub 仓库](https://github.com/dromara/maxkey)
+- [MaxKey Gitee 仓库](https://gitee.com/dromara/maxkey)
+
+## 联系方式
+
+- 官方网站：http://maxkey.top
+- 邮箱：maxkey@163.com
+- QQ 群：1033886520
+
+---
+
+**MaxKey** 是一个功能强大、灵活可扩展的身份认证平台，适用于企业级 SSO、OAuth2、JWT、SAML 等多种认证场景。欢迎加入社区共建！
\ No newline at end of file
-- 
Gitee