Blog
nifildapsecurityauthentication

Apache NiFi LDAP 인증 설정 가이드 (Cloudera CFM 포함)

NiFi 에서 LDAP 인증을 설정하는 방법을 login-identity-providers.xml, authorizers.xml 구성부터 Cloudera Manager 설정까지 단계별로 정리합니다.

Data Dynamics2026년 4월 13일21 min read

회사 건물에 들어가려면 사원증을 찍어야 하죠. NiFi도 마찬가지입니다 — 운영 환경에서는 반드시 누가 들어오는지 확인해야 합니다. 그 확인을 회사 디렉토리 서버(LDAP)에 맡기는 것이 바로 LDAP 인증입니다. 한 번 연결해 두면 LDAP에 등록된 모든 직원이 별도 계정 없이 NiFi에 로그인할 수 있게 됩니다.

이 글에서는 NiFi 의 LDAP 인증 설정 방법을 오픈소스 NiFiCloudera CFM(Cloudera Flow Management) 두 가지 환경으로 나누어 설명합니다. Cloudera CFM 공식 LDAP 인증 문서Apache NiFi Administration Guide 를 참고하여 작성했습니다.

이 글에서 배우는 것

  • LDAP 인증이 NiFi 안에서 어떻게 동작하는지 (인증 vs 인가 구분)
  • login-identity-providers.xmlauthorizers.xml의 핵심 설정 방법
  • Authentication Strategy(SIMPLE/LDAPS/START_TLS)와 Identity Strategy 차이
  • Active Directory 환경에서의 별도 설정 포인트
  • Cloudera Manager(CM) 환경에서 XML 없이 UI로 설정하는 방법

1. 사전 요구사항

LDAP 인증을 시작하기 전에 반드시 확인해야 할 전제 조건들이 있습니다. 특히 HTTPS 활성화는 선택이 아니라 필수 — 이게 빠지면 LDAP 설정 자체가 불가능합니다.

항목설명
TLS/SSL 활성화NiFi 에 LDAP 인증을 적용하려면 반드시 HTTPS 가 활성화되어 있어야 함
LDAP 서버OpenLDAP, Active Directory, 389 Directory Server 등 접근 가능한 LDAP 서버
서비스 계정LDAP 서버에서 사용자 검색을 수행할 Manager DN 과 패스워드
인증서LDAPS 또는 START_TLS 를 사용하는 경우 LDAP 서버의 CA 인증서가 포함된 truststore

주의: NiFi 는 HTTPS 가 활성화되지 않은 상태에서는 인증을 설정할 수 없습니다. LDAP 설정 전에 반드시 TLS/SSL 을 먼저 구성하세요.

2. LDAP 인증의 동작 원리

NiFi 의 LDAP 인증은 "너 맞아?"(인증)"너 뭐할 수 있어?"(인가) 라는 두 단계로 나뉩니다. 이 둘을 별도의 파일로 관리하는 것이 NiFi 설정의 핵심 구조입니다.

Loading diagram…
구성 요소설정 파일역할
Login Identity Providerlogin-identity-providers.xml사용자 이름/패스워드를 LDAP 서버에 바인딩하여 인증 수행
Authorizerauthorizers.xml인증된 사용자가 어떤 리소스에 접근할 수 있는지 권한 결정

3. 오픈소스 NiFi 에서 LDAP 설정

3.1 nifi.properties 설정

설정의 출발점은 nifi.properties 입니다. 딱 한 줄만 추가하면 NiFi 가 LDAP Provider 를 사용하도록 스위치가 켜집니다.

# LDAP Login Identity Provider 활성화
nifi.security.user.login.identity.provider=ldap-provider

3.2 login-identity-providers.xml 설정

이 파일이 LDAP 인증의 심장입니다. LDAP 서버 주소, 관리자 계정, 사용자 검색 방식, TLS 설정이 모두 여기 들어갑니다.

