LDAP 다중 도메인 컨트롤러 인증(배포 플랜)¶

배포 플랜은 동일한 LDAP ID 디렉터리에 대해 여러 도메인 컨트롤러 주소를 구성할 수 있도록 지원합니다. 로그인 시 구성된 순서대로 연결하며, 사용자 비밀번호를 제출하기 전에 전환 가능한 서비스 장애가 발생하면 다음 주소를 시도합니다.

여기서 '다중 도메인 컨트롤러'란 계정, 디렉터리 구조 및 인증 규칙을 공유하는 여러 컨트롤러(예: 동일한 AD 도메인의 복제본)를 의미합니다. 여러 독립적인 AD 도메인 간 계정 라우팅을 제공하지 않으며, 도메인별로 비밀번호를 시도하여 사용자를 찾지도 않습니다. 독립적인 ID 소스에 사용자 지정 인증이 필요한 경우 LDAP 사용자 지정 인증 및 Func 속성 가공을 참조하세요.

업그레이드 및 호환성¶

사용 전에 배포된 Studio 백엔드 버전에 LDAPClientSet.authMode 및 LDAPClientSet.server.hosts 구성 기능이 포함되어 있는지 확인하세요. 도움말 문서나 Func 스크립트만 업데이트해도 이전 버전 백엔드에 기능이 추가되지는 않습니다.

기존 단일 주소 배포는 구성을 수정할 필요가 없습니다. authMode가 기본값이거나 builtin이고 server.hosts가 구성되지 않았거나 null 또는 []인 경우 기존 단일 주소 인증 흐름이 계속 사용됩니다. 새로 추가된 인증 총 시간 제한과 외부 함수 구성은 해당 흐름을 변경하지 않습니다. 단순 업그레이드를 위해 원래 주소만 포함된 hosts 목록을 추가하지 마세요. 비어 있지 않은 목록은 새 흐름을 적극적으로 활성화함을 의미합니다.

활성화 전에 다음 사항을 확인하세요.

• 모든 후보 도메인 컨트롤러가 동일한 baseDN, 서비스 계정, 사용자 검색 조건, TLS 구성 및 mapping을 사용합니다. 각 복제본의 동일한 사용자에 대한 exterId가 일치합니다.
• 후보 도메인 컨트롤러에 모두 Studio 백엔드 컨테이너에서 액세스할 수 있으며, CA 파일이 컨테이너에 마운트되어 있고 인증서에 연결된 도메인 이름이 포함되어 있습니다.
• 디렉터리가 검색 결과의 사용자 DN을 사용한 SIMPLE 비밀번호 검증을 허용하며, LDAPS 또는 StartTLS를 통해 비밀번호 전송이 보호됩니다. 서비스 계정 바인딩 방식과 최종 사용자 비밀번호 검증은 별도의 두 단계입니다.
• 이 기능을 지원하는 공식 서비스 시작 방식을 사용합니다. 새 흐름은 중단 가능한 네트워크 및 DNS 실행 환경을 요구합니다. 사용자 지정 시작 방식에서 gevent_runtime 또는 gevent_dns 구성 오류가 발생하면 시작 환경을 수정해야 합니다.

여러 도메인 컨트롤러 구성¶

애플리케이션 구성 안내에 따라 Launcher의 forethought-core 네임스페이스에서 Core 구성을 수정합니다. 다음은 LDAPS 예시로, 도메인 이름, DN, 인증서 경로 및 자리 표시자 비밀번호를 실제 구성으로 교체하세요. 기존 사용자의 ID 매핑은 유지합니다.

LDAPClientSet:
  enable: true
  authMode: builtin
  authTimeoutSeconds: 20
  server:
    # 비어 있지 않은 hosts는 host를 완전히 대체합니다. 실패 시 host로 폴백되지 않습니다.
    hosts:
      - "ldaps://ldap-a.example.com:636"
      - "ldaps://ldap-b.example.com:636"
    connect_timeout: 6
    use_ssl: true
    get_info: SCHEMA
    tls:
      validate: CERT_REQUIRED
      ca_certs_file: "/config/ldap/ca.pem"
  connection:
    authentication: SIMPLE
    client_strategy: SAFE_SYNC
    receive_timeout: 5
  startTls: false
  baseDN: "dc=example,dc=com"
  bindDN: "cn=studio-reader,ou=service,dc=example,dc=com"
  bindPassword: "<서비스 계정 비밀번호>"
  searchAttribute: "uid"
  personObjectClass: "inetOrgPerson"
  mapping:
    exterId: uid
    username: uid
    email: mail
    mobile: mobile

