joungmin/vpd-permission-poc

Fork 0

Files

History

devmrko e9d50e6a32 refs #741 #742 : reorganize repository by application

2026-08-03 10:20:36 +09:00

README.md

refs #741 #742 : reorganize repository by application

2026-08-03 10:20:36 +09:00

README.md

HMM 백오피스 환경 기반 공통 카탈로그 전환

Redmine: #723
기준 설계: Smilegate #722 docs/design/722-configurable-data-catalog/README.md
기준 커밋: 53342e7 (smilegate)
적용 브랜치: hmm-backoffice
운영 주소: https://hmm-backoffice.cloud-handson.com

1. 배경

현재 HMM 백오피스는 정형 데이터 목록을 별도 JSON 파일로 분리했지만 제품명, MCP 도구, 마스킹 대상, 보안 SQL 목록 등은 Java와 Thymeleaf에 남아 있다. 같은 백오피스 틀을 다른 고객사에 재사용하려면 소스를 수정하고 다시 빌드해야 한다.

Smilegate #722는 데이터 객체, 제품 표시명, 마스킹 정책, MCP/Select AI, 보안 SQL 목록을 환경 설정으로 옮겼다. HMM에는 이 구조를 적용하되 다음 현행 기능을 보존해야 한다.

HMM 직원 Bearer token을 해시로 검증한다.
MCP discovery와 tool call 모두 인증한다.
AI Agent Tool 실행과 같은 DB 세션에서 HMM_ACCESS_CTX를 설정하고 반드시 해제한다.
용어 변환, 정형 HR 조회, 규정 PDF 검색의 세 MCP 도구를 계속 제공한다.
팀장과 팀원의 VPD 행 접근 규칙 및 마스킹 관리 기능을 유지한다.

2. 목표

승인 데이터 객체와 객체 유형을 환경 JSON으로 설정한다.
TABLE과 VIEW를 모두 읽기 전용 미리보기 대상으로 지원한다.
DB comment는 TABLE/VIEW에 지원하고 Oracle annotation 변경은 TABLE에만 허용한다.
Data Redaction 관리 대상과 정책명을 별도 환경 JSON으로 설정한다.
제품명, 페이지 타이틀, 데이터 명칭, MCP 공개 주소와 도구 계약을 환경 설정으로 옮긴다.
Smilegate #722의 단일 Select AI 도구 설정과 HMM의 복수 Agent Tool 설정을 모두 수용한다.
번들 보안 SQL 화면의 노출 목록을 환경 allowlist로 제한한다.
잘못된 설정은 애플리케이션 시작 시 거부한다.

3. 제외 범위

HMM 사용자·그룹·역할·권한 테이블 구조 변경
HMM 지식 문서 적재 구조 변경
기존 VPD 함수와 Data Redaction 정책 DDL 재작성
Select AI 프로파일의 object list 자동 변경
운영 Bearer token 원문을 설정이나 Git에 저장

4. 설정 계약

4.1 데이터 카탈로그

BACKOFFICE_CATALOG_OWNER
BACKOFFICE_CATALOG_OBJECTS

BACKOFFICE_CATALOG_OBJECTS는 아래 필드를 갖는 JSON 배열이다.

[
  {
    "key": "employees",
    "tableName": "HMM_HR_EMPLOYEES",
    "objectType": "TABLE",
    "businessName": "직원 원장",
    "description": "직원·매니저·소속팀 정보",
    "previewColumns": ["EMPLOYEE_ID", "EMPLOYEE_CODE", "EMPLOYEE_NAME"]
  }
]

검증 규칙:

owner와 tableName은 Oracle simple identifier만 허용한다.
key는 소문자 영문으로 시작하고 소문자, 숫자, 하이픈만 허용한다.
objectType은 TABLE 또는 VIEW만 허용한다.
key와 tableName은 각각 중복될 수 없다.
businessName과 description은 비어 있을 수 없다.
previewColumns는 선택값이다. 지정하면 검증된 컬럼만 조회하며 VECTOR/BLOB 등 관리자 미리보기에 부적합한 컬럼을 제외할 수 있다.
빈 목록이나 잘못된 JSON이면 애플리케이션 시작을 실패시킨다.

