메인 콘텐츠로 건너뛰기
이 페이지는 ClickHouse Cloud에는 적용되지 않습니다. 여기에서 설명하는 기능은 ClickHouse Cloud 서비스에서 지원되지 않습니다. 자세한 내용은 ClickHouse의 Cloud Compatibility 가이드를 참조하십시오.
LDAP 서버는 ClickHouse 사용자를 인증하는 데 사용할 수 있습니다. 이를 수행하는 방법은 두 가지입니다.
  • users.xml 또는 로컬 액세스 제어 경로에 정의된 기존 사용자에 대해 LDAP를 외부 인증자로 사용합니다.
  • LDAP를 외부 사용자 디렉터리로 사용하고, 로컬에 정의되지 않은 사용자라도 LDAP 서버에 존재하면 인증을 허용합니다.
이 두 가지 방식 모두에서, 구성의 다른 부분이 이를 참조할 수 있도록 내부 이름이 지정된 LDAP 서버를 ClickHouse 구성에 정의해야 합니다.

​
LDAP 서버 정의

LDAP 서버를 정의하려면 config.xml에 ldap_servers 섹션을 추가해야 합니다. 예시 
<clickhouse>
    <!- ... -->
    <ldap_servers>
        <!- 일반적인 LDAP 서버. -->
        <my_ldap_server>
            <host>localhost</host>
            <port>636</port>
            <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
            <verification_cooldown>300</verification_cooldown>
            <follow_referrals>false</follow_referrals>
            <enable_tls>yes</enable_tls>
            <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
            <tls_require_cert>demand</tls_require_cert>
            <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
            <tls_key_file>/path/to/tls_key_file</tls_key_file>
            <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
            <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
            <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
        </my_ldap_server>

        <!- 사용자 DN 감지가 구성된 일반적인 Active Directory(추가 역할 매핑용). -->
        <my_ad_server>
            <host>localhost</host>
            <port>389</port>
            <bind_dn>EXAMPLE\{user_name}</bind_dn>
            <user_dn_detection>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
            </user_dn_detection>
            <enable_tls>no</enable_tls>
        </my_ad_server>
    </ldap_servers>
