SSO 를 LDAP 과 "연결한다"는 것은 대개 다음 구조를 뜻한다. 애플리케이션은 LDAP 을 직접 보지 않고 Keycloak 만 상대하며, Keycloak 이 사용자 저장소로 AD · OpenLDAP 을 참조한다.
애플리케이션 --OIDC/SAML--> Keycloak --LDAP--> AD / OpenLDAP
이렇게 두면 애플리케이션마다 LDAP 설정을 복제하지 않아도 되고, 다중 인증 · 세션 정책 같은 것을 Keycloak 한 곳에서 건다.
Keycloak 에서 이 기능의 이름은 User Federation 이다. Identity Provider 는 다른 IdP 에 로그인을 위임하는 별개 기능이므로 혼동하지 않는다.
관리 콘솔에서 realm 을 고르고 User federation → Add Ldap providers 로 들어간다.
| 항목 | Active Directory | OpenLDAP |
|---|---|---|
| Vendor | Active Directory | Other |
| Connection URL | ldaps://ad.example.com:636 |
ldaps://ldap.example.com:636 |
| Bind type | simple | simple |
| Bind DN | svc-keycloak@example.com |
cn=readonly,dc=example,dc=com |
| Users DN | OU=Users,DC=example,DC=com |
ou=people,dc=example,dc=com |
| Username LDAP attribute | sAMAccountName |
uid |
| RDN LDAP attribute | cn |
uid |
| UUID LDAP attribute | objectGUID |
entryUUID |
| User object classes | person, organizationalPerson, user |
inetOrgPerson, organizationalPerson |
| Edit mode | READ_ONLY | 용도에 따라 |
Edit mode 는 세 가지다. READ_ONLY 는 Keycloak 에서 사용자 정보를 고칠 수 없고, WRITABLE 은 LDAP 에 되쓰며, UNSYNCED 는 Keycloak 안에서만 고친다. 디렉터리를 원본으로 삼는 구성이라면 READ_ONLY 가 안전하다.
Vendor 를 Active Directory 로 두면 AD 특성(계정 비활성 판정, objectGUID 처리 등)이 자동으로 반영되므로 반드시 맞게 고른다.
설정 후 Test connection 과 Test authentication 으로 확인한다.
Import users 를 켜면 로그인한 사용자가 Keycloak DB 에 저장되고, 껐다면 매번 LDAP 을 조회한다.
Periodic full sync : 전체를 주기적으로 맞춘다.Periodic changed users sync : 변경분만 가져온다. AD 는 whenChanged, OpenLDAP 은 modifyTimestamp 를 기준으로 삼는다.사용자 수가 많으면 전체 동기화는 부하가 크므로 변경분 위주로 잡고 전체는 주기를 길게 둔다. 동기화 주기를 짧게 해도 LDAP 쪽 인덱스가 없으면 조회가 느려 오히려 실패한다.
기본 상태로는 사용자만 넘어오고 그룹은 오지 않는다. Mappers 에서 group-ldap-mapper 를 추가한다.
| 항목 | 값 예 |
|---|---|
| Groups DN | OU=Groups,DC=example,DC=com |
| Group name LDAP attribute | cn |
| Group object classes | group(AD) · groupOfNames(OpenLDAP) |
| Membership LDAP attribute | member |
| Membership user LDAP attribute | distinguishedName(AD) · uid |
| Mode | READ_ONLY |
| User groups retrieve strategy | LOAD_GROUPS_BY_MEMBER_ATTRIBUTE |
그렇게 들어온 그룹을 애플리케이션 권한과 잇는 방법은 두 가지다. Keycloak 그룹에 realm · client role 을 부여하거나, 토큰에 그룹 목록을 담아 애플리케이션이 판단하게 한다. 후자는 client scope 에 groups 매퍼를 추가한다.
# 토큰을 직접 받아 클레임 확인
curl -s -X POST \
"https://keycloak.example.com/realms/<realm>/protocol/openid-connect/token" \
-d "grant_type=password" -d "client_id=<client>" \
-d "username=<user>" -d "password=<PASSWORD>" \
| cut -d. -f2 | base64 -d 2>/dev/null
grant_type=password 는 시험용이며 운영 클라이언트에서는 꺼 두는 것이 권장이다.
로그인이 실패하면 Keycloak 서버 로그에 LDAP 응답이 그대로 남으므로, 먼저 그것을 보고 OpenLDAP 운영 중 나는 오류 의 결과 코드와 대조한다.