CSV 디렉터리 동기화

메뉴 경로 : 설정 > 인바운드 프로비저닝 > CSV 디렉터리 동기화

개요

FTP 또는 SFTP 서버에 업로드된 CSV 파일을 주기적으로 감시하여 사용자 및 그룹 정보를 Security365 관리센터로 자동 동기화하는 기능입니다. HR 시스템 등 외부 시스템에서 정기적으로 생성하는 CSV 파일을 연동할 때 활용합니다.

관리자가 서버 접속 정보, 파일 경로, 변환 규칙, 실행 주기를 한 번 설정해 두면, 이후에는 시스템이 자동으로 파일 변경을 감지하고 반영합니다.

동작 흐름:

단계	내용
1	FTP/SFTP 서버에 접속
2	지정된 경로의 CSV 파일 다운로드
3	이전 동기화 대비 파일 변경 여부 확인 (파일 내용 해시 비교)
4	CSV 데이터 변환 및 유효성 검증 (필드 매핑, 필터링 등)
5	관리센터 사용자/그룹 정보 반영 (그룹 → 사용자 순서)

참고: 하나의 인바운드 프로비저닝 방식만 활성화할 수 있습니다. CSV 디렉터리 동기화를 활성화하면 다른 방식(SCI Server, Microsoft365, 로컬 Active Directory)은 비활성 상태가 됩니다.

참고: 파일 내용이 이전 동기화와 동일한 경우, 동기화를 건너뜁니다. 이는 불필요한 처리를 방지하는 정상 동작입니다.

시작하기 전에

설정을 시작하기 전에 아래 정보를 미리 준비해 두세요.

준비 항목	설명	예시
FTP/SFTP 서버 주소	고객사 파일 서버의 IP 또는 도메인	`ftp.example.com`
포트 번호	SFTP 기본 22, FTP 기본 21	`22`
접속 계정	서버 로그인 ID / 비밀번호	`ftpuser`
CSV 파일 경로	서버 내 CSV 파일이 위치한 디렉터리	`/data/hr/users/`
CSV 파일명 패턴	파일명이 고정인지, 날짜별로 바뀌는지	`users.csv` 또는 `users_yyyyMMdd.csv`
CSV 컬럼 정보	고객사 CSV의 헤더명 또는 컬럼 순서	`사원번호, 이름, 메일, 부서ID, 재직상태`

화면 구성

설정 전: CSV 디렉터리 동기화 카드에 "설정 후 사용할 수 있습니다." 안내가 표시됩니다.

설정 완료 후: 카드에 다음 정보가 표시됩니다.

정보	설명
연결 방식 및 서버 정보	접속 방식(SFTP/FTP), 호스트 주소, 포트, 접속 ID
마지막 동기화 일시 및 결과	최근 동기화 실행 시각과 성공/실패 여부
동기화 주기	자동 동기화 설정 시각
[수정] 버튼	설정 변경
[수동 동기화] 버튼	즉시 동기화 실행

설정 방법 (4단계)

[1단계] 서버 연결

FTP/SFTP 서버 접속 정보를 입력합니다.

항목	설명	예시
접속 방식 (프로토콜)	FTP 또는 SFTP 선택	SFTP
호스트(서버 주소)	서버 IP 또는 도메인 주소	`ftp.example.com`
포트	접속 포트 번호 (프로토콜 변경 시 자동 변경)	`22`
접속 ID	서버 계정 ID	`ftpuser`
접속 비밀번호	서버 계정 비밀번호 (암호화 저장)

접속 방식 선택 기준:

방식	기본 포트	설명	권장 상황
SFTP	22	SSH 기반 암호화 전송	외부망 또는 보안이 필요한 환경 (권장)
FTP	21	비암호화 전송	내부 네트워크 등 보안 요건이 낮은 환경

설정 후 [연동 테스트] 버튼을 클릭하여 서버 연결 상태를 반드시 확인하세요.

참고: 비밀번호는 RSA 암호화되어 저장되며, 설정 화면에서 평문으로 노출되지 않습니다.

버튼: 취소 | 임시 저장 | 다음

[2단계] 사용자 설정

사용자 CSV 파일의 감시 방식과 데이터 변환 규칙을 설정합니다.

