Files
clean-architecture-backend-…/docs/manual/07-authorization.md
T
DongHyeonka f40c03c6d3 fix: 3차 확인 리뷰의 Minor 19건을 고친다
문제: 3차 수정의 확인 리뷰가 새 Important 없이 Minor 19건을 남겼다.
동작에 닿는 것이 셋이다. JDK read-idle watchdog이 공용 ForkJoinPool에서
돌아 그 풀이 바쁘면 300ms timeout이 6초 가까이 늦었다. 붙여 쓴
-x<task>를 verifyStrictLaneStages가 읽지 않아 lane을 뺀 workflow가
통과했다. 사용자 전송이 중간 클래스를 거쳐 @SystemCaller bean을 부르면
ArchUnit 규칙을 지났다. 잠금 대기 검사기는 FK·trigger·REINDEX와
lock_timeout = 0을 못 봤고, 쿼터 보정 SQL은 코드와 다른 모양의 행을
넣었다.

방법: 영역별 4묶음이 맡은 Minor만 test-driven-development 절차로
고쳤다(재리뷰 README 12절).
- watchdog은 전용 데몬 스레드 하나에서 돌고 스트림을 닫으면 작업을
  취소한다. read당 비용은 그대로다(21–24ns).
- 사용자 전송 → @SystemCaller는 직접·간접 의존 모두 거부한다. 리뷰가
  권한 직접 의존 검사는 중간 클래스 하나로 다시 열려서 버렸다.
- 검사기를 보강하면서 새로 걸린 이미 배포된 마이그레이션 5개는 내용을
  바꾸지 않고 동결 목록에 더했다(main과 blob이 같다).
- 비밀 목록 bean은 규칙보다 먼저 만들어 실제 클래스로 검사한다.

위험·한계: 회복 필요 예외 메시지 끝에 scope digest가 붙고 기동 실패
문구가 바뀌어, 문구 전체에 맞추던 로그 매처는 고쳐야 한다. 코드가 든
Redis 계정 참조의 fixture- 검사는 문서로만 막았다(코드로 막으려면 새
의존 edge가 필요하다). failure-retention ≥ replay-ttl 기동 검사는 넣지
않았다. -mx 같은 짧은 플래그 묶음과 graphql 전송 fixture는 남았다.
spotbugsTestFixtures(게이트 밖)의 정규식 경고가 15건으로 늘었다.

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. watchdog은
공용 풀을 채운 상태에서 300ms 설정이 300ms에 끝나는 것을 쟀다.

Refs: docs/reviews/2026-11-03-rereview/README.md 11·12절, round3/
2026-11-04 03:00:21 +09:00

11 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 값을 믿지 않는다.

시스템이 부르는 쓰기: @SystemInvoked

스케줄러·relay·메시지 소비자처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 @RequiresPermission 대신 @SystemInvoked(reason = "...")를 단다(src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java). 스케줄러·소비 스레드에는 인증(Authentication)이 없어서 권한 선언은 매번 거부되거나 아예 검사되지 않는 장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 권한 검사가 없는 쓰기다. 그래서 사용자 요청이 닿으면 안 된다.

사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemInvoked 유스케이스   (빌드 실패)
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemCaller             (빌드 실패, 중간 클래스를 거쳐도)
시스템     ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
시스템     ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
시스템     ─▶ 예약 작업(@SystemCaller, 직접 new) ──────▶ @SystemInvoked 유스케이스
어디서든   ─▶ @SystemInvoked 유스케이스를 bean으로 등록 ──✗ (기동 실패)
  • 사용자 전송: 사용자가 보낸 요청이 들어오는 inbound adapter다(web·GraphQL·gRPC·WebSocket).
  • 시스템 호출자: broker 전달이나 시간(tick)이 깨우는 코드다. 사용자 요청은 여기로 들어오지 않는다.

