표준프레임워크 공통컴포넌트

공통컴포넌트 정의

• 공통컴포넌트는 전자정부 사업에서 응용SW 개발 시 공통적으로 활용하기 위하여, 재사용이 가능하도록 개발한 어플리케이션의 집합임
• 공통컴포넌트는 표준프레임워크 실행환경을 기반으로 MVC 아키텍처를 준수하여 설계 및 개발함
• 전자정부 사업에서 쉽게 커스터마이징하여 재사용할 수 있도록 전자정부 표준프레임워크 포털을 통해 소스코드와 가이드를 제공

공통컴포넌트 구성

egovframe-common-components
  ├─script
  └─src
     ├─main
     │  ├─java/egovframework/com
     │  │  ├─cmm
     │  │  ├─cop
     │  │  ├─dam
     │  │  ├─ext
     │  │  ├─sec
     │  │  ├─ssi/syi
     │  │  ├─sts
     │  │  ├─sym
     │  │  ├─uat
     │  │  ├─uss
     │  │  └─utl
     │  ├─resources
     │  └─webapp
     └─script

공통컴포넌트 구성 설명

• script : 공통컴포넌트에서 지원하는 데이터베이스(mysql, oracle, altibase, tibero, cubrid, mariadb, postgres, goldilocks 8종)에 대한 전체 DDL, DML, Comment 제공
• src/main/java/egovframework/com/cmm : 공통으로 사용하는 클래스들로 구성
• src/main/java/egovframework/com/cop : 게시판, 커뮤니티, 일정관리 같은 협업 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/dam : 개인지식관리, 지식맵 관리 같은 디지털 자산관리 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/ext : LDAP, Oauth 연동 같은 외부 추가 컴포넌트 클래스들로 구성
• src/main/java/egovframework/com/sec : 권한관리, 그룹관리, 롤관리와 같은 보안 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/ssi/syi : 시스템연계, 연계현황관리 서비스 연계 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/sts : 게시물통계, 사용자통계 같은 통계관리 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/sym : 공통코드관리, 로그관리, 메뉴관리 같은 시스템관리 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/uat : 로그인, 인증서관리 같은 통합인증 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/uss : 회원관리, 약관관리, 정보제공/알림 같은 사용자 지원 업무에서 사용하는 클래스들로 구성
• src/main/java/egovframework/com/utl : 달력, 포맷/계산/변환, 유효성검증 같은 유틸리티 클래스들로 구성
• src/main/resources : 공통컴포넌트 코드에서 사용하는 리소스 폴더
• src/main/webapp : 공통컴포넌트 웹페이지 루트 폴더
• src/script : 공통컴포넌트에서 지원하는 데이터베이스에 대한 업무 분류별 DDL, DML 제공

공통컴포넌트 구동 방법

1. 개발환경 Eclipse IDE를 실행함
2. Eclipse IDE 메뉴에서 File>Import… 를 클릭하여 프로젝트를 가져옴
3. 프로젝트명을 마우스 우클릭하여 Maven > Update Project… > Force Update of Snapshots/Releases 체크 후 Update를 실행함
4. 공통컴포넌트를 설치한 프로젝트 내에 위치한 globals.properties(src/main/resources/egovframework/egovProps/globals.properties) 파일의 데이터베이스 정보를 설정함
5. 프로젝트 루트에서 암호화 키 초기화 도구를 실행함 — 기본 키 그대로는 어떤 화면으로 접속해도 안내 페이지만 보입니다(아래 보안 주의사항 1 참조)
   • Windows: init-crypto-key.bat · Linux/macOS·Git Bash: ./init-crypto-key.sh
6. globals.properties 파일의 인증/권한방식 정보를 설정함
7. 프로젝트명을 마우스 우클릭하여 Run As > Run on Server를 실행함
8. 브라우저를 통해 공통컴포넌트 서비스를 확인함

⚠️ 보안 주의사항 (개발 적용 전 필수 변경)

공통컴포넌트가 기본으로 제공하는 암호화 키와 사용자 계정 정보는 공개된 값입니다. 개발 환경에 적용하기 전 아래 두 가지를 반드시 변경하시기 바랍니다.

1. Crypto 암호화 키 변경 (algorithmKey / algorithmKeyHash)

표준프레임워크 Crypto 암호화 서비스는 국정원 ARIA 암호화 알고리즘 기반입니다. egov-crypto-config.properties 의 algorithmKey 기본값 egovframe 은 공개된 값이라, 그대로 쓰면 이 키로 암호화한 DB 비밀번호 등을 누구나 풀 수 있습니다. 변경하지 않는 것은 우리집 도어락 비밀번호를 1234 초기값 그대로 사용하는 것과 동일합니다.

기본 키 그대로는 서비스되지 않습니다. 애플리케이션은 기동하지만, 아래 중 하나에 해당하면 키를 초기화하기 전까지 어떤 주소로 접속해도 "암호화 키 초기화가 필요합니다" 안내 페이지(HTTP 503) 가 보이고 서버 로그에도 같은 안내가 남습니다. 안내 페이지는 보안상 이유와 조치 방법(키 초기화 도구 실행 → 다시 빌드·재기동)을 브라우저 언어(한국어/영어)로 설명합니다.

• algorithmKey 가 기본값(egovframe)이다 — 설정 파일 경로가 틀려 실행환경이 기본값으로 대체한 경우 포함
• algorithmKeyHash 가 기본 키의 해시다(키만 바꾸고 해시를 그대로 둔 경우)
• algorithmKey 와 algorithmKeyHash 가 서로 맞지 않는다

