Skip to main content

自助注册

管理员可在「设置 → 安全」中开启「允许自助注册」,默认关闭。开启后,登录页显示「创建账号」入口。 自助注册始终创建普通用户,不能授予管理员权限。即使原账号已删除,仍被资源所有权、共享名单、认证状态或用户配置引用的用户名也不能通过自助注册领取。密码至少八位,且包含字母、数字和特殊字符。 该配置保存在 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)
启用条件:
  1. 配置 DB_URL(Better Auth 当前依赖 PostgreSQL,会话不支持纯文件模式)
  2. 配置 Better Auth 启动参数并重启 MCPHub
  3. 为对应登录方式提供客户端凭据
Better Auth 的非敏感配置现在既可以来自环境变量,也可以来自 systemConfig.auth.betterAuth(mcp_settings.json 或数据库系统配置)。优先级如下:
  1. BETTER_AUTH_* 环境变量
  2. systemConfig.auth.betterAuth
  3. 默认值
常用环境变量包括:
  • 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 代码

审计日志

启用审计日志

跟踪所有认证和授权事件:

查看审计日志

密码策略

配置密码要求

故障排除

常见认证问题

  1. JWT 令牌过期
  2. 权限被拒绝
  3. 会话问题
    • 清除浏览器 cookies
    • 检查会话配置
    • 验证服务器时间同步

调试认证流程

启用调试日志:

安全最佳实践

  1. 定期更新凭据: 定期轮换 JWT 密钥和 API 密钥
  2. 最小权限原则: 只授予用户执行其任务所需的最小权限
  3. 监控异常活动: 设置警报以检测可疑的登录模式
  4. 备份配置: 定期备份认证配置和用户数据
  5. 安全更新: 保持 MCPHub 和依赖项的最新状态
更多安全配置选项,请参阅 环境变量配置 和 Docker 设置 文档。