LDAP SSO¶
LDAP(Lightweight Directory Access Protocol)은 다양한 디렉터리 서비스를 처리하는 데 사용되는 애플리케이션 프로토콜입니다. Microsoft Entra ID는 Microsoft Entra 도메인 서비스(AD DS)를 통해 이 방식을 지원합니다.
배포 플랜은 LDAP 서비스를 이미 보유한 사용자가 이 프로토콜을 통해 원클릭 로그인할 수 있도록 지원합니다. 필요한 설정 필드는 다음과 같습니다.
| 필드 | 설명 |
|---|---|
host |
LDAP 서버 도메인 이름으로, 도메인, ldap://域名:端口 또는 ldaps://域名:端口 형식을 지원합니다. 포트를 지정해야 하는 경우 주소에 직접 표기하며, 별도의 server.port 설정은 적용되지 않습니다. |
baseDN |
기본 디렉터리 위치. 【필드 개념 보충】 참조 |
bindDN |
LDAP 서비스와 연결을 수립할 때 검증에 사용되는 사용자 이름 정보(DN 인터페이스). |
searchAttribute |
다른 계정을 검색할 때 계정을 필터링하는 데 사용되는 항목 이름. 이 항목 이름은 사용자가 입력한 사용자 이름과 함께 DIT 항목 정보를 구성합니다. (이 값을 통해 사용자 이름으로 고유 사용자를 확인할 수 있습니다.) |
bindPassword |
LDAP 서비스와 연결을 수립할 때 검증에 사용되는 비밀번호 정보. |
mapping |
플랫폼에 매핑해야 하는 계정 속성의 속성 필드 매핑 정보. LDAP에서 제공되는 계정 속성의 속성 값은 일반적으로 리스트입니다. 플랫폼에서 속성 값이 배열/리스트 구조인 경우 기본적으로 첫 번째 요소를 값으로 처리합니다. 【필드 개념 보충 > 2. 계정 속성 필드】 참조 |
필드 개념 보충
-
디렉터리 정보 트리(DIT): DIT는 파일 시스템과 유사한 계층 구조입니다. 항목을 식별하려면 항목을 나타내는 리프에서 트리 상단까지 DIT 내에서 해당 경로를 지정해야 합니다. 이 경로를 항목의 고유 이름(DN)이라고 합니다.
- 항목의 고유 이름(DN): 항목의 이름과 값의 키-값 쌍(쉼표로 구분)으로 구성되며, 리프에서 트리 상단까지의 경로를 나타냅니다. 항목의 DN은 전체 DIT에서 고유하며, 항목이 DIT 내의 다른 컨테이너로 이동할 때만 변경됩니다.
-
계정 속성 필드:
| 플랫폼의 계정 속성 | 플랫폼 측 필드 설명 | LDAP 서비스 측에서 제공하는 계정 속성으로, ldap3 변환 이후 속성(기본 필드) |
|---|---|---|
username |
로그인 계정의 사용자 이름. 미반환 시 이메일로 사용자 이름 생성 | uid |
email |
로그인 계정의 이메일 속성. 비어 있지 않은 값이 반환되면 유효한 이메일 주소여야 함 | mail |
mobile |
인증 서비스에서 로그인 계정의 휴대폰 번호 필드 이름. 선택 | mobile |
exterId |
인증 서비스에서 로그인 계정의 고유 식별자 필드 이름. 필수 | uid |
확장 인증 방식¶
- LDAP 다중 도메인 컨트롤러 인증(배포 플랜): 동일한 ID 디렉터리에 여러 컨트롤러를 구성하고 규칙에 따라 전환합니다.
- LDAP 사용자 지정 인증 및 Func 속성 가공(배포 플랜): 고객사 Func를 사용하여 인증을 수행하거나 인증 후 사용자 속성을 가공합니다.
기존 단일 주소 배포 환경은 업그레이드 시 기존 설정을 유지할 수 있습니다. 확장 기능을 활성화하기 전에 해당 문서의 버전, 호환성 및 인수 요구 사항을 먼저 확인하세요.
설정 상세 정보¶
Launcher 네임스페이스의 forethought-core > core에 다음과 같은 설정을 추가합니다. 설정 변수 값은 필요에 따라 조정해야 합니다.
# LDAP 클라이언트 구성(구성 참고: https://ldap3.readthedocs.io/en/latest/server.html)
LDAPClientSet:
# LDAP 활성화 여부, 기본값은 비활성화
enable: false
# server 매개변수 형식은 https://ldap3.readthedocs.io/en/latest/server.html 을 따릅니다
server:
# LDAP 서버 도메인 이름. 도메인 또는 ldap://xxx 또는 ldaps://xxx 형식
host: "ipa.demo1.freeipa.org"
# 연결 타임아웃 시간
connect_timeout: 6
# SSL 활성화 여부를 제어합니다
use_ssl: false
# 서버 스키마와 서버별 정보를 반드시 읽어야 하는지 여부를 지정합니다(기본값: SCHEMA). 옵션 값 설명: https://ldap3.readthedocs.io/en/latest/server.html#server-object
get_info: "SCHEMA"
tls:
# 기본값 없음. 클라이언트 개인 키가 포함된 파일 경로
local_private_key_file:
# 기본값 없음. 서버 인증서 파일 경로
local_certificate_file:
# 기본값 없음. 인증 기관 인증서가 포함된 파일 경로
ca_certs_file:
# 기본값 없음. 사용해야 할 암호(cipher)를 지정하는 문자열입니다. 최신 Python 인터프리터에 적용되며, SSLContext 또는 wrap_socket() 메서드에서 암호를 변경할 수 있습니다. 구버전에서는 무시됩니다. 기본값은 없음
ciphers:
# 서버 인증서 검증 필수 여부를 지정합니다. 옵션 값: CERT_NONE(인증서 무시), CERT_OPTIONAL(필수는 아니지만 제공되는 경우 검증), CERT_REQUIRED(필수이며 검증)
validate: "CERT_REQUIRED"
# 사용할 SSL 또는 TLS 버전. SSLv2, SSLv3, SSLv23, TLSv1 중 하나일 수 있습니다(Python 3.3 기준. 버전 목록은 다른 Python 버전에서 다를 수 있음). 현재 기본값은 TLS 1.2
version: "PROTOCOL_TLSv1_2"
connection:
# 기본값 없음. Active Directory 접근: ldap3을 사용하면 NTLM v2 프로토콜로 Active Directory 서버에 연결할 수도 있습니다. 이 경우 여기에 NTLM을 설정할 수 있습니다
authentication:
# authentication, sasl_mechanism, sasl_credentials는 여기서 https://ldap3.readthedocs.io/en/latest/bind.html?highlight=Active%20Directory#digest-md5 을 따라야 합니다
# 기본값 없음. Active Directory 접근 시 sasl_mechanism은 DIGEST_MD5가 될 수 있습니다. 기본값 없음
sasl_mechanism:
# Active Directory 접근 시 필요합니다.
# DIGEST-MD5 메커니즘을 사용하려면 sasl_credentials로 4개 또는 5개 값의 튜플을 전달해야 합니다: (realm, user, password, authz_id, enable_signing). 사용하지 않는 경우 'realm', 'authz_id', 'enable_signing'에는 None을 전달할 수 있습니다:
sasl_credentials:
# 표준 연결을 수립한 후 TLS를 활성화할지 여부. true인 경우 LDAP와 연결을 수립한 후 TLS를 확인하고 활성화합니다
startTls: false
baseDN: "dc=demo1,dc=freeipa,dc=org"
bindDN: "uid=admin,cn=users,cn=accounts,dc=demo1,dc=freeipa,dc=org"
bindPassword: "Secret123"
# 계정 검색에 사용되는 속성. 방법 1: `searchAttribute: uid`는 속성 필드 이름만 지정합니다. 방법 2: `searchAttribute: "(uid={username})"`처럼 사용자 지정 필터 문을 사용합니다. 이 방식에서는 괄호와 중괄호 안의 username이 필수입니다.
# 참고: AD 사용자라면 일반적으로 sAMAccountName으로 설정합니다.
searchAttribute: "uid"
# 계정 검색 시 계정 정보에 해당하는 클래스 이름. 참고: 연동 대상이 Microsoft AD의 LDAP인 경우 실제 디렉터리 구성에 따라 설정해야 합니다(예: person).
# 확인 방법: `ldapsearch`(타사 LDAP 연결 도구)를 설치하고 `ldapsearch -x -H ldap://xxx.cn:389 -D "bindDN信息" -w "bindPassword信息" -b "baseDN内容" "(cn=目标用户)"` 명령을 실행하면 반환 결과의 objectClass가 선택 가능한 목록입니다.
personObjectClass: "inetOrgPerson"
mapping:
# 인증 서비스에서 로그인 계정의 사용자 이름 필드 이름. 필수. 값이 없으면 email을 사용합니다
username: uid
# 인증 서비스에서 로그인 계정의 이메일 필드 이름. 필수
email: mail
# 인증 서비스에서 로그인 계정의 휴대폰 번호 필드 이름. 선택
mobile: mobile
# 인증 서비스에서 로그인 계정의 고유 식별자 필드 이름. 필수
exterId: uid
SSL을 사용하지 않는 경우, 내부 네트워크에서 LDAP 서비스에 접근하는 설정 예시:
# LDAP 클라이언트 구성(구성 참고: https://ldap3.readthedocs.io/en/latest/server.html)
LDAPClientSet:
# LDAP 활성화 여부, 기본값은 비활성화
enable: true
# server 매개변수 형식은 https://ldap3.readthedocs.io/en/latest/server.html 을 따릅니다
server:
# LDAP 서버 도메인 이름. 도메인 또는 ldap://xxx 또는 ldaps://xxx 형식
# 로컬 개발 주소, hosts 바인딩: 172.16.211.111 openldap-server
host: "<域名 、 协议+域名+端口>"
# 서버 스키마와 서버별 정보를 반드시 읽어야 하는지 여부를 지정합니다(기본값: SCHEMA). 옵션 값 설명: https://ldap3.readthedocs.io/en/latest/server.html#server-object
get_info: "ALL"
# 기본 DN 정보
baseDN: "<基础DN>"
# 클라이언트가 연결을 수립할 때 바인딩하는 DN
bindDN: "<客户端建立连接时绑定的DN>"
# bindDN에 해당하는 비밀번호
bindPassword: "<与 bindDN 对应的密码>"
# 계정 검색에 사용되는 속성
searchAttribute: cn
# 계정 검색 시 계정 정보에 해당하는 클래스 이름. 참고: 연동 대상이 Microsoft AD의 LDAP인 경우 실제 디렉터리 구성에 따라 설정해야 합니다(예: person).
# 확인 방법: `ldapsearch`(타사 LDAP 연결 도구)를 설치하고 `ldapsearch -x -H ldap://xxx.cn:389 -D "bindDN信息" -w "bindPassword信息" -b "baseDN内容" "(cn=目标用户)"` 명령을 실행하면 반환 결과의 objectClass가 선택 가능한 목록입니다.
personObjectClass: "inetOrgPerson"
# 계정 속성이 아래 표와 일치하지 않으면 조정해야 합니다
mapping:
# 인증 서비스에서 로그인 계정의 사용자 이름 필드 이름. 필수. 값이 없으면 email을 사용합니다
username: cn
# 인증 서비스에서 로그인 계정의 이메일 필드 이름. 필수
email: mail
# 인증 서비스에서 로그인 계정의 휴대폰 번호 필드 이름. 선택
mobile: mobile
# 인증 서비스에서 로그인 계정의 고유 식별자 필드 이름. 필수
exterId: cn
LDAP SSO 사용¶
위 설정을 모두 추가하면 LDAP SSO를 사용할 수 있습니다.
1)배포 플랜 로그인 주소를 열고 로그인 페이지에서 LDAP 로그인을 선택합니다.
2)LDAP 서버에서 사용하는 사용자 이름과 비밀번호를 입력합니다.
3)해당 워크스페이스로 로그인합니다.