NiFi 를 HTTP + 인증 없이 띄우기 — 로컬 개발 · PoC 가이드

Apache NiFi 1.14 부터는 기본 설치가 HTTPS + Single User 인증 으로 올라오기 때문에, 처음 설치한 개발자가 UI 에 들어가려고 하면 self-signed 인증서 경고 → 자동 생성된 username/password 확인 → 로그인 이라는 3단계를 거쳐야 합니다. 실제 데이터 흐름을 설계하기도 전에 인증부터 잡혀 있으니, 로컬 개발·PoC·내부 샌드박스 에서는 이걸 걷어내는 편이 훨씬 빠릅니다. 이 글은 nifi.properties 를 수정해 NiFi 를 HTTP + 익명 으로 띄우는 가장 짧은 경로를 정리합니다.

경고: 이 설정은 로컬 개발과 격리된 샌드박스 전용 입니다. HTTP + 익명 NiFi 는 UI 에 접근 가능한 누구나 플로우 변경·시크릿 노출·프로세서 실행이 가능하다는 뜻입니다. 사무실 네트워크·클라우드 VM·멀티테넌트 환경·운영 서버에는 절대 이렇게 올리지 마세요. 운영 환경 설정은 공식 문서의 TLS + 사용자 인증 가이드를 따라야 합니다.

1. 언제 이 설정이 필요한가

2. 전제

• Apache NiFi 1.x (1.14 ~ 1.28). NiFi 2.x 는 일부 속성명이 바뀌었으므로 뒤에서 별도 언급합니다.
• JDK 11 또는 17 (NiFi 버전에 따라)
• 8080 포트가 비어 있음
• NiFi 를 바이너리 배포본으로 설치했거나, 공식 Docker 이미지를 사용할 수 있음

3. nifi.properties 수정

NiFi 설치 디렉터리의 conf/nifi.properties 를 엽니다. 수정해야 할 블록이 두 군데 있습니다.

3.1 웹 서버 포트 설정

기본값은 HTTPS 가 켜져 있고 HTTP 는 비어 있습니다. 이걸 반대로 바꿔줍니다.

# 수정 전 (기본값)
nifi.web.http.host=
nifi.web.http.port=
nifi.web.https.host=127.0.0.1
nifi.web.https.port=8443
 
# 수정 후
nifi.web.http.host=0.0.0.0
nifi.web.http.port=8080
nifi.web.https.host=
nifi.web.https.port=

포인트:

• nifi.web.http.host=0.0.0.0 은 "모든 네트워크 인터페이스에서 수신" 의 의미입니다. 로컬 PC 에서만 접근할 거면 127.0.0.1 로 두는 편이 안전합니다. VM 에서 호스트로 접근해야 하면 0.0.0.0 이 편합니다.
• nifi.web.https.host 와 nifi.web.https.port 는 반드시 비워야 합니다. 둘 다 값이 남아있으면 NiFi 는 HTTPS 모드로 기동됩니다.

3.2 보안/인증 설정 제거

HTTP 모드에서는 keystore·truststore·사용자 인증 설정이 모두 불필요합니다. 아래 키들을 전부 빈 값 으로 지웁니다.

# 수정 후 — 전부 빈 값
nifi.security.keystore=
nifi.security.keystoreType=
nifi.security.keystorePasswd=
nifi.security.keyPasswd=
nifi.security.truststore=
nifi.security.truststoreType=
nifi.security.truststorePasswd=
 
# 사용자 인증도 끔
nifi.security.user.login.identity.provider=
nifi.security.user.authorizer=
 
# 클러스터 보안 옵션도 꺼둠
nifi.cluster.protocol.is.secure=false
 
# Site-to-Site (다른 NiFi 인스턴스가 원격으로 데이터를 푸시해 들어오는 경로) 의
# TLS 도 해제. HTTP 모드에서는 반드시 false 여야 기동이 올라갑니다.
nifi.remote.input.secure=false

