使用 BobIDP 自訂資源和 bobctl configure-idp 指令為 IBM Bob 本地部署設定 LDAP 或 Active Directory 聯合。

使用 bobctl configure-idp 將你的 LDAP 或 Active Directory 環境連接至 Keycloak，作為使用者聯合提供者。你可以在安裝期間或部署後的任何時間完成此設定。

開始之前

在設定 LDAP 聯合之前，請確保符合以下需求：

OpenShift Container Platform（OCP）叢集能夠透過適當連接埠連線至 LDAP 伺服器：

ldap:// 使用 389 連接埠
ldaps:// 使用 636 連接埠

具有目錄讀取權限的服務帳戶（Bind DN）可用，或者 LDAP 伺服器設定為允許匿名連結。

如果使用帶有私有或內部簽署憑證授權單位（CA）的 ldaps://，請取得 PEM 格式的 LDAP 伺服器 CA 憑證。

bobctl 命令列工具已安裝，並且 oc 已設定並通過對目標叢集的身分驗證。

設定檔參考

在註冊 LDAP 提供者之前，請從提供的範本建立 IDP 設定檔。

cp config-idp-template.yaml my-idp.yaml

設定檔有兩個區段：套用至整個部署的頂層欄位，以及每個項目描述一個 LDAP 聯合提供者的可選 ldaps 清單。

頂層欄位

欄位	是否必填	描述
`domains`	是	Bob 在登入時接受的電子郵件網域清單。移除網域會取消其註冊；擁有該網域的使用者將無法登入。
`adminEmails`	否	要授予 Bob 管理員存取權限的使用者電子郵件清單。Operator 會以原子方式同時更新 Keycloak `bob-admins` 群組和 Bob 管理員資料庫。
`ldaps`	否	LDAP 聯合提供者設定清單。對於僅使用直接 Keycloak 使用者的部署，可完全省略此項。

必填欄位（每個 LDAP 提供者項目）

欄位	描述
`name`	LDAP 提供者的唯一描述性 ID。每個已設定的提供者必須有不同的名稱。
`vendor`	指定要整合的 LDAP 目錄類型。支援的數值：`other`（OpenLDAP 和 LDAPv3 相容）、`ad`（Microsoft Active Directory）、`rhds`（Red Hat Directory Server）、`tivoli`（IBM Security Directory Server）、`edirectory`（NetIQ eDirectory）。
`connectionUrl`	LDAP 伺服器的完整 URL，包括通訊協定（`ldap://` 或 `ldaps://`）、主機名稱和連接埠號碼。
`usersDn`	使用者帳戶儲存的目錄位置，使用者項目將從此處搜尋和匯入。
`usernameLDAPAttribute`	使用者在身分驗證時提供的使用者名稱所對應的目錄屬性。
`rdnLDAPAttribute`	用於識別目錄結構中項目的目錄屬性。在大多數設定中，這與 `usernameLDAPAttribute` 相同。
`uuidLDAPAttribute`	用於永久識別每個使用者帳戶的唯一、穩定、不變的目錄屬性。
`userObjectClasses`	以逗號分隔的 LDAP 物件類別清單，用於定義哪些目錄項目被識別和處理為使用者帳戶。

重要：

domains 欄位是在本地部署中設定基於網域路由的唯一方法。請勿透過 Bob 管理使用者介面設定網域，因為這不是正確的方式，可能導致身分驗證錯誤。

選用欄位（每個 LDAP 提供者項目）

欄位	描述
`bindDn`	用於身分驗證和連線目錄的服務帳戶 DN。如果目錄允許匿名連結存取，可以省略。
`bindPasswordSecret`	包含連結帳戶密碼的預先存在 Secret 的名稱。必須在執行 `bobctl configure-idp` 之前在執行個體命名空間中建立。
`useTruststoreSpi`	指定何時使用 LDAP CA 憑證進行伺服器驗證。數值：`always`（預設，用於私有或內部發行的 CA 憑證）、`ldapsOnly`（用於公開受信任的 CA 憑證）、`never`（透過不安全的 `ldap://` 連線時）。
`ldapsCACertSecret`	包含 PEM 格式 LDAP 伺服器 CA 憑證的預先存在 Secret 的名稱。必須在執行 `bobctl configure-idp` 之前在執行個體命名空間中建立。
`searchScope`	決定目錄搜尋的深度。`2` 搜尋所有子容器和子樹狀結構（預設）；`1` 僅限於直接子項目的搜尋。
`customUserSearchFilter`	套用於所有使用者搜尋操作的額外篩選器，例如用於排除服務帳戶或將搜尋限制為特定使用者類型。
`userSync.enabled`	設定為 `true` 時，初始設定提供者時會匯入所有使用者，後續目錄變更每五分鐘同步一次。建議用於大多數部署。
`userAttributeMappings`	定義目錄屬性如何對應至 Bob 使用者設定檔欄位，例如 `email`、`firstName` 和 `lastName`。
`priority`	決定設定了多個提供者時的評估順序。數值較低的提供者優先檢查。預設值為 `0`。
`groupMapper`	將 LDAP 群組同步至 Keycloak。請參閱設定 LDAP 群組同步。

