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. SANDBOX and FULL decide who owns authentication; whether AI decisions (BLOCK, CHALLENGE, and so on) are enforced or only observed is controlled separately by the Zero Trust mode (SHADOW/ENFORCE). Unless contexa.bridge.ownership is set explicitly, this mode runs as HOST_OWNED: Contexa does not build an authentication SecurityFilterChain, and the host application's own Spring Security configuration owns authentication and authorization (see HOST_OWNED behavior and requirements below).
• FULL (Full Protection Mode): Activates active Zero Trust enforcement. Unless contexa.bridge.ownership is set explicitly, this mode runs as CONTEXA_OWNED and Contexa builds the authentication SecurityFilterChain. 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.

An explicitly configured contexa.bridge.ownership always wins. The SANDBOX chain defined by Contexa (/contexa/admin/login permitted, /contexa/admin/** authenticated, every other request permitted, CSRF, CORS and security headers disabled) is created only when the application explicitly sets contexa.bridge.ownership=CONTEXA_OWNED together with SANDBOX mode.

HOST_OWNED Behavior and Requirements

• Host security configuration: In HOST_OWNED, Contexa registers neither an authentication chain nor a placeholder chain. If the host has no SecurityFilterChain bean, Spring Boot's default security applies: every request requires authentication, and a generated form login and HTTP Basic login are added. An application that did not use Spring Security before adding Contexa must therefore declare its own SecurityFilterChain to keep its existing behavior (see the installation guide example). When only Spring Boot's default chain is present, Contexa reports this situation with an error log at startup.
• What stays unchanged: As long as the host declares its own Spring Security configuration, Contexa does not change the host's login pages, session management, or access rules.
• Bridge evidence: The bridge resolution filter is registered as a servlet filter and runs after the host's Spring Security filter chain on each request. It resolves evidence only when the current SecurityContext holds an authenticated, non-anonymous Authentication, reading the principal, authorities, and token claims (JWT claims, OAuth2 user attributes) from that Authentication. Requests without such an Authentication produce no bridge evidence.
• Handoff: In HOST_OWNED, ContexaAuthBridge.handoff(...) does not populate or persist the Spring SecurityContext. It records the bridge evidence for the current request and synchronizes the bridge user mirror. When the same request also carries a host Authentication for the same principal, the explicit handoff result is kept. contexa.bridge.populate-security-context only has an effect in CONTEXA_OWNED.
• @Protectable: A Spring Authentication is required at invocation time. Without one, or with an anonymous one, the call is rejected and the response is determined by the host's Spring Security exception handling. A host that authenticates users with its own legacy mechanism must place the authenticated user into the Spring SecurityContext (a host responsibility, for example a filter in its own chain), or use CONTEXA_OWNED so that Contexa owns authentication.

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. Publishes these values, as the properties shown in the table below, into the application Environment as its highest-priority property source. They are not set as JVM system properties.
3. Returns the class name of the target configuration in contexa-autoconfigure: io.contexa.autoconfigure.ai.AiSecurityConfiguration, triggering dynamic bean provisioning.

Published Environment Properties

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.