<loginIdentityProviders>
    <provider>
        <identifier>ldap-provider</identifier>
        <class>org.apache.nifi.ldap.LdapProvider</class>
        <property name="Authentication Strategy">START_TLS</property>
 
        <property name="Manager DN">uid=admin,ou=people,dc=example,dc=com</property>
        <property name="Manager Password">admin-password</property>
 
        <property name="Referral Strategy">FOLLOW</property>
        <property name="Connect Timeout">10 secs</property>
        <property name="Read Timeout">10 secs</property>
 
        <property name="Url">ldap://ldap.example.com:389</property>
        <property name="User Search Base">ou=people,dc=example,dc=com</property>
        <property name="User Search Filter">uid={0}</property>
 
        <property name="Identity Strategy">USE_USERNAME</property>
        <property name="Authentication Expiration">12 hours</property>
 
        <!-- TLS 설정 (START_TLS 또는 LDAPS 사용 시 필수) -->
        <property name="TLS - Keystore">/opt/nifi/conf/keystore.jks</property>
        <property name="TLS - Keystore Password">keystore-password</property>
        <property name="TLS - Keystore Type">JKS</property>
        <property name="TLS - Truststore">/opt/nifi/conf/truststore.jks</property>
        <property name="TLS - Truststore Password">truststore-password</property>
        <property name="TLS - Truststore Type">JKS</property>
        <property name="TLS - Client Auth">NONE</property>
        <property name="TLS - Protocol">TLSv1.2</property>
        <property name="TLS - Shutdown Gracefully">false</property>
    </provider>
</loginIdentityProviders>

3.3 주요 속성 상세 설명

각 속성이 무엇을 의미하는지 알아야 실수 없이 설정할 수 있습니다. 특히 Authentication Strategy 와 Identity Strategy 의 조합이 자주 혼란을 일으키므로 꼼꼼히 읽어 두세요.

Authentication Strategy (인증 전략)

전략설명LDAP URL 예시
ANONYMOUS인증 없이 LDAP 에 접속. 테스트 환경에서만 사용ldap://ldap.example.com:389
SIMPLEManager DN/Password 로 평문 바인딩. 반드시 LDAPS 와 함께 사용 권장ldap://ldap.example.com:389
LDAPSSSL 로 암호화된 연결 (포트 636). 처음부터 SSL 연결ldaps://ldap.example.com:636
START_TLS평문 연결 후 TLS 로 업그레이드 (포트 389)ldap://ldap.example.com:389

운영 환경 권장: LDAPS 또는 START_TLS 를 사용하세요. SIMPLE 은 네트워크 상에서 패스워드가 평문으로 전송되므로 위험합니다.

Identity Strategy (사용자 식별 전략)

전략설명예시
USE_DNLDAP 에서 검색된 사용자의 전체 DN 을 NiFi 사용자 ID 로 사용uid=john,ou=people,dc=example,dc=com
USE_USERNAME사용자가 로그인 시 입력한 사용자 이름을 그대로 NiFi 사용자 ID 로 사용john

권장: USE_USERNAME 을 사용하면 NiFi UI 에서 사용자 이름이 간결하게 표시되고, authorizers.xml 에서 Initial Admin Identity 등을 설정할 때도 간단한 사용자 이름을 사용할 수 있습니다.

Referral Strategy (참조 전략)

전략설명
FOLLOWLDAP referral 을 자동으로 따라감 (Active Directory 환경에서 권장)
IGNORELDAP referral 을 무시함
THROWLDAP referral 발생 시 예외를 던짐

User Search Filter (사용자 검색 필터)

{0} 은 사용자가 입력한 로그인 ID 로 대체됩니다.

LDAP 서버일반적인 필터설명
OpenLDAPuid={0}uid 속성으로 검색
Active DirectorysAMAccountName={0}SAM 계정 이름으로 검색
Active Directory (UPN)userPrincipalName={0}UPN 으로 검색

3.4 authorizers.xml 설정

LDAP 로 인증이 성공하더라도, NiFi 는 그 사용자가 뭘 할 수 있는지를 authorizers.xml 에서 따로 확인합니다. Initial Admin Identity 가 틀리면 로그인은 돼도 아무것도 볼 수 없는 상황이 됩니다.