감시 경로

감시 모드 선택

고객사 서버에서 파일을 어떻게 관리하는지에 따라 선택합니다.

상황	선택 모드	파일 패턴 예시
항상 같은 파일명으로 덮어쓰기	단일 파일	`users.csv`
날짜별로 새 파일이 생성됨	디렉터리 > 파일명 기준	`users_yyyyMMdd`
최근 수정된 파일을 자동으로 감지	디렉터리 > 수정일 기준	`users`

디렉터리 모드 선택 시 — 최신 파일 판단 기준

기준	설명	사용 상황
수정일 기준	지정한 키워드가 포함된 파일 중 수정일이 가장 최근인 파일 선택	파일명에 날짜가 없는 경우
파일명 기준	파일명의 날짜를 파싱하여 가장 최신 날짜의 파일 선택	HR 시스템이 날짜를 파일명에 포함하는 경우

지원 날짜 포맷 (파일명 기준 선택 시):

포맷	파일명 예시
yyyyMMdd	`users_20260101.csv`
yyyy-MM-dd	`users_2026-01-01.csv`
yy-MM-dd	`users_26-01-01.csv`
yyMMdd	`users_260101.csv`

경로 및 파일 패턴

항목	설명	예시
경로	서버 내 CSV 파일이 위치한 디렉터리 절대 경로	`/data/hr/users`
파일 패턴	감시할 파일명 패턴	`users_yyyyMMdd`

참고: 파일명이 #으로 시작하는 파일은 주석으로 처리되어 동기화 대상에서 제외됩니다.

동기화 옵션

항목	옵션	설명
CSV 미포함 항목 처리	유지 (기본값)	CSV에 없는 기존 사용자를 그대로 유지. 누락이 단순 실수일 가능성이 있을 때 권장
	비활성화	CSV에 없는 기존 사용자를 비활성화 처리. HR 시스템에서 퇴사자가 CSV에서 빠지는 환경에 적합
검증 오류 시 동기화 중단	사용	검증 오류가 하나라도 있으면 전체 동기화를 중단. 데이터 무결성을 우선시할 때 사용
	사용 안함 (기본값)	오류 레코드는 건너뛰고 나머지 정상 데이터만 반영

주의: 비활성화 선택 시, CSV 파일에 포함되지 않은 기존 사용자가 모두 비활성화됩니다. 파일 내용을 반드시 사전에 확인하세요.

CSV 컨버팅 설정

CSV 파일 형식과 필드 매핑 규칙을 설정합니다. 사용자 동기화를 사용하는 경우 필드 매핑은 필수입니다.

입력 CSV 구분자

옵션	구분자	사용 예
콤마 (기본값)	`,`	`EMP01,홍길동,영업`
파이프	`\|`	`EMP01\|홍길동\|영업` (데이터에 콤마가 포함될 때 안전)
탭	(탭 문자)	`EMP01 홍길동 영업`

필드 매핑 방식

방식	설명	사용 상황
헤더 기반 (기본값)	CSV 첫 행(헤더)의 컬럼명으로 매핑	CSV 파일에 헤더 행이 있을 때
인덱스 기반	컬럼 순서(0부터 시작)로 매핑	CSV 파일에 헤더 행이 없을 때

헤더 기반 매핑 예시 (고객사 CSV 컬럼명 → 표준 필드):

고객사 CSV 컬럼명	표준 필드	필수 여부
사원번호	USER_ID	필수
이름	USER_NAME	필수
메일주소	EMAIL	선택
소속부서ID	GROUP_ID_LIST	선택
재직상태	ACTIVE_STATUS	선택

인덱스 기반 매핑 예시 (헤더 없는 CSV):

컬럼 순서	표준 필드	필수 여부
0 (첫 번째 컬럼)	USER_ID	필수
1 (두 번째 컬럼)	USER_NAME	필수
2 (세 번째 컬럼)	EMAIL	선택
3 (네 번째 컬럼)	GROUP_ID_LIST	선택
4 (다섯 번째 컬럼)	ACTIVE_STATUS	선택

표준 필드 목록 (사용자)