使用者同步行為

當 userSync.enabled 設定為 true 時，Bob 在註冊 LDAP 提供者時執行一次性的完整使用者匯入。初始匯入完成後，後續使用者生命週期同步透過 SCIM 自動處理。

提示：

對於大型 LDAP 目錄，考慮將 userSync.enabled 設定為 false，讓使用者在首次登入時佈建。這種方式可以縮短註冊 LDAP 提供者所需的時間。

設定 LDAP 群組同步

使用選用的 groupMapper 設定將 LDAP 群組與 Keycloak 同步。透過群組同步，來自 LDAP 目錄的使用者和群組成員資格會透過 Keycloak 匯入和管理。

groupsDn 參數為必填項。所有其他參數為選用項目，可自訂以符合你的 LDAP 目錄綱要（Schema）和群組結構。

限制：

bob-admins 和 bob-users 群組是平台管理的群組。它們不包含在 LDAP 群組同步中。

參數	預設值	描述
`groupsDn`	必填	包含 LDAP 群組項目的基本辨別名稱（DN）。
`name`	`groups`	Keycloak 中群組對應器的顯示名稱。
`groupNameLdapAttribute`	`cn`	Keycloak 用作群組名稱的 LDAP 屬性。
`groupObjectClasses`	`groupOfNames`	識別群組項目的 LDAP 物件類別。
`membershipLdapAttribute`	`member`	群組項目中包含成員資訊的屬性。
`membershipAttributeType`	`DN`	成員數值的格式。支援的值：`DN`（辨別名稱）和 `UID`（使用者 ID）。
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	用於確定群組成員資格的方法。
`memberOfLdapAttribute`	`memberOf`	使用 `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` 時包含群組成員資訊的使用者屬性。
`customGroupSearchFilter`	無	搜尋群組時使用的額外 LDAP 篩選器。篩選器必須用括號括起來，例如 `(cn=dept-*)`。
`mode`	`LDAP_ONLY`	同步模式。支援的值：`LDAP_ONLY` 和 `READ_ONLY`。
`groupsPath`	`/`	在 Keycloak 群組階層架構中建立同步群組的位置。

群組成員資格擷取策略

userRolesRetrieveStrategy 參數控制 Keycloak 如何識別使用者的群組成員資格。

策略	描述
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	透過搜尋包含使用者參照的群組項目來擷取群組成員資格。
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	從使用者的 `memberOf` 屬性擷取群組成員資格。
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	遞迴擷取群組成員資格，包括 LDAP 目錄支援的巢狀群組。

提示：

除非你的 LDAP 目錄透過 memberOf 屬性在使用者項目中儲存群組成員資訊，或使用需要遞迴搜尋的巢狀群組結構，否則請使用 LOAD_GROUPS_BY_MEMBER_ATTRIBUTE。

設定範例

# Bob 在登入時應接受的電子郵件網域
domains:
  - corp.example.com

# 要授予 Bob 管理員存取權限的使用者
adminEmails:
  - alice@corp.example.com

# LDAP 聯合提供者
ldaps:
  - name: corp-ldap

    vendor: other
    connectionUrl: ldaps://ldap.corp.example.com:636
    usersDn: ou=People,dc=corp,dc=example,dc=com
    usernameLDAPAttribute: uid
    rdnLDAPAttribute: uid
    uuidLDAPAttribute: entryUUID
    userObjectClasses: inetOrgPerson,organizationalPerson,person

    bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
    bindPasswordSecret: corp-ldap-bind

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    userSync:
      enabled: true

    userAttributeMappings:
      - ldapAttribute: mail
        userModelAttribute: email
      - ldapAttribute: givenName
        userModelAttribute: firstName
      - ldapAttribute: sn
        userModelAttribute: lastName

    # 選用：將 LDAP 群組同步至 Keycloak
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

./bobctl configure-idp --config my-idp.yaml

在套用前驗證 IDP 設定