nifi.security.user.login.identity.provider 와 nifi.security.user.authorizer 두 키를 반드시 빈 값 으로 만들어야 합니다. 기본값인 single-user-provider / single-user-authorizer 가 남아 있으면 HTTP 모드에서도 로그인 화면이 먼저 뜨면서 "이 provider 는 HTTPS 전용" 이라는 에러로 막힙니다.

그리고 nifi.remote.input.secure 는 놓치기 쉬운 키입니다. 이 값의 기본값은 true 인데, 전체 웹 UI 를 HTTP 로 내려도 이 키가 true 로 남아있으면 Site-to-Site 연결 경로는 여전히 TLS 를 요구하고, 로그에 "Remote input requires TLS ..." 경고와 함께 S2S 기능이 시작되지 않습니다. 이 글처럼 전체를 평문으로 돌릴 때는 반드시 false 로 맞춰주세요.

3.3 리버스 프록시 뒤에서 돌릴 때만

NiFi 를 nginx 등의 리버스 프록시 뒤에 두는 경우에만 아래 한 줄이 더 필요합니다. 직접 노출하는 경우는 건너뛰세요.

nifi.web.proxy.host=myhost.internal:8080

이 값이 실제 요청의 Host: 헤더와 일치하지 않으면 NiFi 가 System Error — the request contained an invalid host header 로 거부합니다.

4. 실행

4.1 바이너리 설치본

cd /opt/nifi-1.28.0
./bin/nifi.sh start
 
# 기동 상태 확인
./bin/nifi.sh status
 
# 로그에서 "JettyServer ... Started Server" 가 뜰 때까지 대기
tail -f logs/nifi-app.log | grep -E "Started Server|ERROR"

기동까지 30초 ~ 1분 정도 걸립니다. 아래 메시지가 보이면 준비 완료입니다.

INFO  org.apache.nifi.web.server.JettyServer ... Started Server @45123ms

브라우저에서 http://localhost:8080/nifi 로 접속하면 로그인 화면 없이 바로 캔버스 가 나타납니다.

4.2 Docker 로 더 빠르게

바이너리를 내려받고 설정 편집까지 하지 않고 빠르게 띄우고 싶다면 공식 이미지에 환경변수를 주는 방식이 편합니다.

docker run --rm -d --name nifi \
  -p 8080:8080 \
  -e NIFI_WEB_HTTP_PORT=8080 \
  -e NIFI_WEB_HTTP_HOST=0.0.0.0 \
  apache/nifi:1.28.0

이미지의 엔트리포인트 스크립트가 NIFI_WEB_HTTP_PORT 가 지정되면 자동으로 HTTPS 를 끄고 HTTP 모드로 nifi.properties 를 재작성해 줍니다. 기동 로그는 다음과 같이 확인합니다.

docker logs -f nifi | grep -E "Started Server|ERROR"

http://localhost:8080/nifi 로 접속 → 로그인 없음 → 바로 캔버스.

5. 흔한 문제 해결

System Error — the request contained an invalid host header

원인: NiFi 는 Host: 헤더 값을 화이트리스트와 비교합니다. 브라우저가 보내는 호스트가 기본 화이트리스트(localhost, 바인드 IP) 에 없으면 거부됩니다.

• http://localhost:8080 으로 접속하는지 확인. http://<VM_IP>:8080 으로 접속하려면 nifi.web.proxy.host=<VM_IP>:8080 을 추가.
• 여러 호스트에서 접속해야 하면 쉼표로 구분: nifi.web.proxy.host=localhost:8080,10.0.0.5:8080,dev.example.com:8080

HTTPS is required for this login identity provider

원인: 3.2 단계에서 nifi.security.user.login.identity.provider / nifi.security.user.authorizer 를 비우지 않았습니다. single-user-provider 가 남아 HTTPS 를 강제합니다.

• 두 속성을 모두 빈 값으로 저장했는지 다시 확인
• 저장 후 NiFi 재기동 (./bin/nifi.sh restart)

Address already in use (port 8080)

원인: 다른 프로세스가 8080 을 점유 중.

