# 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`에 기록한다.