표준 필드	필수 여부	설명
USER_ID	필수	사용자 고유 ID (이메일 형식 권장)
USER_NAME	필수	사용자 이름
EMAIL	선택	이메일 주소
GROUP_ID_LIST	선택	소속 그룹 ID (여러 그룹은 콤마로 구분)
ACTIVE_STATUS	선택	활성화 여부

ACTIVE_STATUS 인식 값:

인식 값	처리 결과
`ACTIVE`, `Y`, `1`, `true` (대소문자 무관)	활성 사용자로 처리
그 외 모든 값 (`재직`, `사용`, `N`, 빈 값 등)	비활성 사용자로 처리

주의: ACTIVE_STATUS 컬럼이 잘못 매핑되거나 시스템이 인식할 수 없는 값이 입력된 경우, 전체 사용자가 비활성화될 수 있습니다. 설정 변경 후 반드시 소규모 테스트를 먼저 진행하세요.

자주 발생하는 실수: 고객사가 재직/퇴직, 사용/미사용 같은 한글 값을 사용하는 경우, 시스템이 모두 비활성으로 처리합니다. 이 경우 레코드 필터링으로 활성 사용자만 통과시키거나, ACTIVE_STATUS 매핑 없이 동기화 후 수동으로 상태를 확인하세요.

레코드 필터링 (선택)

특정 조건에 맞는 레코드만 동기화 대상으로 포함할 수 있습니다. 복수 조건 입력 시 모든 조건을 만족(AND)하는 레코드만 처리됩니다.

와일드카드(*) 패턴 예시:

패턴	매칭 예시	의미
`ACTIVE`	`ACTIVE`	정확히 'ACTIVE'와 일치
`*@company.com`	`hong@company.com`	특정 도메인으로 끝나는 값
`EMP_*`	`EMP_001`, `EMP_HR`	특정 접두사로 시작하는 값
`부서`	`영업부서`, `개발부서`	특정 문자열을 포함하는 값

기본 이메일 도메인 (선택)

USER_ID가 이메일 형식(@ 포함)이 아닌 경우, 설정한 도메인을 자동으로 추가하여 이메일 형식으로 변환합니다. EMAIL 필드가 비어 있으면 함께 채워집니다.

USER_ID (입력)	EMAIL (입력)	도메인 설정	USER_ID (출력)	비고
`EMP001`	(빈값)	`company.com`	`EMP001@company.com`	변환됨, EMAIL도 자동 채워짐
`EMP001`	`hong@other.com`	`company.com`	`EMP001@company.com`	EMAIL은 기존 값 유지
`user@a.com`	(빈값)	`company.com`	`user@a.com`	이미 이메일 형식이면 변경 없음

버튼: 취소 | 임시 저장 | 이전 | 다음

[3단계] 그룹 설정

그룹 CSV 파일의 감시 방식과 데이터 변환 규칙을 설정합니다. 구성은 사용자 설정과 동일하며, 다음과 같은 차이가 있습니다.

사용자 설정과의 차이점:

항목	사용자 설정	그룹 설정
CSV 미포함 항목 처리 옵션	유지 / 비활성화	유지 / 삭제
검증 오류 시 동기화 중단	있음 (선택 가능)	없음 (오류 시 항상 전체 중단)
기본 이메일 도메인	있음	없음

동기화 옵션 (그룹)

항목	옵션	설명
CSV 미포함 항목 처리	유지 (기본값)	CSV에 없는 기존 그룹을 그대로 유지
	삭제	CSV에 없는 기존 그룹을 삭제 (멤버가 없는 빈 그룹만 삭제 가능)

표준 필드 목록 (그룹)

표준 필드	필수 여부	설명
GROUP_ID	필수	그룹 고유 ID
GROUP_NAME	필수	그룹 이름
DESCRIPTION	선택	그룹 설명
PARENT_GROUP_ID	선택	상위 그룹 ID (계층 구조 구성 시 사용)

헤더 기반 매핑 예시 (그룹):

고객사 CSV 컬럼명	표준 필드
부서코드	GROUP_ID
부서명	GROUP_NAME
설명	DESCRIPTION
상위부서코드	PARENT_GROUP_ID