<authorizers>
    <userGroupProvider>
        <identifier>file-user-group-provider</identifier>
        <class>org.apache.nifi.authorization.FileUserGroupProvider</class>
        <property name="Users File">./conf/users.xml</property>
        <property name="Initial User Identity 1">admin</property>
    </userGroupProvider>
 
    <accessPolicyProvider>
        <identifier>file-access-policy-provider</identifier>
        <class>org.apache.nifi.authorization.FileAccessPolicyProvider</class>
        <property name="User Group Provider">file-user-group-provider</property>
        <property name="Authorizations File">./conf/authorizations.xml</property>
        <property name="Initial Admin Identity">admin</property>
        <property name="Node Identity 1">CN=nifi-node1.example.com, OU=NiFi</property>
    </accessPolicyProvider>
 
    <authorizer>
        <identifier>managed-authorizer</identifier>
        <class>org.apache.nifi.authorization.StandardManagedAuthorizer</class>
        <property name="Access Policy Provider">file-access-policy-provider</property>
    </authorizer>
</authorizers>

중요: Initial Admin Identity 의 값은 login-identity-providers.xmlIdentity Strategy 에 따라 달라집니다. USE_USERNAME 이면 admin, USE_DN 이면 uid=admin,ou=people,dc=example,dc=com 형태여야 합니다.

3.5 LDAP User Group Provider (선택 사항)

사용자 수가 많은 조직이라면 매번 수동으로 권한을 부여하는 것은 비효율적입니다. LdapUserGroupProvider 를 사용하면 LDAP 의 사용자와 그룹을 주기적으로 자동 동기화할 수 있습니다.

<userGroupProvider>
    <identifier>ldap-user-group-provider</identifier>
    <class>org.apache.nifi.ldap.tenants.LdapUserGroupProvider</class>
    <property name="Authentication Strategy">START_TLS</property>
 
    <property name="Manager DN">uid=admin,ou=people,dc=example,dc=com</property>
    <property name="Manager Password">admin-password</property>
 
    <property name="Url">ldap://ldap.example.com:389</property>
 
    <property name="User Search Base">ou=people,dc=example,dc=com</property>
    <property name="User Object Class">person</property>
    <property name="User Search Scope">ONE_LEVEL</property>
    <property name="User Search Filter">(objectClass=person)</property>
    <property name="User Identity Attribute">uid</property>
 
    <property name="Group Search Base">ou=groups,dc=example,dc=com</property>
    <property name="Group Object Class">groupOfNames</property>
    <property name="Group Search Scope">ONE_LEVEL</property>
    <property name="Group Search Filter">(objectClass=groupOfNames)</property>
    <property name="Group Name Attribute">cn</property>
    <property name="Group Member Attribute">member</property>
    <property name="Group Member Attribute - Referenced Member Identity">dn</property>
 
    <property name="Sync Interval">30 mins</property>
    <property name="Page Size">500</property>
    <property name="Group Membership - Enforce Case Sensitivity">false</property>
 
    <!-- TLS 설정 (START_TLS 또는 LDAPS 사용 시) -->
    <property name="TLS - Keystore">/opt/nifi/conf/keystore.jks</property>
    <property name="TLS - Keystore Password">keystore-password</property>
    <property name="TLS - Keystore Type">JKS</property>
    <property name="TLS - Truststore">/opt/nifi/conf/truststore.jks</property>
    <property name="TLS - Truststore Password">truststore-password</property>
    <property name="TLS - Truststore Type">JKS</property>
    <property name="TLS - Client Auth">NONE</property>
    <property name="TLS - Protocol">TLSv1.2</property>
</userGroupProvider>

LdapUserGroupProvider 의 주요 속성:

속성설명
User Search Base사용자를 검색할 LDAP 베이스 DN
User Object Class사용자 객체 클래스 (예: person, inetOrgPerson)
User Identity AttributeNiFi 에서 사용자 ID 로 사용할 LDAP 속성 (예: uid, sAMAccountName)
Group Search Base그룹을 검색할 LDAP 베이스 DN
Group Object Class그룹 객체 클래스 (예: groupOfNames, group)
Group Name Attribute그룹 이름으로 사용할 LDAP 속성 (예: cn)
Group Member Attribute그룹 멤버 관계를 나타내는 속성 (예: member, memberUid)
Sync IntervalLDAP 에서 사용자/그룹 정보를 동기화하는 주기 (예: 30 mins)
Page SizeLDAP 검색 시 페이지 크기 (대규모 디렉토리에서 필수)

4. Cloudera CFM 환경에서 LDAP 설정