AD 환경에서는 일반적으로 실제 디렉터리에 맞게 searchAttribute(예: sAMAccountName) 및 personObjectClass(예: person)를 조정해야 합니다. 예제를 그대로 적용하여 기존 mapping.exterId를 덮어쓰지 마세요.

StartTLS를 사용하는 경우 후보 주소를 ldap://도메인:389로 변경하고 server.use_ssl: false, startTls: true로 설정하며 인증서 검증은 유지합니다. 새 흐름은 TLS 핸드셰이크를 완료한 후 서비스 계정을 바인딩합니다. LDAPS와 StartTLS를 동시에 활성화하지 마세요.

환경 변수로 목록을 구성하는 경우 JSON 배열 문자열을 사용합니다. 예:

STUDIO__LDAPClientSet__server__hosts='["ldaps://ldap-a.example.com:636","ldaps://ldap-b.example.com:636"]'

구성 변경 후 Launcher의 구성 변경 후 관련 서비스 자동 재시작 옵션을 선택하고 확인하여 로그인 요청을 처리하는 모든 복제본이 동일한 구성을 사용하도록 하세요.

어떤 장애에서 도메인 컨트롤러를 전환하나요¶

각 인증은 목록의 첫 번째 주소에서 시작합니다. 전환은 서비스 불가를 처리하기 위한 것이며 인증 거부를 우회하는 데 사용되지 않습니다.

따라서 특정 도메인 컨트롤러에 사용자가 없는 경우 다른 독립 디렉터리에서 '동일한 이름의 계정'을 계속 찾지 않습니다. 먼저 복제본 동기화 및 ID 일관성을 확인하세요.

로그인 및 검증¶

사용자는 여전히 배포 플랜 로그인 페이지에서 LDAP 로그인을 선택하고 기존 사용자 이름과 비밀번호를 입력합니다. 도메인 컨트롤러를 선택할 필요가 없습니다. 워크스페이스 권한은 기존 SSO 매핑 규칙을 계속 사용합니다.

전용 테스트 계정으로 먼저 검증한 후 기존 사용자에게 공개하는 것이 좋습니다.

1. 모든 주소가 정상일 때 로그인에 성공하며 기존 사용자는 원래 계정으로 진입하고 워크스페이스와 역할이 예상대로 표시됩니다.
2. 통제된 테스트에서 첫 번째 주소의 연결 불가를 시뮬레이션하여 두 번째 주소로 로그인할 수 있는지 확인하고 전체 소요 시간이 총 시간 제한의 적용을 받는지 확인합니다.
3. 잘못된 비밀번호를 입력하여 여러 컨트롤러를 시도해도 비밀번호 재시도 횟수가 늘어나지 않는지 확인하고 디렉터리 측 잠금 정책을 확인합니다.
4. 인증서 오류, 서비스 계정 오류, 사용자 검색 실패가 모두 실패하며 전환을 통해 오류를 우회하지 않는지 확인합니다.
5. 두 컨트롤러에서 각각 동일한 사용자의 ID 필드와 권한에 필요한 그룹 속성을 비교하여 일치하는지 확인합니다.

mapping.exterId는 LDAP 사용자의 안정적인 ID에 해당합니다. 매핑 필드 또는 필드 값을 변경하면 새 계정이 생성될 수 있습니다. 동일한 이메일 또는 사용자 이름에 의존하여 ID를 자동으로 병합하지 마세요.

롤백¶

업그레이드 전 구성을 유지하세요. 이전 단일 주소 인증으로 복원해야 하는 경우 authMode를 builtin으로 설정하고 server.hosts를 비우거나 삭제한 후 원래 server.host 및 기존 연결, TLS 및 매핑 구성을 복원하고 관련 서비스를 재시작하세요. host만 수정하고 비어 있지 않은 hosts를 유지하면 적용되지 않습니다.

롤백 구성은 이미 생성된 계정을 자동으로 병합하지 않으며 변경된 역할 매핑도 복원하지 않습니다. 속성 가공 또는 ID 매핑을 동시에 변경한 경우 먼저 계정 및 권한 영향을 확인하세요.