refs #712: authenticate backoffice MCP user tokens

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