跳到主要内容
版本:0.4 · 当前版

设置登录提供商

操作指南审阅日期:2026年10月11日
适用于:Excubius 0.4角色: 安装人员(Linux 管理员), 超级管理员, 实体管理员
计划Free · Core · Pro · Enterprise部署自托管

用户使用其组织的账户登录 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)。

  1. 在 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。
  2. 在 Overview 上,复制 Directory (tenant) ID 和 Application (client) ID。
  3. 在 Certificates & secrets › Client secrets 下,选择 New client secret 并复制它的 Value,而不是它的 ID。它只显示一次。请记下到期日期:客户端密码到期后登录会停止,因此请在此之前创建下一个密码并替换这个值。
  4. 在 Authentication 下,保持隐式流和混合流的 Access tokens 和 ID tokens 关闭,并将 Front-channel logout URL 留空。Excubius 使用带 PKCE 的授权代码流。
  5. 在 API permissions 下,保留 Microsoft Graph 的委托权限 openid、profile 和 email。默认添加的 User.Read 没有影响。如果你的租户不允许用户自行同意,请授予管理员同意。
  6. 在 Token configuration 下,选择 Add optional claim,令牌类型选择 ID,声明选择 email,并接受添加 Graph email 权限的提示。没有它时,Excubius 使用 preferred_username,当用户主体名称就是电子邮件地址时,这样没有问题。
  7. 如果要向目录组授予角色,请在 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 会认为此人根本没有目录组。
  8. 也可以在 Enterprise applications › 你的应用 › Properties 下,将 Assignment required? 设置为 Yes。这样,在 Excubius 应用自己的规则之前,只有分配给该应用的用户和组才能登录。

现在把这些值提供给 Excubius:

  1. 连接到服务器,使用 sudo -iu excubius 切换为服务账户,并将这三个值添加到 /opt/excubius/.env:

    ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2b
    ENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555
    ENTRA_CLIENT_SECRET=<the secret value>
  2. 重启平台:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

三个值都设置后,登录页会显示 Sign in with Microsoft。客户端密码只从配置文件读取:它从不写入数据库,从不由 API 返回,也从不记录到日志。

向 Google 注册 Excubius​

  1. 在 Google Cloud console 中,打开 Google Auth Platform。
    • Audience:当所有人都拥有你的组织的 Google Workspace 账户时,选择 Internal;否则选择 External。请发布该应用,或在测试期间添加测试用户。
    • Data access:范围为 openid、.../auth/userinfo.email 和 .../auth/userinfo.profile。
  2. 在 Clients 下,选择 Create client,类型选择 Web application,并添加授权的重定向 URI https://<primary name>/api/v1/auth/google/callback。你不需要 JavaScript 源。
  3. 将 Client ID 和 Client secret 作为 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 复制到 /opt/excubius/.env,然后按照 Entra ID 步骤中的方式重启平台。
  4. 在 Settings › Instance 中检查功能 access.google_login 是否已开启。它默认开启。

登录页会显示 Sign in with Google。当 access.google_login 关闭时,Google 登录会被拒绝,而不只是隐藏。

Google 和允许的域

任何人都可以使用自己能收到邮件的任意电子邮件地址创建个人 Google 账户。因此,只有当 Google 对该地址具有权威性时,Google 登录才算作允许的域:即该域本身的 Google Workspace 账户,并且地址已验证。个人 Google 账户始终需要邀请,而对于邀请,Google 必须报告该地址已验证。

选择谁可以获得账户​

每个实体都有一个注册模式,适用于该实体及其下的所有内容,直到下级实体设置自己的模式。

模式没有邀请的首次登录授予的角色
By invitation(默认)被拒绝—
Allowed domains当电子邮件地址的域在列表中时接受。匹配是精确的;子域不算在内设置该注册的实体上的 Default role(除非你选择其他角色,否则为 Viewer;绝不会是 Super admin),像任何角色一样向下继承

设置方法:

  1. 打开 Settings › Users and roles,并在选取器中选择实体,例如 高密物流。
  2. 选择 Registration 选项卡。页面会说明当前设置的来源:此实体、其上级实体,或安装本身。
  3. 选择 By invitation 或 Allowed domains。
  4. 对于 Allowed domains,输入 Domains,以逗号或空格分隔(最多 50 个),例如 ciguapa.example,并选择 Default role。
  5. 选择 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。