refs #712: authenticate backoffice MCP user tokens

2026-07-23 14:45:18 +09:00
parent ce4b418603
commit 1917df09a2
18 changed files with 525 additions and 37 deletions
--- a/docs/design/702-hmm-backoffice-identity/README.md
+++ b/docs/design/702-hmm-backoffice-identity/README.md
@@ -75,7 +75,7 @@ HMM_KNOWLEDGE_DOCUMENTS ──< HMM_KNOWLEDGE_CHUNKS ──< HMM_KNOWLEDGE_TAGS
 ## HMM MCP 및 시스템 설정

 - 운영 MCP 주소는 환경변수 `BACKOFFICE_HMM_MCP_PUBLIC_URL`로 관리하며 기본값은
-  `https://hmm-mcp.cloud-handson.com/mcp`이다. 시스템 설정과 MCP 연동 화면은 이 값을 표시하므로
+  사용자 토큰용 주소는 `https://hmm-backoffice.cloud-handson.com/mcp`이다. 시스템 설정과 MCP 연동 화면은 이 값을 표시하므로
  도메인 변경 시 화면 소스를 수정하지 않는다.
 - HMM MCP와 백오피스 호환 `/mcp`는 동일하게 `resolve_hr_term`, `search_hr_data`,
  `search_hr_policy`를 제공한다. 각각 `HMM_HR_TERM_RESOLVER`,
