Files
clean-architecture-backend-…/docs/manual/07-authorization.md
T
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00

18 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)과 분리되어 있다. 서비스가 자기 인증 방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(2026-11-01부터. 전에는 인증 체인 자동 설정을 빼면 권한 검사도 함께 빠졌다).

지켜야 할 것 셋

  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는 필수다(2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다). 같은 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). STOMP 클라이언트가 보낸 프레임마다 도는 inbound channel interceptor도 여기에 든다.
  • 시스템 호출자: 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 메서드다. Runnable·ApplicationRunner 같은 프로젝트 밖 타입을 구현하지 않는다. task scheduler에 직접 등록하면 그 자리에서 job::run을 넘긴다

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

규칙 무엇을 막나 어디
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과 channel interceptor·gRPC·servlet)에 의존하지 않는다 SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS(같은 파일)
전송 → 시스템 호출자 금지 사용자 전송 클래스가 @SystemCaller나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(@Configuration·@AutoConfiguration) 클래스 자신이 요청 처리기 타입(함수형 RouterFunction·HandlerFunction, @RestController·@RequestMapping, servlet·Filter·HandlerInterceptor, WebSocketHandler, GraphQL DataFetcher·RuntimeWiringConfigurer, gRPC BindableService·ServerInterceptor, STOMP ChannelInterceptor·ExecutorChannelInterceptor 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 @Bean으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(route().GET("/orders", orders::list)) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·@ServerEndpoint, configureClientInboundChannel에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(WebMvcConfigurer·WebSocketConfigurer·STOMP broker 설정과 그 registry, CORS 설정, RequestMethod)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 WebMvcConfigurer(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS(같은 파일)
프로젝트 밖 상위 타입 금지 @SystemCaller 클래스와 그 안에 중첩된 클래스(익명·지역 클래스와 예외 제외)는 프로젝트(dev.caskeleton..) 밖의 클래스·인터페이스를 상속·구현하지 않는다. Runnable은 누구나 의존하는 타입이라, endpoint가 작업을 Runnable로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 MessageHandler<T>는 프로젝트 타입이라 된다. record·enum은 언어가 붙이는 상위 타입(Record, Enum과 Enum이 구현하는 Comparable·Serializable·Constable)만은 가져도 된다. 그래서 handler 안의 파싱 결과 record, 결과 enum, 독(poison) 메시지 예외, record로 쓴 handler는 통과하고, Runnable을 구현한 record는 걸린다 SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES(같은 파일)

규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 패키지 쪽에서만 온다. 패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 타입 쪽은 나열 목록이다(ARE_USER_TRANSPORT_TYPES). 시스템 패키지 안에 놓인 endpoint를 알아보는 데 쓰는 목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를 들이면 그 패키지를 이 목록에 더한다. 들인 라이브러리에서 사용자 요청이 지나는 타입을 새로 쓸 때도 같다. STOMP는 org.springframework.messaging 가운데 simp 패키지, @MessageMapping, inbound channel interceptor 두 타입(ChannelInterceptor·ExecutorChannelInterceptor)만 목록에 있다. 같은 라이브러리의 broker listener용 @Payload·@Header는 시스템 쪽이라 넣지 않는다. 설정 클래스 자신을 판정하는 요청 처리기 타입(ARE_REQUEST_HANDLER_TYPES)도 나열 목록이라, 새 전송 라이브러리의 handler 타입을 함께 더한다. 요청 처리기 타입은 모두 사용자 전송 타입이어야 하고, 설정용 타입(ARE_TRANSPORT_SETUP_TYPES)은 요청 처리기 타입을 덮지 않아야 한다. UserTransportTypeListsTest가 둘을 검사한다. 설정용 타입 목록에 없는 configurer 타입을 쓰는 중첩 클래스는 사용자 전송으로 읽혀, 설정 필드를 읽으면 빌드가 실패한다. 그 타입이 요청마다 도는 코드가 아니라 기동 때 한 번 도는 설정용 타입이면 설정용 타입 목록에 더한다.

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

규칙이 못 보는 길

이 규칙들은 클래스 의존만 본다. 그래서 타입 이름이 코드에 남는 길은 모두 잡는다. ObjectProvider<작업 클래스>, getBean(작업 클래스.class), 작업의 인터페이스 주입이 여기에 든다. 타입 이름이 남지 않는 길은 못 본다.

  • 이름이나 Object로 bean을 찾는 코드: getBean("nightlyJob"), Map<String, Object> 주입 뒤 reflection 호출.
  • 설정이 사용자 전송에 작업을 감싼 함수를 넘기는 코드: new RunNowController(job::run)처럼 controller는 Runnable만 받는다. 의존은 설정 → 작업 쪽에만 있고, 요청 처리기 타입에 의존하지 않는 설정은 사용자 전송이 아니다.
  • 설정 클래스 자신에 쓴 요청 처리 코드가 요청 처리기 타입 목록(ARE_REQUEST_HANDLER_TYPES)에 없는 타입으로 쓰인 경우. 목록 방식이라, 목록에 없는 endpoint 타입으로 설정 클래스에 직접 쓴 endpoint는 사용자 전송으로 보이지 않는다. 설정 안에 중첩한 클래스는 더 넓은 사용자 전송 타입 목록으로 보므로 여기에 들지 않는다. 다만 그 목록도 나열 목록이라, 그 목록에 없는 타입으로 만든 endpoint는 어디에 두든 보이지 않는다. 그런 타입을 쓰게 되면 앞 절의 사용자 전송 타입 목록 문단대로 목록에 더한다.

이 길을 막는 것은 ArchUnit 규칙이 아니라 다음 셋이다.

  • @SystemInvoked 유스케이스는 bean이 아니고(PermissionEnforcementGuard), 시스템 호출자가 new로 만들어 혼자 든다. 그래서 사용자 전송은 시스템 호출자 객체를 거치지 않고는 그 유스케이스를 부를 수 없다.
  • 의존 방향 게이트(src/config/architecture/modules.json): 등록된 leaf 가운데 adapter:inbound:messaging에 의존할 수 있는 것은 조립 루트(app-bootstrap)뿐이다. 다른 leaf의 사용자 전송은 handler 타입을 컴파일조차 못 한다. 예약 작업은 서비스 자기 leaf에 있어서 같은 leaf의 controller와 사이에는 이 게이트가 없다. 그래서 위 길들은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
  • 리뷰: 설정에서 시스템 호출자를 함수로 감싸 다른 bean에 넘기거나, 사용자 전송이 bean을 이름으로 찾거나, 목록에 없는 타입으로 설정 클래스에 endpoint를 쓰는 코드는 리뷰에서 거절한다. 사용자도 같은 일을 시켜야 하면 위 문단대로 사용자용 유스케이스를 따로 만든다.

web 없는 조립

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

지금 이해하면 되는 것

  • 쓰기 = @RequiresPermission + non-final + bean + 역할 매핑.
  • 시스템만 부르는 쓰기 = @SystemInvoked + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다: 조립 모듈의 스케줄러, @SystemCaller 메시지 handler, @SystemCaller 예약 작업. 사용자 전송은 @SystemCaller에도, 그 작업의 인터페이스에도 닿지 못한다. 타입 이름이 남지 않는 길(이름으로 찾기, 설정이 넘기는 함수)은 빌드가 못 보니 리뷰가 막는다.
  • 객체 판정은 유스케이스 안, 남의 것은 404.
  • 역할은 자기 client 것만 읽는다.