Files
clean-architecture-backend-…/docs/manual/07-authorization.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

8.0 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 유스케이스   (빌드 실패)
시스템     ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
시스템     ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
어디서든   ─▶ @SystemInvoked 유스케이스를 bean으로 등록 ──✗ (기동 실패)
  • 사용자 전송: 사용자가 보낸 요청이 들어오는 inbound adapter다(web·GraphQL·gRPC·WebSocket).
  • 시스템 호출자: broker 전달이나 시간(tick)이 깨우는 코드다. 사용자 요청은 여기로 들어오지 않는다.
규칙 무엇을 막나 어디
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·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS(같은 파일)

규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 그래서 나중에 새 전송이 생겨도 따로 고치지 않아도 막힌다. 메시지 소비자의 작업 순서는 09장 「소비」 4단계다.

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뿐이다.
  • 객체 판정은 유스케이스 안, 남의 것은 404.
  • 역할은 자기 client 것만 읽는다.