Files
clean-architecture-backend-…/docs/runbooks/auth-claim-mapping-failed.md
T
DongHyeonka 2f0aefadee fix(security)!: 모든 전송이 같은 호출자로 권한을 판정하고 JWT·tenant 빈틈을 막는다
@RequiresPermission이 web 밖에서 늘 거부한다. gRPC·STOMP는 인증한
호출자를 SecurityContext에 넣지 않아 권한 있는 호출자도 거부되고, 거부는
web 403, gRPC INTERNAL+ERROR, GraphQL 가린 INTERNAL_ERROR+ERROR로 갈린다.
GraphQL 정책은 하위 좌표(User.salary) 규칙을 받고 판정하지 않는다. 배포
jar가 SPRING_PROFILES_ACTIVE=test로 떠 prod 검사가 꺼진다. JWT 변환은
최상위 roles claim을 권한으로 읽고, sub 없는 token을 통과시켜 뒤에서 500이
되고, 틀린 tenant claim을 AUTH_TOKEN_MALFORMED로 본다. 모르는 profile의
알림 callback은 500+ERROR이고 공격자 문자열을 감사 WARN에 남긴다. patch
거부는 요청이 쓴 이름을 제한 없이 되풀이한다. tenant 입력 이름 거부가
web·GraphQL에서 갈리고, 익명 GraphQL tenant 출처가 SYSTEM이다. STOMP
거부는 자기 로그가 없고 설정 주석이 순서를 틀리게 적는다.

- AuthorizationDeniedException을 AUTHZ_INSUFFICIENT_PERMISSION carrier로
  만들고 method security가 그것을 그대로 던진다. 전송마다 이미 있는
  carrier 대응이 같은 코드로 답한다(gRPC PERMISSION_DENIED, GraphQL
  FORBIDDEN). 버린 안: 전송마다 AccessDeniedException 대응 추가(네 곳에
  같은 표를 둔다).
- gRPC listener callback과 STOMP frame 처리 동안 호출자를 SecurityContext에
  둔다(spring-security-core 의존, lockfile 갱신). Authentication이면
  그대로, 아니면 권한 없는 인증 token이다. 역할은 AuthenticatedPrincipal
  에서만 읽는다.
- GraphQL 실행 전 판정이 fragment를 한 번씩 펼치며 typed parent로 좌표를
  모은다. root는 늘, 하위 좌표는 규칙이 있을 때 판정하고 interface·구현
  좌표의 규칙도 본다.
- 배포 산출물은 test profile을 기동 실패로 거부한다.
- JWT: 최상위 roles를 버리고, sub 없음·틀린 tenant는 401
  AUTH_CLAIM_MAPPING_FAILED다.
- callback은 profile을 먼저 찾고 없으면 감사 없이 400이다
  (ProviderCallbackAdapterRegistry.require → find).
- patch 거부는 이름을 16개·128자·안전 문자만 되풀이한다.
- tenant 입력 이름 어휘를 TenantId.namesATenant 하나로 모으고, 익명
  GraphQL 출처를 ANONYMOUS로 둔다(값 public, 거부는 하지 않는다 — 공개
  DataLoader가 그 tenant로 돈다).
- STOMP 거부는 사유·command만 담은 WARN 한 줄을 남긴다(session id는
  SockJS가 client URL에서 받아 뺀다).
- 고치며 찾음: decoder를 만든 뒤 JWKS 재조회를 IdP가 받지 않으면 라이브러리
  문구("…decode the Jwt: <HTTP 오류>") 때문에 401 AUTH_TOKEN_MALFORMED로
  분류됐다. 원인 사슬의 HTTP·I/O 실패를 먼저 보고 503
  AUTH_JWKS_UNAVAILABLE로 답한다.

위험: 응답이 바뀐다(gRPC·GraphQL 거부 코드, sub 없음 401, JWKS 재조회
실패 503, 모르는 callback 400, test profile 기동 실패). 할 일은
docs/upgrade/2026-11-round9-authz.md 1~11행이다. registry 구현은 find를
구현해야 컴파일된다.

검증: desktop에서 바뀐 leaf check·systemTest, :app-bootstrap:test·
architectureTest·documentContractTest, verifyDependencyLocks rc=0. 새
시험은 고치기 전 트리에서 실패했다(RED).

Refs: RR9-02-02, RR9-02-16, RR9-02-17, RR9-02-18, RR9-02-20, RR9-02-23,
  RR9-02-25, RR9-02-28, RR9-02-29
BREAKING CHANGE: gRPC·GraphQL 권한 거부 코드, JWT sub 없음·틀린 tenant
  응답, 모르는 알림 callback 응답, test profile 기동, registry require→find
  가 바뀐다. 옮기는 법은 docs/upgrade/2026-11-round9-authz.md 1~11행.
2026-11-13 12:24:54 +09:00

45 lines
1.9 KiB
Markdown

---
title: Runbook — AUTH_CLAIM_MAPPING_FAILED (클레임 매핑 실패)
category: AUTH
error_codes: [AUTH_CLAIM_MAPPING_FAILED]
severity: P2
owner: oncall
last_updated: 2026-11-13
status: 초안
---
# Runbook: AUTH_CLAIM_MAPPING_FAILED (`runbook://auth/claim-mapping-failed`)
## 증상
- HTTP 401, `error.code=AUTH_CLAIM_MAPPING_FAILED`, `WWW-Authenticate: Bearer error="invalid_token"`.
- WARN 로그 줄 `security failure: code=AUTH_CLAIM_MAPPING_FAILED category=AUTH method=… path=…`(logger
`AuthErrorResponseWriter`).
- 서명·issuer·audience·만료 검증은 통과했지만 principal을 만들 수 없다: `sub` claim이 없거나 비었다, 또는
`tenant_id` claim이 있는데 tenant 문법(`TenantId.GRAMMAR`)에 맞지 않는다(`JwtToAuthenticatedPrincipalConverter`).
- 역할 claim이 없는 것은 이 코드가 아니다. 역할 없는 사용자는 인증되고, 권한이 필요한 쓰기에서 403
`AUTHZ_INSUFFICIENT_PERMISSION`이 된다.
## 진단
- 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 클라이언트 쪽에서 token을 받아 `sub`와
`tenant_id`를 본다.
- claim 이름은 코드에 고정돼 있다: `sub`, `tenant_id`, 역할은 `realm_access.roles`와 자기 client(`app.security.audience`)의
`resource_access.<client>.roles`. 따로 고칠 claim 대응 설정은 없다.
## 조치
- IdP token 템플릿이 `sub`를 넣는지, `tenant_id`를 넣는다면 문법에 맞는 값인지 고친다.
- IdP가 tenant를 다른 claim에 둔다면 IdP 쪽 mapper로 `tenant_id`에 옮긴다.
## 에스컬레이션
- IdP가 claim 스키마를 바꿨으면 인증 플랫폼 팀에 넘긴다.
> 이력: 2026-11-12 리뷰 전에는 `sub` 없는 token이 통과해 뒤에서 500이 됐고, 틀린 tenant claim은
> `AUTH_TOKEN_MALFORMED`였다.
---
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.