• lsof -iTCP:8080 -sTCP:LISTEN 로 확인 후 해당 프로세스 종료
• 아니면 nifi.web.http.port 를 8081 등으로 변경

접속은 되는데 로그인 화면이 뜬다

• nifi.web.https.host 와 nifi.web.https.port 가 정말로 빈 값인지 확인 (공백/탭 없이 = 뒤가 비어있어야 함)
• nifi.properties 를 수정한 뒤 재기동했는지 확인. NiFi 는 런타임 중 파일을 다시 읽지 않습니다.
• 혹시 이전에 한 번 HTTPS 로 기동해 생성된 conf/flow.xml.gz, conf/users.xml, conf/authorizations.xml 이 남아 있으면 삭제 후 재기동 (데이터가 날아가므로 개발 환경에서만)

6. NiFi 2.x 사용자를 위한 주의사항

NiFi 2.x 부터는 다음 차이가 있습니다.

• nifi.web.http.host / nifi.web.http.port 속성 자체는 그대로 유지 되지만, 프로젝트 공식 권장사항은 "운영은 물론 개발도 HTTPS + single-user 로 가라" 는 쪽으로 더 강해졌습니다.
• 일부 컴포넌트가 "보안 컨텍스트 없음" 을 거부하는 경우가 있습니다. 특히 AWS/GCP 커넥터 계열에서 서명 로직이 JKS 를 요구할 수 있습니다.
• single-user-provider 를 남겨둔 채 HTTP 로 돌리면 1.x 보다 더 명확한 에러 메시지로 차단됩니다.

결론: 가능하면 NiFi 2.x 는 single-user HTTPS 로 올리는 것을 권장합니다. 자동 생성되는 계정 정보는 logs/nifi-app.log 에 한 번만 찍히므로 첫 기동 직후 캡처해두면 됩니다.

7. 되돌리기 — HTTPS 로 복귀

개발이 끝난 뒤 이 설정을 운영에 절대 실수로라도 배포하지 않도록, 되돌리는 절차를 문서화해 둡니다.

1. ./bin/nifi.sh stop
2. conf/nifi.properties 를 원본 백업 파일로 복원 (cp conf/nifi.properties.bak conf/nifi.properties)
3. conf/flow.xml.gz, conf/users.xml, conf/authorizations.xml 을 삭제 (HTTPS 모드가 새로 자동 생성합니다)
4. 로그인 계정을 직접 지정 (다음 8장 참고) 하거나, 건너뛰면 ./bin/nifi.sh start 후 logs/nifi-app.log 에서 자동 생성된 username/password 확인
5. https://localhost:8443/nifi 접속

팁: 3.1 단계를 수행하기 전에 반드시 cp conf/nifi.properties conf/nifi.properties.bak 를 해두세요. 기본값으로 돌아가는 가장 빠른 길입니다.

8. 단일 사용자 비밀번호를 미리 지정하기

이 글의 본문은 "HTTP + 익명" 을 전제로 하지만, 같은 로컬 환경에서도 조금이라도 넓게 공유되는 샌드박스(팀 VM, PoC 클러스터 등) 는 HTTPS + 단일 사용자 로그인 이 더 안전한 중간 지점입니다. 문제는 single-user 모드가 첫 기동 시 자동으로 랜덤 username / password 를 생성해 로그에만 찍고 지나간다 는 것입니다. 로그를 놓치면 다시 찾기 번거롭고, 여러 사람이 접속해야 하면 더 난감합니다.

NiFi 1.14 이상은 이 시나리오를 위해 단일 사용자 계정 정보를 명시적으로 지정할 수 있는 CLI 커맨드 를 제공합니다.

8.1 전제: NiFi 를 먼저 정지

./bin/nifi.sh stop

set-single-user-credentials 는 기동 중에는 변경 사항이 반영되지 않습니다. 반드시 멈춘 상태에서 실행하세요.

8.2 사용자명 / 비밀번호 설정

커맨드 구문은 다음과 같습니다.

./bin/nifi.sh set-single-user-credentials <USERNAME> <PASSWORD>

예시:

./bin/nifi.sh set-single-user-credentials admin 'VeryLongDevPassword!2026'

요구사항:

• 사용자명은 4자 이상
• 비밀번호는 12자 이상

길이 조건을 만족하지 못하면 커맨드가 즉시 에러로 종료됩니다. 이건 NiFi 가 강제하는 최소 조건이므로 dev / admin1234 같은 짧은 값은 아예 들어가지 않습니다.

8.3 이 커맨드가 하는 일

내부적으로는 conf/login-identity-providers.xml 의 single-user-provider 섹션을 찾아 두 필드를 갱신합니다.

• Username → 지정한 사용자명 그대로 저장
• Password → 전달한 평문을 bcrypt 로 해시해서 저장. 평문은 디스크에 남지 않음

즉 비밀번호 자체가 파일에 적히는 게 아니라 해시만 저장되므로, 나중에 login-identity-providers.xml 을 보더라도 원래 비밀번호를 역으로 알아낼 수는 없습니다.

8.4 쉘 히스토리에 비밀번호가 남지 않도록

위처럼 명령어 뒤에 비밀번호를 그대로 쓰면 ~/.bash_history 에 영구히 기록됩니다. 운영자 PC 나 공용 VM 에서는 피해야 할 패턴입니다.

# 방법 1: 환경변수 경유 (권장)
read -s -p "NiFi single-user password: " DEV_NIFI_PW
echo
./bin/nifi.sh set-single-user-credentials admin "$DEV_NIFI_PW"
unset DEV_NIFI_PW
 
# 방법 2: 커맨드 앞에 공백을 붙이면 HISTCONTROL=ignorespace 환경에서 히스토리 제외
 ./bin/nifi.sh set-single-user-credentials admin 'VeryLongDevPassword!2026'

방법 1 이 이식성이 더 좋습니다. read -s 는 비밀번호 입력 시 echo 를 끄고, 변수는 사용 직후 unset 으로 제거합니다.

8.5 기동 및 검증

./bin/nifi.sh start
tail -f logs/nifi-app.log | grep -E "Started Server|ERROR"

https://localhost:8443/nifi 로 접속하면 로그인 화면이 나오며, 방금 지정한 사용자명/비밀번호로 로그인됩니다. 로그인 성공 직후 logs/nifi-user.log 에 Authentication successful for user admin 같은 라인이 찍히면 완료입니다.

주의: set-single-user-credentials 는 HTTPS 전용입니다. 이 글 3장의 HTTP 설정 상태에서 이 커맨드를 돌리면 동작은 하지만, 기동 시 "single-user provider requires HTTPS" 에러로 NiFi 가 올라오지 않습니다. 8장을 쓰려면 먼저 7장 되돌리기 절차로 HTTPS 설정을 복원 한 뒤에 실행하세요.

9. 운영 체크리스트

이 설정이 운영 환경에 섞여들어가지 않게 하기 위한 방어선입니다.

• HTTP 설정이 포함된 nifi.properties 를 Git 에 커밋하지 않음. 샘플만 남기고 실제 값은 .env / Ansible vault / Terraform variables 로 주입
• 개발용 Docker compose 의 이미지 태그는 apache/nifi:X.Y.Z-dev 같이 운영 태그와 반드시 구분
• 운영 배포 파이프라인에서 nifi.web.http.port 값이 비어 있는지 검사하는 lint 스텝 추가
• 내부망 DNS 에서 개발 NiFi 주소가 외부로 새지 않도록 방화벽 규칙 확인
• 주기적으로 conf/nifi.properties 를 md5sum 으로 비교해 누군가 몰래 HTTP 로 바꾸지 않았는지 감사

이 글은 NiFi 를 시작하기 위한 가장 빠른 경로만 다뤘습니다. 실제 데이터 파이프라인이 돌기 시작하면 곧 인증·TLS·프로세서 권한이 필요해지는데, 그 시점에 Data Dynamics 가 TLS/LDAP 설정을 도와드린 경험을 다른 글로 풀어낼 예정입니다.

— Data Dynamics 엔지니어링 팀