Cloudera Manager 환경이라면 XML 파일을 직접 편집할 필요가 없습니다. CM UI 의 Configuration 탭에서 속성값을 입력하면 자동으로 배포됩니다. 훨씬 편리하지만 속성명을 잘 찾아야 합니다.

4.1 NiFi LDAP 설정 (Cloudera Manager)

CM 에서 NiFi 서비스의 Configuration 탭으로 이동하여 다음 속성을 설정합니다.

CM 속성명설정값 예시설명
Enable TLS/SSL for NiFi Node체크HTTPS 활성화 (필수 전제조건)
LDAP Enabled체크LDAP 인증 활성화
Login Identity Provider: Default LDAP Provider Classorg.apache.nifi.ldap.LdapProviderLDAP Provider 클래스
Login Identity Provider IDldap-providerProvider 식별자
Initial Admin Identityadmin초기 관리자 사용자
LDAP Authentication StrategySTART_TLS인증 전략
LDAP Manager DNuid=admin,ou=people,dc=example,dc=comLDAP 서비스 계정 DN
LDAP Manager Password(패스워드)서비스 계정 패스워드
LDAP URLldap://ldap.example.com:389LDAP 서버 URL
LDAP User Search Baseou=people,dc=example,dc=com사용자 검색 베이스 DN
Login Identity Provider: Default LDAP User Search Filteruid={0}사용자 검색 필터
Login Identity Provider: Default LDAP Identity StrategyUSE_USERNAME사용자 식별 전략

TLS 관련 속성 (LDAPS 또는 START_TLS 사용 시)

CM 속성명설정값 예시
Login Identity Provider: Default LDAP TLS - Keystore/opt/nifi/conf/keystore.jks
Login Identity Provider: Default LDAP TLS - Keystore Password(패스워드)
Login Identity Provider: Default LDAP TLS - Keystore TypeJKS
Login Identity Provider: Default LDAP TLS - Truststore/opt/nifi/conf/truststore.jks
Login Identity Provider: Default LDAP TLS - Truststore Password(패스워드)
Login Identity Provider: Default LDAP TLS - Truststore TypeJKS
TLS - Client AuthNONE
TLS - ProtocolTLSv1.2
TLS - Shutdown Gracefullyfalse

4.2 NiFi Registry LDAP 설정 (Cloudera Manager)

NiFi Registry 도 별도로 LDAP 을 설정해야 합니다. 속성은 NiFi 와 거의 동일하지만 클래스 이름이 다릅니다.

CM 속성명설정값
Identity Provider: Default LDAP Provider Classorg.apache.nifi.registry.security.ldap.LdapIdentityProvider
Identity Provider Identifierldap-provider

나머지 LDAP URL, Manager DN, Search Base, TLS 설정 등은 NiFi 와 동일하게 구성합니다.

4.3 Initial Admin Identity 재설정

CM 에서 Initial Admin Identity 를 잘못 설정한 경우, 서비스의 Actions > Reset File-based Authorizer Users and Policies 를 실행하면 users.xmlauthorizations.xml 이 재생성됩니다. 기존 파일은 아카이브됩니다.

5. Active Directory 환경 설정 예시

많은 기업이 Microsoft Active Directory 를 사용합니다. AD는 OpenLDAP 과 사용자 검색 필터, DN 형식, Referral 처리 방식 등이 다르므로 별도 설정이 필요합니다.

5.1 login-identity-providers.xml (Active Directory)

<provider>
    <identifier>ldap-provider</identifier>
    <class>org.apache.nifi.ldap.LdapProvider</class>
    <property name="Authentication Strategy">LDAPS</property>
 
    <property name="Manager DN">CN=svc-nifi,OU=ServiceAccounts,DC=corp,DC=example,DC=com</property>
    <property name="Manager Password">service-account-password</property>
 
    <property name="Referral Strategy">FOLLOW</property>
    <property name="Connect Timeout">10 secs</property>
    <property name="Read Timeout">10 secs</property>
 
    <property name="Url">ldaps://ad.corp.example.com:636</property>
    <property name="User Search Base">OU=Users,DC=corp,DC=example,DC=com</property>
    <property name="User Search Filter">sAMAccountName={0}</property>
 
    <property name="Identity Strategy">USE_USERNAME</property>
    <property name="Authentication Expiration">12 hours</property>
 
    <property name="TLS - Keystore">/opt/nifi/conf/keystore.jks</property>
    <property name="TLS - Keystore Password">keystore-password</property>
    <property name="TLS - Keystore Type">JKS</property>
    <property name="TLS - Truststore">/opt/nifi/conf/truststore.jks</property>
    <property name="TLS - Truststore Password">truststore-password</property>
    <property name="TLS - Truststore Type">JKS</property>
    <property name="TLS - Client Auth">NONE</property>
    <property name="TLS - Protocol">TLSv1.2</property>
    <property name="TLS - Shutdown Gracefully">false</property>
