Pingvin Share项目集成Authelia OIDC认证的配置指南

在自建文件分享服务Pingvin Share中，集成第三方认证服务是提升安全性的重要手段。本文将详细介绍如何正确配置Authelia作为OpenID Connect(OIDC)提供者，实现用户统一认证。

核心配置要点

1. 服务端配置

Authelia作为OIDC提供者需要正确配置客户端信息，关键参数包括：

• client_id: 客户端标识符(如"pingvin")
• client_secret: 客户端密钥
• redirect_uris: 必须包含Pingvin的回调地址(格式为https://yourdomain.com/api/oauth/callback/oidc)
• 建议的scope范围应包含openid、profile、email等基本声明

2. 客户端配置

在Pingvin Share管理界面中需要特别注意：

• OpenID Connect Discovery URI必须指向Authelia的发现文档地址，标准格式为https://auth.yourdomain.com/.well-known/openid-configuration
• 用户名声明字段(username claim)应保持为空，系统会自动从ID Token中提取preferred_username字段
• 客户端ID和密钥必须与Authelia配置完全一致

常见问题解决

发现文档配置错误

初期配置时常见的500错误通常源于Discovery URI不正确。当出现类似错误日志时：

ERROR [ExceptionsHandler] invalid json response body

应检查是否使用了完整的发现文档URL，而非Authelia的基础地址。

用户信息获取失败

当出现"Unable to get your user information"错误时，需注意：

1. 确保ID Token包含标准声明字段(preferred_username或email)
2. 检查Authelia的scope配置是否包含profile和email
3. 在Pingvin配置中不要填写username claim字段，系统会自动处理

最佳实践建议

1. 测试阶段建议开启所有相关服务的调试日志
2. 先确保Authelia的基础OIDC功能正常工作，再集成到Pingvin
3. 生产环境应使用HTTPS并配置合理的密钥轮换策略
4. 定期检查令牌的有效期设置是否符合安全要求

通过以上配置，可以实现Pingvin Share与Authelia的无缝集成，既保持了系统的安全性，又提供了统一的认证体验。