跳至主要内容
版本: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 複製到 /opt/excubius/.env,分別作為 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET,然後按 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。