WiKID 4.0 Quick-setup 빠른 구성 가이드

TL;DR

WiKID 4.0의 Quick-setup 기능으로 텍스트 설정 파일 하나로 2단계 인증 서버를 빠르게 구축할 수 있습니다. 이 가이드는 샘플 파일 복사, 각 필드 설명, quick-setup 실행, 서버 시작, 그리고 보안·문제해결 체크리스트까지 단계별로 안내합니다.

개요

WiKID Strong Authentication 4.0은 두 가지 주요 변경점을 포함합니다. 첫째, 최대 5명까지 무료로 사용할 수 있어 소규모 환경이나 장기 테스트에 적합합니다. 둘째, Quick-setup이라는 빠른 시작 구성 시스템이 추가되어, 네트워크 정보를 담은 텍스트 파일 한 개로 완전한 2단계 인증 서버를 자동 생성할 수 있습니다.

중요: 평가용 인증서(evaluation cert)는 30일 내에 5-user 무료 라이선스로 갱신해야 합니다. 또한 설정에 쓰인 민감한 값(예: passphrase, radiushostsecret)은 설정 완료 후 제거하거나 안전하게 보관해야 합니다.

요구사항

루트 계정 또는 sudo 권한
PostgreSQL이 설치되어 있고 실행 중일 것
서버의 공인 IP 또는 FQDN 접근 가능
방화벽에서 HTTPS/Tomcat 포트 허용

빠른 설정 파일 복사 및 편집

샘플 파일을 현재 디렉토리로 복사합니다. 루트 권한으로 실행하세요.

# cp /opt/WiKID/conf/sample-quick-setup.properties wikid.conf

편집기(예: vim)로 파일을 엽니다.

# vim wikid.conf

파일 안의 각 항목과 권장 값을 아래에서 설명합니다. 세미콜론(;)으로 시작하는 줄은 주석입니다.

passphrase: 인증서 보호용 암호

; passphrase for protecting certs --------------------------------------  
passphrase=protectme  
; *NOTE*: YOU SHOULD REMOVE THIS SETTING AFTER CONFIGURATION FOR SECURITY

이 암호는 서버의 평가용 인증서를 보호하는 데 사용됩니다. 잃어버리지 마세요. 서버 시작 시 필요하며(/etc/WiKID/security에 보관할 수도 있음), 정식 인증서 설치 시에도 필요합니다. 설정 완료 후 보안상 이 필드를 파일에 남기지 마세요.

domainname: 도메인 명칭

; name to give the domain ----------------------------------------------  
domainname=mydomain

이 값은 WiKID 토큰에 표시되는 도메인 이름입니다. VPN, SSH, Google Apps 등 향후 확장 가능성을 고려하여 일반적인 이름을 권장합니다.

domainip: 서버 외부 IP

; IP of the server -----------------------------------------------------  
domainip=127.0.0.1

토큰이 통신할 서버의 외부 IP 주소입니다.

domaincode: 토큰 등록용 0패딩 도메인 코드

; 0-Padded IP without dots ---------------------------------------------  
domaincode=127000000001

사용자가 토큰 설정 시 한 번 입력하는 도메인 코드입니다. 입력 편의성 때문에 0으로 패딩했으며, 비밀로 유지할 필요는 없습니다. 보안은 등록 과정에서 확보됩니다.

hostname: 서버의 FQDN

; full hostname of the server; can be same as cn value ----------------------  
hostname=localhost.localdomain

서버의 정규화된 호스트명입니다.

RADIUS 설정 (네트워크 클라이언트)

; information for setting up a RADIUS host  
radiushostip=10.1.2.3  
radiushostsecret=mysharedsecret  
; *NOTE*: YOU SHOULD REMOVE THIS SETTING AFTER CONFIGURATION FOR SECURITY

WiKID 서버에 RADIUS 클라이언트를 설정합니다. 이 값은 WiKID와 연동할 VPN, RADIUS 서버(NPS, FreeRADIUS 등)의 정보입니다. 설정 완료 후 shared secret은 제거하거나 안전한 저장소로 이동하세요.

wAuth 클라이언트 (선택)

; optionally create an extra host cert for wauth; leave blank if not needed  
wauthhostip=

API를 사용하는 wAuth 클라이언트를 만들 경우 해당 클라이언트의 IP를 입력합니다. 모르면 비워두어도 됩니다. 이 클라이언트의 p12 파일은 위의 passphrase로 보호됩니다.

인증서 정보(CSR 생성용)

; cert properties ------------------------------------------------------  
; administrative email for this server  
[email protected]  
; hostname of server  
cn=localhost.localdomain  
; organization/company name  
o=myorganization  
; department or other OU  
ou=mydepartment  
; city  
l=mylocation  
; full name of state  
st=mystate  
; 2-letter country code  
c=us

이 정보는 서버 인증서 생성에 사용됩니다. 고유한 값이어야 하며, 정확히 입력하면 평가용 인증서를 생산용으로 전환하기가 쉬워집니다. (개인정보는 판매하지 않습니다.)

Quick-setup 실행

설정을 저장한 뒤 quick-setup 명령을 실행합니다.

# wikidctl quick-setup configfile=wikid.conf

실행 중에는 다음과 유사한 로그가 표시될 수 있습니다:

