在Beszel项目中集成Authelia OIDC认证的实践指南

背景介绍

Beszel是一个基于PocketBase的开源项目，提供了丰富的功能。在实际部署中，许多用户希望将其与Authelia身份认证系统集成，以实现统一认证。本文将详细介绍如何正确配置Authelia OIDC与Beszel的集成，以及解决过程中可能遇到的各种问题。

基础配置

Authelia与Beszel的OIDC集成基础配置相对简单，主要涉及Authelia的配置文件修改。以下是标准的配置示例：

- client_id: 'beszel-client'
  client_name: 'Beszel OpenID Client'
  client_secret: 'your-secret-here'
  public: false
  authorization_policy: 'two_factor'
  redirect_uris:
    - 'https://your-domain.com/api/oauth2-redirect'
  scopes:
    - 'email'
    - 'groups'
    - 'openid'
    - 'profile'
  userinfo_signed_response_alg: 'none'

常见问题及解决方案

1. 空白弹出窗口问题

许多用户反馈点击Authelia登录按钮后会出现空白弹出窗口(about:blank)。经过排查，这通常与反向代理的压缩中间件有关。

解决方案：

• 在Traefik或其他反向代理中禁用压缩中间件
• 检查是否有其他中间件可能干扰OIDC流程

2. 用户创建与角色分配

成功认证后，用户可能无法登录，这是因为Beszel要求用户必须先在系统中存在。

解决方案：

• 预先在PocketBase中创建用户记录
• 确保OIDC返回的email与PocketBase中的用户email匹配
• 可以通过API批量创建用户：

// 使用PocketBase JS SDK创建用户示例
await pb.collection('users').create({
  username: 'example-user',
  email: '[e-mail]',
  password: 'randompassword',
  passwordConfirm: 'randompassword',
  role: 'user',
  verified: true
});

3. 日志分析与调试

当集成出现问题时，检查以下日志位置：

• Authelia服务日志
• Beszel(PocketBase)的管理界面日志
• 反向代理的访问日志

高级配置建议

1. 用户自动创建：虽然当前版本需要预创建用户，但可以考虑修改PocketBase的规则来实现OIDC用户的自动创建。

2. 角色管理：建议实现以下角色分配逻辑：

   • 第一个用户自动获得admin角色
   • 后续通过OIDC登录的用户默认获得user角色
   • admin用户可以在后台提升其他用户的权限

3. 多因素认证：利用Authelia的authorization_policy配置可以实现不同级别的认证要求。

总结

Authelia与Beszel的OIDC集成虽然需要一些配置工作，但一旦正确设置，可以提供强大而安全的认证方案。关键点在于：

• 正确配置Authelia的OIDC客户端
• 处理好反向代理的中间件设置
• 确保用户数据同步
• 合理规划角色和权限系统

通过本文的指导，管理员应该能够顺利完成集成工作，并为用户提供无缝的认证体验。