設定 Active Directory (AD)
如果您的組織使用 Microsoft Active Directory 作為中央使用者儲存庫,您可以設定 Rancher 與 Active Directory 伺服器通訊以驗證使用者。這允許 Rancher 管理員根據在 Active Directory 中外部管理的使用者和群組來控制叢集和專案的存取權限,同時允許終端使用者在登入 Rancher UI 時使用他們的 AD 憑證進行身份驗證。
Rancher 使用 LDAP 與 Active Directory 伺服器通訊。因此,Active Directory 的身份驗證流程與 OpenLDAP 身份驗證整合相同。
在開始之前,請先熟悉外部身份驗證設定和主要使用者的概念。
前置需求
您需要建立或從 AD 管理員處取得一個新的 AD 使用者來作為 Rancher 的服務帳戶。此 使用者必須具有足夠的權限來執行 LDAP 搜尋並讀取 AD 網域下的使用者和群組屬性。
通常應該使用(非管理員)的 Domain User 帳戶來達成此目的,因為預設情況下,這類使用者對網域分割區中的大多數物件都具有唯讀權限。
但請注意,在某些受限的 Active Directory 設定中,此預設行為可能不適用。在這種情況下,您需要確保服務帳戶使用者至少被授予 Read 和 List Content 權限,這些權限可以授予在基礎 OU(包含使用者和群組)上或全域授予網域。
-
如果 AD 伺服器使用的憑證是自簽憑證或不是來自認可的憑證授權單位,請確保手邊有 PEM 格式的 CA 憑證(與任何中繼憑證串接)。您需要在設定期間貼上此憑證,以便 Rancher 能夠驗證憑證鏈。
-
升級到 v2.6.0 後,如果 AD 伺服器上的憑證不支援 SAN 屬性,則使用 TLS 透過 Rancher 對 Active Directory 進行身份驗證可能會失敗。這是 Go v1.15 中預設啟用的檢查。
-
收到的錯誤是 "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0"。
-
要解決此錯誤,請使用支援 SAN 屬性的新憑證更新或替換 AD 伺服器上的憑證。或者,可以透過將
GODEBUG=x509ignoreCN=0設定為 Rancher 伺服器容器的環境變數來忽略此錯誤。
-
設定步驟
開啟 Active Directory 設定
- 使用初始本地
admin帳戶登入 Rancher UI。 - 在左上角,點擊 ☰ > Users & Authentication。
- 在左側導覽選單中,點擊 Auth Provider。
- 點擊 ActiveDirectory。將顯示 Authentication Provider: ActiveDirectory 表單。
- 填寫表單。如需協助,請參閱下面有關設定選項的詳細資訊。
- 點擊 Enable。
設定 Active Directory 伺服器設定
在標題為 1. Configure an Active Directory server 的部分中,使用您的 Active Directory 伺服器的特定資訊完成欄位。請參閱下表以取得每個參數所需值的詳細資訊。
如果您不確定要在使用者/群組搜尋基礎欄位中輸入的正確值,請參閱使用 ldapsearch 識別搜尋基礎和架構。
表 1: AD 伺服器參數
| 參數 | 描述 |
|---|---|
| Hostname | 指定 AD 伺服器的主機名稱或 IP 位址 |
| Port | 指定 Active Directory 伺服器偵聽連線的埠。未加密的 LDAP 通常使用標準埠 389,而 LDAPS 使用埠 636。 |
| TLS | 勾選此方塊以啟用 LDAP over SSL/TLS(通常稱為 LDAPS)。 |
| Server Connection Timeout | Rancher 在將 AD 伺服器視為無法存取之前等待的秒數。 |
| Service Account Username | 輸入具有網域分割區唯讀存取權限的 AD 帳戶的使用者名稱(請參閱前置需求)。使用者名稱可以使用 NetBIOS 格式輸入(例如 "DOMAIN\serviceaccount")或 UPN 格式(例如 "serviceaccount@domain.com")。 |
| Service Account Password | 服務帳戶的密碼。 |
| Default Login Domain | 當您使用 AD 網域的 NetBIOS 名稱設定此欄位時,未輸入網域的使用者名稱(例如 "jdoe")將在綁定到 AD 伺服器時自動轉換為斜線分隔的 NetBIOS 登入(例如 "LOGIN_DOMAIN\jdoe")。如果您的使用者使用 UPN(例如 "jdoe@acme.com")作為使用者名稱進行身份驗證,則此欄位必須保持空白。 |
| User Search Base | 您目錄樹中節點的辨別名稱,從該節點開始搜尋使用者物件。所有使用者都必須是此基礎 DN 的後代。例如:"ou=people,dc=acme,dc=com"。 |
| Group Search Base | 如果您的群組位於與 User Search Base 下設定的節點不同的節點下,您需要在此處提供辨別名稱。否則保持空白。例如:"ou=groups,dc=acme,dc=com"。 |
設定使用者/群組架構
在標題為 2. Customize Schema 的部分中,您必須為 Rancher 提供與您目錄中使用的架構相對應的正確使用者和群組屬性對應。
Rancher 使用 LDAP 查詢來搜尋和檢索 Active Directory 中有關使用者和群組的資訊。本部分中設定的屬性對應用於建構搜尋篩選器和解析群組成員資格。因此,提供的設定必須反映您 AD 網域的實際情況,這一點至關重要。
如果您不熟悉 Active Directory 網域中使用的架構,請參閱使用 ldapsearch 識別搜尋基礎和架構以確定正確的設定值。
使用者架構
下表詳細說明使用者架構部分設定的參數。
表 2: 使用者架構設定參數
| 參數 | 描述 |
|---|---|
| Object Class | 您網域中用於使用者物件的物件類別名稱。如果已定義,僅指定物件類別的名稱 - 不要將其包含在 LDAP 包裝器中,例如 &(objectClass=xxxx) |
| Username Attribute | 其值適合作為顯示名稱的使用者屬性。 |
| Login Attribute | 其值與使用者登入 Rancher 時輸入的憑證的使用者名稱部分相符的屬性。如果您的使用者使用 UPN(例如 "jdoe@acme.com")作為使用者名稱進行身份驗證,則此欄位通常必須設定為 userPrincipalName。否則,對於舊的 NetBIOS 風格登入名稱(例如 "jdoe"),通常是 sAMAccountName。 |
| User Member Attribute | 包含使用者所屬群組的屬性。 |
| Search Attribute | 當使用者輸入文字以在 UI 中新增使用者或群組時,Rancher 會查詢 AD 伺服器並嘗試透過此設定中提供的屬性來匹配使用者。可以透過使用管道符號(" |
| Search Filter | 當 Rancher 嘗試將使用者新增至站台存取清單或嘗試將成員新增至叢集或專案時,此篩選器會套用於搜尋的使用者清單。例如,使用者搜尋篩選器可以是 (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io))。注意:如果搜尋篩選器不使用有效的 AD 搜尋語法,使用者清單將為空白。 |
| User Enabled Attribute | 包含代表使用者帳戶旗標的位元枚舉的整數值的屬性。Rancher 使用此屬性來確定使用者帳戶是否已停用。您通常應該將其保持設定為 AD 標準 userAccountControl。 |
| Disabled Status Bitmask | 這是指定已停用使用者帳戶的 User Enabled Attribute 的值。您通常應該將其保持設定為 Microsoft Active Directory 架構中指定的預設值 "2"(請參閱此處)。 |
群組架構
下表詳細說明群組架構設定的參數。
表 3: 群組架構設定參數
| 參數 | 描述 |
|---|---|
| Object Class | 您網域中用於群組物件的物件類別名稱。如果已定義,僅指定物件類別的名稱 - 不要將其包含在 LDAP 包裝器中,例如 &(objectClass=xxxx) |
| Name Attribute | 其值適合作為顯示名稱的群組屬性。 |
| Group Member User Attribute | 其格式與 Group Member Mapping Attribute 中的群組成員相符的使用者屬性的名稱。 |
| Group Member Mapping Attribute | 包含群組成員的群組屬性的名稱。 |
| Search Attribute | 將群組新增至叢集或專案時用於建構搜尋篩選器的屬性。請參閱使用者架構 Search Attribute 的描述。 |
| Search Filter | 當 Rancher 嘗試將群組新增至站台存取清單或嘗試將群組新增至叢集或專案時,此篩選器會套用於搜尋的群組清單。例如,群組搜尋篩選器可以是 (|(cn=group1)(cn=group2))。注意:如果搜尋篩選器不使用有效的 AD 搜尋語法,群組清單將為空白。 |
| Group DN Attribute | 其格式與描述使用者成員資格的使用者屬性中的值相符的群組屬性的名稱。請參閱 User Member Attribute。 |
| Nested Group Membership | 此設定定義 Rancher 是否應解析巢狀群組成員資格。僅當您的組織使用這些巢狀成員資格時才使用(即,您有包含其他群組作為成員的群組。我們建議盡可能避免使用巢狀群組,以避免當存在大量巢狀成員資格時可能出現的效能問題)。 |
測試身份驗證
完成設定後,請繼續使用您的 AD 管理員帳戶測試與 AD 伺服器的連線。如果測試成功,將隱式啟用已設定的 Active Directory 身份驗證,並將您用於測試的帳戶設定為管理員。
在此步驟中輸入的憑證所屬的 AD 使用者將對應到本地主體帳戶,並在 Rancher 中被分配管理員權限。因此,您應該有意識地決定使用哪個 AD 帳戶來執行此步驟。
- 輸入應對應至本地主體帳戶的 AD 帳戶的使用者名稱和密碼。
- 點擊 Authenticate with Active Directory 以完成設定。
結果:
- Active Directory 身份驗證已啟用。
- 您已使用提供的 AD 憑證以管理員身分登入 Rancher。
在 LDAP 服務中斷的情況下,您仍然可以使用本地設定的 admin 帳戶和密碼登入。
附錄:使用 ldapsearch 識別搜尋基礎和架構
為了成功設定 AD 身份驗證,您必須提供與 AD 伺服器的階層和架構相關的正確設定,這一點至關重要。
ldapsearch 工具允許您查詢 AD 伺服器以了解用於使用者和群組物件的架構。
對於下面提供的範例命令,我們將假設:
- Active Directory 伺服器的主機名稱為
ad.acme.com - 伺服器正在埠
389上偵聽未加密的連線 - Active Directory 網域為
acme - 您有一個有效的 AD 帳戶,使用者名稱為
jdoe,密碼為secret
識別搜尋基礎
首先,我們將使用 ldapsearch 來識別使用者和群組的父節點的辨別名稱(DN):
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"
此命令執行 LDAP 搜尋,搜尋基礎設定為網域根(-b "dc=acme,dc=com"),篩選器以使用者帳戶為目標(sAMAccountNam=jdoe),返回該使用者的屬性:
由於在這種情況下,使用者的 DN 是 CN=John Doe,CN=Users,DC=acme,DC=com [5],我們應該使用父節點 DN CN=Users,DC=acme,DC=com 設定 User Search Base。
同樣地,根據 memberOf 屬性 [4] 中引用的群組的 DN,Group Search Base 的正確值將是該值的父節點,即 OU=Groups,DC=acme,DC=com。
識別使用者架構
上述 ldapsearch 查詢的輸出還允許確定在使用者架構設定中使用的正確值:
Object Class: person [1]Username Attribute: name [2]Login Attribute: sAMAccountName [3]User Member Attribute: memberOf [4]
如果我們組織中的 AD 使用者使用他們的 UPN(例如 jdoe@acme.com)而不是短登入名稱進行身份驗證,那麼我們必須將 Login Attribute 設定為 userPrincipalName。
我們還將 Search Attribute 參數設定為 sAMAccountName|name。這樣,使用者可以透過輸入他們的使用者名稱或全名在 Rancher UI 中新增至叢集/專案。
識別群組架構
接下來,我們將查詢與此使用者關聯的其中一個群組,在本例中為 CN=examplegroup,OU=Groups,DC=acme,DC=com:
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
-s sub "CN=examplegroup"
此命令將告訴我們用於群組物件的屬性:
同樣地,這允許我們確定在群組架構設定中輸入的正確值:
Object Class: group [1]Name Attribute: name [2]Group Member Mapping Attribute: member [3]Search Attribute: sAMAccountName [4]
查看 member 屬性的值,我們可以看到它包含引用使用者的 DN。這對應於我們使用者物件中的 distinguishedName 屬性。因此,我們必須將 Group Member User Attribute 參數的值設定為此屬性。
同樣地,我們可以觀察到使用者物件中 memberOf 屬性的值對應於群組的 distinguishedName [5]。因此,我們需要將 Group DN Attribute 參數的值設定為此屬性。
附錄:疑難排解
如果您在測試與 Active Directory 伺服器的連線時遇到問題,請先仔細檢查為服務帳戶輸入的憑證以及搜尋基礎設定。您還可以檢查 Rancher 日誌以幫助找出問題原因。除錯日誌可能包含有關錯誤的更詳細資訊。請參閱本文件中的如何啟用除錯日誌。