----------------------------------------------  
= Checking for valid args ...  
= Make sure Pg is running ...  
= Checking if DB exists ...NO!  
== Setting up new DB ...  
log4j:WARN No appenders could be found for logger (com.mchange.v2.log.MLog).  
log4j:WARN Please initialize the log4j system properly.  
== Got Pg connection ...  
= Setting up intermediate CA cert ...  
= Submitting intermediate CA CSR ...  
= Creating Tomcat cert ...  
= Installing intermediate CA cert ...  
== Intermediate cert installation completed!  
= Setting up cert for localhost ...  
== Setting up localhost settings ...  
== RADIUS host does not exist!  
== Setting up wAuth client ...  
= Setting up cert for 10.100.0.112 ...  
== Setting up non-localhost settings ...  
== Domain exists! 1  
== Adding keys ...

로그는 환경에 따라 달라집니다. 오류가 보이면 아래의 문제 해결 섹션을 확인하세요.

서버 시작 및 웹 UI 접속

quick-setup이 성공하면 서버를 시작합니다.

# wikidctl start

브라우저로 WiKIDAdmin 인터페이스에 접속합니다:

https://yourserver.com/WiKIDAdmin/

도메인이 생성되었고, RADIUS 네트워크 클라이언트가 설정되었으며, 필요한 인증서가 모두 설치되어 있으면 UI에서 확인할 수 있습니다. 이제 WiKID 토큰을 설치하고 사용자 등록을 진행하면 됩니다.

설치 후 보안 권장 사항 (중요)

설정 파일에 남겨둔 passphrase와 radiushostsecret은 즉시 제거하거나 안전한 파일(/etc/WiKID/security 등)에 이동하십시오.
평가 인증서를 정식 인증서로 갱신하거나 PKI 정책에 맞게 교체하십시오.
서버와 RADIUS 사이의 통신은 내부 네트워크 또는 VPN으로 제한하세요.
관리자 계정의 암호 정책을 강화하고, 웹 UI 접근을 IP 화이트리스트로 제한하세요.

문제 해결: 흔한 실패와 해결책

PostgreSQL 연결 실패: Pg가 실행 중인지, 연결 문자열과 권한을 확인하세요.
DB 존재 여부 관련 메시지: 기존 DB가 있다면 백업 후 정리하거나 기존 설정을 확인하세요.
인증서 관련 오류: passphrase가 맞는지 확인하고, CSR 필드(cn, o 등)를 점검하세요.
포트/방화벽 문제: HTTPS/Tomcat 포트(예: 443 또는 8443)가 열려 있는지 검사하세요.
radiushostsecret 분실: 클라이언트와 서버 양쪽에서 새로운 shared secret을 설정하세요.
UI가 로드되지 않음: Tomcat 로그와 시스템 로그(/var/log/)를 확인해 원인을 찾으세요.

중요: passphrase를 잃어버리면 인증서 p12 파일을 열 수 없으므로 서버 시작이나 인증서 설치에 실패합니다. 항상 안전하게 백업해 두세요.

역할별 체크리스트

관리자(설치 담당)
- 샘플 파일 복사 및 편집
- quick-setup 실행
- 서버 시작 및 기본 기능 확인
- 평가 인증서 갱신 계획 수립
네트워크 엔지니어
- RADIUS 연동 확인 및 shared secret 전달
- 방화벽/네트워크 경로 점검
운영팀
- 토큰 배포 및 사용자 등록
- 모니터링과 로그 회수 설정

수락 기준

WiKIDAdmin 웹 UI가 https로 접근 가능하다.
지정한 domainname과 domainip가 UI에 표시된다.
RADIUS 호스트가 추가되어 있고, shared secret이 구성되어 있다.
필요한 서버 인증서(중간 CA 포함)가 설치되어 있다.
토큰 1개 이상을 생성·등록하고 인증 테스트에 성공했다.

미니 단계별 방법론 (간단 체크리스트)

샘플 파일 복사: cp /opt/WiKID/conf/sample-quick-setup.properties wikid.conf
wikid.conf 편집: 필수 필드(domainname, domainip, domaincode, cn 등) 채움
quick-setup 실행: wikidctl quick-setup configfile=wikid.conf
로그 검토 및 문제 해결
서버 시작: wikidctl start
웹 UI 접속 및 토큰 등록
민감 값 정리, 인증서 갱신 계획 수립

간단 용어 사전

Quick-setup: 텍스트 파일로 자동 구성하는 WiKID의 설치 모드
passphrase: 인증서 파일(p12)을 보호하는 암호
RADIUS: 네트워크 인증 프로토콜

요약

WiKID 4.0의 Quick-setup은 소규모 환경에서 빠르게 2단계 인증 서버를 구축할 수 있는 효율적인 방법입니다. 설정 파일의 각 필드를 정확히 입력하고, 실행 후 로그와 웹 UI로 정상 동작을 확인한 뒤 민감 정보를 정리하는 것을 잊지 마세요.

주의: 설정 과정에서 사용한 비밀값은 절대 공개 저장소에 남기지 말고, 평가 인증서는 30일 내에 정식 라이선스로 갱신하세요.

WiKID Strong Authentication 4.0 Quick-setup 구성 방법