設定Keycloak v19串接Windows AD / LDAP
Keycloak與Windows AD / LDAP的關係
Keycloak作為一個開源的單點登入開源軟體，提供多種登入方式，包含SAML、OIDC亦或是串接第三方認證服務，如Google、Facebook等；而Windows AD (or LDAP)是一般企業最常使用的目錄管理工具，將員工的帳號、密碼及各種屬性存放在Windows AD (or LDAP)集中管理，尤其Windows AD還可以整合微軟各種辦公室生產力軟體，如Windows、Outlook、Teams…等。
Keycloak官方網站：Link
本篇的目標與架構
本篇分享如何整合Keycloak與Windows AD (or LDAP)：
- Keycloak串接Windows AD (od LDAP)，並將Keycloak作為Windows AD (or LDAP)的的代理(Proxy)服務
- 將Windows AD (or LDAP)的使用者與群組同步至Keycloak
環境準備：Windows AD群組與使用者的結構
Keyclaok
安裝詳見”安裝Keycloak v19提供身份認證與SSO服務“。
Windows AD
為了本篇範例，準備一個Windows AD，建立一個OU名為Jovepater，並增加群組與使用者，結構及關係圖如下：
設定Windows AD為Keycloak的認證服務
步驟1：登入Keycloak的Administration Console，新增一個Realm名為”WebUserRealm”。
步驟2：左側Menu處點選”Config” > “User Federation”，在”Add provider”處下拉選擇”LDAP”，畫面如下圖：
步驟3：以下針對每個欄位說明 (順序依照畫面由上而下)：
| # | 欄位名稱 | 說明 | 本篇輸入範例 |
| 1 | Console Display Name | 本設定的名字 | ldap |
| 2 | Priority | 當同一個Realm中有多個Provider時，Provider數字越小，表示越優先被使用 | 0 (預設值) |
| 3 | Import Users | 若選”On”，Windows AD中的使用者會被同步至Keycloak的資料庫中 | On (預設值) |
| 4 | Edit Mode | – READ_ONLY：從LDAP同步到Keycloak，在Keycloak不可更新數據 – WRITABLE：Keycloak與LDAP雙向同步 – UNSYNCED：從LDAP同步到Keycloak，在Keycloak可更新數據 | READ_ONLY (預設值) |
| 5 | Sync Registrations | 若選”On”，LDAP新增的User會即時同步到Keycloak | OFF (預設值) |
| 6 | Vendor | 提供目錄或認證的提供者 | Active Directory |
| 7 | Username LDAP attribute | 所登入帳號的LDAP屬性，通常是cn或uid | cn (預設值) |
| 8 | RDN LDAP attribute | 對應到LDAP RDN屬性，通常是cn | cn (預設值) |
| 9 | UUID LDAP attribute | 對應到LDAP UUID屬性，用於對應單一帳號，通常是objectGUID | objectGUID (預設值) |
| 10 | User Object Classes | 指定User的屬性，通常是person, organizationalPerson, user | person, organizationalPerson, user (預設值) |
| 11 | Connection URL | Windows AD (or LDAP)的網路位置，通常是ldap://開頭 | ldap://{IP or hostname} |
| 12 | Users DN | 指定某個節點向下的所有物件，通常會指定一個OU | OU=jovepater,DC=jovepater,DC=tw |
| 13 | Custom User LDAP Filter | 如果要過濾特別的屬性，可以在這個欄位指定 | 空 |
| 14 | Search Scope | – One Level：只讀取Users DN同一層 – Subtree：讀取Users DN向下所有階層 | Subtree |
| 15 | Bind Type | 指定Windows AD (or LDAP)驗證方式，simple表示使用帳號/密碼 | simple |
| 16 | Bind DN | 指定Windows AD (or LDAP)的驗證帳號 | CN=Administrator,CN=Users,DC=jovepater,DC=tw |
| 17 | Bind Credential | Windows AD (or LDAP)驗證帳號的密碼 | ************ |
步驟4：畫面右邊有”Test connection”與”Test authentication”，這兩個按鈕可以提供連接與驗證測試，都通過，即可點擊下方”Save”存檔，並再次點擊”Synchronize all users”來同步使用者到Keycloak。
設定同步LDAP物件的屬性
在Keycloak的LDAP設定中有一個”Mappers”選項 (如下圖)，顧名思義就是對應LDAP物件的屬性，並將該屬性同步至Keycloak。
系統已經預設了幾個一般而言最基本的屬性，包含姓、名、創建日期、異動日期等，接著我們以Email這個屬性來作為範例。
步驟1：依序”User Frederation” > “Ldap” > “LDAP Mappers”，點選右邊的”Create”，輸入：
- Name：此處就命名為”email”
- Mapper Type：選擇”user-attribute-ldap-mapper”
接著畫面上會展出對應的表單，如下圖：
步驟2：以下就每個欄位做說明，並附上範例參數：
| # | 欄位名稱 | 說明 | 本篇輸入範例 |
| 1 | ID | 唯一的序號 | 由系統自動產生 |
| 2 | Name | 設定的名字，同一個Provider內不可重複 | |
| 3 | Mapper Type | Mapper類別 | user-attribute-ldap-mapper |
| 4 | User Model Attribute | 同步至Keycloak的欄位名稱，可按需求自由設定 | |
| 5 | LDAP Attribute | 對應至LDAP的屬性 | |
| 6 | Read Only | ON：只從LDAP同步而來 OFF：LDAP/Keycloak雙向同步 | ON |
| 7 | Always Read Value From LDAP | ON：讀取資訊時，永遠向LDAP詢問 | OFF |
| 8 | Is Mandatory In LDAP | ON：該屬性在 LDAP 中是必需的，如果 Keycloak 中沒有值，則默認值或空值將被同步到 LDAP | OFF |
| 9 | Attribute default value | 當空值或null時，預設寫入的值 | 空值 |
| 10 | Is Binary Attribute | ON：表示該值為True or False | OFF |
步驟3：回到”Ldap”設定畫面，點選下方”Synchronize all users”，若畫面顯示如下圖的示意，則代表同步成功了。
步驟4：移至”Manage” > “Users”，若畫面空白，可以點選”View all users”，會列出所有從LDAP同步而來的帳號，如下圖：
可以看到，包含Email這個屬性都已經同步到Keycloak囉！
同步LDAP的群組與轄下User到Keycloak
步驟1：依序”User Frederation” > “Ldap” > “LDAP Mappers”，點選右邊的”Create”，輸入：
- Name：此處就命名為”group”
- Mapper Type：選擇”group-ldap-mapper”
接著畫面上會展出對應的表單，如下圖：
步驟2：以下就每個欄位做說明，並附上範例參數：
| # | 欄位名稱 | 說明 | 本篇輸入範例 |
| 1 | ID | 唯一的序號 | 由系統自動產生 |
| 2 | Name | 設定的名字，同一個Provider內不可重複 | group |
| 3 | Mapper Type | Mapper類別 | group-ldap-mapper |
| 4 | LDAP Groups DN | Group的DN | OU=jovepater,DC=jovepater,DC=tw |
| 5 | Group Name LDAP Attribute | Group name的屬性欄位 | cn (預設值) |
| 6 | Group Object Classes | 定義Group物件的類別，通常是”group” | group (預設值) |
| 7 | Preserve Group Inheritance | 是否保留LDAP中group的上下層關係 | ON (預設值) |
| 8 | Ignore Missing Groups | 忽略遺失或有問題group | ON |
| 9 | Membership LDAP Attribute | LDAP指定group的屬性欄位 | member |
| 10 | Membership Attribute Type | 成員屬性欄位 | DN (預設值) |
| 11 | Membership User LDAP Attribute | 成員在LDAP的屬性欄位 | cn (預設值) |
| 12 | LDAP Filter | LDAP的過濾器，可以透過LDAP語法來下條件 | (|(CN=WebAdmin)(CN=WebUser)) |
| 13 | Mode | – LDAP_ONLY：無論如何都從LDAP查詢 – IMPORT：將Keycloak與LDAP資料合併存在Keycloak中 – READ_ONLY：將LDAP資料同步到Keycloak，並由Keycloak提供查詢 | READ_ONLY |
| 14 | User Groups Retrieve Strategy | 群組檢索策略 | LOAD_GROUP_BY_MEMBER_ATTRIBUTE |
| 15 | Member-Of LDAP Attribute | LDAP成員屬性 | memberOf |
| 16 | Mapped Group Attributes | 映射到group的屬性 | 空值 (預設值) |
| 17 | Drop non-existing groups during sync | 同步期間刪除不存在的group | OFF |
| 18 | Groups Path | group的路徑 | / (預設值) |
步驟3：表格填寫完畢後，儲存，並可以按下”Sync LDAP Groups To Keycloak”，若顯示成功，就可以到”Manage” > “Groups”查看group是否同步，如下圖：
步驟4：點選”WebUser”群組，查看該群組的屬性，也可以點選頁簽”Members”，查看該group下的成員，如下圖：
以上就完成設定與同步LDAP Group與User到Keycloak了！
~ END ~
