身份认证与安全

概述

MCPHub 提供灵活的身份认证机制来保护您的 MCP 服务器管理平台。系统支持多种身份认证方法和基于角色的访问控制。

Better Auth（GitHub / Google / 本地 OIDC）

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_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 的用户，映射后才会拥有管理员权限。

身份认证方法

基于环境变量的认证

使用环境变量配置基础认证：

# 基础认证凭据
AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password

# JWT 设置
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=24h

数据库认证

对于生产环境部署，启用基于数据库的用户管理：

{
  "auth": {
    "provider": "database",
    "database": {
      "url": "postgresql://user:pass@localhost:5432/mcphub",
      "userTable": "users"
    }
  }
}

用户管理

创建用户

通过管理界面或 API 创建用户：

# 通过 API
curl -X POST http://localhost:3000/api/auth/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "securepassword",
    "role": "user"
  }'

用户角色

MCPHub 支持基于角色的访问控制：

管理员: 完整系统访问权限、用户管理、服务器配置
管理者: 服务器管理、组管理、监控
用户: 在分配组内的基本服务器访问权限
查看者: 对分配资源的只读访问权限

基于组的访问控制

将用户分配到组

# 添加用户到组
curl -X POST http://localhost:3000/api/groups/{groupId}/users \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"userId": "user123"}'

组权限

配置组级别权限：

{
  "groupId": "dev-team",
  "permissions": {
    "servers": ["read", "write", "execute"],
    "tools": ["read", "execute"],
    "logs": ["read"],
    "config": ["read"]
  }
}

API 认证

JWT 令牌认证

// 获取认证令牌
const response = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'your-username',
    password: 'your-password',
  }),
});

const { token } = await response.json();

// 在后续请求中使用令牌
const protectedResponse = await fetch('/api/servers', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

API 密钥认证

为系统集成生成 API 密钥：

# 生成新的 API 密钥
curl -X POST http://localhost:3000/api/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Integration Key",
    "permissions": ["servers:read", "servers:write"],
    "expiresAt": "2024-12-31T23:59:59.000Z"
  }'

安全设置

HTTPS 配置

为生产环境启用 HTTPS：

server {
    listen 443 ssl http2;
    server_name mcphub.example.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

会话安全

配置安全的会话设置：

// 会话配置
{
  "session": {
    "secret": "your-session-secret",
    "secure": true,  // 生产环境中需要 HTTPS
    "httpOnly": true,
    "maxAge": 86400000,  // 24 小时
    "sameSite": "strict"
  }
}

速率限制

实施 API 速率限制：

{
  "rateLimit": {
    "windowMs": 900000,  // 15 分钟
    "max": 100,  // 每个 IP 限制 100 个请求
    "message": "请求过于频繁，请稍后再试",
    "standardHeaders": true,
    "legacyHeaders": false
  }
}

多因素认证 (MFA)

启用 TOTP

为管理员帐户启用基于时间的一次性密码：

# 启用 MFA
curl -X POST http://localhost:3000/api/auth/mfa/enable \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "type": "totp",
    "appName": "MCPHub"
  }'

验证 MFA 代码

// 登录时验证 MFA
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'password',
    mfaCode: '123456', // 来自认证器应用的 6 位数字
  }),
});

审计日志

启用审计日志

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

{
  "audit": {
    "enabled": true,
    "logLevel": "info",
    "events": [
      "login",
      "logout",
      "password_change",
      "role_change",
      "permission_change",
      "server_access",
      "config_change"
    ],
    "storage": {
      "type": "database",
      "retention": "90d"
    }
  }
}

查看审计日志

# 获取审计日志
curl -X GET "http://localhost:3000/api/audit/logs?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer $TOKEN"

密码策略

配置密码要求

{
  "passwordPolicy": {
    "minLength": 12,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "preventCommonPasswords": true,
    "preventReuse": 5, // 防止重复使用最近 5 个密码
    "maxAge": 7776000 // 90 天后过期
  }
}

故障排除

常见认证问题

JWT 令牌过期

# 检查令牌有效期
curl -X GET http://localhost:3000/api/auth/verify \
  -H "Authorization: Bearer $TOKEN"

权限被拒绝

# 检查用户权限
curl -X GET http://localhost:3000/api/auth/permissions \
  -H "Authorization: Bearer $TOKEN"

会话问题
- 清除浏览器 cookies
- 检查会话配置
- 验证服务器时间同步

调试认证流程

启用调试日志：

# 设置环境变量
export DEBUG=auth:*
export LOG_LEVEL=debug

# 启动服务器
npm start

安全最佳实践

定期更新凭据: 定期轮换 JWT 密钥和 API 密钥
最小权限原则: 只授予用户执行其任务所需的最小权限
监控异常活动: 设置警报以检测可疑的登录模式
备份配置: 定期备份认证配置和用户数据
安全更新: 保持 MCPHub 和依赖项的最新状态

更多安全配置选项，请参阅环境变量配置和 Docker 设置文档。

开始使用

核心功能

配置指南

概述

Better Auth（GitHub / Google / 本地 OIDC）

本地用户映射规则

身份认证方法

基于环境变量的认证

数据库认证

用户管理

创建用户

用户角色

基于组的访问控制

将用户分配到组

组权限

API 认证

JWT 令牌认证

API 密钥认证

安全设置

HTTPS 配置

会话安全

速率限制

多因素认证 (MFA)

启用 TOTP

验证 MFA 代码

审计日志

启用审计日志

查看审计日志

密码策略

配置密码要求

故障排除

常见认证问题

调试认证流程

安全最佳实践

​概述

​Better Auth（GitHub / Google / 本地 OIDC）

​本地用户映射规则

​身份认证方法

​基于环境变量的认证

​数据库认证

​用户管理

​创建用户

​用户角色

​基于组的访问控制

​将用户分配到组

​组权限

​API 认证

​JWT 令牌认证

​API 密钥认证

​安全设置

​HTTPS 配置

​会话安全

​速率限制

​多因素认证 (MFA)

​启用 TOTP

​验证 MFA 代码

​审计日志

​启用审计日志

​查看审计日志

​密码策略

​配置密码要求

​故障排除

​常见认证问题

​调试认证流程

​安全最佳实践

概述

Better Auth（GitHub / Google / 本地 OIDC）

本地用户映射规则

身份认证方法

基于环境变量的认证

数据库认证

用户管理

创建用户

用户角色

基于组的访问控制

将用户分配到组

组权限

API 认证

JWT 令牌认证

API 密钥认证

安全设置

HTTPS 配置

会话安全

速率限制

多因素认证 (MFA)

启用 TOTP

验证 MFA 代码

审计日志

启用审计日志

查看审计日志

密码策略

配置密码要求

故障排除

常见认证问题

调试认证流程

安全最佳实践