pr / done (pull_request) Canceled after 0s
GraphQL cursor·connection 예외는 Javadoc이 「안정 요청 오류 코드」라면서 플랫폼 거부가 아니라 INTERNAL_ERROR와 ERROR 로그가 된다. STOMP ERROR frame은 code만 싣고, 원인 사슬 어디에 IllegalArgumentException이 있든 BAD_PARAMETER로 본다(다른 전송은 실패 자신만 본다). STOMP broadcast는 모든 인증 세션에 가는데 projector가 무엇을 실어도 되는지 규칙이 없다. maxInputListElements Javadoc은 실제보다 넓은 상한을 약속한다. - 두 예외를 GraphQlPlatformRejection으로 만들고 GRAPHQL_CURSOR_REJECTED· GRAPHQL_CONNECTION_REJECTED를 catalog에 더한다. - STOMP 오류 처리기는 MessagingException 포장을 벗긴 실패 자신만 IAE로 보고, 등록된 코드면 error-category·error-retryable header를 더한다(gRPC trailer와 같은 이름·값). - broadcast 규칙(모든 tenant의 인증 사용자가 읽어도 되는 것만)을 projector Javadoc·README·AGENTS에 적는다. 버린 안: destination을 tenant별로 나누기(projector가 tenant를 모르고, simple broker는 R1 증거라 범위 밖). - maxInputListElements Javadoc을 실제 검사 범위로 좁힌다. 위험: client가 보는 GraphQL 코드와 STOMP header가 바뀐다. docs/upgrade/2026-11-round9-authz.md 12~13행. 검증: desktop :adapter:inbound:graphql:check·systemTest, :adapter:inbound:websocket:check·systemTest rc=0(묶음 전체 실행). Refs: RR9-02-19, RR9-02-31, RR9-03-14, RR9-03-29 BREAKING CHANGE: GraphQL cursor·connection 거부 코드와 STOMP ERROR frame의 error-code(묻힌 IAE)·새 header. docs/upgrade/2026-11-round9-authz.md 12~13행.
6.5 KiB
6.5 KiB
업그레이드 안내 — 2026-11 인증·인가와 GraphQL·WebSocket 계약
- 범위: 2026-11-12 전체 리뷰의 인증·인가 묶음과 GraphQL·WebSocket 계약 묶음을 고친 변경. JWT 역할·claim 대응, JWKS 재조회 실패의 분류, 배포 산출물의 profile 검사, 알림 callback, GraphQL 인가·tenant·오류 코드, 전송별 권한 판정, STOMP 오류 frame이 바뀌었다.
- 근거: 2026-11-12 전체 리뷰(
docs/reviews/2026-11-12-round9-review/)의 RR9-02-02·16·17·18·19·20·23·25·28·29·31, RR9-03-14·29
1. 누가 읽나
이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 JWT로 인증하는 서비스, gRPC·STOMP·GraphQL에서
@RequiresPermission 유스케이스를 부르는 서비스, web-advanced patch나 GraphQL tenant 정책을 쓰는 서비스다.
2. 할 일
| # | 바뀐 것 | 할 일 | 안 하면 | 해당 서비스 |
|---|---|---|---|---|
| 1 | JWT 최상위 roles claim을 역할로 읽지 않는다. realm_access.roles와 자기 client(app.security.audience)의 resource_access.<client>.roles만 읽는다 |
IdP가 최상위 roles에만 역할을 넣고 있으면 realm role이나 자기 client role로 옮긴다 |
그 역할이 준 권한이 사라져 쓰기가 403이 된다 | JWT 인증 |
| 2 | sub 없는 token, 형식이 틀린 tenant_id claim은 401 AUTH_CLAIM_MAPPING_FAILED다(전에는 sub 없음이 뒤에서 500, 틀린 tenant는 AUTH_TOKEN_MALFORMED) |
경보·대시보드가 틀린 tenant를 AUTH_TOKEN_MALFORMED로 셌으면 새 코드도 센다 |
claim 문제가 「token 깨짐」으로 보인다 | JWT 인증 |
| 3 | decoder를 만든 뒤 JWKS를 다시 받다(모르는 kid, 키 캐시 만료) IdP가 답하지 않으면 503 AUTH_JWKS_UNAVAILABLE(Retry-After: 30)이다(전에는 401 AUTH_TOKEN_MALFORMED) |
경보·대시보드가 이 상황을 AUTH_TOKEN_MALFORMED로 셌으면 AUTH_JWKS_UNAVAILABLE도 센다 |
IdP 장애가 「token 깨짐」으로 보이고 client가 다시 시도하지 않는다 | JWT 인증 |
| 4 | 배포 산출물(CaSkeletonApplication)은 SPRING_PROFILES_ACTIVE에 test가 있으면 기동하지 않는다 |
배포·스테이징 env에서 test를 지우고 local·dev·prod 하나를 쓴다. 시험이 이 main class를 test로 띄우면 local이나 dev로 바꾼다 |
기동이 STARTUP_VALIDATION_FAILED로 멈춘다 |
test profile로 띄우던 서비스 |
| 5 | 권한 거부는 Spring AccessDeniedException이 아니라 AuthorizationDeniedException(AUTHZ_INSUFFICIENT_PERMISSION carrier)으로 나간다. web은 전과 같은 403이다. gRPC는 PERMISSION_DENIED(전에는 INTERNAL), GraphQL은 AUTHZ_INSUFFICIENT_PERMISSION·FORBIDDEN(전에는 INTERNAL_ERROR)이다. STOMP @MessageMapping 안의 거부는 frame을 보내지 않고 로그도 남기지 않는다(4xx carrier, 전에는 ERROR 로그) |
method security 거부를 AccessDeniedException으로 잡던 코드는 AuthorizationDeniedException(또는 ApiErrorCarrier)으로 잡는다 |
그 catch가 거부를 놓친다 | 거부를 직접 잡던 서비스 |
| 6 | gRPC 인증 정책이 돌려준 호출자, STOMP handshake 사용자가 handler가 도는 동안 SecurityContext에 들어간다. Authentication이면 그대로, 아니면 권한 없는 인증 token이다. 역할은 principal이 web의 AuthenticatedPrincipal일 때만 읽힌다 |
gRPC 정책이 JWT를 검증한다면 web의 decoder와 JwtToAuthenticatedPrincipalConverter가 만든 token을 돌려준다 |
gRPC handler가 부른 @RequiresPermission 유스케이스가 역할 없이 거부된다 |
gRPC·STOMP |
| 7 | GraphQL 인가 규칙이 root 아래 좌표(User.salary)도 실행 전에 판정한다. 아래 좌표는 규칙이 있는 것만 판정한다 |
하위 좌표 규칙을 둔 정책이 있으면 그 규칙이 이제 실제로 거부함을 확인한다 | 전에 통과하던 query가 COORDINATE_NOT_AUTHORIZED로 거부된다 |
GraphQL 정책에 하위 좌표 규칙을 둔 서비스 |
| 8 | GraphQL 익명 요청의 tenant 출처가 SYSTEM이 아니라 ANONYMOUS다(값은 그대로 public). GraphQlTenantIsolationPolicy.require(context)의 출처 검사는 늘 통과하던 죽은 코드라 지웠다 |
TenantSource.SYSTEM을 「익명」으로 읽던 코드가 있으면 ANONYMOUS로 바꾼다. 증명된 tenant가 필요한 곳은 출처를 본다 |
익명 요청을 플랫폼 작업으로 잘못 본다 | GraphQL tenant 출처를 읽는 서비스 |
| 9 | tenant를 제안하는 입력 이름을 web-advanced와 GraphQL이 같은 어휘로 거부한다(tenant, tenant_id, tenantId, X-Tenant-Id, 대소문자·-·_ 무관) |
그런 이름의 header·parameter·argument를 쓰던 client를 고친다 | 403 TENANT_INPUT_UNTRUSTED나 GraphQL tenant 거부가 난다 |
tenant 입력 검사를 쓰는 서비스 |
| 10 | PATCH_PATH_FORBIDDEN의 details.refusedPaths는 16개까지, [A-Za-z0-9_.~/-] 128자 이하 이름만 그대로 싣고 나머지는 <not echoed>다 |
그 칸을 화면에 그대로 보이던 client는 대체 문자열을 처리한다 | — | web-advanced patch |
| 11 | 알림 callback: 설정하지 않은 profile로 온 callback은 400이다(전에는 500과 ERROR 로그). ProviderCallbackAdapterRegistry.require가 find(Optional)로 바뀌었다 |
registry를 직접 구현한 서비스는 find를 구현한다 |
컴파일이 실패한다 | 알림 platform |
| 12 | GraphQL cursor·connection 거부가 GRAPHQL_CURSOR_REJECTED·GRAPHQL_CONNECTION_REJECTED 요청 오류다(전에는 INTERNAL_ERROR와 ERROR 로그) |
client가 그 코드로 분기하게 한다 | — | GraphQL pagination API를 쓰는 서비스 |
| 13 | STOMP ERROR frame: 다른 실패의 원인으로 묻힌 IllegalArgumentException은 BAD_PARAMETER가 아니라 WEBSOCKET_REQUEST_REJECTED다. 모든 ERROR frame에 error-retryable header가 붙고, 등록된 코드면 error-category도 붙는다 |
client가 새 header를 읽게 한다 | — | STOMP client |
3. 바뀌지 않은 것
- web의 403 응답(
AUTHZ_INSUFFICIENT_PERMISSION), 401 응답 모양,WWW-Authenticate는 그대로다. @RequiresPermission·역할 매핑 설정 키는 그대로다.- STOMP broadcast는 여전히 destination 하나로 모든 인증된 세션에 간다. 그래서
LiveEventProjector는 모든 tenant의 인증된 사용자가 읽어도 되는 것만 싣는다(src/adapter/inbound/websocket/README.md「한계」). 이 규칙을 이번에 문서로 적었다.