79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# 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`에 기록한다.
|