Knock 敲门

外观切换

外部账号登录（OIDC / OAuth） ​

这页解决什么问题 ​

外部账号登录 让你可以把 Google、Microsoft、GitHub 或自定义 OIDC 账号绑定到 fknock 的登录体系里。

它适合这些场景：

  • 想用公司或个人已有账号登录 fknock
  • 想给家人或团队成员一个更熟悉的登录入口
  • 想减少日常输入 TOTP 的次数，但仍保留 TOTP 作为恢复凭据

需要先明确一点：

外部账号不是独立管理员体系，而是绑定在某个 TOTP 凭据下面的快捷登录方式。

也就是说，TOTP 仍然是基础凭据。外部账号登录成功后，系统会找到它绑定的 TOTP，再按同一套会话和 IP 授权策略创建登录状态。

支持哪些提供商 ​

当前内置提供商包括：

提供商协议常见用途
GoogleOIDCGoogle 账号登录
MicrosoftOIDCMicrosoft / Azure AD 登录
GitHubOAuth2 ProfileGitHub 账号登录
自定义 OIDCOIDCAuthentik、Keycloak、Zitadel 等标准 OIDC 服务

Google、Microsoft 和自定义 OIDC 会走标准 OpenID Connect Discovery；GitHub 使用 OAuth 授权后读取用户资料。

第一步：添加外部登录提供商 ​

路径：

  • 认证配置 → 外部账号登录

添加提供商时通常要填写：

  • 提供商
  • 显示名称
  • Client ID
  • Client Secret
  • Scopes

不同提供商还有少量差异：

  • Microsoft 需要填写 Tenant，常见值是 common、organizations 或具体租户 ID
  • 自定义 OIDC 需要填写 Issuer，例如 https://idp.example.com
  • GitHub 默认使用 read:user 和 user:email

保存后，列表里会显示每个提供商的：

  • 名称
  • 类型
  • 状态
  • Callback URL

第三方控制台里的回调地址必须和这里展示的 Callback URL 完全一致。

Callback URL 应该怎么填 ​

不要手写猜地址，直接复制页面里显示的 Callback URL。

这是因为它会受这些因素影响：

  • 你当前是直接访问鉴权服务，还是经过反代 / 子域入口
  • 子域模式里有没有配置公开鉴权地址
  • 前面是否接了 EdgeOne / ESA
  • 外部访问是否带端口

如果你后来改了外部入口、鉴权子域、EdgeOne / ESA 支持或反代链路，建议回到：

  • 认证配置 → 外部账号登录

重新复制新的 Callback URL，并同步更新第三方控制台。

第二步：把外部账号绑定到 TOTP ​

外部账号必须先绑定，不能拿任意第三方账号直接登录。

路径：

  • 认证配置 → 管理快捷登录 → 外部账号绑定

操作流程：

  1. 进入某个 TOTP 的 管理快捷登录
  2. 在 外部账号绑定 里点击 生成绑定邀请
  3. 选择一个已启用的提供商
  4. 复制邀请链接
  5. 打开邀请链接，完成对应第三方登录
  6. 授权成功后，外部账号会绑定到这个 TOTP

绑定邀请链接有效期固定为：

  • 30 分钟

如果链接过期、已经使用过，或提供商后来被停用，就需要重新生成。

登录页会发生什么变化 ​

只要至少有一个可用的外部登录提供商，登录页就会出现类似：

  • 使用 Google 登录
  • 使用 Microsoft 登录
  • 使用 GitHub 登录
  • 使用 自定义 OIDC 登录

外部账号登录成功后，系统仍会：

  1. 创建登录会话
  2. 根据 系统设置 → 凭据 的策略决定是否给当前 IP 授权
  3. 记录登录事件，认证方式会显示为 OIDC
  4. 如果勾选了 记住我，会使用对应的长期登录有效期

也就是说，外部账号只改变“你如何证明身份”，不会绕开会话、白名单、退出登录和有效期这些后续规则。

和 TOTP / Passkey 的关系 ​

可以这样理解：

  • TOTP：基础凭据和恢复锚点
  • Passkey：绑定在 TOTP 下的本机设备快捷登录
  • 外部账号：绑定在 TOTP 下的第三方账号快捷登录

删除某个 TOTP 时：

  • 这个 TOTP 不能再登录
  • 关联的 Passkey 会失效
  • 关联的外部账号绑定也会被删除

删除某个外部登录提供商时：

  • 该提供商配置会被删除
  • 这个提供商下面的外部账号绑定也会被移除

删除某条外部账号绑定时：

  • 只影响这个外部账号的登录能力
  • 不会删除对应的 TOTP
  • 不会删除同一个 TOTP 下的其他 Passkey

建议的配置顺序 ​

第一次使用时，建议这样做：

  1. 先确认至少有一个可用 TOTP
  2. 添加外部登录提供商
  3. 复制 Callback URL 到第三方控制台
  4. 回到 fknock 里确认提供商状态为已启用
  5. 给目标 TOTP 生成绑定邀请
  6. 用外部账号完成绑定
  7. 退出后再用外部账号登录验证一次

不要在还没有可用 TOTP 的情况下，把外部账号当成唯一登录方式。

常见排查思路 ​

登录页没有出现外部登录按钮 ​

优先检查：

  1. 是否已经添加提供商
  2. 提供商是否启用
  3. Client ID / Client Secret / Issuer 等必填项是否完整
  4. 是否保存后刷新过登录页

第三方登录后回调失败 ​

优先检查：

  1. 第三方控制台里的回调地址是否和 fknock 展示的 Callback URL 完全一致
  2. 外部访问地址是否已经换过域名、端口或路径
  3. 子域模式的鉴权服务是否仍然可访问
  4. EdgeOne / ESA 等前置平台是否正确回源到 fknock

提示外部账号未绑定 ​

这通常说明：

  • 这个第三方账号还没有绑定到任何 TOTP
  • 或原来的绑定已经随 TOTP / 提供商删除而失效

处理方式是重新进入对应 TOTP 的 管理快捷登录，生成绑定邀请并完成绑定。

Microsoft 登录失败 ​

优先确认：

  • Tenant 是否填对
  • 第三方控制台中的 Redirect URI 是否匹配
  • 应用是否允许当前账号或组织登录

不确定时可以先用：

text
common

跑通基础流程，再按组织策略收紧。

相关阅读 ​

QQ群：1081609274

Copyright © fn-knock docs