OAuth 2.0 표준 준수 명세

대상: 고객사 보안·감사·조달팀 / MCP 클라이언트 개발자 버전: 2026-07-25 기준 참고: MCP 전반 준수는 별도 문서 MCP 표준 준수 명세

WRKS MCP Hub 가 어떤 표준 (RFC) 을 준수하고, 어떤 부분에서 의도적으로 확장·비준수 하는지 정리한 문서. 대기업 조달 시 "OAuth 구현이 표준 준수하냐" 문의에 대한 근거 자료이자, MCP 클라이언트 (WRKS AI 등) 개발자가 통합 시 참조.

1. 한 눈에 요약

WRKS MCP Hub 는 OAuth 2.0 Authorization Server 역할 을 하면서 동시에 고객사 사내 OAuth 앱 (Google Workspace / Microsoft Entra ID 등) 의 broker 로 동작합니다. MCP 표준 (2025-11-25 revision) 인증 요구사항을 준수하며, 브라우저를 통한 사용자별 로그인 (per-user) 과 서비스 계정 (M2M) 방식을 모두 지원.

2. 준수 표준 (Compliance Matrix)

2-1. PKCE 세부 (RFC 7636 §4.6 준수 이유)

Hub 은 MCP 클라이언트 (WRKS AI) 에게 PKCE S256 을 필수 강제합니다. 반면 Hub 이 upstream (Google / Entra ID) 에게 요청 시에는 PKCE 파라미터를 forward 하지 않습니다. 이유:

• MCP 클라이언트 ↔ Hub 레이어: 클라이언트가 verifier 를 만들고 관리 → PKCE 유효
• Hub ↔ upstream 레이어: Hub 은 confidential client (client_secret 보유) 라 PKCE 불필요. 만약 MCP 클라이언트의 challenge 를 upstream 에 forward 하면 Hub 이 verifier 를 몰라 token 교환 시 invalid_grant: Missing code verifier 로 실패 — RFC 7636 §4.6 (server behavior) 대로

2-2. RFC 8707 Resource Indicators (lenient 모드)

MCP 2025-11-25 spec 은 client 에게 resource 파라미터를 authorize/token 요청 시 필수로 붙이라 요구. Hub 은:

• resource 있으면: 이 endpoint 의 canonical URI 와 매치 검증. 불일치 시 400 invalid_target (confused deputy 방어)
• resource 없으면: backward-compat 로 통과. 아직 대응 안 한 client 를 즉시 breaking 시키지 않음
• Audience binding 자체는 우리 endpoint scoping 으로 이미 강제 (한 endpoint 의 token 은 다른 endpoint 에서 못 씀)
• Metadata 응답에 resource_indicators_supported: true 광고

향후 클라이언트 대응 진행되면 strict 모드로 전환 예정.

3. 확장 · 우리만의 설계

RFC 에 없지만 MCP 사용 패턴을 지원하기 위해 추가한 확장:

3-1. Endpoint-scoped Authorization Server

각 MCP endpoint (slug) 를 독립 OAuth AS 로 취급. issuer = https://mcp-hub.wrks.ai/mcp/<slug> 형식. 이유:

• Multi-tenant 격리 — 한 endpoint 의 client_id 로 다른 endpoint 진입 불가
• MCP 클라이언트 관점에서 endpoint 마다 다른 IdP 처럼 동작 (실제로도 각 endpoint 가 다른 upstream 을 가리킬 수 있음)

3-2. Upstream OAuth Broker

Hub 이 broker 로 동작해 MCP 클라이언트가 upstream (Google 등) 을 직접 몰라도 됨:

• MCP 클라이언트: Hub 만 OAuth AS 로 인식
• Hub: upstream authorize URL 로 redirect + callback 수신 + code 교환
• 사용자 브라우저: Hub → upstream → Hub 왕복 (표준 OAuth flow)

Google 대응 시 access_type=offline + prompt=consent 자동 세팅 (refresh_token 확보), Entra ID 는 offline_access scope 필수 (사용자 설정).

3-3. 4-tier Architecture

일반 3-tier OAuth (Client → AS → Resource) 와 다른 4-tier 구조:

MCP Client  ↔  Hub (public SaaS)  ↔  Connector (고객 사내망)  ↔  Upstream IdP + API

• Hub 자체는 고객 IdP · client_secret 을 저장하지 않음 — 커넥터 host 에만 존재
• Upstream token 교환 · refresh 는 커넥터가 수행 (Hub 이 터널로 위임)
• 데이터 residency: 고객 credential 이 SaaS 경계를 넘지 않음

3-4. Token 저장 · 암호화

• Upstream (Google / Entra ID) access_token · refresh_token 은 AEAD (Authenticated Encryption with Associated Data) 방식으로 암호화 저장. Key rotation 지원
• 개별 토큰별로 서로 다른 암호화 컨텍스트 사용 — 한 토큰 유출로 다른 토큰 복호화 불가
• Hub 발급 access_token 은 SHA-256 해시만 저장, 평문 X