시스템 호출자가 @SystemInvoked 유스케이스를 얻는 길은 아래 셋뿐이다. 이 표가 정본이고, 다른 문서는 이 절을 가리킨다.

경로 어디에 두나 유스케이스는 누가 만드나
조립 모듈의 스케줄러 composition:* leaf. 예: outbox relay(src/composition/outbox-relay) 조립 모듈의 @Bean 메서드가 new로 만들어 스케줄러에 넘긴다
메시지 handler adapter:inbound:messaging leaf, 또는 서비스 leaf의 ..adapter.inbound.messaging.. 패키지 handler 생성자가 port를 받아 new로 만든다. handler에 @SystemCaller. 작업 순서는 09장 「소비」 4단계
예약 작업 서비스 자기 leaf의 ..adapter.inbound.scheduler.. 패키지. 등록된 scheduler leaf는 없다 작업 클래스 생성자가 port를 받아 new로 만든다. 작업 클래스에 @SystemCaller. 모양은 메시지 handler와 같고, 깨우는 것이 @Scheduled 메서드다

예약 작업은 controller와 같은 leaf에 놓이기 쉽다. 그때 "지금 실행" endpoint가 작업 bean을 주입받아 부르면 권한 검사 없는 쓰기를 사용자가 부르게 된다. 아래 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가 이것을 빌드에서 막는다. 사용자도 같은 일을 시켜야 하면 @RequiresPermission을 단 사용자용 유스케이스를 따로 만든다(아래 D4 문단).

규칙 무엇을 막나 어디
bean 금지 @SystemInvoked 유스케이스가 bean이면 기동 실패. 호출자가 new로 만들어 혼자 들고 있는 것만 허용한다 src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java
시스템 호출자만 inbound adapter가 그 클래스에 의존하면 빌드 실패. @SystemCaller(reason = "...")를 단 클래스와 그 안에 중첩된 클래스만 예외 ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES(ApplicationBoundaryArchitectureTest)
표시 검사 @SystemCaller 클래스와 그 안에 중첩된 클래스는 ..adapter.inbound.messaging..·..adapter.inbound.scheduler..에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS(같은 파일)
전송 → 시스템 호출자 금지 사용자 전송 클래스가 @SystemCaller에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 사용자 전송 패키지에 있거나 사용자 전송 타입에 의존하는 클래스다. 그래서 handler를 bean으로 등록하는 @Configuration은 걸리지 않는다 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS(같은 파일)

규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 패키지 쪽에서만 온다. 패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 타입 쪽은 나열 목록이다(ARE_USER_TRANSPORT_TYPES). 시스템 패키지 안에 놓인 endpoint를 알아보는 데 쓰는 목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를 들이면 그 패키지를 이 목록에 더한다.

이 규칙들은 클래스 의존만 본다. 실행 중에 bean을 찾는 코드(getBean, ObjectProvider)는 의존이 아니라서 잡지 못한다.

D4 실패(MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는 쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다 (사용자용 @RequiresPermission, 시스템용 @SystemInvoked). 업무 규칙은 domain에 두고 둘이 같이 쓴다.

web 없는 조립

web이 빠진 조립(gRPC 전용·배치 전용)에는 @RequiresPermission을 검사할 advisor가 없다. 그런 조립에 권한을 선언한 bean이 있으면 PermissionEnforcementGuard가 기동을 실패시킨다(리뷰 01-06). web 없이 조립하는 서비스는 자기 전송에 맞는 검사 advisor를 함께 넣어야 기동한다.

지금 이해하면 되는 것

  • 쓰기 = @RequiresPermission + non-final + bean + 역할 매핑.
  • 시스템만 부르는 쓰기 = @SystemInvoked + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다: 조립 모듈의 스케줄러, @SystemCaller 메시지 handler, @SystemCaller 예약 작업. 사용자 전송은 @SystemCaller에도 닿지 못한다.
  • 객체 판정은 유스케이스 안, 남의 것은 404.
  • 역할은 자기 client 것만 읽는다.