</provider>

Active Directory 와 OpenLDAP 의 주요 차이점:

항목OpenLDAPActive Directory
사용자 검색 필터uid={0}sAMAccountName={0}
Manager DN 형식uid=admin,ou=people,dc=...CN=svc-nifi,OU=ServiceAccounts,DC=...
기본 포트 (SSL)636636
기본 포트 (평문)389389
Referral StrategyIGNORE 가능FOLLOW 권장 (도메인 간 참조)
그룹 Object ClassgroupOfNamesgroup
멤버 속성membermember

6. 클러스터 환경 주의사항

단일 노드에서는 잘 되던 LDAP 설정이 클러스터에서 문제가 생기는 경우가 있습니다. 아래 세 가지 포인트를 반드시 확인하세요.

6.1 모든 노드의 설정 일치

login-identity-providers.xmlauthorizers.xml클러스터의 모든 노드에서 반드시 동일해야 합니다. 노드마다 다르면 어떤 노드로 요청이 라우팅되느냐에 따라 인증 결과가 달라지는 기이한 현상이 발생합니다.

6.2 Node Identity 설정

클러스터의 각 노드는 authorizers.xml 에 Node Identity 로 등록되어야 합니다.

<property name="Node Identity 1">CN=nifi-node1.example.com, OU=NiFi</property>
<property name="Node Identity 2">CN=nifi-node2.example.com, OU=NiFi</property>
<property name="Node Identity 3">CN=nifi-node3.example.com, OU=NiFi</property>

6.3 LDAP 서버 가용성

LDAP 서버가 다운되는 순간 NiFi 에 로그인하는 모든 사용자가 접근 불가 상태가 됩니다. 운영 환경에서는 LDAP 서버를 이중화하고, Url 속성에 공백으로 구분하여 여러 LDAP URL 을 지정해 두세요.

<property name="Url">ldaps://ldap1.example.com:636 ldaps://ldap2.example.com:636</property>

7. 트러블슈팅

LDAP 설정은 세팅 자체보다 "왜 안 되는지" 찾는 데 시간이 더 걸릴 수 있습니다. 증상별로 원인과 해결 방법을 정리했습니다.

7.1 로그인 실패 시 확인 사항

증상원인해결
로그인 페이지가 표시되지 않음HTTPS 가 활성화되지 않음nifi.properties 에서 HTTPS 활성화
"Login credentials were not verified"LDAP 서버 연결 실패LDAP URL, Manager DN/Password 확인
로그인 성공 후 권한 없음Initial Admin Identity 불일치Identity Strategy 에 맞는 값으로 수정
"Connect timeout" 에러LDAP 서버 네트워크 문제방화벽, 포트(389/636) 확인
"PKIX path building failed"TLS 인증서 신뢰 문제LDAP 서버의 CA 인증서를 truststore 에 추가
"Referral" 관련 에러AD 환경에서 referral 미처리Referral Strategy 를 FOLLOW 로 변경

7.2 로그 확인

설정을 바꾼 뒤에는 항상 로그를 확인하세요. NiFi 로그에 LDAP 연결 오류가 상세하게 기록됩니다.

# NiFi 로그에서 LDAP 관련 메시지 확인
grep -i "ldap\|login\|identity\|auth" /opt/nifi/logs/nifi-app.log | tail -50
 
# 인증서 관련 에러 확인
grep -i "ssl\|tls\|certificate\|pkix" /opt/nifi/logs/nifi-app.log | tail -30

7.3 LDAP 연결 테스트

NiFi 를 재시작하기 전에 ldapsearch 로 먼저 연결을 검증하세요. NiFi 를 올렸다 내리는 과정 없이 빠르게 LDAP 접속 여부를 확인할 수 있습니다.