주의: 그룹 동기화 중 오류가 발생하면, 그룹은 부분 반영 없이 전체가 중단됩니다. 단, 사용자 동기화는 그룹과 독립적으로 실행되므로 그룹 오류 여부에 관계없이 계속 진행됩니다. 그룹 CSV 파일의 데이터 정합성을 사전에 충분히 검토하세요.

참고: 사용자 설정과 그룹 설정 중 최소 한 쪽은 반드시 필드 매핑을 완료해야 저장할 수 있습니다.

버튼: 취소 | 임시 저장 | 이전 | 다음

[4단계] 동기화 설정

자동 동기화 주기 및 백업 옵션을 설정합니다.

항목	설명
자동 동기화	사용 시 설정한 주기로 자동 실행. 사용 안함 시 [수동 동기화] 버튼으로만 실행 가능
동기화 주기	자동 동기화 사용 시, 매일 실행할 시각(시/분) 설정
동기화 전 백업	사용 시, 동기화 실행 전 현재 사용자/그룹 데이터를 자동으로 백업

설정 예시 (매일 새벽 2시 자동 실행):

항목	설정값
자동 동기화	사용
주기	매일
시작 시각	02시 00분
동기화 전 백업	사용 (운영 환경 권장)

참고: 모든 실행 시각은 KST(한국 표준시) 기준입니다.

참고: 현재는 매일 1회 실행만 지원합니다.

주의: 동기화 전 백업이 활성화된 경우, 백업 실패 시 동기화가 진행되지 않습니다. 첫 동기화(백업 대상 데이터 없음)는 백업 단계를 건너뛰고 진행됩니다.

버튼: 취소 | 이전 | 저장

수동 동기화

설정 저장 후 인바운드 프로비저닝 목록 화면의 CSV 디렉터리 동기화 카드에서 [수동 동기화] 버튼을 클릭하면 즉시 동기화가 실행됩니다.

실행 흐름:

[수동 동기화] 클릭 → 확인 팝업에서 [실행] 클릭
동기화 진행 중 — 버튼 비활성화 및 진행 중 메시지 표시
완료 — 성공/실패 메시지와 함께 카드의 마지막 동기화 정보가 갱신됨

참고: 그룹 → 사용자 순서로 처리됩니다.

주의: 동기화 진행 중에는 중복 실행이 불가합니다. 이전 동기화가 완료된 후 다시 실행하세요.

동기화 결과 확인

설정 완료 후 카드에서 마지막 동기화 결과를 확인할 수 있습니다. [마지막 동기화 정보] 링크를 클릭하면 상세 슬라이드가 열립니다.

마지막 동기화 상태 종류:

상태	설명
성공	파일 감시 및 데이터 반영 완료
부분 실패	일부 레코드 반영 실패, 나머지는 정상 반영됨 (사용자 동기화에서 발생 가능)
변경 없음	이전 동기화 대비 파일 내용 변경 없음 (정상 동작)
연결 실패	FTP/SFTP 서버 접속 불가
파일 없음	지정된 경로에 파일이 존재하지 않음
실패	데이터 변환, 검증, 또는 반영 과정에서 오류 발생

상세 슬라이드 표시 항목:

슬라이드에서는 그룹 동기화와 사용자 동기화 각각의 결과를 확인할 수 있습니다.

항목	표시 내용
상태	성공 / 부분 실패 / 변경 없음 / 실패 등
감시 대상	설정된 경로 및 파일 패턴
마지막 동기화 일시	실행 완료 시각
실패 사유 (실패 시)	오류 메시지 및 오류 코드

참고: 실패 상태인 경우 오류 메시지와 함께 오류 코드가 표시됩니다. 코드를 확인하여 오류 대처를 참고하세요.

오류 대처

오류 유형	주요 증상	조치 방법
연결 오류	상태: 연결 실패	서버 주소·포트·계정 정보 확인 / 방화벽에서 해당 포트 개방 여부 확인
파일 오류	상태: 파일 없음	지정된 경로 및 파일 패턴 확인 / 파일이 서버에 업로드되어 있는지 확인
변환 오류	상태: 실패	CSV 구분자 설정 확인 / 필드 매핑 설정 확인 / CSV 파일 인코딩(UTF-8) 확인
검증 오류	상태: 실패	필수 필드(USER_ID, USER_NAME / GROUP_ID, GROUP_NAME) 누락 여부 확인
반영 오류	상태: 실패	동기화 로그에서 오류 상세 내용 확인 후 담당팀 문의
백업 실패	동기화 미실행	동기화 전 백업 설정 확인 / 백업 저장 공간 확인

