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

1.9 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — AUTH_CLAIM_MAPPING_FAILED (클레임 매핑 실패) AUTH
AUTH_CLAIM_MAPPING_FAILED
P2 oncall 2026-11-13 초안

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였다.


초안: 서비스가 도메인을 채운 뒤 본문을 쓴다.