默认安装使用 MCPHub 内建账号。首次部署只需要网关公开 HTTPS 地址和配置加密密钥，不需要另外安装身份服务。外部 OIDC/企业 SSO 是可选接入方式。
初始化与登录
- 使用包内
config.example.yaml校验并启动 MCPHub。管理台首次显示本机初始化提示。 - 在服务器本机的另一个终端加载同一份部署环境，执行
mcphub init-admin --config config.yaml --username admin。终端隐藏密码输入，并要求重复确认；密码至少 12 个字符。 - 打开
http://127.0.0.1:8081/，使用刚创建的账号登录。远程部署使用配置的管理员 HTTPS 地址。 - 在「用户与组」先创建组，为组分配角色、Scope、服务、工具和业务资源权限，再创建用户并加入组。新建账号可以登录，但未授权工具不能调用。
初始化只能在服务器本机执行，不能通过匿名网页创建首位管理员；再次初始化会被拒绝。没有默认密码。初始化同时创建带 admin 角色的 Administrators（管理员）组，并将首位管理员加入该组；用户身上不保存直接权限。初始化命令读取 YAML 与环境变量，第二个终端也必须设置 MCPHUB_PUBLIC_URL 和同一份 MCPHUB_CONFIG_KEY。
自动化安装可以用 --password-stdin 从标准输入读取单行密码；不要把密码写进命令参数、公开脚本或 YAML。
组与权限
用户只维护账号状态和所属组，角色、Scope、服务与业务资源权限分配给权限组。权限组的来源为 mcphub:permissions，独立于本地、LDAP 和 OIDC 身份源；组不支持嵌套。
- 点击「创建组」，填写名称。新组默认没有权限。
- 展开权限组，选择角色、服务、精确工具名称和资源条件。默认 按访问意图生成 保存当前所选能力所需 Scope 的快照；工具目录变化不会自动扩大权限。高级：显式 Scope 可手工维护 Scope。
- 本地用户可直接加入权限组；企业用户通过权限组中的 组织组映射 继承权限。一个权限组可映射多个 LDAP/OIDC 组织组，任一有效映射命中即可继承。映射引用稳定的 MCPHub 组 ID，不按名字或邮箱合并身份。
- 在用户记录点击 查看有效权限，核对组、直接成员关系或组织映射、角色、Scope 和服务授权；再登录验证实际目录和调用。
组织组由身份源同步，控制台不在组织组上编辑业务权限。用户、组或映射停用后重新计算权限并撤销越权调用；同一用户的不同权限组取并集，不提供拒绝覆盖。一次工具调用的工具、写开关与所有资源条件必须在同一条授权内成立，不能跨组拼接。
企业用户的组关系在登录或完整目录同步时验证。auth.enterprise_membership_max_age 默认 24h，支持 1m–720h；超过有效期必须重新登录或刷新目录快照，已有长连接也受到该截止时间约束。本地账号不受企业组有效期影响。MCPHub 不轮询 LDAP；需要即时阻断时，应在 MCPHub 停用用户或组织组、取消映射或撤销权限。
最后一位有效管理员不能被停用或降权。初始化的 Administrators 组保持本机恢复入口；先给另一位有效用户授予管理员权限，再调整现有管理员。
密码、停用与恢复
用户在管理台或个人授权中心的「我的账号」修改密码。管理员在「用户与组」重置本地用户密码或停用账号。重置后通过可信渠道交付新密码，并让用户自行修改。
密码重置、修改或账号停用会撤销该用户的访问会话和刷新凭证；重置前未兑换的授权码也会失效。重新启用账号不会恢复旧会话。最后一位有效本地管理员不能被停用或移除管理权限。
密码使用带随机盐的 Argon2id 散列（19 MiB、2 次迭代、1 lane）保存。每个账号连续 5 次失败会锁定 5 分钟；来源 IP 另有限速和密码散列并发上限。服务重启不会清除账号锁定。
并发登录仍共享同一账号的失败计数和动态验证码使用记录。同一个 TOTP 验证码最多成功一次；登录过程中重置密码或停用账号，会使旧密码校验结果失效。
忘记密码时，由另一位管理员重置。如果唯一管理员丢失密码或验证器，持有服务器与数据库密钥的运维人员可在本机执行：
mcphub init-admin --config config.yaml --username admin --reset
# 只有丢失验证器时才额外清除 MFA：
mcphub init-admin --config config.yaml --username admin --reset --reset-mfa
这些命令不会启用已停用用户，也不会改变组成员关系或组权限；会撤销现有会话。保护服务器访问权、数据库和配置密钥。
MFA 与审批加强认证
「我的账号」分别提供修改密码和 MFA 设置表单。展开「启用 MFA」，输入当前密码后点击「生成验证器密钥」，把显示的密钥添加到支持 TOTP 的验证器，并在 5 分钟内输入 6 位验证码确认。确认失败会保留设置说明和密钥；密钥过期可点击「重新开始设置」。成功确认后才会启用 MFA。密钥使用配置密钥加密保存，绑定确认后所有会话退出。
启用后，每次本地账号登录和密码修改均要求密码与 TOTP。采用 RFC 6238 的 SHA1、6 位、30 秒周期，容许相邻一个时间窗；验证码不能重复使用。刚用于绑定或登录的验证码不能立即用于下一次认证，请等待下一周期。
审批要求 require_step_up: true 时，审批人必须为该审批单重新输入密码和动态验证码。证明绑定同一用户、同一浏览器会话和同一审批单，2 分钟内仅能使用一次。普通密码登录不构成 MFA，也不会满足加强认证要求。 本地账号的 ACR 为 urn:mcphub:auth:password-totp；无验证器时加强认证失败，应先绑定 MFA。
企业身份使用所属 OIDC 服务的加强认证；需要显式配置并验收企业 ACR。纯 OAuth2 UserInfo 不提供可靠的 MFA 证明。MFA 不授予审批权限，也不替代具体操作审批。
OAuth 与企业身份
内建模式为 auth.mode: builtin，签发者从 server.public_url 的 HTTPS origin 推导为 /sso。不设置 MCPHUB_AUTH_ISSUER。管理台、个人授权中心和 MCPBridge 复用同一组继承权限与 Hub Token/刷新流程。
默认注册的公开 OAuth 客户端为：
| client ID | 用途 | 资源 |
|---|---|---|
mcpbridge |
用户连接器，回环回调可使用临时端口 | 完整 MCP URL |
mcpbridge-admin |
远程管理 CLI | 管理员 origin |
mcphub-admin |
管理台浏览器 | 管理员 origin |
mcphub-portal |
个人授权中心 | 完整 MCP URL |
公开客户端使用标准授权码、PKCE S256、resource 绑定和可轮换的刷新凭证。代理必须转发 /sso/*、/.well-known/oauth-authorization-server/sso、/.well-known/openid-configuration/sso、MCP 元数据路径和 /client-auth/*。本机管理台登录不依赖这些公开地址可达，但远程用户与 MCPBridge 需要可用且可信的 HTTPS。
需要企业统一登录时，在管理台的「身份服务」配置 LDAP 与 OIDC，可同时启用。登录页面会显示企业登录入口；LDAP 用户在授权页选择 LDAP。企业身份与本地账号保存为不同身份来源，组也分别管理，即使姓名或账号相同，也不会合并或继承权限。新企业身份默认待授权；目录同步只更新配置的企业来源。默认保留本地管理员用于本机恢复。
高级部署也可使用 auth.mode: external 和外部 auth.issuer，或纯 YAML 示例；此模式不提供内建账号。这些是独立部署选择，不是默认安装要求。