BillionMail 与 aaPanel 如何开启单点登录SSOAAPANEL_SSO_SECRET 配置【免费下载链接】BillionMailBillionMail gives you open-source MailServer, NewsLetter, Email Marketing — fully self-hosted, dev-friendly, and free from monthly fees. Join the discord: https://discord.gg/asfXzBUhZr项目地址: https://gitcode.com/GitHub_Trending/bi/BillionMail如果你的 BillionMail 部署在 aaPanel 环境中例如通过 aaPanel 的 Docker 一键安装或挂在 aaPanel 的路径代理后面你可能希望从 aaPanel 侧带着可信签名直接进入 BillionMail 管理后台而不是让用户再单独输一遍账密。BillionMail 提供了POST /api/aapanel/sso接口专门处理这种请求整个功能由.env里的AAPANEL_SSO_SECRET一个变量控制留空即关闭填入共享密钥即开启。本文给出完整的配置、重启生效、发起签名请求和验证结果的步骤。前提条件BillionMail 已按 README.md 完成安装并运行bash install.sh或cp env_init .env docker compose up -d并且已经存在要通过 SSO 登录的 BillionMail 账号。工作原理先看清约束再动手实现逻辑在 core/internal/controller/rbac/rbac_v1_aapanel_sso.go几个关键点决定了后面的操作服务端读取AAPANEL_SSO_SECRET也接受BT_PANEL_SSO_SECRET作为备用变量名两者同时存在时AAPANEL_SSO_SECRET优先。请求必须带三个请求头X-Aapanel-TimestampUnix 秒、X-Aapanel-Nonce不超过 128 字符、X-Aapanel-SignatureHMAC-SHA256 签名。签名内容为timestamp \n nonce \n username三段拼接以密钥为 key 做 HMAC-SHA256结果转小写十六进制。请求头里的签名带sha256前缀时会被自动去除。时间戳与服务器当前时间偏差不超过 300 秒否则报请求过期nonce 在 300 秒内只能使用一次重复使用会被拒绝。请求体的username可选为空时服务端回退读取ADMIN_USERNAME环境变量签名计算的 username 用的是最终解析出的值。第一步在 .env 中设置 AAPANEL_SSO_SECRET.env位于 BillionMail 安装目录走install.sh安装时由 install.sh 自动生成走 Docker 手动安装时由cp env_init .env得到模板见 env_init。找到这一段# Shared secret used by aaPanel to request trusted BillionMail SSO tokens. # Keep empty to disable aaPanel SSO. AAPANEL_SSO_SECRET在后填入你与 aaPanel 侧约定好的共享密钥例如AAPANEL_SSO_SECRET你的共享密钥留空表示关闭 SSO此时任何签名请求都会返回aaPanel SSO is disabled。密钥一旦改过aaPanel 侧必须同步换用新密钥重新签名。第二步重启 core 服务使配置生效SSO 逻辑跑在 core 服务里修改.env后必须重启才能生效。项目自带管理脚本 bm.sh在 BillionMail 安装目录下执行bm restart该命令会重启 BillionMail 全部容器。如果只想重启 core 一个服务影响面更小用bm r-s corerestart-service支持的服务名为postfix|core|dovecot|rspamd|redis|webmail|pgsql本文只需要core。第三步发起一个带签名的 SSO 请求接口是POST /api/aapanel/sso请求体为 JSONusername可填可不填。下面给出一个可直接执行的验证脚本把三个占位值替换掉即可SECRET换成.env里设置的密钥USERNAME换成 BillionMail 中已存在的账号名BASE_URL换成 BillionMail 的访问地址如https://mail.example.com。SECRET替换为 .env 中设置的 AAPANEL_SSO_SECRET USERNAME替换为已存在的 BillionMail 账号名 BASE_URL替换为 BillionMail 访问地址如 https://mail.example.com TIMESTAMP$(date %s) NONCE$(cat /proc/sys/kernel/random/uuid) SIGNATURE$(printf %s\n%s\n%s $TIMESTAMP $NONCE $USERNAME | openssl dgst -sha256 -hmac $SECRET -hex | awk {print $2}) curl -sS -X POST ${BASE_URL}/api/aapanel/sso \ -H Content-Type: application/json \ -H X-Aapanel-Timestamp: ${TIMESTAMP} \ -H X-Aapanel-Nonce: ${NONCE} \ -H X-Aapanel-Signature: ${SIGNATURE} \ -d {\username\: \${USERNAME}\}说明两点printf拼出的内容末尾没有多余换行与源码里的签名拼接方式一致如果你把 BillionMail 部署在 aaPanel 路径代理下.env中WEB_BASE_PATH/billionmail见 env_init 注释请求路径相应变为/billionmail/api/aapanel/sso。第四步验证结果与失败排查成功时接口返回的 JSON 中success为truecode为0msg为aaPanel SSO successfuldata里带有token、refreshToken、ttl和accountInfo含账号 id、用户名、邮箱、状态、语言拿到token即表示已以该账号身份完成登录无需再走密码登录。同时系统会写入一条操作日志The user:用户名 login by aaPanel SSO was successful可作为登录成功与否的二次确认。请求失败时按返回的错误信息对照下面的表定位均为实现中的原始报错错误信息原因aaPanel SSO is disabledAAPANEL_SSO_SECRET未设置或为空missing aaPanel SSO signature headers三个X-Aapanel-*请求头有缺失invalid aaPanel SSO noncenonce 长度超过 128 字符invalid aaPanel SSO timestamptimestamp 不是数字形式的 Unix 秒aaPanel SSO request expiredtimestamp 与服务器时间偏差超过 300 秒检查服务器时钟aaPanel SSO nonce already used同一 nonce 在 300 秒内被重复使用invalid aaPanel SSO signature签名不匹配通常是两边密钥不一致或签名拼接方式不对account does not exist请求的 username 在 BillionMail 中没有对应账号username cannot be empty请求体 username 为空且ADMIN_USERNAME未设置边界说明该接口的鉴权依赖共享密钥与时间戳/nonce 防重放机制/api/aapanel/sso本身被排除在 IP 白名单与 JWT 中间件之外见 core/internal/cmd/cmd.go、core/internal/service/rbac/jwt.go因此密钥本身必须保密泄露等同于登录能力泄露。SSO 登录的是请求里指定的既有账号接口不会创建账号想换登录身份改请求体里的username并保证签名覆盖同一值即可。关闭 SSO 只需把AAPANEL_SSO_SECRET清空并再次执行bm restart或bm r-s core。【免费下载链接】BillionMailBillionMail gives you open-source MailServer, NewsLetter, Email Marketing — fully self-hosted, dev-friendly, and free from monthly fees. Join the discord: https://discord.gg/asfXzBUhZr项目地址: https://gitcode.com/GitHub_Trending/bi/BillionMail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 11:21:03 · 阅读 1.2k BillionMail 与 aaPanel 如何开启单点登录（SSO，AAPANEL_SSO_SECRET 配置）
BillionMail 与 aaPanel 如何开启单点登录SSOAAPANEL_SSO_SECRET 配置【免费下载链接】BillionMailBillionMail gives you open-source MailServer, NewsLetter, Email Marketing — fully self-hosted, dev-friendly, and free from monthly fees. Join the discord: https://discord.gg/asfXzBUhZr项目地址: https://gitcode.com/GitHub_Trending/bi/BillionMail如果你的 BillionMail 部署在 aaPanel 环境中例如通过 aaPanel 的 Docker 一键安装或挂在 aaPanel 的路径代理后面你可能希望从 aaPanel 侧带着可信签名直接进入 BillionMail 管理后台而不是让用户再单独输一遍账密。BillionMail 提供了POST /api/aapanel/sso接口专门处理这种请求整个功能由.env里的AAPANEL_SSO_SECRET一个变量控制留空即关闭填入共享密钥即开启。本文给出完整的配置、重启生效、发起签名请求和验证结果的步骤。前提条件BillionMail 已按 README.md 完成安装并运行bash install.sh或cp env_init .env docker compose up -d并且已经存在要通过 SSO 登录的 BillionMail 账号。工作原理先看清约束再动手实现逻辑在 core/internal/controller/rbac/rbac_v1_aapanel_sso.go几个关键点决定了后面的操作服务端读取AAPANEL_SSO_SECRET也接受BT_PANEL_SSO_SECRET作为备用变量名两者同时存在时AAPANEL_SSO_SECRET优先。请求必须带三个请求头X-Aapanel-TimestampUnix 秒、X-Aapanel-Nonce不超过 128 字符、X-Aapanel-SignatureHMAC-SHA256 签名。签名内容为timestamp \n nonce \n username三段拼接以密钥为 key 做 HMAC-SHA256结果转小写十六进制。请求头里的签名带sha256前缀时会被自动去除。时间戳与服务器当前时间偏差不超过 300 秒否则报请求过期nonce 在 300 秒内只能使用一次重复使用会被拒绝。请求体的username可选为空时服务端回退读取ADMIN_USERNAME环境变量签名计算的 username 用的是最终解析出的值。第一步在 .env 中设置 AAPANEL_SSO_SECRET.env位于 BillionMail 安装目录走install.sh安装时由 install.sh 自动生成走 Docker 手动安装时由cp env_init .env得到模板见 env_init。找到这一段# Shared secret used by aaPanel to request trusted BillionMail SSO tokens. # Keep empty to disable aaPanel SSO. AAPANEL_SSO_SECRET在后填入你与 aaPanel 侧约定好的共享密钥例如AAPANEL_SSO_SECRET你的共享密钥留空表示关闭 SSO此时任何签名请求都会返回aaPanel SSO is disabled。密钥一旦改过aaPanel 侧必须同步换用新密钥重新签名。第二步重启 core 服务使配置生效SSO 逻辑跑在 core 服务里修改.env后必须重启才能生效。项目自带管理脚本 bm.sh在 BillionMail 安装目录下执行bm restart该命令会重启 BillionMail 全部容器。如果只想重启 core 一个服务影响面更小用bm r-s corerestart-service支持的服务名为postfix|core|dovecot|rspamd|redis|webmail|pgsql本文只需要core。第三步发起一个带签名的 SSO 请求接口是POST /api/aapanel/sso请求体为 JSONusername可填可不填。下面给出一个可直接执行的验证脚本把三个占位值替换掉即可SECRET换成.env里设置的密钥USERNAME换成 BillionMail 中已存在的账号名BASE_URL换成 BillionMail 的访问地址如https://mail.example.com。SECRET替换为 .env 中设置的 AAPANEL_SSO_SECRET USERNAME替换为已存在的 BillionMail 账号名 BASE_URL替换为 BillionMail 访问地址如 https://mail.example.com TIMESTAMP$(date %s) NONCE$(cat /proc/sys/kernel/random/uuid) SIGNATURE$(printf %s\n%s\n%s $TIMESTAMP $NONCE $USERNAME | openssl dgst -sha256 -hmac $SECRET -hex | awk {print $2}) curl -sS -X POST ${BASE_URL}/api/aapanel/sso \ -H Content-Type: application/json \ -H X-Aapanel-Timestamp: ${TIMESTAMP} \ -H X-Aapanel-Nonce: ${NONCE} \ -H X-Aapanel-Signature: ${SIGNATURE} \ -d {\username\: \${USERNAME}\}说明两点printf拼出的内容末尾没有多余换行与源码里的签名拼接方式一致如果你把 BillionMail 部署在 aaPanel 路径代理下.env中WEB_BASE_PATH/billionmail见 env_init 注释请求路径相应变为/billionmail/api/aapanel/sso。第四步验证结果与失败排查成功时接口返回的 JSON 中success为truecode为0msg为aaPanel SSO successfuldata里带有token、refreshToken、ttl和accountInfo含账号 id、用户名、邮箱、状态、语言拿到token即表示已以该账号身份完成登录无需再走密码登录。同时系统会写入一条操作日志The user:用户名 login by aaPanel SSO was successful可作为登录成功与否的二次确认。请求失败时按返回的错误信息对照下面的表定位均为实现中的原始报错错误信息原因aaPanel SSO is disabledAAPANEL_SSO_SECRET未设置或为空missing aaPanel SSO signature headers三个X-Aapanel-*请求头有缺失invalid aaPanel SSO noncenonce 长度超过 128 字符invalid aaPanel SSO timestamptimestamp 不是数字形式的 Unix 秒aaPanel SSO request expiredtimestamp 与服务器时间偏差超过 300 秒检查服务器时钟aaPanel SSO nonce already used同一 nonce 在 300 秒内被重复使用invalid aaPanel SSO signature签名不匹配通常是两边密钥不一致或签名拼接方式不对account does not exist请求的 username 在 BillionMail 中没有对应账号username cannot be empty请求体 username 为空且ADMIN_USERNAME未设置边界说明该接口的鉴权依赖共享密钥与时间戳/nonce 防重放机制/api/aapanel/sso本身被排除在 IP 白名单与 JWT 中间件之外见 core/internal/cmd/cmd.go、core/internal/service/rbac/jwt.go因此密钥本身必须保密泄露等同于登录能力泄露。SSO 登录的是请求里指定的既有账号接口不会创建账号想换登录身份改请求体里的username并保证签名覆盖同一值即可。关闭 SSO 只需把AAPANEL_SSO_SECRET清空并再次执行bm restart或bm r-s core。【免费下载链接】BillionMailBillionMail gives you open-source MailServer, NewsLetter, Email Marketing — fully self-hosted, dev-friendly, and free from monthly fees. Join the discord: https://discord.gg/asfXzBUhZr项目地址: https://gitcode.com/GitHub_Trending/bi/BillionMail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考