정형 데이터 미리보기는 카탈로그에서 선택한 객체만 SQL 식별자로 사용하고 최대 50건만 반환한다. 요청 파라미터를 SQL 객체명으로 직접 사용하지 않는다.

4.2 제품 표시

BACKOFFICE_PRODUCT_NAME
BACKOFFICE_PRODUCT_TITLE
BACKOFFICE_PRODUCT_DATA_LABEL

공통 레이아웃, 데이터 화면, 메타데이터 화면, MCP 화면은 이 값을 사용한다. HMM 운영값은 HMM HR Access Console과 HMM HR 데이터이다.

4.3 마스킹 정책

BACKOFFICE_MASKING_POLICIES

[
  {
    "objectName": "HMM_HR_EMPLOYEES",
    "policyName": "HMM_EMPLOYEE_PII_REDACT"
  }
]

객체명과 정책명은 Oracle simple identifier로 검증하고, objectName과 policyName 중복을 각각 거부한다. 빈 값이면 관리 가능한 Data Redaction 정책이 없는 fail-closed 상태로 동작한다.

4.4 MCP

Smilegate #722의 단일 Select AI 도구 환경변수를 호환한다.

BACKOFFICE_MCP_PUBLIC_URL
BACKOFFICE_MCP_SERVER_NAME
BACKOFFICE_MCP_TOOL_NAME
BACKOFFICE_MCP_TOOL_LABEL
BACKOFFICE_MCP_TOOL_DESCRIPTION
BACKOFFICE_MCP_PROMPT_DESCRIPTION

HMM처럼 여러 DBMS Cloud AI Agent Tool을 노출하는 배포는 다음 JSON을 사용한다.

BACKOFFICE_MCP_TOOLS

[
  {
    "name": "resolve_hr_term",
    "label": "HMM HR 용어 표준화",
    "description": "휴가·근태 표현을 표준 용어와 코드로 변환합니다.",
    "argumentName": "term",
    "argumentDescription": "확인할 휴가·근태 용어, 동의어 또는 코드입니다.",
    "executionType": "AGENT_TOOL",
    "targetName": "HMM_HR_TERM_RESOLVER",
    "targetParameterName": "P_TERM"
  }
]

executionType은 AGENT_TOOL 또는 SELECT_AI만 허용한다. BACKOFFICE_MCP_TOOLS가 비어 있으면 #722의 단일 SELECT_AI 도구 설정을 사용한다. HMM 운영은 세 개의 AGENT_TOOL 정의를 환경에 둔다.

MCP 보안 경계:

initialize, tools/list, tools/call 모두 유효한 HMM 사용자 Bearer token이 필요하다.
token 원문은 로그, 응답, DB에 저장하지 않는다.
AGENT_TOOL 실행 전 같은 JDBC 연결에서 ADMIN.HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER를 실행한다.
성공·실패와 관계없이 같은 연결에서 CLEAR_USER를 실행한다.
MCP JSON-RPC 오류에 DB password, SQL 전체 stack trace를 포함하지 않는다.

4.5 Select AI

BACKOFFICE_SELECT_AI_DB_URL
BACKOFFICE_SELECT_AI_DB_USERNAME
BACKOFFICE_SELECT_AI_DB_PASSWORD
BACKOFFICE_SELECT_AI_PROFILE

단일 Select AI 도구는 프로파일 소유 계정으로 SHOWSQL을 생성한 후 다음 검증을 모두 통과한 SQL만 읽기 전용 트랜잭션에서 실행한다.

첫 문장은 SELECT 또는 WITH
세미콜론을 이용한 다중 문장 금지
DDL, DML, transaction, lock, PL/SQL, DBMS/UTL/SYS 호출 금지
최대 100건, query timeout 30초
실행 후 항상 rollback

HMM 운영 MCP는 현재 세 개의 Agent Tool을 사용하므로 Select AI 접속은 선택 설정이다. 다른 고객사는 단일 Select AI 도구만 설정할 수 있다.

4.6 보안 SQL

