設定登入提供者
人員使用所屬機構的帳戶登入 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 複製到
/opt/excubius/.env,分別作為GOOGLE_CLIENT_ID和GOOGLE_CLIENT_SECRET,然後按 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。