Data Dynamics
Blog
nifildapsecurityauthentication

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

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

Data Dynamics2026年4月13日17 min read
This post is not yet translated. The original Korean version is shown below.

Apache NiFi 는 기본적으로 사용자 인증 없이 동작하지만, 운영 환경에서는 반드시 인증을 활성화해야 합니다. 가장 널리 사용되는 방식 중 하나가 LDAP(Lightweight Directory Access Protocol) 인증 입니다. 이 글에서는 NiFi 의 LDAP 인증 설정 방법을 오픈소스 NiFi 와 Cloudera CFM(Cloudera Flow Management) 두 가지 환경으로 나누어 설명합니다. Cloudera CFM 공식 LDAP 인증 문서 와 Apache NiFi Administration Guide 를 참고하여 작성했습니다.

1. 사전 요구사항

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 로그인 화면 → Login Identity Provider (인증)
                                    ↓
                              LDAP 서버에 바인딩하여 사용자 확인
                                    ↓
                              Authorizer (인가) → 권한 확인
구성 요소설정 파일역할
Login Identity Providerlogin-identity-providers.xml사용자 이름/패스워드를 LDAP 서버에 바인딩하여 인증 수행
Authorizerauthorizers.xml인증된 사용자가 어떤 리소스에 접근할 수 있는지 권한 결정

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

3.1 nifi.properties 설정

먼저 nifi.properties 에서 Login Identity Provider 를 활성화합니다.

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

3.2 login-identity-providers.xml 설정

conf/login-identity-providers.xml 파일에서 LDAP Provider 를 구성합니다. 이 파일이 NiFi LDAP 인증의 핵심 설정입니다.

<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 (인증 전략)

전략설명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 설정

인증(Authentication) 후 인가(Authorization) 를 위해 authorizers.xml 을 설정합니다. 여기서 Initial Admin Identity 는 LDAP 로 인증된 사용자 중 최초 관리자를 지정합니다.

<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.xml 의 Identity Strategy 에 따라 달라집니다. USE_USERNAME 이면 admin, USE_DN 이면 uid=admin,ou=people,dc=example,dc=com 형태여야 합니다.

3.5 LDAP User Group Provider (선택 사항)

LDAP 서버에서 사용자와 그룹 정보를 자동으로 동기화하려면 LdapUserGroupProvider 를 설정할 수 있습니다.

<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(CM) 를 통해 NiFi 를 관리하는 환경에서는 XML 파일을 직접 편집하는 대신 CM UI 에서 설정합니다.

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.xml 과 authorizations.xml 이 재생성됩니다. 기존 파일은 아카이브됩니다.

5. Active Directory 환경 설정 예시

Active Directory(AD) 를 사용하는 경우 일반 OpenLDAP 과 다른 설정이 필요합니다.

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. 클러스터 환경 주의사항

NiFi 클러스터에서 LDAP 인증을 설정할 때 추가로 고려해야 할 사항입니다.

6.1 모든 노드의 설정 일치

login-identity-providers.xml 과 authorizers.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. 트러블슈팅

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 관련 메시지 확인
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 를 재시작하기 전에 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 로그를 반드시 확인하세요.

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

— Data Dynamics 엔지니어링 팀