4. 의도적 비준수 / 제한

투명성을 위해 준수 안 하는 부분도 명시:

5. 보안 부가 정보

5-1. 전송 보안

• MCP 클라이언트 ↔ Hub: TLS 1.2+
• Hub ↔ 커넥터: mTLS (상호 TLS 인증서 검증) + WebSocket over TLS
• 커넥터 ↔ 고객 백엔드: 고객 정책 (내부망이면 HTTP 도 허용, public 이면 HTTPS 강제)

5-2. 인증서 관리

• 커넥터 페어링: 짧은 수명 pairing token (한 번만 사용) 으로 client 인증서 발급
• 인증서 rotation: 커넥터 재시작 시 자동 갱신 요청 (신원 검증 후)
• Fatal close codes 로 revoke 즉시 반영

5-3. Rate Limiting

OAuth flow 남용 방지:

• Authorize endpoint: IP + endpoint 조합으로 rate limit
• DCR endpoint: endpoint 별 신규 등록 rate limit
• Token endpoint: client_id 별 rate limit

5-4. 감사 로그

모든 OAuth 이벤트 (issue / rotate / revoke) 는 append-only 로 기록. 90일 보관 (기본).

6. 준수 검증 방법

고객사 감사팀이 직접 확인 가능한 방법:

6-1. Metadata 응답 검증

curl https://mcp-hub.wrks.ai/.well-known/oauth-authorization-server/mcp/<slug>

RFC 8414 §3 이 요구하는 모든 필드 (issuer, authorization_endpoint, token_endpoint, grant_types_supported, code_challenge_methods_supported) + resource_indicators_supported: true 응답 확인.

6-2. Protected Resource Metadata 검증

curl https://mcp-hub.wrks.ai/.well-known/oauth-protected-resource/mcp/<slug>

RFC 9728 §2 응답 형식 준수 확인.

6-3. WWW-Authenticate 헤더 검증

curl -i https://mcp-hub.wrks.ai/mcp/<slug>

401 응답에 WWW-Authenticate: Bearer error="...", resource_metadata="..." 헤더 포함 확인.

6-4. PKCE S256 강제 검증

Authorization URL 에 code_challenge_method=plain 으로 요청 시 400 pkce_S256_required 반환 확인.

6-5. DCR 검증

curl -X POST https://mcp-hub.wrks.ai/oauth/<slug>/register \
  -H 'Content-Type: application/json' \
  -d '{"redirect_uris":["https://example.com/cb"],"token_endpoint_auth_method":"client_secret_basic"}'

201 응답 + client_id / client_secret 반환 확인.

6-6. Resource Indicators (RFC 8707) 검증

# 다른 endpoint 대상 resource 로 authorize 시도 → 400 invalid_target
curl -i "https://mcp-hub.wrks.ai/oauth/<slug>/authorize?client_id=x&redirect_uri=https://example.com&state=s&code_challenge=$(head -c 32 /dev/urandom | base64 | tr '+/' '-_' | tr -d '=')&code_challenge_method=S256&resource=https://mcp-hub.wrks.ai/mcp/<다른-slug>"

7. 인증·인가 흐름 요약도

[사용자 브라우저]
      │
      │  ① 도구 호출 → WRKS AI 가 로그인 필요 판단
      ▼
[WRKS AI (MCP client)]
      │
      │  ② DCR 로 client_id 자동 발급
      │  ③ authorize URL 로 브라우저 redirect (resource 파라미터 포함 권장)
      ▼
[Hub 의 authorize endpoint]
      │
      │  ④ 요청 상태 저장 (state + PKCE challenge + resource 검증)
      │  ⑤ upstream authorize URL 로 302
      ▼
[사내 IdP (Google / Entra ID)]
      │
      │  ⑥ 사용자 로그인 + 권한 승인
      │  ⑦ callback URL 로 code 반환
      ▼
[Hub 의 callback endpoint]
      │
      │  ⑧ 커넥터 터널로 code 교환 요청
      ▼
[커넥터 (사내망)]
      │
      │  ⑨ upstream `/token` 호출 (client_secret 사용)
      │  ⑩ access + refresh token 획득
      ▼
[Hub]
      │
      │  ⑪ 암호화 저장 (개별 컨텍스트로 격리)
      │  ⑫ Hub 자체 code 발급 → WRKS AI callback 으로 리다이렉트
      ▼
[WRKS AI]
      │
      │  ⑬ Hub `/token` 으로 access token 획득 (resource 파라미터 포함 권장)
      │  ⑭ 도구 호출 시 Authorization: Bearer 로 사용
      ▼
[정상 도구 사용 시작]

8. 추가 자료

• MCP 전반 표준 준수: MCP 표준 준수 명세
• 심화 위협 모델 · 사고 대응 절차 · pen test 체크리스트: 별도 문서로 감사 요청 시 전달 (내부 아키텍처 세부 포함으로 공개 배포 X)
• 문의: WRKS 담당자