第 13 課：使用者聯合 - LDAP 和 Active Directory

將 LDAP 群組同步到 Keycloak 群組：

Mapper Type: group-ldap-mapper
LDAP Groups DN: ou=Groups,dc=example,dc=com
Group Name LDAP Attribute: cn
Group Object Classes: groupOfNames
Membership LDAP Attribute: member
Membership Attribute Type: DN
Membership User LDAP Attribute: uid
Mode: READ_ONLY
User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE
Drop non-existing groups during sync: false
Groups Path: /

___HTMLTAG_717__HTMLTAG_718___使用者群組擷取策略選項：HTMLTAG_719__HTMLTAG_720

將 LDAP 角色/群組同步到 Keycloak 領域角色：

Mapper Type: role-ldap-mapper
LDAP Roles DN: ou=Roles,dc=example,dc=com
Role Name LDAP Attribute: cn
Role Object Classes: groupOfNames
Membership LDAP Attribute: member
Membership Attribute Type: DN
Membership User LDAP Attribute: uid
Mode: READ_ONLY
Use Realm Roles Mapping: true
Client ID: (để trống nếu dùng realm roles)

HTMLTAG_765__HTMLTAG_766___6.5 硬編碼-ldap-角色映射器___HTMLTAG_767__HTMLTAG_768

自動將固定角色指派給 LDAP 供應商的 所有 使用者：

Mapper Type: hardcoded-ldap-role-mapper
Role: realm-role-name
# Hoặc client role:
Role: client-id.client-role-name

當您想要使用角色標記來區分 LDAP 使用者和本機使用者時很有用。

HTMLTAG_775__HTMLTAG_776___6.6 msad-使用者帳號控制映射器___HTMLTAG_777__HTMLTAG_778

用於 Active Directory 的特殊映射器，處理 userAccountControl 屬性：

Mapper Type: msad-user-account-control-mapper
# Xử lý:
# - Account enabled/disabled status
# - Password expired status
# - Account locked status
# - Require user to change password at next login

此映射器讀取 AD 的位元遮罩 userAccountControl 以對應到 Keycloak 使用者狀態：

HTMLTAG_825__HTMLTAG_826___6.7 憑證-ldap-映射器___HTMLTAG_827__HTMLTAG_828

將 LDAP 憑證屬性對應到 Keycloak 使用者屬性以進行 X.509 驗證：

Mapper Type: certificate-ldap-mapper
LDAP Attribute: userCertificate
User Model Attribute: usercertificate
Is DER Formatted: true
Always Read Value From LDAP: true

HTMLTAG_831__HTMLTAG_832___7。密碼雜湊___HTMLTAG_833__HTMLTAG_834

使用 LDAP 聯合時，密碼雜湊有幾個重要特徵：

# Kiểm tra password policy trên LDAP (OpenLDAP)
ldapsearch -x -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=com" -W \
  -b "cn=config" "(objectClass=olcGlobal)" olcPasswordHash

# Output ví dụ:
# olcPasswordHash: {SSHA}

HTMLTAG_881__HTMLTAG_882___8。 SSSD 與 FreeIPA 整合___HTMLTAG_883__HTMLTAG_884

Keycloak 支援透過 D-Bus 介面與 SSSD（系統安全服務守護程序） 集成，允許從 FreeIPA 或 Red Hat Identity Manager 對使用者進行身份驗證。

HTMLTAG_889__HTMLTAG_890___8.1 先修條件___HTMLTAG_891__HTMLTAG_892

# Cài đặt SSSD trên Keycloak server
sudo dnf install sssd sssd-dbus

# Cấu hình SSSD (/etc/sssd/sssd.conf)
[sssd]
services = nss, pam, ifp
domains = example.com

[domain/example.com]
id_provider = ipa
auth_provider = ipa
access_provider = ipa
ipa_domain = example.com
ipa_server = ipa.example.com

[ifp]
allowed_uids = root, keycloak
user_attributes = +mail, +givenname, +sn, +telephoneNumber

HTMLTAG_893__HTMLTAG_894___8.2 設定 SSSD 聯合提供者___HTMLTAG_895__HTMLTAG_896

在管理控制台中，新增 SSSD 聯合提供者 — Keycloak 將透過 D-Bus 與 SSSD 通訊至：

• 對使用者進行身份驗證 (PAM)
• 取得使用者屬性 (InfoPipe)
• 取得群組成員資格__HTMLTAG_907___

HTMLTAG_909__HTMLTAG_910___9。 Kerberos 橋接器___HTMLTAG_911__HTMLTAG_912

Keycloak 可以使用 Kerberos 驗證 以及 LDAP 聯合，允許使用者使用 Kerberos 票證 (SPNEGO) 自動登入。

HTMLTAG_917__HTMLTAG_918___9.1 使用 LDAP 設定 Kerberos___HTMLTAG_919__HTMLTAG_920

# Trong LDAP provider settings
Allow Kerberos authentication: ON
Kerberos Realm: EXAMPLE.COM
Server Principal: HTTP/[email protected]
KeyTab: /etc/keycloak/keycloak.keytab
Use Kerberos for password authentication: ON

# Tạo keytab cho Keycloak service principal
kadmin.local -q "addprinc -randkey HTTP/[email protected]"
kadmin.local -q "ktadd -k /etc/keycloak/keycloak.keytab HTTP/[email protected]"