BACKOFFICE_SECURITY_SQL_SCRIPTS

번들된 database/adb 경로 안의 파일만 허용하며 요청값을 resource path로 사용하지 않는다. HMM 운영에서는 72_hmm_leave_team_vpd.sql 등 HMM 관련 SQL만 노출한다.

5. 코드 구조

구성	역할
`DataCatalog`	승인 객체 조회 인터페이스
`EnvironmentDataCatalog`	환경 JSON 파싱, 정규화, fail-fast 검증
`MaskingPolicyCatalog`	관리 가능한 Data Redaction 대상 조회
`EnvironmentMaskingPolicyCatalog`	마스킹 환경 JSON 파싱과 검증
`ProductProperties`	제품명, 타이틀, 데이터 표시명
`McpProperties`	공개 URL, 서버명, 단일 Select AI 호환 설정, 복수 도구 JSON
`EnvironmentMcpToolCatalog`	MCP 도구 계약 파싱과 allowlist
`McpSseService`	JSON-RPC와 인증 경계, 설정 기반 도구 dispatch
`SelectAiService`	SHOWSQL 생성, 읽기 전용 검증 및 제한 실행
`SecuritySqlScriptProperties`	보안 SQL allowlist

고객사별 이름과 객체는 application.yml의 환경 매핑과 운영 env에만 둔다. HMM의 DB 매퍼와 VPD 함수는 HMM 업무 모델 자체이므로 이번 공통화 대상이 아니다.

6. TABLE/VIEW 메타데이터

all_tab_comments, all_tab_columns, all_col_comments는 TABLE/VIEW 공통 조회에 쓴다.
COMMENT ON TABLE과 COMMENT ON COLUMN은 승인 객체에만 실행한다.
Oracle annotation 조회·변경은 TABLE에만 허용한다.
VIEW를 선택한 경우 annotation 입력 UI를 숨기고 서버도 요청을 거부한다.
화면에는 카탈로그의 objectType과 owner를 표시한다.

7. 운영 이행

기존 /etc/vpd-backoffice.env를 백업한다.
기존 DB 비밀번호와 remember-me secret은 변경하지 않는다.
데이터 카탈로그 6개, 마스킹 정책 4개, MCP 도구 3개, HMM 보안 SQL 목록을 추가한다.
BACKOFFICE_HMM_MCP_PUBLIC_URL은 BACKOFFICE_MCP_PUBLIC_URL로 이전하되 한 릴리스 동안 fallback을 지원한다.
JAR 교체 후 systemd를 재시작한다.
10초 간격으로 health, 로그인, 정형 데이터, 메타데이터, 마스킹, MCP를 확인한다.
실패 시 기존 JAR와 env 백업으로 복구한다.

8. 검증

자동 검증:

카탈로그 정상/빈 값/잘못된 식별자/중복 key/중복 object 테스트
TABLE/VIEW 미리보기 SQL과 row limit 테스트
VIEW annotation 변경 거부 테스트
마스킹 정책 정상/빈 값/중복 테스트
MCP 3개 도구 discovery, 정확한 argument/target dispatch, 인증 거부 테스트
Select AI 안전 SQL 검증 테스트
보안 SQL resource allowlist 테스트
전체 mvn test

운영 검증:

관리자 로그인과 지속 로그인
전체 메뉴 HTTP 200 및 HMM 데이터 표시
정형 데이터 6개 객체 조회
메타데이터 6개 객체 조회
마스킹 정책 4개 상태 조회
MCP 무토큰 401, 잘못된 token 401
임시 사용자 token으로 tools/list와 세 도구 call
서비스 로그에 startup 오류와 비밀정보 출력이 없는지 확인

9. 완료 조건

HMM 백오피스의 고객사별 카탈로그와 표시 설정이 운영 env로 이전되어 있다.
기존 HMM 토큰 인증과 VPD 컨텍스트 적용이 회귀하지 않는다.
Maven 테스트와 운영 전수 검증이 통과한다.
Gitea hmm-backoffice에 #723 커밋이 push되어 있다.
Redmine #723이 Planner부터 Documenter까지 근거와 함께 완료되어 있다.