# 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은 사용하지 않는다.