Skip to content
KsuserCNPublic

About

Ksuser Auth

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Auth

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

快速开始

1. 准备后端环境变量

API 从 api/ 目录读取 .env.<KSUSER_ENV>:

cp api/.env.example api/.env.development

至少需要补全这些配置:

  • DB_URL
  • DB_USERNAME
  • DB_PASSWORD
  • REDIS_HOST
  • REDIS_PORT
  • JWT_SECRET

2. 安装 Web 依赖

cd web
npm install

3. 启动核心开发环境

仓库根目录提供了统一脚本,会同时启动 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

  • 环境文件目录:api/
  • 环境选择变量:KSUSER_ENV
  • 默认端口:8000
  • 详细说明见 api/README.md 与 api/docs/README.md

Web

  • 环境文件:web/.env.development、web/.env.production
  • 本地开发默认通过 VITE_API_BASE_URL=http://localhost:8000 连接 API
  • Vite 配置未自定义端口时,开发环境通常为 5173

Desktop

  • 环境文件:desktop/.env.development、desktop/.env.production
  • 关键配置:
    • FLUTTER_API_BASE_URL
    • FLUTTER_PASSKEY_ORIGIN
    • FLUTTER_OIDC_CLIENT_ID

Mobile Android

  • 可选环境文件:mobile/android/.env.development、mobile/android/.env.production
  • 支持配置:
    • API_BASE_URL
    • PASSKEY_RP_ID
    • PASSKEY_ORIGIN_HINT
    • APP_ENV
    • ENABLE_HTTP_LOGGING
  • 若未提供环境文件,Gradle 脚本会回落到默认值

Mobile iOS

  • 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 授权 SDK

其他 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 授权 SDK

其他 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 放行。

子项目文档

CI / 构建工作流

仓库当前按模块拆分了 GitHub Actions:

  • .github/workflows/build-desktop.yml
  • .github/workflows/build-mobile-android.yml

这些工作流会在对应目录变更时触发,也支持手动触发。

目录协作建议

  • 后端接口或认证逻辑变更,优先同步更新 api/docs/
  • Web 授权页或登录流程变更,优先检查 web/ 对 API 地址与 OAuth 参数的依赖
  • 桌面端与移动端默认通过环境文件切换联调地址,不要把真实密钥直接写入仓库
  • Demo 目录适合做本地联调与第三方接入验证,不建议作为生产代码入口

License

本项目使用 Apache License 2.0:

  • 许可证正文:LICENSE
  • 署名通知:NOTICE

分发或二次修改时,请保留协议和通知文件中的版权与署名信息。

Console 管理面板

新增独立 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:console

dev:core / build:core 现在包括 API、通行证 Web 和 Console。

外部服务接入 Ksuser 通行证官方应用的完整步骤、客户端类型、OIDC 授权、scope、令牌校验与撤销方法,见官方应用接入指南。

About

Ksuser Auth

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages