设置登录提供商
用户使用其组织的账户登录 Excubius,账户来自 Microsoft Entra ID 或 Google。Excubius 从不存储目录密码:它从提供商接收已签名的令牌并进行检查,将账户记录为提供商加上此人在该提供商中的标识符,绝不只以电子邮件地址记录。本指南说明如何向每个提供商注册 Excubius,以及如何决定谁可以获得账户。
开始之前
- 了解服务器的公共地址
https://<primary name>。下面的每个重定向地址都以它开头。通过别名打开 Excubius 的用户会被转到主要名称登录,因此每个提供商一个重定向地址就足够了。请参阅设置名称和 TLS。 - 使用 HTTPS。Microsoft Entra ID 只对
localhost接受http。 - 你需要能访问服务器的配置文件
/opt/excubius/.env,或者能运行安装程序:sudo ./install.sh --reconfigure会再次询问 Entra ID 的值。 - 若要开启或关闭 Google 登录,你需要 Super admin(超级管理员)角色。若要选择谁可以获得某个实体上的账户,你需要在该实体上拥有 Entity admin(实体管理员)角色。
如何决定首次登录
只有在创建账户或接受邀请时才会授予角色。现有账户使用其已有的角色登录,因此管理员删除的角色不会在下次登录时恢复。
在 Microsoft Entra ID 中注册 Excubius
使用 Microsoft Entra ID 登录属于 Core、Pro 和 Enterprise 计划。
为每个安装创建一个应用注册,针对单个租户。不支持多租户注册(common 或 organizations)。
- 在 Microsoft Entra admin center 中,打开 App registrations 并选择 New registration。
- Name:用户在同意提示上看到的名称,例如他们熟悉的该监视系统的名称。
- Supported account types:Accounts in this organizational directory only (single tenant)。
- Redirect URI:平台选择 Web,地址为
https://<primary name>/api/v1/auth/entra/callback。
- 在 Overview 上,复制 Directory (tenant) ID 和 Application (client) ID。
- 在 Certificates & secrets › Client secrets 下,选择 New client secret 并复制它的 Value,而不是它的 ID。它只显示一次。请记下到期日期:客户端密码到期后登录会停止,因此请在此之前创建下一个密码并替换这个值。
- 在 Authentication 下,保持隐式流和混合流的 Access tokens 和 ID tokens 关闭,并将 Front-channel logout URL 留空。Excubius 使用带 PKCE 的授权代码流。
- 在 API permissions 下,保留 Microsoft Graph 的委托权限
openid、profile和email。默认添加的User.Read没有影响。如果你的租户不允许用户自行同意,请授予管理员同意。 - 在 Token configuration 下,选择 Add optional claim,令牌类型选择 ID,声明选择
email,并接受添加 Graphemail权限的提示。没有它时,Excubius 使用preferred_username,当用户主体名称就是电子邮件地址时,这样没有问题。 - 如果要向目录组授予角色,请在 Token configuration 下选择 Add groups claim:
- 选择 Groups assigned to the application,然后在 Enterprise applications › 你的应用 › Users and groups 下分配这些组。这样可以让令牌保持较小,并且只携带你映射的组。Security groups 也可以使用。
- 对于 ID 令牌,选择 Group ID。Excubius 匹配组的对象 ID;名称不能匹配。
- 一个令牌最多携带 200 个组。超过这个数量,Entra ID 不会发送任何组,Excubius 会认为此人根本没有目录组。
- 也可以在 Enterprise applications › 你的应用 › Properties 下,将 Assignment required? 设置为 Yes。这样,在 Excubius 应用自己的规则之前,只有分配给该应用的用户和组才能登录。
现在把这些值提供给 Excubius:
-
连接到服务器,使用
sudo -iu excubius切换为服务账户,并将这三个值添加到/opt/excubius/.env:ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
重启平台:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
三个值都设置后,登录页会显示 Sign in with Microsoft。客户端密码只从配置文件读取:它从不写入数据库,从不由 API 返回,也从不记录到日志。
向 Google 注册 Excubius
- 在 Google Cloud console 中,打开 Google Auth Platform。
- Audience:当所有人都拥有你的组织的 Google Workspace 账户时,选择 Internal;否则选择 External。请发布该应用,或在测试期间添加测试用户。
- Data access:范围为
openid、.../auth/userinfo.email和.../auth/userinfo.profile。
- 在 Clients 下,选择 Create client,类型选择 Web application,并添加授权的重定向 URI
https://<primary name>/api/v1/auth/google/callback。你不需要 JavaScript 源。 - 将 Client ID 和 Client secret 作为
GOOGLE_CLIENT_ID和GOOGLE_CLIENT_SECRET复制到/opt/excubius/.env,然后按照 Entra ID 步骤中的方式重启平台。 - 在 Settings › Instance 中检查功能
access.google_login是否已开启。它默认开启。
登录页会显示 Sign in with Google。当 access.google_login 关闭时,Google 登录会被拒绝,而不只是隐藏。
任何人都可以使用自己能收到邮件的任意电子邮件地址创建个人 Google 账户。因此,只有当 Google 对该地址具有权威性时,Google 登录才算作允许的域:即该域本身的 Google Workspace 账户,并且地址已验证。个人 Google 账户始终需要邀请,而对于邀请,Google 必须报告该地址已验证。
选择谁可以获得账户
每个实体都有一个注册模式,适用于该实体及其下的所有内容,直到下级实体设置自己的模式。
| 模式 | 没有邀请的首次登录 | 授予的角色 |
|---|---|---|
| By invitation(默认) | 被拒绝 | — |
| Allowed domains | 当电子邮件地址的域在列表中时接受。匹配是精确的;子域不算在内 | 设置该注册的实体上的 Default role(除非你选择其他角色,否则为 Viewer;绝不会是 Super admin),像任何角色一样向下继承 |
设置方法:
- 打开 Settings › Users and roles,并在选取器中选择实体,例如 高密物流。
- 选择 Registration 选项卡。页面会说明当前设置的来源:此实体、其上级实体,或安装本身。
- 选择 By invitation 或 Allowed domains。
- 对于 Allowed domains,输入 Domains,以逗号或空格分隔(最多 50 个),例如
ciguapa.example,并选择 Default role。 - 选择 Save。
若要让下级实体重新跟随其父实体,请选择 Inherit from above again。
- 如果某人的域在多个实体上被允许,则此人会获得每个实体的默认角色。
- 在根实体上,在保存注册之前,适用安装的
ALLOWED_SIGNUP_DOMAINS设置。它的含义是 Allowed domains,域取自该设置,角色为根实体上的 Viewer。保存根实体的注册(即使是 By invitation)会取代它。 - 设置为 By invitation 的实体不再自行按域授予角色,但它无法收回从上级实体的注册继承的角色。
- 若要把某人拒之门外,请停用此人。删除域不会影响现有账户。请参阅管理用户和角色。
邀请和登录
邀请是一个链接 https://<primary name>/invite/<token>,由实体管理员针对一个电子邮件地址、一个角色和一个实体创建;请参阅邀请用户。当此人打开它时:
- 页面显示实体、角色、邀请人和一个被遮盖的地址,然后显示登录按钮。系统会要求提供商预先选择受邀的地址。
- 他们所登录账户的地址必须是受邀的地址,比较时不区分大小写。
- 系统会创建账户,或链接同一提供商的现有账户,并在受邀实体上授予角色。如果该实体上已有较低的角色,则会提升;如果已有较高的角色,则会保留。
- 以后再次打开该链接,只会让此人登录。
登录被拒绝时
浏览器会返回登录页并给出通俗的说明,每次拒绝都会以 login.failed 及其原因写入审核日志。
| 代码 | 含义 | 处理方法 |
|---|---|---|
not_invited | 没有邀请,并且没有实体接受按域注册;或者邀请链接未知 | 邀请此人,或允许其域 |
domain_not_allowed | 存在按域注册,但不适用于此域,或者提供商对该域没有权威性,例如个人 Google 账户 | 添加该域,或邀请此人 |
account_disabled | 账户存在但已停用 | 在 Users and roles 中激活它 |
email_mismatch | 账户的地址不是受邀的地址,或者 Google 未验证它 | 使用受邀的账户登录,或邀请正确的地址 |
invite_expired | 邀请已过期,或者其他人已使用它 | 发送新的邀请 |
invalid_state | 登录耗时超过 10 分钟,在其他浏览器或选项卡中启动,或者响应与请求不匹配 | 从登录页重新开始 |
provider_error | 提供商拒绝(同意被拒绝或被取消)、未配置或已关闭,或者其响应未通过验证 | 检查上面的提供商设置以及后端日志条目 auth.login_refused |
注销 Excubius 不会让此人注销 Microsoft 或 Google。