Quasar框架iOS端Keycloak报redirect_uri错误及SSO跳转问题

问题1：iOS端接入时固定报错Invalid parameter: redirect_uri #

按以下优先级排查：

• 核对Keycloak客户端配置的有效重定向URI：Keycloak 18+版本默认开启严格URI匹配，自定义Scheme回调必须精确填写，不要图省事写yourscheme://*这类全通配，Scheme、host部分不支持通配，只有路径段可以用*做部分匹配。比如回调是quasarapp://auth/callback，配置项里就得完整填这个值，少一个路径段都不行。
• 检查参数编码：Quasar不管是用Capacitor还是Cordova跑iOS，webview发起授权请求时，redirect_uri参数必须用encodeURIComponent()做全编码，iOS系统webview会自动对未编码的特殊字符做二次转义，传到Keycloak的地址和配置值对不上就会报这个错。
• 不要用本地回环地址当回调：别在移动端配置里写localhost、127.0.0.1当回调地址，iOS真机运行时这类地址会被系统替换成当前设备的局域网IP，直接触发参数不匹配，统一用自定义Scheme或者Universal Link/App Links的地址。
• 补全Web Origins配置：如果是内嵌webview发起授权请求，把回调地址对应的根域加到Keycloak客户端的Web Origins列表里，跨域校验失败会连带抛出重定向URI参数错误。

问题2：SSO流程走完无法跳转回Android/iOS端应用 #

按以下顺序排查修复：

• 先确认端侧Scheme配置生效
  • Capacitor项目：检查capacitor.config.ts里的iosScheme、androidScheme配置值和Keycloak侧回调的Scheme完全一致；iOS端确认Info.plist的CFBundleURLSchemes数组已加入对应Scheme；Android端确认主Activity的AndroidManifest.xml配置了正确的intent-filter，参考配置：

    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="quasarapp" android:host="auth" android:pathPrefix="/callback" />
    </intent-filter>
    

  • Cordova项目：检查自定义Scheme插件配置，确保Scheme值和其他已安装应用不重名，重名会导致跳转被其他应用拦截。
• 替换Keycloak适配模式：不要在移动端用Keycloak JS适配器默认的iframe静默校验模式，移动端webview默认限制跨域iframe加载，直接走标准授权码流程即可，授权完成后Keycloak的302跳转可以直接触发应用唤起。
• 放开webview的跳转拦截：Quasar默认webview配置会拦截非http/https协议的跳转请求，需要手动加白名单：Capacitor项目在capacitor.config.ts的server.allowNavigation配置项里加入自定义Scheme；Android端还要重写WebViewClient的shouldOverrideUrlLoading逻辑，遇到自定义Scheme地址直接返回false交给系统处理，不要强行在webview里加载。
• 优先用Universal Link/App Links替代自定义Scheme：如果是在系统外部浏览器走SSO流程，大部分国产浏览器、iOS Safari会拦截自定义Scheme跳转，直接配https域名的通用链接，iOS端配置Associated Domains，Android端配置App Links，把对应https地址加到Keycloak的合法重定向列表里，这种方式兼容性远好于自定义Scheme，不会被拦截。

调试技巧：直接开Keycloak服务端的事件日志，看授权请求实际携带的redirect_uri参数值，和控制台配置的值逐字符对比，90%的不匹配问题都是末尾多斜杠、少路径段、编码不一致这类肉眼容易漏的小问题导致的。

内容的提问来源于stack exchange，提问作者Raju Khunt