AI Security Activation & Bootstrapping

The @EnableAISecurity Annotation

@EnableAISecurity is the core annotation designed for seamless integration with legacy systems. Placing this annotation on a Spring Boot main configuration class (typically annotated with @SpringBootApplication) activates the entire Contexa AI security infrastructure.

Example Usage

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

Annotation Attribute Reference

SecurityMode Operation

To support incremental migration and safe canary deployments, Contexa supports two distinct enforcement modes:

• SANDBOX (Sandbox Mode): The default mode for legacy integration. Rather than directly enforcing actions like block redirection or MFA challenges on client requests, it logs decisions to audit records. Internally, AiSecurityConfiguration binds the filter chain with anyRequest().permitAll() for all general client paths (excluding the /contexa/admin/** admin console path), running background threat detection safely without impacting the host application's existing authentication or authorization logic.
• FULL (Full Protection Mode): Activates active Zero Trust enforcement. AiSecurityConfiguration enforces anyRequest().access(customDynamicAuthorizationManager) for all incoming requests. Any detected anomaly or security violation immediately triggers real-time response actions, such as immediate redirection to blocked status pages or enforcing strong MFA verification step-ups (Step-up MFA) at runtime.

AiSecurityImportSelector and Dynamic Wiring

Contexa uses AiSecurityImportSelector to bootstrap its configuration dynamically without requiring compile-time classpath coupling.

When the Spring application starts, the container parses the @Import(AiSecurityImportSelector.class) metadata on @EnableAISecurity. The selector performs the following steps:

1. Reads annotation attributes (such as mode, authObjectLocation) from the target configuration class.
2. Maps and binds these values to **System Properties** as shown in the table below, distributing them across the runtime context.
3. Returns the class name of the target configuration in contexa-autoconfigure: io.contexa.autoconfigure.ai.AiSecurityConfiguration, triggering dynamic bean provisioning.

System Properties Bindings

Authenticated Object Locations (AuthObjectLocation)

The AuthObjectLocation enum tells the framework where to extract legacy session/user contexts from:

• AUTO: The default setting. The framework sequentially scans the active HttpSession store → HttpServletRequest attributes → HTTP headers to locate and extract legacy authentication objects.
• SESSION: Retrieves authentication details from the active HttpSession via the designated attribute key.
• REQUEST_ATTRIBUTE: Retrieves details directly from the HttpServletRequest attributes.
• HEADER: Extracts values from specific incoming HTTP headers.