跳到正文

外部帐号登录 ​

如果家里已经有自建的 Authentik、Authelia、Keycloak、Pocket ID,或者家人都在使用 Google、Microsoft、GitHub 帐号,可以让大家用这些帐号登录 Keepbay,不需要再单独记一个密码。

外部帐号登录是免费版就有的功能。它属于登录安全功能,Keepbay 的安全功能都不收费。

支持的提供方 ​

  • 通用 OIDC:Authentik、Authelia、Keycloak、Pocket ID、Kanidm、Zitadel 等支持 OpenID Connect 的身份提供方
  • Google
  • Microsoft:可以是个人帐号,也可以是工作或学校帐号
  • GitHub

可以同时添加多个。

微信、企业微信、钉钉、飞书用的是各自的协议,Keepbay 不直接支持。可以先接入 Keycloak 或 Casdoor,再由它们以 OIDC 的方式接入 Keepbay。

添加提供方 ​

  1. 在「系统设置 › 外部登录」中,复制页面上方的「回调地址」
  2. 到提供方的管理后台新建一个应用,把回调地址填为 Redirect URI,记下 Client ID 和 Client Secret
  3. 回到 Keepbay,点「添加」,选择类型,填写 Client ID 和 Client Secret

字段说明:

字段说明
显示名称登录页按钮上的名字,留空时用类型名
Issuer只有通用 OIDC 要填:提供方的 Issuer 地址,不含 /.well-known/openid-configuration
租户只有 Microsoft 有:默认 common,也可以填 organizations、consumers、租户 ID 或域名
Client ID、Client Secret在提供方新建应用后得到。修改时 Client Secret 留空表示不变
启用关闭后登录页不再显示这个按钮
自动建号见下文

新增通用 OIDC、Google、Microsoft 提供方,或者修改了 Issuer 时,Keepbay 会先连接提供方读取配置,无法连接时不会保存。

这一步只能确认地址正确。Client ID 和 Client Secret 是否正确,需要保存后实际登录一次才能确认。

Client Secret 加密保存在数据库中,保存后不再显示。

回调地址 ​

回调地址的格式是:

https://您的域名/api/v1/auth/oidc/callback

部署在子路径下时,回调地址中也包含子路径,比如 https://example.com/keepbay/api/v1/auth/oidc/callback。

在「系统设置 › 通用」中填写了访问地址时(从 1.0.0-beta.8 起),回调地址按访问地址生成,与您当前从哪个地址打开 Keepbay 无关。没有填写时,按您当前访问 Keepbay 的地址生成,请用以后实际访问的域名打开 Keepbay,再复制回调地址。修改访问地址或更换域名后,需要到提供方的管理后台重新登记。

填写了访问地址后,外部帐号登录要从访问地址进行。从局域网地址打开的登录页上点外部帐号时,会自动转到访问地址的登录页再继续。关联外部帐号、用外部帐号验证身份也要从访问地址打开 Keepbay 后进行。

经反向代理访问的,请先设置好可信代理,见外网访问。否则 Keepbay 获取到的是内部地址,生成的回调地址也不正确。

Google 等提供方要求回调地址是 HTTPS(localhost 除外)。通过 IP 和 HTTP 访问时,请先按外网访问配置好 HTTPS。

已经有 Keepbay 帐号的,先用密码登录,在「个人设置 › 安全 › 外部帐号」中点「关联外部帐号」。选择提供方,确认一次密码,在提供方的页面登录,返回后即完成关联。

之后在登录页点该提供方的按钮,即可直接登录。

每个提供方只能关联一个外部帐号。不再使用时,点「解除关联」。

Keepbay 不会按邮箱把外部帐号自动对应到已有帐号。否则,有人在身份提供方中把自己的邮箱改成您的邮箱,就能登录您的帐号。所以必须由您登录后主动关联。

自动创建帐号 ​

如果不想先给每位家人建帐号、再让他们关联,可以打开「自动建号」:没有对应帐号的外部帐号首次登录时,自动创建一个成员帐号。

打开自动建号时,必须填「邮箱白名单」,每行一个:

mom@example.com
@family.example.com

可以写完整的邮箱,也可以写 @域名,表示这个域名下的所有邮箱(不含子域名)。

只有身份提供方确认过(email_verified)、并且在白名单中的邮箱,才会自动建号。

Microsoft 帐号的登录信息中通常没有这一项,自动建号可能不起作用。使用 Microsoft 帐号时,建议先建好帐号,再让家人自行关联。

自动创建的帐号:

  • 一律是成员,所有者身份不会由外部帐号授予
  • 没有任何文件夹授权,三个功能开关都是关闭的,需要所有者另行授权
  • 没有可用的密码,只能用外部帐号登录。所有者给他重设密码后,才能用密码登录

每自动创建一个帐号,所有者会收到一条通知。

GitHub 不支持自动建号。免费版用户数已满时,也不能自动建号。

两步验证 ​

开启了两步验证的帐号,用外部帐号登录后,仍然需要输入验证码。未开启两步验证但添加了通行密钥的,仍然需要用通行密钥确认。

外部帐号和 Keepbay 的验证相互独立。即使外部帐号的密码泄露,没有您的手机也无法登录。

外部帐号登录和密码登录一样受登录限流保护,每次登录都记在日志中。

只用外部帐号登录 ​

成员可以关闭密码登录,只用通行密钥或外部帐号登录:在「个人设置 › 安全」的「密码登录」一节,关闭「用密码登录」。

关闭前,至少需要有一个通行密钥或关联的外部帐号。同样,解除最后一种登录方式的关联时,Keepbay 会拒绝。

所有者必须保留密码登录,不能关闭。这样在更换手机或身份提供方出现故障时,所有者仍可以用密码登录处理。

某个提供方被停用或删除时,只能靠它登录的成员会自动恢复密码登录,所有者给他们重设密码即可。

确认身份 ​

修改密码、开关两步验证、管理登录方式、在网页上更新 Keepbay,都需要先确认一次身份。

用支持重新验证的外部帐号登录过的,可以选择在提供方重新登录一次,代替输入密码,之后 5 分钟内不需要再次确认。GitHub 不支持重新验证。