Immich项目OAuth登录故障分析与解决方案

问题背景

Immich是一款开源的图片备份和管理系统，在最新发布的1.132.0版本中，用户报告了OAuth认证功能在移动端无法正常工作的问题。该问题主要表现为用户在移动应用上尝试通过OAuth登录时，系统会跳转回服务器选择界面并显示错误信息。

故障现象

根据用户反馈，该问题具有以下典型特征：

1. 移动端应用无法完成OAuth登录流程
2. 登录过程中会意外返回服务器选择界面
3. 系统日志中会出现"Missing authentication"等错误信息
4. 部分用户报告Web端也出现类似问题
5. 使用Authelia作为认证提供方的用户受影响较为普遍

技术分析

经过开发团队和社区成员的深入调查，发现该问题主要涉及以下几个方面：

1. PKCE验证机制问题：移动端应用生成的PKCE code verifier包含非法字符，导致认证服务器拒绝请求。PKCE是OAuth 2.0的安全扩展，用于防止授权码拦截攻击。

2. 认证方法变更：从1.132.0版本开始，Immich对OAuth客户端的认证方式要求发生了变化，需要从原来的client_secret_basic改为client_secret_post。

3. 签名算法配置：部分用户配置了无效的签名算法"none"，这不符合OAuth规范，导致认证流程中断。

解决方案

针对上述问题，用户可以采取以下解决方案：

临时解决方案

1. 修改Authelia配置： 在Authelia的OIDC客户端配置中，将token_endpoint_auth_method从client_secret_basic改为client_secret_post。

2. 移除无效scope： 从scope配置中移除不必要的"groups"声明，Immich系统并不需要此scope。

3. 修正签名算法： 避免使用"none"作为签名算法，应选择有效的签名算法如RS256等。

永久解决方案

开发团队已经修复了移动端应用的PKCE生成问题，并计划在下一个版本(1.132.1)中发布修复。用户可以：

1. 等待官方发布新版本
2. 从GitHub Actions下载已修复的测试版应用

最佳实践建议

1. 定期检查OAuth提供方的配置是否符合最新规范
2. 升级前备份关键配置
3. 关注项目更新日志中的重大变更说明
4. 测试环境先行验证新版本功能

总结

Immich 1.132.0版本的OAuth认证问题主要源于移动端PKCE实现和认证方法变更。通过调整Authelia配置或等待官方修复版本，用户可以解决这一问题。这提醒我们在进行系统升级时，需要特别关注认证相关的变更，并做好相应的配置调整准备。