AI Security 활성화 및 부트스트랩

@EnableAISecurity 어노테이션

@EnableAISecurity는 레거시 시스템과의 심리스한 통합을 위해 제공되는 핵심 어노테이션입니다. Spring Boot의 주 설정 클래스(보통 @SpringBootApplication이 선언된 클래스)에 이 어노테이션을 선언하는 것만으로 Contexa의 전체 AI 보안 프레임워크가 활성화됩니다.

선언 예시

@SpringBootApplication
@EnableAISecurity(
    mode = SecurityMode.SANDBOX,
    authObjectLocation = AuthObjectLocation.AUTO
)
public class LegacyApplication {
    public static void main(String[] args) {
        SpringApplication.run(LegacyApplication.class, args);
    }
}

어노테이션 속성 상세

SecurityMode 동작 방식

Contexa는 점진적인 마이그레이션과 안전한 배포를 지원하기 위해 두 가지 보안 동작 모드를 지원합니다.

• SANDBOX (샌드박스 모드): 레거시 통합의 기본값입니다. SANDBOX와 FULL은 인증 소유권을 정하는 모드이며, AI 판정(BLOCK, CHALLENGE 등)을 실제로 집행할지 관찰만 할지는 Zero Trust 모드(SHADOW/ENFORCE)가 따로 정합니다. contexa.bridge.ownership을 따로 설정하지 않으면 HOST_OWNED로 동작합니다. 이때 Contexa는 인증용 SecurityFilterChain을 만들지 않으며, 인증과 인가는 호스트 애플리케이션의 Spring Security 설정이 소유합니다(아래 HOST_OWNED 동작과 요구 사항 참고).
• FULL (전체 보호 모드): 완전한 AI Native Zero Trust 보안을 집행합니다. contexa.bridge.ownership을 따로 설정하지 않으면 CONTEXA_OWNED로 동작하며, Contexa가 인증 SecurityFilterChain을 구성합니다. AiSecurityConfiguration은 모든 요청에 대해 anyRequest().access(customDynamicAuthorizationManager)를 강제 적용하여, 이상 징후나 위협이 감지되면 즉시 실시간 차단 페이지로 리다이렉트하거나 강한 MFA 인증 챌린지(Step-up MFA 등) 정책을 런타임에 직접 집행합니다.

애플리케이션이 contexa.bridge.ownership을 명시적으로 설정하면 그 값이 항상 우선합니다. Contexa가 정의한 SANDBOX 체인(/contexa/admin/login 허용, /contexa/admin/** 인증 필요, 그 밖의 모든 요청 허용, CSRF·CORS·보안 헤더 설정 비활성화)은 SANDBOX 모드에서 contexa.bridge.ownership=CONTEXA_OWNED를 명시적으로 설정한 경우에만 만들어집니다.

HOST_OWNED 동작과 요구 사항

• 호스트 보안 설정: HOST_OWNED에서 Contexa는 인증 체인도, 자리 표시용(placeholder) 체인도 등록하지 않습니다. 호스트에 SecurityFilterChain 빈이 없으면 Spring Boot 기본 보안이 적용되어 모든 요청에 인증이 필요해지고 기본 폼 로그인과 HTTP Basic 로그인이 생성됩니다. 따라서 Spring Security를 사용하지 않던 애플리케이션은 기존 동작을 유지하려면 자신의 SecurityFilterChain을 선언해야 합니다(설치 가이드 예시 참고). Spring Boot 기본 체인만 있는 경우 Contexa는 기동 시 error 로그로 이 상황을 알립니다.
• 변경하지 않는 것: 호스트가 자신의 Spring Security 설정을 선언해 두면 Contexa는 호스트의 로그인 페이지, 세션 관리, 접근 규칙을 바꾸지 않습니다.
• 브리지 증거: 브리지 해석 필터는 서블릿 필터로 등록되어 요청마다 호스트의 Spring Security 필터 체인 다음에 실행됩니다. 현재 SecurityContext에 인증된(익명이 아닌) Authentication이 있을 때만 그 Authentication에서 principal, 권한, 토큰 클레임(JWT 클레임, OAuth2 사용자 속성)을 읽어 증거를 만듭니다. 그런 Authentication이 없는 요청에서는 브리지 증거가 만들어지지 않습니다.
• 핸드오프: HOST_OWNED에서 ContexaAuthBridge.handoff(...)는 Spring SecurityContext를 채우거나 저장하지 않습니다. 현재 요청의 브리지 증거를 기록하고 브리지 사용자 미러를 동기화합니다. 같은 요청에 같은 principal의 호스트 Authentication이 함께 있으면 명시적 핸드오프 결과가 유지됩니다. contexa.bridge.populate-security-context는 CONTEXA_OWNED에서만 효과가 있습니다.
• @Protectable: 호출 시점에 Spring Authentication이 필요합니다. 없거나 익명이면 호출이 거부되며, 응답은 호스트의 Spring Security 예외 처리가 결정합니다. 자체 레거시 방식으로 사용자를 인증하는 호스트는 인증된 사용자를 Spring SecurityContext에 넣어야 합니다(호스트 책임이며, 예를 들어 호스트 체인에 추가한 필터로 처리합니다). 또는 Contexa가 인증을 소유하도록 CONTEXA_OWNED를 사용합니다.

AiSecurityImportSelector와 동적 와이어링

Contexa는 컴파일 타임 의존성을 격리하면서 동적으로 자동 구성을 부트스트랩하기 위해 AiSecurityImportSelector를 활용합니다.

@EnableAISecurity 어노테이션 내부에 선언된 @Import(AiSecurityImportSelector.class)에 의해 Spring Container 기동 시 이 셀렉터가 호출됩니다. AiSecurityImportSelector는 다음과 같은 절차를 밟습니다:

1. 어노테이션의 메타데이터로부터 속성값(mode, authObjectLocation 등)을 읽어들입니다.
2. 읽어들인 설정값들을 아래 표의 프로퍼티로 만들어 애플리케이션 Environment에 가장 높은 우선순위의 프로퍼티 소스로 등록합니다. JVM 시스템 프로퍼티로 설정하지는 않습니다.
3. 최종적으로 contexa-autoconfigure 모듈의 핵심 진입점인 io.contexa.autoconfigure.ai.AiSecurityConfiguration 클래스명을 Spring IoC 컨테이너에 전달하여 동적 임포트를 완료합니다.

등록되는 Environment 프로퍼티

인증 객체 추출 위치 (AuthObjectLocation)

레거시 인증 아티팩트를 획득하기 위해 AuthObjectLocation을 통해 명시적으로 위치를 지정할 수 있습니다.

• AUTO: 기본 설정이며, 프레임워크가 인증 객체를 식별하기 위해 HttpSession 영역 → HttpServletRequest 속성(Request Attributes) → HTTP 요청 헤더(Headers) 순서로 순차적인 체인 스캔을 수행합니다.
• SESSION: HttpSession 영역에서 대상 속성명으로 바인딩된 인증 객체를 로드합니다.
• REQUEST_ATTRIBUTE: HttpServletRequest의 attribute 맵 내에서 데이터를 식별합니다.
• HEADER: HTTP 요청 헤더로부터 전달받은 토큰 정보에서 추출합니다.