Data Dynamics
Blog
nifildapsecurityauthentication

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

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

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

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

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

이 글에서 배우는 것

  • LDAP 인증이 NiFi 안에서 어떻게 동작하는지 (인증 vs 인가 구분)
  • login-identity-providers.xml과 authorizers.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.xml 의 Identity 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.xml 과 authorizations.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.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. 트러블슈팅

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 엔지니어링 팀