# ldapsearch 로 연결 테스트 (OpenLDAP)
ldapsearch -x -H ldap://ldap.example.com:389 \
    -D "uid=admin,ou=people,dc=example,dc=com" \
    -w admin-password \
    -b "ou=people,dc=example,dc=com" \
    "uid=testuser"
 
# ldapsearch 로 연결 테스트 (Active Directory, LDAPS)
ldapsearch -x -H ldaps://ad.corp.example.com:636 \
    -D "CN=svc-nifi,OU=ServiceAccounts,DC=corp,DC=example,DC=com" \
    -w service-account-password \
    -b "OU=Users,DC=corp,DC=example,DC=com" \
    "sAMAccountName=testuser"

8. 설정 체크리스트

단계확인 항목
1NiFi 에 HTTPS(TLS/SSL) 가 활성화되어 있는가?
2LDAP 서버에 네트워크 접근이 가능한가? (포트 389 또는 636)
3Manager DN 으로 LDAP 서버에 바인딩이 가능한가? (ldapsearch 로 테스트)
4User Search Filter 로 사용자를 찾을 수 있는가?
5login-identity-providers.xml 에 LdapProvider 가 올바르게 구성되었는가?
6nifi.properties 에서 nifi.security.user.login.identity.provider=ldap-provider 가 설정되었는가?
7authorizers.xml 의 Initial Admin Identity 가 Identity Strategy 와 일치하는가?
8LDAPS/START_TLS 사용 시 truststore 에 LDAP 서버의 CA 인증서가 포함되어 있는가?
9클러스터 환경이라면 모든 노드의 설정 파일이 동일한가?
10NiFi 를 재시작한 후 로그에 LDAP 관련 에러가 없는가?

9. 정리

항목내용
필수 전제조건HTTPS 활성화
핵심 설정 파일login-identity-providers.xml, authorizers.xml, nifi.properties
권장 Authentication StrategyLDAPS 또는 START_TLS
권장 Identity StrategyUSE_USERNAME (간결한 사용자 ID)
AD 환경 User Search FiltersAMAccountName={0}
OpenLDAP 환경 User Search Filteruid={0}
LDAP 서버 이중화Url 속성에 공백으로 구분된 여러 URL 지정 가능
클러스터 환경모든 노드에서 설정 파일 동일해야 함
CM 환경 (Cloudera)CM UI 에서 설정, XML 직접 편집 불필요
Initial Admin Identity 재설정CM > Actions > Reset File-based Authorizer

LDAP 인증은 NiFi 보안의 가장 기본적인 단계입니다. 설정 자체는 복잡하지 않지만, Identity Strategy 와 Initial Admin Identity 의 불일치, TLS 인증서 문제 등에서 자주 오류가 발생합니다. 설정 전에 ldapsearch 로 LDAP 연결을 먼저 확인하고, 설정 후에는 NiFi 로그를 반드시 확인하세요.

마치며 — 핵심 요약

  • LDAP 인증은 HTTPS 활성화 후에만 설정할 수 있습니다. TLS 가 없으면 시작조차 안 됩니다.
  • login-identity-providers.xml은 인증, authorizers.xml은 인가를 담당합니다. 두 파일의 역할을 구분하면 오류 원인을 빠르게 찾을 수 있습니다.
  • USE_USERNAME Identity Strategy 를 권장합니다. 사용자 ID 가 간결하고, authorizers.xml 설정도 단순해집니다.
  • 운영 환경에서는 반드시 LDAPS 또는 START_TLS 를 사용하세요. SIMPLE 은 패스워드가 평문으로 흐릅니다.
  • 클러스터 환경에서는 모든 노드의 설정 파일이 동일해야 합니다. 한 노드만 달라도 인증 동작이 불안정해집니다.
  • LDAP 서버가 다운되면 NiFi 로그인 자체가 불가능하므로 LDAP 서버를 이중화하는 것이 좋습니다.

설정이 막힐 때는 ldapsearch → NiFi 로그 → Initial Admin Identity 순서로 확인해 보세요. 대부분의 문제는 이 세 단계에서 해결됩니다.


NiFi LDAP 인증 설정에 대해 도움이 필요하시면 언제든 문의해 주세요.

— Data Dynamics 엔지니어링 팀