AI Security Setup | Contexa Docs

@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);
    }
}

어노테이션 속성 상세

속성	타입	기본값	설명
`mode`	`SecurityMode`	`SecurityMode.SANDBOX`	AI 보안의 동작 모드를 결정합니다.
`authObjectLocation`	`AuthObjectLocation`	`AuthObjectLocation.AUTO`	레거시 인증 객체를 추출할 위치를 힌트로 지정합니다.
`authObjectAttribute`	`String`	`""`	세션 또는 요청 속성 기반으로 인증 핸드오프를 수행할 때 사용할 속성명입니다.
`authObjectType`	`Class<?>`	`Object.class`	반사적(Reflective) 추출을 수행할 인증 객체의 구체적인 타입 힌트입니다.

SecurityMode 동작 방식

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

SANDBOX (샌드박스 모드): 레거시 통합의 기본값입니다. AI 기반 차단(BLOCK)이나 MFA 강제(CHALLENGE) 등의 집행 조치를 실제 클라이언트 요청에 직접 적용하는 대신, 감지 및 분석 결과를 감사 로그로만 남깁니다. 내부적으로 AiSecurityConfiguration은 /contexa/admin/** 관리자 경로를 제외한 모든 일반 클라이언트 경로에 대해 anyRequest().permitAll()로 필터 체인을 바인딩하여, 기존 호스트 애플리케이션의 인증/인가 로직에 영향을 주지 않으면서 백그라운드 탐지만 안전하게 수행합니다.
FULL (전체 보호 모드): 완전한 AI Native Zero Trust 보안을 집행합니다. AiSecurityConfiguration은 모든 요청에 대해 anyRequest().access(customDynamicAuthorizationManager)를 강제 적용하여, 이상 징후나 위협이 감지되면 즉시 실시간 차단 페이지로 리다이렉트하거나 강한 MFA 인증 챌린지(Step-up MFA 등) 정책을 런타임에 직접 집행합니다.

AiSecurityImportSelector와 동적 와이어링

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

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

어노테이션의 메타데이터로부터 속성값(mode, authObjectLocation 등)을 읽어들입니다.
읽어들인 설정값들을 아래 표와 같이 시스템 프로퍼티(System Properties)로 바인딩하여 런타임에 전파합니다.
최종적으로 contexa-autoconfigure 모듈의 핵심 진입점인 io.contexa.autoconfigure.ai.AiSecurityConfiguration 클래스명을 Spring IoC 컨테이너에 전달하여 동적 임포트를 완료합니다.

바인딩되는 시스템 프로퍼티

시스템 프로퍼티 키	상응 어노테이션 속성	설명
`contexa.ai.security.mode`	`mode`	시스템 전체의 AI 보안 집행 강도를 제어합니다.
`contexa.ai.security.auth-object.location`	`authObjectLocation`	인증 브릿지가 legacy 인증 스탬프를 추출하는 위치입니다.
`contexa.ai.security.auth-object.attribute`	`authObjectAttribute`	핸드오프에 사용되는 구체적인 속성명 키 정보입니다.
`contexa.ai.security.auth-object.type`	`authObjectType`	역직렬화 및 리플렉션 매핑에 활용되는 클래스 타입 정보입니다.

인증 객체 추출 위치 (AuthObjectLocation)

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

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

AI Security 활성화 및 부트스트랩