--- a/docs/design/712-hmm-backoffice-mcp-bearer/README.md
+++ b/docs/design/712-hmm-backoffice-mcp-bearer/README.md
@@ -0,0 +1,78 @@
+# HMM 백오피스 MCP 사용자 Bearer 인증 설계 (#712)
+
+> 상태: 구현·배포·검증 완료
+> 대상: `https://hmm-backoffice.cloud-handson.com/mcp`
+> 브랜치: `hmm-backoffice`
+
+## 목적
+
+HMM 백오피스에서 발급한 `vpd_live_*` 사용자 토큰을 MCP의 실제 인증 수단으로 사용한다.
+현재 별도 호스트의 `https://hmm-mcp.cloud-handson.com/mcp`는 서버 공용 게이트웨이 토큰만
+허용하므로 사용자 토큰을 보내면 Nginx에서 HTTP 401을 반환한다. 사용자별 HMM 데모는
+백오피스 MCP 주소를 사용해야 한다.
+
+## 확인된 현행 결함
+
+- 백오피스의 `/mcp`는 `initialize`, `tools/list`, `tools/call`을 제공한다.
+- Controller가 `Authorization: Bearer` 값을 추출하지만 Service의
+  `ignoredAuthorization` 인자로 전달해 검증하지 않는다.
+- Tool 실행은 토큰 사용자 컨텍스트를 설정하지 않고 백오피스 JDBC 계정으로 바로
+  `DBMS_CLOUD_AI_AGENT.RUN_TOOL`을 호출한다.
+- 따라서 주소를 올바르게 사용해도 토큰이 인증과 행 접근 문맥에 연결되지 않는다.
+
+## 변경 설계
+
+```text
+Private Agent Factory
+  → POST https://hmm-backoffice.cloud-handson.com/mcp
+  → Authorization: Bearer <vpd_live 사용자 토큰>
+  → HMM_ACCESS_BEARER_TOKENS SHA-256/만료/회수/재직 검증
+  → 동일 JDBC connection에서 HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER
+  → DBMS_CLOUD_AI_AGENT.RUN_TOOL
+  → finally HMM_ACCESS_CTX_PKG.CLEAR_USER
+```
+
+1. 모든 MCP method는 활성 사용자 Bearer를 요구한다. 누락·오류·만료·회수 토큰은 HTTP 401로
+   fail-closed한다.
+2. 원문 토큰은 로그, 응답, DB, Git에 기록하지 않는다. DB에는 기존 SHA-256 해시만 사용한다.
+3. `tools/call`은 토큰 검증과 Tool 실행을 같은 요청에서 수행한다.
+4. Tool 실행 connection에는 컨텍스트를 설정하고 성공·실패와 무관하게 `finally`에서 지운다.
+5. `initialize`와 `tools/list`도 토큰을 검증해 discovery만으로 인증을 우회할 수 없게 한다.
+
+## Agent Factory 설정
+
+| 항목 | 값 |
+|---|---|
+| Server URL | `https://hmm-backoffice.cloud-handson.com/mcp` |
+| Authentication mode | `Bearer Token` |
+| Bearer token | 백오피스에서 발급한 토큰 원문만 입력 (`Bearer ` 접두어 제외) |
+
+별도 서버 `https://hmm-mcp.cloud-handson.com/mcp`에는 사용자 토큰을 사용하지 않는다. 그 주소는
+운영 `HMM_MCP_BEARER_TOKEN`을 사용하는 호환 게이트웨이다.
+
+## 완료 기준
+
+- 활성 사용자 토큰으로 `initialize`, `tools/list`, 세 Tool 호출이 성공한다.
+- 누락·무효·회수 토큰은 HTTP 401이다.
+- Tool 호출 전후 DB context 설정·정리가 자동 테스트로 검증된다.
+- 운영 배포 후 외부 HTTPS에서 discovery와 대표 Tool 호출을 검증한다.
+- 토큰 원문이나 해시는 테스트 출력과 문서에 남지 않는다.
+
+## 배포 검증 결과
+
+2026-07-23 운영 배포에서 다음을 확인했다.
+
+- 자동 테스트 107건 통과
+- 운영 JAR과 검증 빌드 SHA-256 일치
+- 무토큰 `initialize`, `tools/list`: HTTP 401
+- 활성 E1002 임시 사용자 토큰:
+  - `initialize`: HTTP 200
+  - `tools/list`: HTTP 200
+  - `resolve_hr_term`: HTTP 200, 정상 MCP result
+  - 발견 도구: `resolve_hr_term`, `search_hr_data`, `search_hr_policy`
+- 같은 토큰을 회수한 직후 `tools/list`: HTTP 401
+- 검증 중 발급한 임시 토큰과 이전 실패 시 남은 임시 토큰을 모두 회수
+- 백오피스 시스템 설정과 MCP 서비스 화면의 Agent Factory 주소를
+  `https://hmm-backoffice.cloud-handson.com/mcp`로 변경
+
+상세 증거는 `docs/reports/2026-07-23-hmm-backoffice-mcp-bearer-verification.md`에 기록한다.
--- a/docs/reports/2026-07-23-hmm-backoffice-mcp-bearer-verification.md
+++ b/docs/reports/2026-07-23-hmm-backoffice-mcp-bearer-verification.md
@@ -0,0 +1,60 @@
+# HMM 백오피스 MCP 사용자 Bearer 검증 보고서
+
+- 일자: 2026-07-23
+- Redmine: #712
+- 브랜치: `hmm-backoffice`
+- 서비스: `https://hmm-backoffice.cloud-handson.com/mcp`
+
+## 원인
+
+백오피스에서 발급한 `vpd_live_*` 직원 토큰을 별도 호환 서버인
+`https://hmm-mcp.cloud-handson.com/mcp`에 보냈다. 이 서버의 Nginx는 운영 공용
+`HMM_MCP_BEARER_TOKEN` 한 개만 비교하므로, 직원 토큰에서 `Bearer ` 문자열을 제거해도 HTTP 401이
+정상이다.
+
+직원 토큰용 주소는 `https://hmm-backoffice.cloud-handson.com/mcp`다. 조사 시 이 경로는 MCP 도구를
+제공했지만 Authorization 값을 실제로 검증하지 않고 버리는 결함도 확인됐다.
+
+## 수정
+
+- 모든 MCP method에서 `HMM_ACCESS_BEARER_TOKENS`의 SHA-256 해시, 만료, 회수, 직원 재직 상태 검증
+- 누락·무효·만료·회수 토큰은 HTTP 401
+- Tool 호출 connection에서 `HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER` 실행
+- 같은 connection에서 `DBMS_CLOUD_AI_AGENT.RUN_TOOL` 실행
+- 성공·실패와 무관하게 `finally`에서 `HMM_ACCESS_CTX_PKG.CLEAR_USER`
+- Agent Factory 표시 주소를 백오피스 MCP 주소로 수정
+- 공용 gateway와 직원 VPD endpoint의 주소·토큰 조합을 운영 문서에서 분리
+
+토큰 원문은 Controller에서 `Bearer ` 접두어만 제거해 전달하며 로그·응답·DB에 기록하지 않는다.
+DB에는 기존 SHA-256 해시와 식별용 prefix만 남는다.
+
+## 검증
+
+| 항목 | 결과 |
+|---|---|
+| Maven 자동 테스트 | 107건 통과 |
+| 같은 JDBC connection의 context 설정·Tool 실행·context 정리 | 단위 테스트 통과 |
+| 운영 JAR SHA-256 | 로컬 검증 빌드와 일치 |
+| 서비스 | `vpd-backoffice.service` active |
+| 로그인 상태 | HTTP 200 |
+| 무토큰 MCP | HTTP 401 |
+| 활성 E1002 임시 토큰 initialize | HTTP 200 |
+| 활성 E1002 임시 토큰 tools/list | HTTP 200 |
+| Tool discovery | HMM Tool 3개 |
+| `resolve_hr_term` Tool 호출 | HTTP 200 / MCP result 성공 |
+| 회수 후 같은 토큰 | HTTP 401 |
+
+검증용 토큰은 백오피스의 정상 발급 흐름으로 만들고 원문을 출력하지 않았다. 검증 완료 시 즉시
+회수했으며, 이전 실패 과정에서 남은 같은 용도의 임시 토큰 한 건도 함께 회수했다.
+
+## Agent Factory 최종 입력
+
+| 항목 | 값 |
+|---|---|
+| Server name | `hmm-backoffice-mcp` |
+| Server URL | `https://hmm-backoffice.cloud-handson.com/mcp` |
+| Authentication mode | `Bearer Token` |
+| Bearer token | 백오피스 발급 토큰 원문만 입력 |
+
+Token 입력란에 `Bearer ` 접두어를 직접 쓰지 않는다. Agent Factory가 HTTP
+`Authorization: Bearer <token>` 헤더를 조립한다. OAuth URL과 client ID/secret은 사용하지 않는다.
--- a/docs/runbooks/hmm-mcp-token-configuration.md
+++ b/docs/runbooks/hmm-mcp-token-configuration.md
@@ -0,0 +1,140 @@
+# HMM MCP endpoint와 토큰 설정
+
+## 인증 수단 구분
+
+HMM 포털 로그인과 MCP 호출은 서로 다른 인증 수단을 사용한다.
+
+| 인증 수단 | 사용 위치 | 전달 방식 | MCP 호출 사용 여부 |
+|---|---|---|---|
+| `__Host-HMM_PORTAL_SESSION` | `hmm.cloud-handson.com` 포털 로그인 | 브라우저 `Secure; HttpOnly` 쿠키 | 사용 금지 |
+| `HMM_MCP_BEARER_TOKEN` | 별도 호환 MCP 서버 접근 | HTTP `Authorization: Bearer` | 포털의 공용 gateway에 사용 |
+| HMM 직원별 VPD 토큰 | 백오피스 MCP 사용자 인증·DB context | HTTP `Authorization: Bearer` | Agent Factory 사용자별 연동에 사용 |
+
+포털 쿠키를 복사해 MCP Bearer Token으로 사용하면 안 된다. 브라우저 JavaScript에서도 포털 쿠키를
+읽을 수 없도록 `HttpOnly`로 설정한다.
+
+## MCP endpoint 구분
+
+두 주소는 같은 토큰을 받지 않는다.
+
+| 항목 | 값 |
+|---|---|
+| 사용자별 VPD MCP | `https://hmm-backoffice.cloud-handson.com/mcp` |
+| 사용자별 인증 | 백오피스에서 발급한 `vpd_live_*` 토큰 원문 |
+| 공용 호환 MCP | `https://hmm-mcp.cloud-handson.com/mcp` |
+| 공용 인증 | 운영 `HMM_MCP_BEARER_TOKEN` |
+| Transport | Streamable HTTP POST |
+
+허용 도구는 다음 세 개다.
+
+| 도구 | 주요 인자 | 용도 |
+|---|---|---|
+| `search_hr_data` | `query` | 조직, 직원, 휴가 잔여·신청, 근태 조회 |
+| `resolve_hr_term` | `term` | 휴가·근태 표현을 표준 용어와 코드로 변환 |
+| `search_hr_policy` | `query` | HR 규정 PDF 지식 검색 |
+
+## 포털의 현재 공용 토큰 조합
+
+`config/vpd_token_presets.json`의 현재 조합은 다음과 같다.
+
+| 데모 사용자 | 역할 | `mcp_token_env` |
+|---|---|---|
+| E1001 Kim Minseo | HR Team Manager | `HMM_MCP_BEARER_TOKEN` |
+| E1002 Lee Jiwon | HR Operations Specialist | `HMM_MCP_BEARER_TOKEN` |
+| E1003 Park Dohyun | People Analytics Analyst | `HMM_MCP_BEARER_TOKEN` |
+| E1005 Han Seojun | Recruiting Specialist | `HMM_MCP_BEARER_TOKEN` |
+| E1007 Kang Minho | HR Coordinator | `HMM_MCP_BEARER_TOKEN` |
+
+현재는 모든 preset이 같은 서버 관리 토큰을 쓴다. preset을 바꾸면 질문에 포함되는 데모 사용자
+문맥은 바뀌지만, Bearer Token 자체는 바뀌지 않는다. 따라서 이 조합만으로는 사용자별 VPD
+보안 경계를 만들지 못한다.
+
+## 포털 설정
+
+`config/mcp_servers.json`에는 토큰 원문 대신 환경변수 이름만 기록한다.
+
+```json
+{
+  "id": "hmm_hr_mcp",
+  "endpoint_url": "https://hmm-mcp.cloud-handson.com/mcp",
+  "auth_token_env": "HMM_MCP_BEARER_TOKEN",
+  "tool_allowlist": [
+    "search_hr_data",
+    "resolve_hr_term",
+    "search_hr_policy"
+  ]
+}
+```
+
+운영 서버 `/opt/hmm-poc4/.env`에 실제 값이 있어야 한다.
+
+```dotenv
+HMM_MCP_BEARER_TOKEN=<MCP 서버에 등록된 동일한 임의 토큰>
+POC3_MCP_TIMEOUT_SECONDS=45
+```
+
+토큰 원문은 JSON, Git, 대화 기록, 화면 상세에 저장하지 않는다. 환경 파일은 운영 계정만 읽을
+수 있게 제한한다.
+
+## 사용자 VPD MCP 직접 호출 예시
+
+```bash
+export HMM_USER_BEARER_TOKEN='<백오피스 발급 화면에서 한 번 표시된 원문>'
+
+curl --fail-with-body \
+  -H "Authorization: Bearer ${HMM_USER_BEARER_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  --data '{
+    "jsonrpc": "2.0",
+    "id": "tools-list-1",
+    "method": "tools/list",
+    "params": {}
+  }' \
+  https://hmm-backoffice.cloud-handson.com/mcp
+
+unset HMM_USER_BEARER_TOKEN
+```
+
+MCP 서버가 `initialize`와 session ID를 요구하면 다음 순서를 사용한다.
+
+1. `initialize`
+2. 응답의 `Mcp-Session-Id` 보관
+3. `notifications/initialized`
+4. 같은 session header와 Bearer Token으로 `tools/list`
+5. 같은 session header와 Bearer Token으로 `tools/call`
+
+## Oracle AI Database Private Agent Factory 설정
+
+| 입력 항목 | 값 |
+|---|---|
+| Server name | `hmm-backoffice-mcp` |
+| Server URL | `https://hmm-backoffice.cloud-handson.com/mcp` |
+| Authentication mode | Bearer Token |
+| Token | 백오피스에서 해당 직원에게 발급한 토큰 원문. `Bearer ` 문자열은 붙이지 않음 |
+| Allowed tools | 위 세 도구만 선택 |
+| Timeout | 45초부터 시작 |
+
+이 endpoint는 OAuth authorization endpoint가 아니다. OAuth client ID, client secret,
+authorization URL, token URL은 입력하지 않는다.
+
+## 사용자별 VPD 적용 구조
+
+MCP의 표준 `Authorization` header는 하나이므로 “공통 gateway token + 직원 VPD token” 두 개를
+같은 header에 조합하지 않는다. 다음 구조가 권장된다.
+
+1. 백오피스에서 E1001, E1002 등 직원별 opaque token을 각각 발급한다.
+2. MCP 서버는 그 직원 token 자체를 Bearer Token으로 검증한다.
+3. 검증된 같은 token으로 DB 연결에서
+   `ADMIN.HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER(:token)`을 호출한다.
+4. 같은 DB 세션에서 `HMM_LEAVE_BALANCES`, `HMM_LEAVE_REQUESTS`를 조회한다.
+5. `finally`에서 context를 초기화하고 connection pool에 반환한다.
+6. 서버 관리용 공통 토큰과 직원별 토큰을 동시에 요구해야 한다면 OAuth/API Gateway에서
+   application identity와 user subject를 하나의 검증 가능한 access token으로 합친다.
+
+이 흐름은 2026-07-23 백오피스 MCP에 적용됐다. 모든 MCP method가 토큰 해시·만료·회수·재직
+상태를 확인하며, Tool 호출은 같은 JDBC connection에서 `HMM_ACCESS_CTX_PKG.SET_USER_BY_BEARER`
+후 실행하고 `finally`에서 context를 지운다. 무토큰·무효·회수 토큰은 HTTP 401이다.
+
+포털의 `HMM_MCP_BEARER_TOKEN` 공용 preset은 별도 호환 gateway를 사용하는 기존 UI 라우팅이다.
+Agent Factory의 사용자별 권한 검증에는 반드시 백오피스 MCP 주소와 직원 토큰을 사용한다.