HedgeDoc SAML认证配置问题排查指南

问题现象

在使用HedgeDoc的SAML认证功能时，用户发现访问/auth/saml/metadata和/auth/saml/callback端点时返回404错误。根据文档描述，这些端点本应提供SAML元数据和回调功能。

技术背景

SAML(Security Assertion Markup Language)是一种用于身份认证和授权的开放标准。在HedgeDoc中，SAML集成允许用户通过企业身份提供商(如Authentik)进行单点登录。

问题分析

1. 元数据端点404：正常情况下，/auth/saml/metadata应返回XML格式的SAML服务提供商元数据。404错误表明端点未正确注册或配置有误。
2. 回调端点404：SAML规范中，回调端点通常只接受POST请求。直接通过浏览器GET访问会返回404，这是预期行为。

解决方案

1. 配置验证：

   • 确保环境变量CMD_SAML_IDPSSOURL指向正确的身份提供商SSO地址
   • 确认CMD_SAML_IDPCERT指定的证书路径正确且可读
   • 检查CMD_SAML_ISSUER是否与HedgeDoc服务器URL一致

2. 身份提供商配置：

   • 在Authentik等身份提供商中：
     • 设置ACS(Assertion Consumer Service)URL为/auth/saml/callback
     • 选择正确的签名证书
     • 配置服务提供商实体ID为HedgeDoc的CMD_SAML_ISSUER值

3. 请求方式：

   • 回调端点必须使用POST请求
   • 元数据端点应响应GET请求，若仍返回404需检查：
     • HedgeDoc服务是否正常启动
     • SAML模块是否已启用
     • 路由配置是否正确

最佳实践建议

1. 对于使用Authentik的用户，推荐优先考虑OAuth2集成方案，可避免证书过期等问题
2. 生产环境中建议：
   • 定期轮换SAML签名证书
   • 启用SAML消息加密
   • 配置适当的会话超时时间

总结

HedgeDoc的SAML集成在正确配置下能够稳定工作。遇到端点404问题时，应首先验证配置完整性和请求方法是否正确。对于新部署，建议从基础配置开始逐步验证各环节，并使用浏览器开发者工具或专业SAML调试工具检查请求/响应流程。