Files
clean-architecture-backend-…/docs/manual/07-authorization.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

4.9 KiB

07. 권한

핵심

권한 검사는 두 층이다. "이 종류의 작업을 해도 되나"(권한 이름)는 유스케이스의 @RequiresPermission 선언과 web이 켜는 method security가 맡는다. "이 객체를 봐도 되나"(소유자·tenant)는 유스케이스가 객체를 읽은 뒤 직접 판정한다.

요청 ─▶ 인증 필터(JWT 또는 세션) ─▶ AuthenticatedPrincipal(roles, tenant)
     ─▶ 컨트롤러 ─▶ [프록시] RequiresPermissionAuthorizationManager
                        │ role → permission (app.authz.role-permissions)
                        │ 없으면 403, 인증 없으면 401
                     ─▶ 유스케이스 본문 ─▶ 객체 로드 ─▶ 소유자·tenant 판정 ─▶ 남의 것이면 404(존재 숨김)

작업 단위 권한: @RequiresPermission

무엇 어디
선언 src/application-core/src/main/java/dev/caskeleton/application/security/RequiresPermission.java — 쓰기 유스케이스에 필수(MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION)
검사 장치 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/authz/MethodSecurityConfig.java의 advisor
켜는 곳 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java
역할 → 권한 app.authz.role-permissions (src/app-bootstrap/src/main/resources/config/security.yml), 바인딩 RolePermissionPolicy
프록시 가능 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java

검사 자동 설정은 인증 체인(WebSecurityAutoConfiguration)과 분리되어 있다. 서비스가 자기 인증 방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(1라운드 07-03 수정).

지켜야 할 것 셋

  1. 유스케이스는 bean이다. 직접 new 하면 프록시가 없어 선언이 주석이 된다.
  2. 유스케이스 클래스와 그 public 메서드는 final이 아니다. final이면 프록시를 못 만들어 기동이 실패한다.
  3. 유스케이스 안에서 자기 다른 메서드를 부르면(self-invocation) 프록시를 거치지 않는다. 권한이 다른 두 작업은 유스케이스 둘로 나눈다.

판단: 권한 이름과 역할 매핑

  • 고르는 기준: 운영자가 따로 주고 뺄 필요가 있는 작업인가.
  • 기본값: <resource>:<action>, resource는 kebab-case(purchase-order:create). 생성 명령은 <f>:create 하나를 만든다. 역할 매핑은 권한을 명시적으로 나열한다(와일드카드 없음).
  • 예외: 같은 역할이 항상 함께 가지는 작업은 한 역할에 여러 권한을 준다 (operation-submit: operation:submit,operation:cancel).
  • 매핑하지 않은 권한은 아무도 갖지 않는다. 새 기능의 쓰기는 매핑 전까지 모두 403이다 — 실수로 열리지 않는 쪽.
  • 읽기 유스케이스는 선언이 필수가 아니다. 인증된 누구나 읽으면 안 되는 데이터면 선언하거나 객체 판정을 둔다.

역할은 어디서 오나

JWT의 realm_access.roles와 자기 client(app.security.audience)의 resource_access.<client>.roles만 읽는다. audience는 필수다(1라운드 02-03 수정). 같은 issuer의 다른 client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지 않는다(JwtToAuthenticatedPrincipalConverter, docs/runbooks/auth-audience-mismatch.md).

객체 단위 권한

  • 고르는 기준: 같은 권한을 가진 두 사람이 같은 객체에 대해 다른 답을 받아야 하는가(소유자, tenant).
  • 기본값: 유스케이스가 객체를 읽은 뒤 판정하고, 남의 것이면 없는 것과 같은 404로 답한다. 존재 여부도 정보다. 예: GetDurableOperationUseCase와 DurableOperationAccessPolicy (src/application-core/src/main/java/dev/caskeleton/application/operation/).
  • 예외: 여러 전송이 같은 판정을 써야 하거나 목록에서 한 번에 판정해야 하면 ObjectAccessPolicy(src/application-core/src/main/java/dev/caskeleton/application/security/ObjectAccessPolicy.java, batch 메서드로 N+1 회피)를 구현한다. 존재를 숨길 필요가 없는 관리 화면은 403도 된다.
  • tenant: 인증 정보에서만 만든 TenantId를 command에 싣는다. 요청 본문의 tenant 값을 믿지 않는다.

지금 확인되지 않는 것

  • web이 빠진 조립(gRPC 전용·배치 전용)에서는 advisor가 없어 선언이 검사되지 않는다. 이때 기동을 막는 장치는 아직 없다(리뷰 01-06). web 없이 조립하는 서비스는 그 전에 이 문제를 먼저 푼다.

지금 이해하면 되는 것

  • 쓰기 = @RequiresPermission + non-final + bean + 역할 매핑.
  • 객체 판정은 유스케이스 안, 남의 것은 404.
  • 역할은 자기 client 것만 읽는다.