Auth 是一个多项目身份认证仓库,覆盖后端 API、Web 认证门户、桌面端、Android 移动端以及本地联调 Demo。
核心目标:
- 统一账号认证与会话管理
- 支持密码、邮箱验证码、Passkey、TOTP MFA 等认证能力
- 支持 OAuth 登录/绑定与官方应用 OIDC
- 为 Web、桌面端、移动端提供统一认证基础设施
| 目录 | 作用 | 主要技术 |
|---|---|---|
api/ |
认证后端服务,默认端口 8000 |
Spring Boot, Spring Security, JPA, MySQL, Redis |
web/ |
Web 认证中心与 OAuth/官方应用授权页,开发环境默认 5173 |
Vue 3, Vite, TypeScript, Element Plus |
desktop/ |
桌面客户端,当前支持 macOS / Windows |
Flutter |
mobile/android/ |
Android 客户端 | Kotlin, Jetpack Compose, Retrofit |
mobile/ios/ |
iOS 客户端 | SwiftUI, URLSession |
sdk/ios/ |
官方应用与第三方应用的 iOS 授权 SDK、示例 | Swift Package, AuthenticationServices, PKCE |
demos/ |
iOS 授权与本地 OAuth / OIDC / SSPU 接入演示 | SwiftUI, Python, HTML/JS |
.github/workflows/ |
分模块 CI 构建工作流 | GitHub Actions |
- 注册 / 登录(密码、邮箱验证码)
- Passkey(WebAuthn)登录与敏感操作验证
- TOTP 双因素认证与恢复码
- 多设备会话管理、刷新与撤销
- OAuth 登录 / 绑定(GitHub / Google / Microsoft / QQ)
- 官方应用 OIDC Discovery
- iOS App-to-App 授权及同事务网页备用授权,公开客户端使用 PKCE
- 风控、限流、敏感操作日志
- 后端:Java 21, Spring Boot, Spring Security, JPA, MySQL, Redis
- 前端:Vue 3, Vite, TypeScript, Pinia, Element Plus
- 桌面端:Flutter
- Android:Kotlin, Jetpack Compose;iOS:SwiftUI, AuthenticationServices
- Demo:Python 3
按你要运行的模块准备环境:
- 通用:
git - API:
JDK 21、MySQL、Redis - Web:
Node.js 20+、npm - Desktop:Flutter Stable,对应桌面平台工具链
- Mobile Android:Android SDK、JDK 17/21、Gradle
- Mobile iOS:macOS、Xcode 26.5+、iOS 模拟器;真机发布需 Apple 开发者签名
- Demos:
Python 3
API 从 api/ 目录读取 .env.<KSUSER_ENV>:
cp api/.env.example api/.env.development至少需要补全这些配置:
DB_URLDB_USERNAMEDB_PASSWORDREDIS_HOSTREDIS_PORTJWT_SECRET
cd web
npm install仓库根目录提供了统一脚本,会同时启动 API 和 Web:
npm run dev:core这个命令等价于:
- 在
api/中以KSUSER_ENV=development启动 Spring Boot - 在
web/中启动 Vite 开发服务
如果你更喜欢分开运行,可以使用:
npm run dev:api
npm run dev:web在仓库根目录执行:
| 命令 | 说明 |
|---|---|
npm run help |
查看根任务说明 |
npm run dev:core |
同时启动 API + Web |
npm run build:core |
构建 API + Web |
npm run dev:api |
单独启动 API |
npm run test:api |
运行 API 测试 |
npm run build:api |
构建 API |
npm run dev:web |
单独启动 Web |
npm run test:web |
运行 Web 单元测试 |
npm run lint:web |
检查并修复 Web lint |
npm run build:web |
构建 Web |
npm run dev:desktop:macos |
启动 macOS 桌面端 |
npm run dev:desktop:windows |
启动 Windows 桌面端 |
npm run build:desktop:macos |
构建 macOS 桌面端 |
npm run build:desktop:windows |
构建 Windows 桌面端 |
npm run dev:mobile:android |
构建 Android Debug 包 |
npm run build:mobile:android:release |
构建 Android Release 包 |
npm run release:android |
提示签名密码,测试并生成 build/release.apk 和配套 build/web/,见 发布操作 |
npm run dev:demo:oauth |
启动 OAuth localhost Demo |
npm run dev:demo:oidc |
启动 OIDC localhost Demo |
npm run dev:demo:sspu |
启动 SSPU OAuth Demo |
- 环境文件目录:
api/ - 环境选择变量:
KSUSER_ENV - 默认端口:
8000 - 详细说明见
api/README.md与api/docs/README.md
- 环境文件:
web/.env.development、web/.env.production - 本地开发默认通过
VITE_API_BASE_URL=http://localhost:8000连接 API - Vite 配置未自定义端口时,开发环境通常为
5173
- 环境文件:
desktop/.env.development、desktop/.env.production - 关键配置:
FLUTTER_API_BASE_URLFLUTTER_PASSKEY_ORIGINFLUTTER_OIDC_CLIENT_ID
- 可选环境文件:
mobile/android/.env.development、mobile/android/.env.production - 支持配置:
API_BASE_URLPASSKEY_RP_IDPASSKEY_ORIGIN_HINTAPP_ENVENABLE_HTTP_LOGGING
- 若未提供环境文件,Gradle 脚本会回落到默认值
- Xcode 项目:
mobile/ios/KsuserAuth.xcodeproj,共享 Scheme:KsuserAuth - 构建配置:
mobile/ios/Config/Shared.xcconfig,本地覆盖:Config/Local.xcconfig;默认https://api.ksuser.cn - 会话令牌、持久 Cookie 保存至 Keychain,主题与协议偏好保存至 UserDefaults
- 最低 iOS 17,支持 iPhone/iPad 和系统、浅色、深色主题
- 构建、测试、Archive:
dev:mobile:ios、build:mobile:ios、test:mobile:ios、archive:mobile:ios - 原生认证配置和发布验收:iOS 文档
- iOS 安全推送、APNs 密钥和数据库迁移:推送配置
其他 iOS 17.4+ App 可通过根目录的 Swift Package 集成 KsuserAuthSDK,唤起 Ksuser 安全 App 确认授权;无法唤起时使用系统网页认证。官方应用使用 OIDC,第三方应用使用 OAuth;两者都以 public 客户端和 PKCE 接入。
接入与示例见 SDK 文档,API、数据库迁移和部署开关见 原生授权协议。APP_NATIVE_AUTHORIZATION_ENABLED 默认关闭,须在 API、Web/AASA 和 iOS App 部署完成后启用。接入 App 必须配置自己的 HTTPS 回调域名与 AASA。
小型原生示例位于 demos/ios-auth-demo,运行 npm run dev:demo:ios 打开 Xcode 工程,npm run build:demo:ios 验证模拟器构建。
其他 Android 7.0+ App 可通过独立的 Android SDK 接入第三方 OAuth 或官方 OIDC。SDK 使用 public client、PKCE 和精确 HTTPS App Link 回调,支持 App 间授权、同一 ticket 网页继续、取消与冷启动恢复。
运行 npm run test:sdk:android 验证 SDK,npm run build:sdk:android 生成 Release AAR、源码包及本地 Maven 仓库,npm run build:demo:android 构建 独立 Demo。远程 Maven 版本尚未发布。上线前须完成 API、Web、新版 Ksuser Android App 和实际签名域关联部署,再使用现有开关与 client allowlist 放行。
仓库当前按模块拆分了 GitHub Actions:
.github/workflows/build-desktop.yml.github/workflows/build-mobile-android.yml
这些工作流会在对应目录变更时触发,也支持手动触发。
- 后端接口或认证逻辑变更,优先同步更新
api/docs/ - Web 授权页或登录流程变更,优先检查
web/对 API 地址与 OAuth 参数的依赖 - 桌面端与移动端默认通过环境文件切换联调地址,不要把真实密钥直接写入仓库
- Demo 目录适合做本地联调与第三方接入验证,不建议作为生产代码入口
本项目使用 Apache License 2.0:
- 许可证正文:
LICENSE - 署名通知:
NOTICE
分发或二次修改时,请保留协议和通知文件中的版权与署名信息。
新增独立 Vue 3 Web 管理端,部署到 https://console.ksuser.cn,开发端口 5174。
通过 Ksuser 通行证官方应用授权登录,只有超级管理员可以访问。
支持用户查询、普通管理员任免、官方应用配置和操作审计。
部署新版 API 前,先执行 Console 增量迁移与初始化 SQL。 完整步骤、初始超级管理员 UUID、官方应用接入和 Nginx 配置见 Console 文档。
npm --prefix console ci
npm run dev:console
npm run build:console
npm run test:consoledev:core / build:core 现在包括 API、通行证 Web 和 Console。
外部服务接入 Ksuser 通行证官方应用的完整步骤、客户端类型、OIDC 授权、scope、令牌校验与撤销方法,见官方应用接入指南。