contexa-common contexa-autoconfigure bootstrap

AI Security Activation & Bootstrapping

Describes the inner workings of how @EnableAISecurity, SecurityMode, and AiSecurityImportSelector dynamically load and bootstrap the Contexa AI-Native Zero Trust infrastructure in legacy Spring Boot applications.

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

Attribute Type Default Value Description
mode SecurityMode SecurityMode.SANDBOX Determines the operational enforcement mode of the AI security framework.
authObjectLocation AuthObjectLocation AuthObjectLocation.AUTO Provides a hint for extracting legacy authenticated objects.
authObjectAttribute String "" The session or request attribute key used for authentication handoff.
authObjectType Class<?> Object.class Type hint for reflective extraction of the legacy authentication object.

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. This is ideal for validating AI model accuracy without impacting live services.
  • FULL (Full Protection Mode): Activates active Zero Trust enforcement. Any detected anomaly or security violation triggers real-time response actions, such as immediate redirection to blocked status pages or enforcing MFA verification step-ups.

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

System Property Key Source Attribute Description
contexa.ai.security.mode mode Controls the overall enforcement level of the AI security framework.
contexa.ai.security.auth-object.location authObjectLocation Hint identifying where to retrieve the legacy authentication artifact.
contexa.ai.security.auth-object.attribute authObjectAttribute Name of the specific attribute key used in the handoff.
contexa.ai.security.auth-object.type authObjectType Fully qualified class name of the target extraction type.

Authenticated Object Locations (AuthObjectLocation)

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

  • AUTO: Sequentially scans request attributes, session stores, and request headers to locate authentications.
  • 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.