Keycloak 사용자 페더레이션(User Federation) — 외부 사용자 저장소 연동
Keycloak 사용자 페더레이션(User Federation) — 외부 사용자 저장소 연동
조직은 비밀번호·인증 정보 등을 담은 데이터베이스를 갖고 있는데, 보통 기존 데이터 저장소를 Keycloak 배포로 마이그레이션할 수 없어요. 그래서 Keycloak은 기존 외부 사용자 데이터베이스를 페더레이션(federate)할 수 있게 합니다. LDAP과 Active Directory를 내장 지원하고, Keycloak User Storage SPI로 어떤 커스텀 사용자 데이터베이스든 확장 코드를 짤 수 있어요.
출처: Keycloak Server Administration Guide — "Using external storage" — 공식문서
본문
어떻게 동작하나
사용자가 로그인을 시도하면 Keycloak은 그 사용자 저장소를 살펴 사용자를 찾아요. 로컬 DB에서 찾지 못하면 렐름의 각 User Storage provider를 차례로 반복 검색해 일치하는 사용자를 찾습니다. 외부 데이터 저장소의 데이터는 Keycloak 런타임이 소비하는 표준 사용자 모델로 매핑되고, 이 사용자 모델은 다시 OIDC 토큰 클레임과 SAML assertion 속성으로 매핑됩니다.
외부 사용자 데이터베이스는 Keycloak의 모든 기능을 지원할 만큼의 데이터를 갖지 못하는 경우가 많아요. 그래서 User Storage Provider는 일부 항목을 Keycloak 사용자 데이터 저장소에 로컬로 저장하도록 선택할 수 있습니다. 예를 들어 외부 저장소가 OTP를 지원하지 않으면, provider 설정에 따라 Keycloak이 OTP를 처리하고 저장할 수 있어요.
provider 추가하기
메뉴에서 User Federation 을 클릭하고 Kerberos 또는 LDAP provider를 추가하면 해당 provider의 설정 페이지로 이동해요. Keycloak에는 LDAP/AD provider가 포함되어 있어, 하나의 렐름에서 여러 LDAP 서버를 페더레이션하고 LDAP 사용자 속성을 Keycloak 공통 사용자 모델에 매핑할 수 있습니다.
기본적으로 Keycloak은 사용자 계정의 사용자 이름, 이메일, 이름, 성을 매핑하지만 추가 매핑도 구성할 수 있어요. LDAP/AD provider는 LDAP/AD 프로토콜과 저장소를 사용한 비밀번호 검증, 그리고 편집·동기화 모드를 지원합니다.
Storage mode (저장 모드)
Keycloak은 LDAP에서 사용자를 로컬 Keycloak 사용자 데이터베이스로 가져옵니다. 이 사용자 DB 복사본은 온디맨드 또는 주기적인 백그라운드 작업으로 동기화돼요. 비밀번호 동기화는 예외인데, Keycloak은 절대 비밀번호를 가져오지 않고 비밀번호 검증은 항상 LDAP 서버에서 발생합니다.
provider 실패 대처
User Storage Provider가 실패하면 로그인하거나 Admin Console에서 사용자를 보지 못할 수 있어요. Keycloak은 Storage Provider로 사용자를 찾을 때 실패를 탐지하지 못해 호출을 취소합니다. 우선순위가 높은 provider가 사용자 조회에서 실패하면 로그인이나 사용자 쿼리가 예외로 끝나고 다음 provider로 폴백(fail over)되지 않아요. Keycloak은 항상 로컬 사용자 DB를 먼저 검색하므로, LDAP 연결에 문제가 생길 때를 대비해 관리자 계정은 로컬 DB에 만들어 두는 것이 좋습니다.
각 LDAP/커스텀 User Storage Provider는 Admin Console 페이지에 enable 토글을 갖고 있어요. 이를 끄면 쿼리 시 해당 provider를 건너뛰므로, 우선순위가 낮은 다른 provider의 사용자 계정으로 로그인할 수 있습니다. import 전략을 쓰는 provider를 비활성화하면, 가져온 사용자는 읽기 전용 모드로 여전히 조회할 수 있어요.