移动端sso

README.md

@@ -67,6 +67,14 @@ npm run cap:open:android
 并记录签到设备摘要、IP、失败次数和异常频率，供任课教师在考勤明细中复核。Android
 最低版本为 API 26；相机和精确位置权限均按需申请。
 
+### Web/PWA 应用
+
+浏览器通过 HTTPS 打开系统后，可使用浏览器的“安装应用”功能将明序教务固定到桌面或
+开始菜单。PWA 会缓存应用界面与静态资源；接口请求始终走网络，不会离线缓存登录态、
+成绩或其他业务数据。发现新版本时由用户确认刷新，避免正在填写表单时被强制中断。
+Capacitor Android 构建会自动禁用 PWA Service Worker，仍使用原生能力和独立的 OTA
+更新流程。
+
 ### App 前端热更新
 
 App 内置自建 OTA 更新器。它只更新 `dist` 中的 HTML、JavaScript、CSS 和静态资源；
@@ -186,6 +194,14 @@ Sso__CallbackUrl=https://jiaowu.example.edu.cn/signin-keycloak
 显示当前生效的完整回调地址。多实例部署应配置 Redis，以便任意实例都能兑换两分钟内
 有效、使用后即删除的 SSO 登录码及五分钟内有效的绑定意图。
 
+Android App 使用系统浏览器完成 Keycloak 登录，再通过 `https://eis.biss.click/sso/callback`
+或 `/sso/bind` 的 Android App Link 回到应用；Keycloak 的 Valid redirect URI 仍然只配置
+`Sso__CallbackUrl`（即 `/signin-keycloak`），不要配置 `mingxu://`。正式发布前，将 Play
+App Signing 证书的 SHA-256 指纹写入 `web/public/.well-known/assetlinks.json`，并确保该文件
+以 `application/json` 在 `https://eis.biss.click/.well-known/assetlinks.json` 可匿名访问。当前
+配置的包名为 `edu.mingxu.jiaowu`；站点域名或正式签名证书变更时必须同时更新此文件和 Android
+Manifest 后重新签名发布 APK/AAB，此类变更不能通过 OTA 下发。
+
 用户登录后可从页面右上角进入“个人账户”，主动绑定或解除 Keycloak 账号。主动绑定先
 使用当前 JWT 创建五分钟有效的一次性绑定意图，再跳转 Keycloak；回调只能绑定到发起该
 意图的本地账号。解绑需要再次验证本地密码，避免仅凭未锁屏的登录会话解除身份关联。

src/Jiaowu.Api/Controllers/SsoController.cs

@@ -26,6 +26,7 @@ public sealed class SsoController(
     ILogger<SsoController> logger) : ControllerBase
 {
     private const string BindingIntentProperty = "sso-binding-intent";
+    private const string NativeAppProperty = "sso-native-app";
     private readonly SsoOptions _options = options.Value;
 
     [AllowAnonymous]
@@ -42,6 +43,7 @@ public sealed class SsoController(
     public async Task<IActionResult> Login(
         [FromQuery] string? returnUrl = null,
         [FromQuery] string? bindingIntent = null,
+        [FromQuery] bool nativeApp = false,
         CancellationToken cancellationToken = default)
     {
         if (!_options.Enabled)
@@ -49,6 +51,8 @@ public sealed class SsoController(
 
         var safeReturnUrl = NormalizeReturnUrl(returnUrl);
         var properties = new AuthenticationProperties();
+        if (nativeApp)
+            properties.Items[NativeAppProperty] = bool.TrueString;
         if (!string.IsNullOrWhiteSpace(bindingIntent))
         {
             var targetUserId = await cache.GetStringAsync(
@@ -108,6 +112,10 @@ public sealed class SsoController(
                 out var storedBindingIntent)
                 ? storedBindingIntent
                 : null;
+        var nativeApp = authentication.Properties is { } externalProperties &&
+                        externalProperties.Items.TryGetValue(NativeAppProperty, out var nativeAppValue) &&
+                        bool.TryParse(nativeAppValue, out var isNativeApp) &&
+                        isNativeApp;
         if (!string.IsNullOrWhiteSpace(bindingIntent))
         {
             var targetUserId = await cache.GetStringAsync(
@@ -165,7 +173,7 @@ public sealed class SsoController(
                 cancellationToken);
             await HttpContext.SignOutAsync(SsoAuthSchemes.ExternalCookie);
 
-            var bindingPage = BuildFrontendUrl("/sso/bind") +
+            var bindingPage = BuildFrontendUrl("/sso/bind", nativeApp) +
                 $"?code={Uri.EscapeDataString(bindingCode)}" +
                 $"&redirect={Uri.EscapeDataString(NormalizeReturnUrl(returnUrl))}";
             return Redirect(bindingPage);
@@ -190,7 +198,7 @@ public sealed class SsoController(
             cancellationToken);
         await HttpContext.SignOutAsync(SsoAuthSchemes.ExternalCookie);
 
-        var callback = BuildFrontendUrl("/sso/callback") +
+        var callback = BuildFrontendUrl("/sso/callback", nativeApp) +
             $"?code={Uri.EscapeDataString(exchangeCode)}" +
             $"&redirect={Uri.EscapeDataString(NormalizeReturnUrl(returnUrl))}";
         return Redirect(callback);
@@ -344,7 +352,8 @@ public sealed class SsoController(
     [Authorize]
     [HttpPost("prepare-binding")]
     public async Task<ActionResult<SsoBindingStartResponse>> PrepareBinding(
-        CancellationToken cancellationToken)
+        CancellationToken cancellationToken,
+        [FromQuery] bool nativeApp = false)
     {
         if (!_options.Enabled)
             return SsoProblem("统一身份认证尚未启用。", StatusCodes.Status404NotFound);
@@ -373,7 +382,8 @@ public sealed class SsoController(
             values: new
             {
                 returnUrl = "/account",
-                bindingIntent = intentCode
+                bindingIntent = intentCode,
+                nativeApp
             })!;
         return new SsoBindingStartResponse(loginUrl);
     }
@@ -417,10 +427,19 @@ public sealed class SsoController(
             ? returnUrl
             : "/dashboard";
 
-    private string BuildFrontendUrl(string path) =>
+    private string BuildFrontendUrl(string path, bool requireAbsoluteUrl = false)
+    {
+        if (requireAbsoluteUrl && string.IsNullOrWhiteSpace(_options.FrontendBaseUrl))
+        {
+            throw new InvalidOperationException(
+                "原生单点登录需要配置 Sso:FrontendBaseUrl 为已验证的 HTTPS 地址。");
+        }
+
+        return
         string.IsNullOrWhiteSpace(_options.FrontendBaseUrl)
             ? path
             : _options.FrontendBaseUrl.TrimEnd('/') + path;
+    }
 
     private RedirectResult RedirectToFrontendError(
         string error,

web/index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, maximum-scale=1.0, user-scalable=no" />
     <meta name="theme-color" content="#152550" />
     <meta name="description" content="明序大学教务管理系统" />