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을 호출한다.
따라서 주소를 올바르게 사용해도 토큰이 인증과 행 접근 문맥에 연결되지 않는다.

변경 설계

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

모든 MCP method는 활성 사용자 Bearer를 요구한다. 누락·오류·만료·회수 토큰은 HTTP 401로 fail-closed한다.
원문 토큰은 로그, 응답, DB, Git에 기록하지 않는다. DB에는 기존 SHA-256 해시만 사용한다.
tools/call은 토큰 검증과 Tool 실행을 같은 요청에서 수행한다.
Tool 실행 connection에는 컨텍스트를 설정하고 성공·실패와 무관하게 finally에서 지운다.
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에 기록한다.