주의사항

사용자 설정과 그룹 설정 중 최소 한 쪽은 반드시 필드 매핑을 완료해야 합니다. 양쪽 모두 미설정 상태로는 저장되지 않습니다.
ACTIVE_STATUS 필드 매핑이 잘못된 경우, 전체 사용자가 비활성화될 수 있습니다. 설정 변경 후 반드시 소규모 테스트를 먼저 진행하세요.
그룹 동기화 오류 발생 시, 그룹은 부분 반영 없이 전체가 중단됩니다. 단, 사용자 동기화는 그룹과 독립적으로 실행되므로 그룹 오류와 관계없이 계속 진행됩니다.
파일명이 #으로 시작하는 파일은 주석으로 처리되어 동기화 대상에서 제외됩니다.
파일 내용이 변경되지 않으면 동기화를 건너뜁니다. 이는 정상 동작입니다.
동기화 전 백업 옵션 활성화 시, 백업 실패가 발생하면 동기화도 중단됩니다.
모든 실행 시각은 KST(한국 표준시) 기준입니다.
동기화된 사용자/그룹 정보를 관리센터에서 직접 수정해도, 다음 동기화 실행 시 CSV 파일 기준으로 덮어씌워집니다. 영구적인 변경이 필요하다면 원본 CSV 파일 또는 소스 시스템에서 먼저 수정하세요.
하나의 인바운드 프로비저닝 방식만 활성화할 수 있으며, 다른 방식이 이미 활성화된 경우 전환 후 사용해야 합니다.

설정 시나리오 예시

시나리오: HR 시스템이 매일 날짜별 CSV를 FTP 서버에 생성하는 경우

HR 시스템이 매일 오전 1시에 /hr/export/ 경로에 users_20260101.csv 형식으로 사용자 파일을 자동 생성하고, 그룹 파일은 groups.csv로 항상 같은 이름으로 덮어쓰는 환경입니다.

1단계 — 서버 연결 설정:

항목	설정값
접속 방식	SFTP
호스트	`ftp.company.com`
포트	`22`
접속 ID	`hrexport`

2단계 — 사용자 설정:

항목	설정값
감시 모드	디렉터리
최신 파일 판단 기준	파일명 기준
경로	`/hr/export`
파일 패턴	`users_yyyyMMdd`
CSV 미포함 항목 처리	비활성화 (퇴사자 자동 처리)
CSV 구분자	콤마
매핑 모드	헤더 기반
필드 매핑	사원번호 → USER_ID / 이름 → USER_NAME / 이메일 → EMAIL / 부서ID → GROUP_ID_LIST / 재직여부 → ACTIVE_STATUS
레코드 필터링	ACTIVE_STATUS 값이 `Y` (퇴사자 제외)
기본 이메일 도메인	`company.com` (사원번호만 있는 경우 이메일 자동 생성)

3단계 — 그룹 설정:

항목	설정값
감시 모드	단일 파일
경로	`/hr/export`
파일 패턴	`groups.csv`
CSV 미포함 항목 처리	유지
필드 매핑	부서코드 → GROUP_ID / 부서명 → GROUP_NAME / 상위부서코드 → PARENT_GROUP_ID

4단계 — 동기화 설정:

항목	설정값
자동 동기화	사용
시작 시각	02시 00분 (HR 파일 생성 1시간 후)
동기화 전 백업	사용

목차​

개요​

시작하기 전에​

화면 구성​

설정 방법 (4단계)​

[1단계] 서버 연결​

[2단계] 사용자 설정​

감시 경로​

동기화 옵션​

CSV 컨버팅 설정​

[3단계] 그룹 설정​

동기화 옵션 (그룹)​

표준 필드 목록 (그룹)​

[4단계] 동기화 설정​

수동 동기화​

동기화 결과 확인​

오류 대처​

주의사항​

설정 시나리오 예시​

시나리오: HR 시스템이 매일 날짜별 CSV를 FTP 서버에 생성하는 경우​

목차

개요