</clickhouse>
ldap_servers 섹션에서는 서로 다른 이름으로 여러 LDAP 서버를 정의할 수 있습니다. 매개변수
매개변수기본값설명
host—LDAP 서버 호스트명 또는 IP입니다. 이 매개변수는 필수이며 비워 둘 수 없습니다.
port636 / 389LDAP 서버 포트입니다. enable_tls가 yes로 설정된 경우 기본값은 636이고, 그렇지 않으면 389입니다.
bind_dn—bind할 DN을 구성하는 데 사용하는 템플릿입니다. 생성되는 DN은 각 인증 시도 시 템플릿의 모든 {user_name} 부분 문자열을 실제 사용자 이름으로 바꾸어 구성됩니다.
auth_dn_prefix—사용 중단됨. bind_dn의 대안입니다. bind_dn과 함께 사용할 수 없습니다. 지정하면 bind DN은 auth_dn_prefix + {user_name} + auth_dn_suffix로 구성됩니다. 예를 들어 auth_dn_prefix를 uid=로, auth_dn_suffix를 ,ou=users,dc=example,dc=com으로 설정하는 것은 bind_dn을 uid={user_name},ou=users,dc=example,dc=com으로 설정하는 것과 같습니다.
auth_dn_suffix—사용 중단됨. auth_dn_prefix를 참조하십시오.
verification_cooldown0bind가 성공한 후의 기간(초 단위)으로, 이 기간 동안에는 LDAP 서버에 문의하지 않아도 이후의 모든 요청에 대해 사용자가 인증된 것으로 간주됩니다. 캐싱을 비활성화하고 각 인증 요청마다 LDAP 서버에 강제로 문의하려면 0을 지정하십시오.
follow_referralsfalseLDAP 클라이언트 라이브러리가 서버가 반환한 LDAP referral을 자동으로 추적하도록 허용하는 플래그입니다. 주로 Microsoft Active Directory 환경에서 상위 base DN(예: DC=example,DC=com)에 대해 서브트리 검색을 수행할 때 referral/search reference(예: DC=DomainDnsZones,...)가 반환될 수 있는 경우에 해당합니다. 파티션 간 검색이 명시적으로 필요한 경우에만 true로 설정하십시오.
enable_tlsyesLDAP 서버에 대한 보안 연결 사용을 활성화하는 플래그입니다. 일반 텍스트 ldap:// 프로토콜에는 no(권장하지 않음), SSL/TLS를 통한 LDAP ldaps:// 프로토콜에는 yes(권장), 레거시 StartTLS 프로토콜에는 starttls를 지정하십시오(일반 텍스트 ldap:// 프로토콜로 시작한 뒤 TLS로 업그레이드됨).
tls_minimum_protocol_versiontls1.2SSL/TLS의 최소 프로토콜 버전입니다. 허용되는 값: ssl2, ssl3, tls1.0, tls1.1, tls1.2.
tls_require_certdemandSSL/TLS 피어 인증서 검증 동작입니다. 허용되는 값: never, allow, try, demand.
tls_cert_file—인증서 파일 경로입니다.
tls_key_file—인증서 키 파일 경로입니다.
tls_ca_cert_file—CA 인증서 파일 경로입니다.
tls_ca_cert_dir—CA 인증서가 들어 있는 디렉터리 경로입니다.
tls_cipher_suite—허용되는 암호군(ciper suite)입니다(OpenSSL 표기법).
search_limit256이 서버 정의에서 수행하는 LDAP search 쿼리(사용자 DN 감지 및 역할 매핑용)가 반환할 수 있는 최대 엔트리 수입니다.
user_dn_detection 하위 매개변수 bind된 사용자의 실제 user DN을 감지하기 위한 LDAP search 매개변수 섹션입니다. 이는 주로 서버가 Active Directory인 경우, 추가 역할 매핑을 위한 검색 필터에서 사용됩니다. 검색 결과로 얻은 user DN은 허용되는 모든 위치에서 {user_dn} 부분 문자열을 대체할 때 사용됩니다. 기본적으로 user DN은 bind DN과 동일하게 설정되지만, 검색이 수행되면 실제로 감지된 user DN 값으로 갱신됩니다.
매개변수기본값설명
base_dn—LDAP search의 base DN을 구성하는 데 사용하는 템플릿입니다. 생성되는 DN은 LDAP search 중 템플릿의 모든 {user_name} 및 {bind_dn} 부분 문자열을 실제 사용자 이름과 bind DN으로 바꾸어 구성됩니다.
scopesubtreeLDAP search의 범위입니다. 허용되는 값: base, one_level, children, subtree.
search_filter—LDAP search의 검색 필터를 구성하는 데 사용하는 템플릿입니다. 생성되는 필터는 LDAP search 중 템플릿의 모든 {user_name}, {bind_dn}, {base_dn} 부분 문자열을 실제 사용자 이름, bind DN, base DN으로 바꾸어 구성됩니다. XML에서는 특수 문자를 올바르게 이스케이프해야 합니다.

​
LDAP 외부 인증

원격 LDAP 서버는 로컬에 정의된 사용자(users.xml 또는 로컬 액세스 제어 경로(local access control paths)에 정의된 사용자)의 비밀번호를 확인하는 방법으로 사용할 수 있습니다. 이를 위해 사용자 정의에서 password 또는 유사한 섹션 대신, 미리 정의된 LDAP 서버 이름을 지정하십시오. 로그인을 시도할 때마다 ClickHouse는 제공된 자격 증명을 사용해 LDAP 서버 정의의 bind_dn 매개변수에 지정된 DN으로 “bind”를 시도하며, 성공하면 해당 사용자는 인증된 것으로 간주됩니다. 이를 흔히 “simple bind” 방식이라고 합니다. 예시 
<clickhouse>
    <!- ... -->
    <users>
        <!- ... -->
        <my_user>
            <!- ... -->
            <ldap>
                <server>my_ldap_server</server>
            </ldap>
        </my_user>
    </users>
</clickhouse>
참고로 사용자 my_user는 my_ldap_server를 참조합니다. 이 LDAP 서버는 앞서 설명한 대로 기본 config.xml 파일에 구성되어 있어야 합니다. SQL 기반 액세스 제어 및 계정 관리가 활성화된 경우, LDAP 서버로 인증되는 사용자도 CREATE USER SQL 문을 사용해 생성할 수 있습니다.
Query
CREATE USER my_user IDENTIFIED WITH ldap SERVER 'my_ldap_server';

​
LDAP 외부 사용자 디렉터리

