Authelia 集成 Mailcow通过 OpenID Connect 1.0 为邮件系统启用单点登录【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南讲解如何将 Mailcowmailcow-dockerized接入 Authelia 的 OpenID Connect 1.0 Provider使用户可以复用 Authelia 的账户体系与多因素认证2FA直接登录邮件系统。读完本文你将掌握在 Authelia 中注册mailcow客户端的完整 YAML 配置、在 Mailcow Web GUI 中填写 Generic-OIDC 身份提供方参数的逐步操作以及客户端密钥生成、哈希存储等安全最佳实践。测试版本与前提假设本指南基于以下经过验证的版本组合Autheliav4.39.24Mailcowv2025-03示例配置基于如下假设请按你的实际域名替换应用根地址Mailcowhttps://mailcow.example.com/Authelia 根地址https://auth.example.com/Client IDmailcowClient Secretinsecure_secret注意上述client_id与client_secret仅用于演示与可读性严禁直接用于生产环境应按照下文「生成与存储客户端密钥」一节生成随机值。开始前必读在配置任何 OpenID Connect 1.0 注册客户端之前有几个要点需要先了解client_id的约束每个客户端的client_id必须是唯一值只能包含 RFC3986 Unreserved Characters字母、数字及-、.、_、~长度不得超过 100 个字符建议使用 64 位随机字符串。client_secret的约束本指南中的值仅用于演示生产环境必须使用随机生成值强烈建议在 Authelia 配置中以哈希形式存储而非明文明文存储已标记为弃用行为若哈希工作因子过高导致客户端认证超时需要适当调低详见后文「调优工作因子」。配置示例仅为客户端注册片段你仍必须完成 OpenID Connect 1.0 Provider 配置 中要求的其余必填项如issuer、jwks等并且本指南只展示了注册客户端全部可用选项中的一小部分其余选项的详细说明见 OpenID Connect 1.0 Clients 配置指南。在 Authelia 中注册 Mailcow 客户端以下 YAML 是用于对接 Mailcow 的 Authelia 客户端配置示例可直接并入你的configuration.ymlidentity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. clients: - client_id: mailcow client_name: Mailcow client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false authorization_policy: two_factor require_pkce: false pkce_challenge_method: redirect_uris: - https://mailcow.example.com scopes: - openid - profile - email response_types: - code grant_types: - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_post客户端参数逐一解读以下针对示例中出现的每个参数给出含义、默认值与选值依据均依据 clients.md参数说明client_id客户端唯一标识必须与 Mailcow 侧填写的 Client ID 完全一致。client_name在 Authelia 界面上展示的友好名称默认与client_id相同。client_secret与 Mailcow 共享的密钥此处为insecure_secret的 PBKDF2-SHA512 哈希摘要配置侧存哈希Mailcow 侧填明文。public是否启用公开客户端类型。Mailcow 属于能安全保管密钥的 confidential机密客户端因此为false。authorization_policy该客户端的授权策略可选one_factor、two_factor或 Provider 中自定义的authorization_policies。示例使用two_factor即要求用户在登录 Mailcow 时通过 Authelia 完成二次验证。require_pkce是否强制该客户端使用 PKCE。Mailcow 对该机制支持有限示例中保持false。pkce_challenge_method指定 PKCE 挑战方法合法值为空字符串、plain或S256。设置为非空值会同时隐式启用require_pkce。redirect_uris合法的回调 URI 白名单大小写敏感且必须带http/https协议。Mailcow 的回调地址即其应用根地址https://mailcow.example.com。若授权请求中的回调不在此列表内Authelia 将直接拒绝授权。scopes允许该客户端申请的 Scope 列表默认值为openid,groups,profile,email。Mailcow 需要openid profile email。response_types允许的响应类型安全起见仅推荐默认的code授权码流程其余类型Implicit/Hybrid安全性较差。grant_types允许的授权类型默认authorization_code。access_token_signed_response_alg/userinfo_signed_response_algAccess Token 与 UserInfo 响应的签名算法none表示不签名直接返回 JSON。token_endpoint_auth_method客户端在 Token 端点的认证方式Mailcow 使用client_secret_post密钥通过 HTTP POST 表单体传递。在 Mailcow 中配置 Generic-OIDC 身份提供方Mailcow 的配置方式只有一种通过 Web GUI 完成。操作路径如下登录 Mailcow。进入System系统。进入Configuration配置。进入Access访问控制。进入Identity Provider身份提供方。按以下内容填写各选项Mailcow 选项值Identity Provider身份提供方类型Generic-OIDCAuthorization Endpoint授权端点https://auth.example.com/api/oidc/authorizationToken Endpoint令牌端点https://auth.example.com/api/oidc/tokenUser Info Endpoint用户信息端点https://auth.example.com/api/oidc/userinfoClient IDmailcowClient Secretinsecure_secretRedirect URL回调地址https://mailcow.example.comClient Scopesopenid profile email点击页面底部的Save保存完成配置。完成后Mailcow 登录页将把用户重定向到https://auth.example.com由 Authelia 完成认证含可选的 2FA随后通过授权码流程换取令牌并读取用户信息。端点的源码依据上述三个端点路径并非随意填写而是 Authelia 服务端在 internal/oidc/const.go 中定义的固定路由EndpointPathRoot为/api/oidc分别拼接authorization、token、userinfo以及introspection、revocation、device-authorization、pushed-authorization-request等。路由注册逻辑见 internal/server/handlers.go其中授权端点同时支持 GET/POSTToken 端点仅接受 POST且均可通过 OpenID Connect Discovery 自动发现/.well-known/openid-configuration。若 Mailcow 支持自动发现直接指向该地址可避免手工填写出错。生成与存储客户端密钥安全最佳实践生成随机 Client ID推荐使用 Authelia 自带命令生成 72 位、仅含 RFC3986 非保留字符的随机字符串Docker 部署请用docker run --rm authelia/authelia:latest前缀authelia crypto rand --length 72 --charset rfc3986生成随机 Client Secret 并哈希该命令会同时打印明文密钥填入 Mailcow与 PBKDF2 哈希填入 Authelia 配置authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986调优工作因子Authelia 在收到客户端认证请求时需要重新执行哈希运算这是工作因子设计上的「代价」用于拖慢攻击者。若客户端操作出现超时可适当降低迭代次数。可用如下命令度量不同工作因子的耗时time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password关于明文密钥的说明Authelia 目前技术上仍支持在配置中以明文存储client_secret无$前缀或以$plaintext$开头但这一行为已被正式弃用未来可能完全移除。除非实现client_secret_jwt等规范明确要求明文访问密钥的场景否则强烈建议一律改用哈希存储。相关细节见 Frequently Asked Questions。验证与常见问题确认配置加载重启 Authelia 后查看日志确认mailcow客户端注册成功且无 scope 警告若配置了未在 Scope 定义 中出现的 scope日志会出现警告。回调地址必须精确匹配redirect_uris的大小写、协议、端口必须与 Mailcow 实际使用的回调完全一致否则授权请求会被拒绝。密钥不匹配确认 Mailcow 侧填写的是明文密钥而 Authelia 配置中是同一密钥的哈希摘要若使用client_secret_basic类认证方式且密钥含特殊字符还须关注 RFC6749 Appendix B 要求的 URL 编码问题示例采用client_secret_post可规避部分此类问题。授权策略预期authorization_policy: two_factor意味着即便用户在 Authelia 已通过一次认证访问 Mailcow 时仍会按策略要求完成两步验证该策略只作用于授权请求与访问控制规则Access Control Rules是两套独立的机制。相关参考OpenID Connect 1.0 集成总览OpenID Connect 1.0 Clients 配置指南OpenID Connect 1.0 Provider 配置指南OpenID Connect 1.0 常见问题FAQ【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考