在Godoxy中配置Immich与Authentik的OIDC集成指南

背景介绍

在现代自托管环境中，Godoxy作为反向代理解决方案，经常需要与各种应用服务如Immich(照片管理平台)和Authentik(身份认证系统)进行集成。本文将详细介绍如何正确配置这三者之间的OAuth/OIDC认证流程，避免常见的配置陷阱。

核心配置原则

1. 应用原生支持优先原则：对于像Immich这样原生支持OIDC的应用，应当直接在应用内部配置OIDC，而不是通过Godoxy的中间件。这是保证认证流程完整性的关键。

2. 认证流程分离原则：Godoxy的OIDC中间件和应用自身的OIDC配置应当分开处理，避免认证流程的嵌套和冲突。

典型错误分析

在配置过程中，开发者常遇到"Failed to finish oauth"错误，并伴随日志中的JWT解码错误。这通常是由于Authentik中的错误配置导致的：

• 错误配置：在Authentik提供者设置中同时配置了"签名密钥"和"加密密钥"
• 正确做法：只需配置"签名密钥"，不应设置"加密密钥"选项

这种错误会导致JWT令牌被错误地加密，而应用端并未预期接收加密的JWT，从而引发解码失败。

移动端访问考量

当需要同时支持浏览器和移动应用访问时，需注意：

1. 移动应用通常需要直接访问后端服务，不应经过Godoxy的认证层
2. 可以考虑为移动应用创建专用API端点或调整认证策略
3. 确保Immich的移动应用能够正确处理OIDC流程

最佳实践建议

1. 配置顺序：先确保Immich与Authentik的直接OIDC集成工作正常，再配置Godoxy
2. 日志监控：密切监控Immich和Godoxy的日志，及时发现认证流程中的异常
3. 测试验证：分阶段测试浏览器访问和移动应用访问，确保两者都能正常工作
4. 安全考量：合理设置OIDC的作用域(scope)，仅请求必要的用户信息

通过遵循这些原则和实践，可以构建一个既安全又用户友好的认证集成方案，满足不同客户端的访问需求。