自助注册
管理员可在「设置 → 安全」中开启「允许自助注册」,默认关闭。开启后,登录页显示「创建账号」入口。
自助注册始终创建普通用户,不能授予管理员权限。即使原账号已删除,仍被资源所有权、共享名单、认证状态或用户配置引用的用户名也不能通过自助注册领取。密码至少八位,且包含字母、数字和特殊字符。
该配置保存在 mcp_settings.json 的 systemConfig.auth.allowRegistration,支持文件和数据库存储,无需重启。
当生效的 SSO 配置禁用密码登录时,后端同时拒绝本地注册,登录页隐藏注册入口。已有账号仍然保留。
概述
MCPHub 提供灵活的身份认证机制来保护您的 MCP 服务器管理平台。系统支持多种身份认证方法和基于角色的访问控制。
本地用户与凭据失效
Dashboard JWT、通行密钥 和 MCPHub 内置 OAuth 授权绑定签发时的用户密码哈希。删除本地用户或修改密码后,旧凭据失效;重建同名用户不会恢复旧凭据。JWT 请求使用用户当前的管理员权限。删除用户还会清理 OAuth token、处理实例内待兑换的授权码,以及服务器和组的共享名单。
从没有会话版本的旧凭据升级后,需要重新登录并重新连接 OAuth 客户端。数据库模式会通过正常的启动 schema 同步为 oauth_tokens 添加可空的 session_version 列。升级时应重启所有副本。
POST /api/auth/register 遵循上文默认关闭的自助注册策略,并始终创建普通用户。角色分配请使用管理员用户管理 API。
内置 OAuth token 可用于 MCP 传输接口及 /oauth/userinfo,不能访问 /api/* 管理接口。管理操作请使用 Dashboard JWT、Better Auth session、已配置的 forward auth 或系统级全访问 bearer key。
通行密钥(Passkey)
本地账户可以使用通行密钥(WebAuthn)代替密码登录。通行密钥是保存在用户设备、密码管理器或安全密钥中的可发现凭据,因此登录页无需输入用户名:点击 使用通行密钥登录,再通过设备的指纹、面容、屏幕锁或 PIN 确认即可。
添加方法:打开用户菜单 → 通行密钥 → 添加通行密钥,填写可选名称和当前密码,然后按照浏览器提示操作。添加长期凭据前会用密码再次确认会话所有者。页面列出每个通行密钥的添加时间、上次使用时间以及是否已同步,并可在确认后移除。每个账户最多可保存 20 个通行密钥。
- 安全上下文: 浏览器只在 HTTPS 页面或
localhost 上提供通行密钥,并且只支持域名,不支持 IP 地址。
- 绑定主机名: 通行密钥属于创建时打开控制台所用的主机名(WebAuthn 依赖方 ID)。MCPHub 从浏览器的
Origin 获取该值并随通行密钥保存,之后只在同一主机名下接受该通行密钥。通过其他主机名打开控制台时,需要在那里另外添加通行密钥。使用反向代理时,请把原始 Origin(或 Host 与协议)传给 MCPHub。
- 会话: 通行密钥登录签发与密码登录相同的 24 小时 JWT,并要求认证器完成用户验证。每个挑战五分钟后过期,且只被接受一次;在 副本模式 下,已使用的挑战记录在共享的
oauth_state 表中,因此跨副本同样只接受一次。签名计数器会拒绝上报计数器的克隆认证器:已保存的计数器只会前进,并发登录时也是如此;始终上报 0 的认证器(多数同步通行密钥)不受影响。挑战使用 JWT_SECRET 签名,因此一次登录的两个请求可以到达不同副本。
- 策略: 通行密钥属于本地账户凭据,因此 仅允许 SSO 登录 生效时同样拒绝通行密钥登录和注册;重新启用密码登录后,已保存的通行密钥恢复可用。Bearer 密钥、转发认证身份和跳过认证模式不能注册通行密钥;由 SSO 创建的用户没有已知的本地密码,继续通过身份提供商登录。
- 生命周期: 与 JWT 和 OAuth 授权一样,通行密钥绑定账户当前的密码。修改或重置密码、删除后重建同名用户,都会使其失效,用户之后需重新添加。设备丢失时请在通行密钥页面移除对应条目;账户被盗用后,重置密码即可撤销全部通行密钥。
- 存储: 文件模式将通行密钥保存在
<设置文件>.passkeys.json 中(仅所有者可读写),不写入 mcp_settings.json,也不包含在配置导出中。数据库模式使用 user_passkeys 表;若 DB_SYNCHRONIZE=false,升级前请先执行 docs/migrations/0008-passkeys.sql。从文件模式迁移到数据库模式时,通行密钥会随用户一起迁移。
- 限流: 签发登录挑战受
PASSKEY_RATE_LIMIT_MAX / PASSKEY_RATE_LIMIT_WINDOW_MS 限制(默认每 15 分钟 100 次)。失败的通行密钥登录和失败的密码确认计入登录限流(AUTH_RATE_LIMIT_MAX)。
Better Auth(GitHub / Google / 本地 OIDC)
从 MCPHub v1.1.14 或更早版本升级: Better Auth 1.7 将通用 OIDC 登录入口改为 /sign-in/social,Provider 回调路径从 /oauth2/callback/<providerId> 改为 /callback/<providerId>。升级前请在身份提供商中添加新的完整重定向 URI:<MCPHub 公开地址><Better Auth basePath>/callback/<providerId>。使用默认挂载路径和 Provider ID 时为 https://mcphub.example.com/api/auth/better/callback/oidc。请包含安装使用的 BASE_PATH 及自定义 BETTER_AUTH_BASE_PATH。旧实例仍在运行时,请同时保留旧 URI。这是身份提供商返回 MCPHub 的回调地址,并非登录完成后的仪表盘跳转地址。
MCPHub 可以通过 Better Auth 为 Dashboard 提供第三方登录。当前支持:
- GitHub
- Google
- 本地 OIDC Provider(例如 Keycloak、Authentik、Dex)
启用条件:
- 配置
DB_URL(Better Auth 当前依赖 PostgreSQL,会话不支持纯文件模式)
- 配置 Better Auth 启动参数并重启 MCPHub
- 为对应登录方式提供客户端凭据
Better Auth 的非敏感配置现在既可以来自环境变量,也可以来自 systemConfig.auth.betterAuth(mcp_settings.json 或数据库系统配置)。优先级如下:
BETTER_AUTH_* 环境变量
systemConfig.auth.betterAuth
- 默认值
常用环境变量包括:
BETTER_AUTH_ENABLED
BETTER_AUTH_URL
BETTER_AUTH_BASE_PATH
BETTER_AUTH_TRUSTED_ORIGINS
BETTER_AUTH_DISABLE_PASSWORD_LOGIN(参见下文“仅允许 SSO 登录”)
BETTER_AUTH_GOOGLE_ENABLED + GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
BETTER_AUTH_GITHUB_ENABLED + GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET
BETTER_AUTH_OIDC_ENABLED
BETTER_AUTH_OIDC_PROVIDER_ID
BETTER_AUTH_OIDC_DISCOVERY_URL(兼容别名:OIDC_DISCOVERY_URL)
BETTER_AUTH_OIDC_SCOPES
BETTER_AUTH_OIDC_PKCE
BETTER_AUTH_OIDC_PROMPT
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET
本地 OIDC 登录也可以继续在 systemConfig.auth.betterAuth.providers.oidc 中配置:
enabled
providerId
discoveryUrl
- 可选的
scopes、pkce、prompt
discoveryUrl 应指向 OIDC Provider 的 /.well-known/openid-configuration。如果仍然使用配置文件插值,OIDC_DISCOVERY_URL 也会继续生效。
如果 Dashboard 通过不同的公网来源发起登录,请设置 BETTER_AUTH_TRUSTED_ORIGINS(或 systemConfig.auth.betterAuth.trustedOrigins)来允许该来源。如果没有显式配置 trustedOrigins,MCPHub 会自动信任 BETTER_AUTH_URL 和 systemConfig.install.baseUrl 的来源。
当 OIDC Provider 可用时,登录页会显示“使用 OIDC 登录”按钮。
默认挂载路径是 ${BASE_PATH}/api/auth/better;如果需要改路径,可以使用 BETTER_AUTH_BASE_PATH,或者在 systemConfig.auth.betterAuth.basePath 中提供后备值。
本地用户映射规则
Better Auth 登录成功后,MCPHub 会把会话映射回本地用户:
- 优先使用
email
- 其次使用
name
- 最后回退到 provider 返回的
id
如果本地不存在对应 username,MCPHub 会自动创建一个非管理员用户。
OIDC / GitHub / Google 登录都不会自动授予管理员权限。只有本地已存在同名且 isAdmin=true 的用户,映射后才会拥有管理员权限。
仅允许 SSO 登录
如需只允许通过 SSO 提供商登录,可在 设置 → Better Auth 中开启 禁用密码登录,或设置 systemConfig.auth.betterAuth.disablePasswordLogin: true。此时登录页只显示提供商按钮,POST /api/auth/login 返回 403。与其他 Better Auth 设置不同,它无需重启即可生效。
- 不会锁死: 仅在至少有一个提供商真正可用(Better Auth 已开启、数据库模式、凭据齐全),且在 MCPHub 启动时已启用时生效,因为提供商的登录路由只在启动时创建;否则密码登录保持可用:新启用提供商后,需要重启 MCPHub 才会生效。
- 恢复:
BETTER_AUTH_DISABLE_PASSWORD_LOGIN 在两个方向上都优先于已保存的设置。如果身份提供商不可用,将其设为 false 并重启,即可重新使用本地密码登录。为此请给本地管理员保留一个强密码。
- 脚本和 CLI 在禁用期间无法使用密码登录。请使用访问类型为
all 的系统级 Bearer 密钥,它可以访问管理 API(CLI 使用 mcphub config set-token <key> --bearer)。
- 之前通过密码登录签发的令牌在过期前仍然有效。修改本地密码仍然可用,因此可以轮换用于恢复的密码。
- 禁用密码登录期间同样拒绝 通行密钥,因为它们用于登录本地账户。
转发认证(基于 JWKS 验证的网关身份)
当 MCPHub 部署在已完成用户认证的 API 网关或身份感知代理之后时,转发认证允许 MCPHub 信任网关传来的 JWT,用户无需再次登录。MCPHub 会使用身份提供方的 JWKS 自行验证令牌,因此 MCPHub 仍然是安全边界。转发认证默认关闭,同时作用于仪表盘 API 和 MCP 传输路由(/mcp/*、/sse/* 及其用户级路由)。
JWT 从配置的 Bearer 请求头中读取(默认为 Authorization: Bearer <jwt>)。
部分网关会在自己的请求头中发送不带 Bearer 前缀的 JWT,例如 Cloudflare Access 会为每个放行的请求添加 Cf-Access-Jwt-Assertion。将 jwks.tokenHeader 设置为该请求头名称后,令牌将从该请求头读取,可以是原始 JWT,也可以是 Bearer <jwt>。设置令牌请求头后,转发认证只读取该请求头,Bearer 请求头仍可用于 Bearer 密钥和 OAuth 令牌。即使该请求头列在 passthroughHeaders 中,MCPHub 也不会将其转发给上游服务器。请求头名称无效时,转发认证将被禁用。
验证
- 令牌使用
jwks.uri 进行验证。密钥会被缓存,遇到未知 kid 时会重新获取,因此身份提供方轮换密钥无需重启。
- 始终校验
iss、aud 和 exp;sub 与 exp 为必需声明。允许 30 秒的时钟偏差。
- 仅接受非对称算法(
RS*、PS*、ES*、EdDSA;默认 RS256 和 ES256)。配置 HS* 或 none 会使转发认证被禁用。
jwks.uri 必须使用 https(仅 localhost 允许 http)。issuer 和 audience 为必填项。配置不完整或无效时,转发认证保持禁用并记录错误日志。
请求处理
- 转发认证先于 Bearer 密钥、OAuth 令牌、Better Auth 会话和仪表盘 JWT 进行检查。
- 非 JWT 令牌,或
iss 不是所配置签发方的令牌会被忽略,其他认证方式照常执行。
- 来自所配置签发方但验证失败(签名错误、已过期、受众错误、算法不允许)或无法映射到用户的令牌会返回
401,MCPHub 不会回退到其他认证方式。
身份映射
- 身份由(
iss、sub)确定,以 forward-auth: 命名空间存储在用户的 ssoUserId 中,与 Better Auth 身份相互隔离。Better Auth 登录不会接管转发认证用户,反之亦然。
- 首次出现时,MCPHub 会创建一个非管理员本地用户。用户名取自
usernameClaim,其次为 emailClaim,最后为 sub。
- 不会通过用户名或邮箱关联已有账户。如果用户名或邮箱已属于其他账户(包括
admin),请求会返回 401。
- 绑定后,即使用户在身份提供方处改名,本地用户名也不会改变,因为服务器、分组和密钥都引用用户名。
- 管理员身份始终取自本地用户记录,JWT 中的角色声明会被忽略。
- 设置
autoCreate: false 时,只接受已绑定本地用户的身份。由于不会关联已有账户,这实际上会拒绝所有新身份。
转发认证配置在每次请求时读取,修改后无需重启。每个字段都可以通过环境变量覆盖,参见环境变量。
身份认证方法
基于环境变量的认证
使用环境变量配置基础认证:
数据库认证
对于生产环境部署,启用基于数据库的用户管理:
用户管理
创建用户
通过管理界面或 API 创建用户:
用户角色
MCPHub 支持基于角色的访问控制:
- 管理员: 完整系统访问权限、用户管理、服务器配置
- 管理者: 服务器管理、组管理、监控
- 用户: 在分配组内的基本服务器访问权限
- 查看者: 对分配资源的只读访问权限
基于组的访问控制
将用户分配到组
组权限
配置组级别权限:
Bearer 密钥
Bearer 密钥通过 /api/auth/keys 管理。管理员可管理所有密钥,普通用户可创建、重命名、启用、禁用和删除自己的个人密钥。个人密钥(kind: 'user')仅用于 MCP 传输接口,不能访问仪表盘或管理 API;请求时会读取所属用户的当前权限。使用可选的 /:user/mcp/... 路由时,URL 中的用户名必须与密钥所属用户一致。
个人密钥支持默认的 accessType: 'all'(保留所属用户的权限),也支持 accessType: 'groups' 配合非空的 allowedGroups 数组。在设置中创建或编辑密钥时可选择访问范围。API 接受已有分组的名称或 ID,并保存分组 ID;运行时仅按解析出的分组 ID 匹配授权。
限定分组的密钥只能访问 /mcp/{允许的分组}、/mcp/$smart/{允许的分组} 及对应的 SSE 和用户级路由。全局 /mcp、全局 $smart、直接服务器端点和其他分组均被拒绝,即使目标服务器属于允许的分组也不能通过直接服务器端点访问,以保留分组中的能力选择限制。允许多个分组时,需分别连接各分组端点,不提供聚合的全局目录。
密钥范围始终与所属用户当前的分组、服务器可见性及分组中的能力选择取交集,不会授予额外权限。管理员拥有的个人密钥同样受分组范围限制。分组删除或已保存的允许列表为空时会拒绝访问,不会恢复为无限制访问。未限定分组的已有密钥保持原有行为。即使 enableBearerAuth 为 false,已识别的个人密钥仍会校验身份和范围;匿名请求继续遵循该部署设置。
系统密钥(kind: 'system')保留原有范围规则。只有 accessType: 'all' 的系统密钥可访问仪表盘和管理 API,受限系统密钥的范围在 MCP 传输层执行。
重置 Bearer key
管理员和用户级 key 的所有者可在设置中点击重置 Bearer key。确认后,POST /api/auth/keys/:id/reset 生成新 token,仅展示一次,供查看和复制;原 token 立即失效。key 的 ID、名称、类型、归属用户、启用状态及资源权限均保持不变。存储中仅保留 hash 和前缀,列表仍返回脱敏值。
API 认证
JWT 令牌认证
API 密钥认证
为系统集成生成 API 密钥:
安全设置
HTTPS 配置
为生产环境启用 HTTPS:
会话安全
配置安全的会话设置:
速率限制
实施 API 速率限制:
多因素认证 (MFA)
启用 TOTP
为管理员帐户启用基于时间的一次性密码:
验证 MFA 代码
审计日志
启用审计日志
跟踪所有认证和授权事件:
查看审计日志
密码策略
配置密码要求
故障排除
常见认证问题
-
JWT 令牌过期
-
权限被拒绝
-
会话问题
- 清除浏览器 cookies
- 检查会话配置
- 验证服务器时间同步
调试认证流程
启用调试日志:
安全最佳实践
- 定期更新凭据: 定期轮换 JWT 密钥和 API 密钥
- 最小权限原则: 只授予用户执行其任务所需的最小权限
- 监控异常活动: 设置警报以检测可疑的登录模式
- 备份配置: 定期备份认证配置和用户数据
- 安全更新: 保持 MCPHub 和依赖项的最新状态
更多安全配置选项,请参阅 环境变量配置 和 Docker 设置 文档。