在將 IDP 設定套用至叢集之前，使用 --dry-run 選項驗證設定並預覽將要建立的資源。執行模擬測試有助於在對叢集進行任何變更之前識別常見的設定問題。

./bobctl configure-idp --config my-idp.yaml --dry-run

模擬測試執行以下檢查：

驗證設定檔中是否存在所有必填設定參數。

顯示將要建立或更新的 BobIDP 自訂資源預覽。

結束而不在叢集中建立、修改或刪除任何資源。

注意：

模擬測試操作不會驗證至 LDAP 伺服器的網路連線、對目錄驗證提供的憑證，也不會確認叢集中參照的 Secret 是否存在。這些驗證僅在設定套用後執行，並反映在 LDAPReachable 和 LDAPAuthenticated 狀態條件中。

套用設定

建立並驗證 IDP 設定檔後，執行 configure-idp 指令將設定套用至叢集。

./bobctl configure-idp --config my-idp.yaml

旗標	是否必填	描述
`--config <file>`	是	指定 IDP 設定檔的路徑。
`--dry-run`	否	驗證設定並顯示將要建立或更新的資源預覽，不對叢集套用任何變更。

指令執行時，bobctl 會等待 Operator 調試設定，並透過檢查 BobIDP 自訂資源回報的狀態條件來驗證 IDP。

檢查項目	確認內容
`Ready`	設定已成功套用。
`LDAPRegistered`	LDAP 提供者已在 Keycloak 中註冊。
`LDAPReachable`	LDAP 伺服器可從叢集存取。
`LDAPAuthenticated`	設定的連結憑證有效。
`LDAPUserSyncSucceeded`	初始使用者匯入已成功完成。僅在 `userSync.enabled` 設定為 `true` 時評估此條件。

預設驗證逾時為 600 秒（10 分鐘）。在目錄項目龐大的環境中，初始使用者同步可能需要幾分鐘完成。若要增加逾時，請設定 BOB_IDP_WAIT_TIMEOUT 環境變數：

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

設定多個 LDAP 提供者

若要整合來自多個 LDAP 或 Active Directory 來源的使用者，請在 IDP 設定檔的 ldaps 清單中為每個目錄新增一個獨立項目，並重新執行 configure-idp。

./bobctl configure-idp --config my-idp.yaml

檢查 IDP 資源狀態

檢視 IDP 設定的狀態：

oc get bobidp -n <instance-namespace>

檢視詳細的設定和狀態資訊：

oc get bobidp bob-idp -n <instance-namespace> -o yaml

驗證整合

bobctl configure-idp 成功完成後，驗證 LDAP 整合是否正常運作。

檢查 BobIDP 自訂資源的狀態：

oc get bobidp bob-idp -n <instance-namespace> -o yaml

驗證以下狀態條件是否設定為 True：

條件	用途
`Ready`	確認設定已成功套用。
`LDAPRegistered`	確認 LDAP 提供者已在 Keycloak 中註冊。
`LDAPReachable`	確認叢集可以與 LDAP 伺服器通訊。
`LDAPAuthenticated`	確認設定的連結憑證有效。
`LDAPUserSyncSucceeded`	確認所有使用者已成功匯入。僅在 `userSync.enabled: true` 時存在。

如果任何條件為 False，請檢視對應的 message 欄位以取得診斷詳細資訊。

使用聯合 LDAP 目錄中的憑證登入，以驗證使用者身分驗證是否正常運作。

開啟 Bob URL：

https://bob.<namespace>.<ingress-domain>

成功登入確認了連線能力、身分驗證、網域路由、SCIM 佈建和角色對應均正常運作。

使用者首次登入後，確認使用者記錄在 Bob 中可用。

開啟 Bob 管理 UI：

https://bob.<namespace>.<ingress-domain>/admin

以 Bob 管理員身分登入，並驗證測試使用者是否出現在使用者清單中。

如果設定了 groupMapper 以將 LDAP 群組對應至 Bob 管理員：

使用屬於已對應管理員群組的使用者帳戶登入。
確認該使用者可以存取 Bob 管理 UI。
驗證管理員層級功能是否可用。

如果 userSync.enabled: true，則在註冊 LDAP 提供者後自動匯入使用者。測試使用者無需初始登入即可出現在 Bob 中。

如果使用者在幾分鐘後仍未出現，請檢視 bob-admin 日誌以了解佈建錯誤：

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

檢視任何回報的 SCIM 相關錯誤，並在重試同步程序之前解決它們。

LDAP 整合

本頁內容