로컬에 정의된 사용자 외에도 원격 LDAP 서버를 사용자 정의 정보의 소스로 사용할 수 있습니다. 이를 위해 config.xml 파일의 users_directories 섹션 내 ldap 섹션에 미리 정의된 LDAP 서버 이름(LDAP 서버 정의 참조)을 지정하십시오. 로그인을 시도할 때마다 ClickHouse는 먼저 로컬에서 사용자 정의 정보를 찾고 평소와 같이 인증을 시도합니다. 사용자가 정의되어 있지 않으면 ClickHouse는 해당 정의 정보가 외부 LDAP 디렉터리에 있다고 가정하고, 제공된 자격 증명을 사용해 LDAP 서버의 지정된 DN에 “bind”를 시도합니다. 이 작업이 성공하면 해당 사용자는 존재하며 인증된 것으로 간주됩니다. 사용자에게는 roles 섹션에 지정된 역할 목록이 할당됩니다. 또한 role_mapping 섹션도 구성되어 있으면 LDAP “search”를 수행할 수 있으며, 그 결과를 변환해 역할 이름으로 취급한 뒤 사용자에게 할당할 수 있습니다. 이는 SQL 기반 액세스 제어 및 계정 관리가 활성화되어 있고, CREATE ROLE SQL 문을 사용해 역할이 생성되어 있음을 의미합니다. 예시 다음 내용은 config.xml에 추가합니다. 
<clickhouse>
    <!- ... -->
    <user_directories>
        <!- 일반적인 LDAP 서버. -->
        <ldap>
            <server>my_ldap_server</server>
            <roles>
                <my_local_role1 />
                <my_local_role2 />
            </roles>
            <role_mapping>
                <base_dn>ou=groups,dc=example,dc=com</base_dn>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=groupOfNames)(member={bind_dn}))</search_filter>
                <attribute>cn</attribute>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>

        <!- 감지된 사용자 DN을 기반으로 역할 매핑을 사용하는 일반적인 Active Directory. -->
        <ldap>
            <server>my_ad_server</server>
            <role_mapping>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <attribute>CN</attribute>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=group)(member={user_dn}))</search_filter>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>
    </user_directories>
</clickhouse>
user_directories 섹션 내부의 ldap 섹션에서 참조하는 my_ldap_server는 config.xml에 구성된, 미리 정의된 LDAP 서버여야 합니다(LDAP 서버 정의 참조). 매개변수
매개변수기본값설명
server—위의 ldap_servers 구성 섹션에 정의된 LDAP 서버 이름 중 하나입니다. 이 매개변수는 필수이며 비워 둘 수 없습니다.
roles—LDAP 서버에서 가져온 각 사용자에게 할당할, 로컬에 정의된 역할 목록이 있는 섹션입니다. 여기에서 역할을 지정하지 않거나 역할 매핑(아래) 중에 할당하지 않으면 사용자는 인증 후 어떤 작업도 수행할 수 없습니다.
role_mapping 하위 매개변수 LDAP search 매개변수와 매핑 규칙이 있는 섹션입니다. 사용자가 인증하면, 아직 LDAP에 바인딩된 상태에서 search_filter와 로그인한 사용자 이름을 사용해 LDAP search를 수행합니다. 이 검색에서 찾은 각 엔트리에 대해 지정된 속성 값을 추출합니다. 지정된 접두사가 있는 각 속성 값에서는 해당 접두사를 제거하며, 나머지 값은 ClickHouse에 정의된 로컬 역할 이름이 됩니다. 이 역할은 CREATE ROLE 문으로 미리 생성되어 있어야 합니다. 동일한 ldap 섹션 안에 여러 개의 role_mapping 섹션을 정의할 수 있습니다. 이들은 모두 적용됩니다.
매개변수기본값설명
base_dn—LDAP search에 사용할 base DN을 구성하는 템플릿입니다. 각 LDAP search 시 템플릿에 있는 모든 {user_name}, {bind_dn}, {user_dn} 부분 문자열이 실제 사용자 이름, bind DN, user DN으로 치환되어 최종 DN이 구성됩니다.
scopesubtreeLDAP search의 범위입니다. 허용되는 값: base, one_level, children, subtree.
search_filter—LDAP search에 사용할 검색 필터를 구성하는 템플릿입니다. 각 LDAP search 시 템플릿에 있는 모든 {user_name}, {bind_dn}, {user_dn}, {base_dn} 부분 문자열이 실제 사용자 이름, bind DN, user DN, base DN으로 치환되어 최종 filter가 구성됩니다. XML에서는 특수 문자를 올바르게 이스케이프해야 합니다.
attributecnLDAP search에서 반환할 값이 들어 있는 속성 이름입니다.
prefix비어 있음LDAP search가 반환한 원본 문자열 목록에서 각 문자열 앞에 있을 것으로 예상되는 접두사입니다. 이 접두사는 원본 문자열에서 제거되며, 그 결과 문자열은 로컬 역할 이름으로 처리됩니다.
마지막 수정일 2026년 6월 10일