SWAG与Authelia集成配置问题解析及解决方案

背景介绍

在自托管环境中，SWAG(安全Web应用网关)与Authelia(开源认证系统)的集成是常见的组合方案。近期Authelia进行了重要版本更新(4.38+)，导致原有的SWAG配置不再兼容，许多用户遇到了500错误问题。

问题现象

当用户升级Authelia到4.38+版本后，使用SWAG作为反向代理时，所有受Authelia保护的服务都会返回500错误。Nginx日志中会显示"missing required X-Original-URL header"的错误信息。

配置变更分析

旧版配置(4.37及以下)

旧版Authelia的authelia-location.conf配置相对简单，主要包含：

• 使用/authelia/api/verify端点进行验证
• 设置用户信息头
• 401错误重定向到登录页面

新版配置(4.38及以上)

新版Authelia引入了重大变更：

• 验证端点改为/authelia/api/authz/auth-request
• 需要额外处理Set-Cookie和Location头
• 错误处理方式改变

解决方案

1. 配置文件调整

需要修改authelia-server.conf文件，确保代理路径正确指向Authelia的新端点：

# 适用于4.37及以下版本的验证端点
location = /authelia/api/verify {
    internal;
    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;
    set $upstream_authelia authelia;
    proxy_pass http://$upstream_authelia:9091/api/verify;
    auth_request_set $set_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $set_cookie;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

# 适用于4.38及以上版本的验证端点
location = /authelia/api/authz/auth-request {
    internal;
    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;
    set $upstream_authelia authelia;
    proxy_pass http://$upstream_authelia:9091/api/authz/auth-request;
    auth_request_set $set_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $set_cookie;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

2. Authelia服务配置

在Authelia的configuration.yml中，确保server部分配置正确：

server:
  address: "tcp://:9091/authelia"
  read_buffer_size: 4096
  write_buffer_size: 4096

3. 完整配置检查

确保以下文件都已正确配置：

• authelia-location.conf - 使用新版端点
• authelia-server.conf - 包含新旧两个端点配置
• configuration.yml - 使用新版地址格式

技术原理

Authelia 4.38+版本对API端点进行了重构，主要变化包括：

1. 验证端点从/api/verify改为/api/authz/auth-request
2. 更严格的头部要求，特别是X-Original-URL头
3. 更完善的错误处理机制

这些变更使得代理配置需要更精确地传递请求信息，否则会导致验证失败。

最佳实践

1. 版本兼容性：升级前检查Authelia版本，选择对应的配置方案
2. 配置备份：修改前备份原有配置，便于回滚
3. 逐步验证：先测试单个服务，确认无误后再全面应用
4. 日志监控：密切关注Nginx和Authelia日志，及时发现配置问题

总结

SWAG与Authelia的集成在4.38+版本中需要特别注意端点变更和头部传递问题。通过正确配置代理路径和Authelia服务地址，可以解决500错误问题。建议用户在升级前详细阅读官方文档，了解版本间的差异，确保平滑过渡。