LDAP 로그인 설정

사내 디렉터리(OpenLDAP, Active Directory 등)의 계정으로 로그인하게 하는 설정이다. 기본은 꺼져 있다. 로그인 경로는 POST /api/auth/ldap/login(사용자 이름·비밀번호)이다.

1. 환경변수 (.env)

변수	기본값	설명
LDAP_ENABLED	false	true 면 LDAP 로그인을 켠다. 꺼져 있으면 로그인 요청은 디렉터리에 접속하지 않고 403 으로 거부된다.
LDAP_URL	(비움)	예: ldap://ldap.example.com:389, ldaps://ldap.example.com:636
LDAP_BASE_DN	(비움)	사용자를 찾을 기준 DN. 예: dc=example,dc=com
LDAP_BIND_DN	(비움)	사용자 검색에 쓰는 바인드 계정 DN
LDAP_BIND_PASSWORD	(비움)	바인드 계정 비밀번호. .env 에만 둔다(DB·관리 화면·문서·이슈에 적지 않는다).
LDAP_USER_SEARCH_FILTER	(uid={0})	로그인 이름으로 사용자를 찾는 필터. {0} 이 로그인 이름(특수문자는 이스케이프된다). Active Directory 는 보통 (sAMAccountName={0}).
LDAP_USERNAME_ATTRIBUTE	uid	앱 사용자 이름으로 쓸 속성(AD 는 보통 sAMAccountName)
LDAP_EMAIL_ATTRIBUTE	mail	이메일 속성
LDAP_DISPLAY_NAME_ATTRIBUTE	cn	표시 이름 속성(AD 는 보통 displayName)
LDAP_MEMBER_OF_ATTRIBUTE	memberOf	사용자가 속한 그룹 DN 목록 속성
LDAP_ALLOWED_GROUP_FILTER	(비움)	선택. 로그인을 허용할 그룹 필터. 예: (memberOf=cn=chat-users,ou=groups,dc=example,dc=com)
LDAP_GROUP_PREFIX	(비움)	선택. 이 접두사로 시작하는 디렉터리 그룹만 앱 그룹으로 가져오고 접두사는 뗀다(예: chat-).

LDAP_URL·LDAP_BASE_DN·LDAP_BIND_DN·LDAP_USER_SEARCH_FILTER·LDAP_ALLOWED_GROUP_FILTER 는 관리자 화면(관리자 설정 → LDAP 연결)에서도 바꿀 수 있고, 화면에 저장한 값이 환경변수보다 우선한다. 바인드 비밀번호는 화면에서 다루지 않는다.

켠 뒤 GET <evo-api>/api/auth/config 의 ldapEnabled 가 true 인지 확인한다.

2. 디렉터리 쪽 준비

• 바인드 계정은 사용자 항목을 읽기만 할 수 있으면 된다(쓰기 권한 불필요).
• 그룹은 사용자 항목의 memberOf 로 읽는다. OpenLDAP 은 memberOf 오버레이를 켜야 이 값이 생긴다. memberOf 는 대부분 운영 속성이라 앱이 검색할 때 이름으로 요청한다(별도 설정 불필요).
• 그룹 이름은 그룹 DN 의 첫 값이다. cn=chat-users,ou=groups,dc=example,dc=com → chat-users.

3. 로그인할 때 일어나는 일

1. 로그인 이름으로 사용자를 찾아 그 DN 과 비밀번호로 bind 해 확인한다. 틀리면 401 “LDAP 인증에 실패했습니다”.
2. 허용 그룹 필터가 있으면 사용자 필터와 AND 로 묶어 다시 찾는다. 자격증명은 맞지만 허용 그룹 밖이면 403 “허용된 그룹에 속하지 않습니다”이고 계정을 만들지 않는다.
3. 앱 계정을 만들거나(처음, 인증 출처 ldap, 이름이 겹치면 _ldap 이 붙는다) 이메일·표시 이름을 갱신한다. 앱에서 비활성화한 계정은 403.
4. 디렉터리 그룹을 앱 그룹으로 맞춘다. 없는 그룹은 출처 ldap 으로 만들고, 디렉터리에서 빠진 ldap 출처 그룹 소속은 다음 로그인에 지운다.
5. 앱 로그인 규칙대로 기본 그룹 user 또는 admin 소속이 있어야 토큰이 발급된다. 없으면 403 “접근 권한이 없습니다.”

4. 알아 둘 점 (현재 한계)

• LDAP 계정은 기본 그룹 user 에 자동으로 들어가지 않는다. 디렉터리에 이름이 user 로 매핑되는 그룹(접두사를 쓰면 <접두사>user)을 두거나, 관리자가 앱에서 그 계정을 user 그룹에 넣어야 로그인할 수 있다. 이렇게 넣은 user 소속은 디렉터리에서 빠져도 지워지지 않는다. LDAP 과 로그인 규칙의 정렬은 에서 다룬다.
• 로그인 규칙에 막힌 첫 로그인에도 앱 계정 행은 만들어진다(관리자가 소속을 줄 수 있게).
• 관리자 역할로 자동 승격하지 않는다. 관리자는 앱에서 admin 그룹에 넣는다.
• 확인한 환경: OpenLDAP 2.4(memberOf 오버레이)와 시험용 내장 디렉터리. Active Directory·LDAPS 는 실제로 확인하지 않았다.