키 초기화 도구 (권장)

프로젝트 루트에서 실행합니다(Maven 필요).

init-crypto-key.bat          (Windows 명령 프롬프트)
./init-crypto-key.sh         (Linux · macOS · Git Bash)

옵션 없이 실행하면 키를 자동 생성(권장, 무작위 43자)할지 직접 입력할지 묻습니다. 도구는 다음을 한 번에 처리합니다.

1. 새 키를 정하고 그 해시(algorithmKeyHash)를 계산합니다 — 해시는 키에서 계산되므로 직접 입력하지 않습니다.
2. globals.properties 의 DB 비밀번호(Globals.*.Password)를 옛 키로 풀어 새 키로 다시 암호화합니다. 키만 바꾸면 이 값들을 풀 수 없어 기동이 실패하므로 함께 바꿔야 합니다.
3. 원본을 프로젝트 루트 crypto-key-backup/ 에 백업하고, 해당 줄만 바꾼 뒤 다시 읽어 검증합니다(실패하면 원복).

옵션	의미
(없음)	자동 생성 / 직접 입력을 묻는다
--generate	묻지 않고 자동 생성 (CI·Docker 빌드용, -y 와 함께)
--key <값> / 환경변수 EGOV_CRYPTO_KEY	묻지 않고 이 키 사용 (명령 기록에 남지 않는 환경변수 권장)
--dry-run	바뀔 항목만 보여 주고 파일은 쓰지 않음
-y	마지막 확인 질문 생략
--help	전체 옵션

• 직접 입력하는 키는 12자 이상, 영문·숫자·기호(공백·한글·역슬래시 제외), 대문자·소문자·숫자·기호 중 3가지 이상이어야 합니다.
• 입력을 받을 수 없는 환경(CI, docker build)에서는 기다리지 않고 바로 실패합니다. --generate -y 를 쓰십시오.
• 이미 초기화된 키는 다시 바꾸지 않습니다. 운영 중인 키를 바꾸면(--force) 게시물 본문에 저장된 웹에디터 이미지 주소처럼 옛 키로 암호화된 데이터는 새 키로 풀리지 않으므로, 먼저 데이터 영향을 확인하십시오.
• 초기화한 두 설정 파일(egov-crypto-config.properties, globals.properties)을 공개 저장소에 커밋하지 마십시오. 자기 프로젝트 저장소에서 아래처럼 제외하는 것을 권장합니다.

# .gitignore (각자의 프로젝트 저장소)
src/main/resources/egovframework/egovProps/conf/egov-crypto-config.properties

• 참고 자료: Crypto 위키 가이드

2. 기본 사용자 계정 비밀번호 변경

script/dml 의 초기 데이터에는 아래 테스트용 사용자 정보가 포함되어 있습니다. (ID 대소문자 유의)

구분	ID	초기 PW	권한	초기 상태
업무사용자1	TEST1	rhdxhd12	관리자(ROLE_ADMIN)	사용 가능
일반사용자	USER	rhdxhd12	사용자	잠김
기업사용자	ENTERPRISE	rhdxhd12	사용자	잠김
업무사용자2	webmaster	rhdxhd12	관리자(ROLE_ADMIN)	잠김

초기 비밀번호 rhdxhd12 는 "공통12" 를 영문 자판으로 입력한 값입니다.

모든 계정이 같은 공개 비밀번호를 쓰므로, TEST1 을 제외한 세 계정은 잠긴 상태로 들어갑니다(script/dml 의 LOCK_AT = 'Y' — 로그인 인증 제한 Globals.login.Lock). 잠긴 계정은 비밀번호가 맞아도 로그인되지 않습니다.

1. TEST1 로 로그인해 비밀번호를 먼저 변경합니다.
2. 다른 계정이 필요하면 TEST1 로 사용자관리(업무사용자 / 일반회원 / 기업회원) 화면에서 해당 계정의 로그인 인증 제한(잠금)을 해제하고 비밀번호를 바꾼 뒤 사용합니다.

초기 비밀번호를 쓰는 계정으로 로그인하면 첫 화면에 닫을 수 없는 "초기 비밀번호 변경 안내" 팝업이 뜨고, "지금 즉시 변경하기" 로 사용자 구분에 맞는 비밀번호 변경 화면으로 이동합니다. 비밀번호를 바꾸기 전에는 첫 화면에 올 때마다 다시 뜹니다.

• 판정은 DB 에 저장된 비밀번호 해시를 초기 비밀번호의 해시와 비교합니다(비밀번호는 사용자 ID 를 salt 로 한 SHA-256 이라 계정마다 계산).

• 초기 비밀번호 목록은 globals.properties 의 Globals.InitialPasswords(쉼표 구분, 기본 rhdxhd12)이며, 비우면 검사하지 않습니다. 사이트에서 발급하는 임시 비밀번호가 있으면 여기에 추가할 수 있습니다.

• 위 계정의 비밀번호를 반드시 변경하고, 사용하지 않는 계정은 삭제한 후 운영하시기 바랍니다.

• 개발시 초기값을 그대로 사용할 경우, 그대로 배포까지 이어져서 누구나 알고 있는 계정정보로 시스템에 접근할 수 있어 심각한 보안 위험이 발생합니다.

5.0.7 패치 내용

• 2026년 컨트리뷰션 반영
• 접근 제어 보안 수정 (IDOR : 요청 식별자 조작을 통한 다른 사용자 데이터 접근 차단)
• 기능별 접근권한 정비 및 주요 기능의 소유권 검증 보완

참조

1. 개발환경 다운로드
2. 공통컴포넌트 다운로드