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행.
37 lines
6.5 KiB
Markdown
37 lines
6.5 KiB
Markdown
# 업그레이드 안내 — 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` 「한계」). 이 규칙을 이번에 문서로 적었다.
|