Files
clean-architecture-backend-…/docs/manual/07-authorization.md
T
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

6.3 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). 스케줄러 스레드에는 인증이 없어 권한 선언은 장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 권한 검사가 없는 쓰기이므로 전송 계층이 닿으면 안 된다. 그래서 두 가지가 막는다.

막는 것 어디
bean으로 등록하면 기동 실패. 조립 모듈이 new로 만들어 스케줄러에만 준다(예: composition:outbox-relay) src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java
inbound adapter가 그 클래스를 직접 쓰면 빌드 실패 INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES(ApplicationBoundaryArchitectureTest)

D4 실패(MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는 쓰기라면 권한을 선언하고 역할에 매핑한다.

web 없는 조립

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

지금 이해하면 되는 것

  • 쓰기 = @RequiresPermission + non-final + bean + 역할 매핑.
  • 시스템만 부르는 쓰기 = @SystemInvoked + bean 아님 + 전송에서 안 닿음.
  • 객체 판정은 유스케이스 안, 남의 것은 404.
  • 역할은 자기 client 것만 읽는다.