# Set permissions
chown keycloak:keycloak /etc/keycloak/keycloak.keytab
chmod 600 /etc/keycloak/keycloak.keytab

HTMLTAG_921__HTMLTAG_922___9.2 SPNEGO 的瀏覽器設定___HTMLTAG_923__HTMLTAG_924

預編碼_20

HTMLTAG_925__HTMLTAG_926___10。自訂使用者儲存 SPI___HTMLTAG_927__HTMLTAG_928

當LDAP不夠用時，您可以編寫自訂使用者儲存提供者來連接任何資料來源（SQL資料庫、REST API、遺留系統...）.

HTMLTAG_933__HTMLTAG_934___10.1 SPI 介面___HTMLTAG_935__HTMLTAG_936

// UserStorageProviderFactory — tạo provider instances
public class MyUserStorageProviderFactory
    implements UserStorageProviderFactory<MyUserStorageProvider> {

    @Override
    public String getId() {
        return "my-user-storage";
    }

    @Override
    public MyUserStorageProvider create(KeycloakSession session,
                                         ComponentModel model) {
        return new MyUserStorageProvider(session, model);
    }
}

// UserStorageProvider — implement các interfaces cần thiết
public class MyUserStorageProvider implements
    UserStorageProvider,
    UserLookupProvider,
    CredentialInputValidator,
    UserQueryProvider {

    @Override
    public UserModel getUserByUsername(RealmModel realm, String username) {
        // Query external database
        ExternalUser extUser = externalDb.findByUsername(username);
        if (extUser == null) return null;

        // Wrap vào Keycloak UserModel
        return new UserAdapter(session, realm, model, extUser);
    }

    @Override
    public boolean isValid(RealmModel realm, UserModel user,
                           CredentialInput input) {
        if (!supportsCredentialType(input.getType())) return false;
        // Verify password với external system
        return externalDb.verifyPassword(
            user.getUsername(),
            input.getChallengeResponse()
        );
    }
}

HTMLTAG_937__HTMLTAG_938___10.2 部署自訂提供者___HTMLTAG_939__HTMLTAG_940

# Build JAR
mvn clean package

# Copy vào Keycloak providers directory
cp target/my-user-storage.jar /opt/keycloak/providers/

# Rebuild Keycloak
/opt/keycloak/bin/kc.sh build

HTMLTAG_941__HTMLTAG_942___11。使用 kcadm.sh 設定 LDAP___HTMLTAG_943__HTMLTAG_944

使用 kcadm.sh 透過命令列設定 LDAP 聯合：

# Đăng nhập
kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password admin

# Tạo LDAP provider
kcadm.sh create components -r my-realm \
  -s name="Corporate LDAP" \
  -s providerId=ldap \
  -s providerType=org.keycloak.storage.UserStorageProvider \
  -s 'config.vendor=["other"]' \
  -s 'config.connectionUrl=["ldap://ldap.example.com:389"]' \
  -s 'config.bindDn=["cn=admin,dc=example,dc=com"]' \
  -s 'config.bindCredential=["admin_password"]' \
  -s 'config.usersDn=["ou=People,dc=example,dc=com"]' \
  -s 'config.userObjectClasses=["inetOrgPerson, organizationalPerson"]' \
  -s 'config.usernameLDAPAttribute=["uid"]' \
  -s 'config.rdnLDAPAttribute=["uid"]' \
  -s 'config.uuidLDAPAttribute=["entryUUID"]' \
  -s 'config.editMode=["READ_ONLY"]' \
  -s 'config.syncRegistrations=["false"]' \
  -s 'config.searchScope=["2"]' \
  -s 'config.importEnabled=["true"]' \
  -s 'config.enabled=["true"]' \
  -s 'config.priority=["0"]' \
  -s 'config.fullSyncPeriod=["604800"]' \
  -s 'config.changedSyncPeriod=["86400"]'

# Lấy LDAP provider ID
LDAP_ID=$(kcadm.sh get components -r my-realm \
  --fields id,name \
  -q providerType=org.keycloak.storage.UserStorageProvider \
  | jq -r '.[0].id')

# Thêm group mapper
kcadm.sh create components -r my-realm \
  -s name="group-mapper" \
  -s providerId=group-ldap-mapper \
  -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper \
  -s parentId=$LDAP_ID \
  -s 'config.groups.dn=["ou=Groups,dc=example,dc=com"]' \
  -s 'config.group.name.ldap.attribute=["cn"]' \
  -s 'config.group.object.classes=["groupOfNames"]' \
  -s 'config.membership.ldap.attribute=["member"]' \
  -s 'config.membership.attribute.type=["DN"]' \
  -s 'config.membership.user.ldap.attribute=["uid"]' \
  -s 'config.mode=["READ_ONLY"]' \
  -s 'config.drop.non.existing.groups.during.sync=["false"]'

# Trigger full sync
kcadm.sh create user-storage/$LDAP_ID/sync -r my-realm \
  -s action=triggerFullSync

HTMLTAG_949__HTMLTAG_950___12。 LDAP 問題故障排除___HTMLTAG_951__HTMLTAG_952

HTMLTAG_953__HTMLTAG_954___12.1 連線問題___HTMLTAG_955__HTMLTAG_956