用 SSO 讓團隊登入

你將建構出什麼

完成本教學後，你將擁有：

• 一條介於你的 Control Center 伺服器與身分識別供應商之間的 SAML 連線（我們以 Okta 為例），
• 一位在首次登入時自動完成佈建的使用者，以及
• 一套由你刻意選擇的工作區成員資格政策。

你需要一台由你管理的伺服器（即伺服器擁有者——這套安裝的操作者）， 以及一個你可以設定的 IdP 應用程式。請預留 20 分鐘。

1. 開啟單一登入設定

登入 Control Center，然後前往 設定 → 伺服器 → 單一登入。畫面可在 SAML 與 OpenID Connect 之間切換，另有一張使用者佈建（SCIM） 卡片。請停留在 SAML。

這個畫面上的每一項設定都是伺服器層級：一個 IdP 會為每個工作區的人員 完成驗證，因此只有伺服器擁有者可以編輯。

2. 貼上 IdP 中繼資料

在 Okta 中開啟應用程式的 Sign On 分頁，複製中繼資料 XML（或將它下載 下來並貼上檔案的內容）。回到 Control Center，將它貼到 IdP 中繼資料 XML 並按下測試連線。

提示訊息會報告 IdP 的登入端點——這證明中繼資料已解析、憑證已讀取，而且 伺服器能據此建立登入要求（此測試會演練瀏覽器往返以外的所有環節）。 如果失敗，代表該 XML 不是完整的 EntityDescriptor（Okta 的 SAML 分頁 稱之為「Metadata URL」；請開啟該 URL 並複製它提供的內容）。 OpenID Connect 上的同一顆按鈕則改為檢查簽發者的探索文件。若想一併 抓出即將到期的憑證，並查看 IdP 是否認得 Control Center，請使用 第 6 步的檢查器。

3. 在 IdP 註冊 Control Center

按下複製 SP 中繼資料，將它交給負責設定 Okta 一方的人（或讀出 對方索取的兩個值）：

• ACS URL：https://<your-server>/saml/acs
• 實體 ID：https://<your-server>/saml

這些 URL 衍生自使用者瀏覽器所連到的來源。如果伺服器在通道或反向代理 之後執行，請確保該來源穩定 （設定 → 伺服器 → 連線與狀態 → 分享此伺服器會顯示公開 URL）——或在 SP 實體 ID 欄位中明確固定實體 ID。

在 NAT 之後？

SAML 登入不需要公開 IP 或網域：IdP 永遠不會連到你的伺服器—— 往返由使用者的瀏覽器負責傳遞，因此 localhost、LAN、VPN、Tailscale 或通道都能勝任。有兩點要弄清楚：

• 瀏覽器所使用的來源必須與在 IdP 註冊的 ACS URL／實體 ID 相符 （如果使用者會透過多於一個來源連到伺服器，請固定實體 ID），
• SCIM 佈建則是例外——IdP 會直接呼叫你的伺服器，因此需要通道或 公開 URL（以 SCIM 佈建使用者）。

4. 選擇一次登入會授予什麼

兩項政策決定首次登入會做什麼：

• 首次登入時將使用者加入每個工作區——在 SSO 等同信任的單一團隊 部署中請保持開啟。當多個團隊或客戶共用同一台伺服器時，請將它關閉： 這樣每位新加入者都需要明確的工作區邀請，是較安全的預設值。
• 首次登入時佈建未知使用者——預設為開啟；將它關閉即可拒絕 任何帳戶尚不存在的人。

你也可以選擇對應一個載有群組名稱的屬性（Okta 的通常是 groups）， 並用對應表將群組轉為角色——例如 {"platform-leads": "admin"}。SSO 永遠無法授予擁有者角色。

5. 啟用並實際登入一次

開啟使用 SAML 登入，按下儲存連線，然後在私密瀏覽視窗中開啟 https://<your-server>/saml/login。在 Okta 登入後，你會回到網頁 用戶端——已登入，帳戶已建立，其成員資格也依你選擇的政策授予。

當你在網頁連線畫面輸入伺服器位址的那一刻，同一個進入點就會出現 （以 SAML 登入）——表單會依伺服器提供的內容調整 （OpenID Connect 會顯示以 OpenID Connect 登入）。該按鈕會在新分頁 中開啟登入；當往返完成後，等待中的分頁會自動接上該工作階段。桌面版的 伺服器設定畫面也一樣：輸入伺服器 URL 後，會出現以 SAML 登入按鈕， 它會開啟你的瀏覽器，並在往返完成後讓應用程式登入。

6. 從本頁檢查

在推行 SSO 之前，或當登入失敗時，可在此檢查各個環節。檢查器完全在你的 瀏覽器中執行：它會讀取你在本分頁貼上的中繼資料，並套用與伺服器相同的 規則。若提供伺服器位址，它亦會向該伺服器查詢 SAML 登入是否已開啟。

它能抓出應用程式中測試連線看不見的問題：即將到期的簽署憑證、 堅持每個要求都須簽署的 IdP，以及（透過測試登入）IdP 究竟是否認得 Control Center。

Runs in your browserYour metadata is read in this tab and never uploaded. Add a server address and your browser also asks that server which sign-in methods it offers.

IdP metadata XMLLoad a file

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

SP entity ID (optional)

Only if you pinned one in the app.

Check metadata

下一步

• 也讓你的 IdP 掌管生命週期： 以 SCIM 佈建及解除佈建使用者。
• 你的 IdP 使用 OpenID Connect 而非 SAML？ 連接 OpenID Connect 供應商。
• 想知道瀏覽器往返實際驗證了什麼？ 單一登入的運作方式。