Integrating Contexa into Your Spring Boot Application

Contexa's runtime scope is determined by the activation mode, not by installation alone. Treat Starter-only, host-owned SANDBOX, and Contexa-owned FULL as three different states.

Current validation baseline — this release is validated with Java 17 and Spring Boot 3.5.4. Spring Boot 3.x is the target; 4.x is not supported. Declaring @EnableAISecurity on 4.x blocks startup.

Three runtime states

  • Starter only: without @EnableAISecurity, Contexa does not activate AI security, filters, authentication providers, or the IAM schema.
  • SANDBOX (default): the HOST_OWNED contract. The host owns authentication and SecurityContext; Contexa receives the principal through the bridge and independently evaluates policies only for selected resources.
  • FULL: the CONTEXA_OWNED contract. Select it explicitly only for a new application that uses Contexa as the global authentication and authorization platform.

What Happens Under the Hood

Adding @EnableAISecurity first selects the ownership boundary. The authentication DSL and filter-chain creation process below apply to FULL / CONTEXA_OWNED configuration.

1

Import & Detect

@EnableAISecurity imports AiSecurityImportSelector, which loads AiSecurityConfiguration. If no custom PlatformConfig bean exists (@ConditionalOnMissingBean), a default one is created automatically.

2

Create Flows

FlowContextFactory reads the PlatformConfig and creates an independent HttpSecurity instance for each authentication flow — Form, REST, MFA, OTT, or Passkey.

3

Apply Adapters

SecurityConfigurerOrchestrator runs a chain of adapters that call the Spring Security methods you already know: http.formLogin(), http.webAuthn() (invoked by the DSL's passkey()), http.oneTimeTokenLogin(). Zero Trust filters are added at this stage.

4

Register Chains

SecurityFilterChainRegistrar wraps each built HttpSecurity into an OrderedSecurityFilterChain and registers it as a Spring bean via BeanDefinitionRegistry — alongside your existing filter chains, never replacing them.

In FULL mode, the default PlatformConfig configures Form Login, OTT MFA, session management, and AISessionSecurityContextRepository. Do not use this as a reason to transfer host authentication ownership in SANDBOX.

FULL-mode internals — Contexa configures the standard Spring Security DSL. It owns host authentication configuration only when FULL is explicitly selected.

SANDBOX Preserves Host Security Ownership

SANDBOX is defined by the HOST_OWNED boundary, not merely by bean coexistence. The host continues to own login, sessions, authentication providers, and SecurityContext.

Before Contexa
Your SecurityFilterChain
Your UserDetailsService
Your AuthenticationProvider
spring.security.* properties
After SANDBOX Activation
Your SecurityFilterChain (unchanged)
Your UserDetailsService (unchanged)
Your AuthenticationProvider (unchanged)
spring.security.* properties (unchanged)
+ Selected Contexa resource evaluation (independent)
+ Host-principal bridge (read only)
+ DB policy decision (separate from host IAM)

Why Nothing Breaks

Your Existing Bean After Adding Contexa Mechanism
SecurityFilterChain Not replaced or owned in SANDBOX HOST_OWNED ownership boundary
UserDetailsService Unchanged — the host implementation is used The bridge only receives and reads the principal
AuthenticationProvider Unchanged — SANDBOX does not replace host authentication providers HOST_OWNED authentication boundary
CSRF / CORS settings Unchanged — host settings remain in control Separated from Contexa resource evaluation
spring.security.* Unchanged — no namespace conflict Contexa uses contexa.* and contexa.security.zerotrust.*

Start Safe with Shadow Mode

Shadow Mode runs the entire Zero Trust pipeline — behavioral analysis, risk scoring, AI decisions — but never enforces those decisions.

Shadow Mode

Start here. Zero risk to existing behavior.

  • AI analyzes requests for selected Contexa resources
  • Decisions are logged only
  • No user is ever blocked or challenged
  • Behavioral baselines are built from real traffic
  • Minimal request overhead — analysis runs asynchronously by default

Enforce Mode

Switch when baselines are established.

  • AI analyzes requests for selected Contexa resources
  • Decisions are enforced in real-time
  • ALLOW proceeds normally
  • CHALLENGE triggers MFA
  • BLOCK denies access
YAML 
contexa:
  security:
    zerotrust:
      mode: SHADOW   # Analyze selected resources without enforcement

The contexa.security.zerotrust.mode property is bound to SecurityZeroTrustProperties (values: SHADOW, ENFORCE; default ENFORCE). SecurityZeroTrustProperties.isEnforcementEnabled() returns true only when mode == ENFORCE. In SHADOW mode, SecurityDecisionEnforcementHandler skips decision persistence and blocking side-effects, and AuthorizationManagerMethodInterceptor treats @Protectable(sync = true) BLOCK/CHALLENGE/ESCALATE decisions as observation-only (the method proceeds instead of throwing ZeroTrustAccessDeniedException). Because the property is bound via @ConfigurationProperties, a restart is required after changing the YAML value.

Validate before production — Shadow Mode does not enforce decisions, but it runs the actual analysis path. Validate resource scope, logs, latency, and external AI calls in your environment. Shadow Mode Guide →

Going Live — Shadow to Enforce

When your behavioral baselines are established, switch to Enforce mode with a single property change:

YAML 
contexa:
  security:
    zerotrust:
      mode: ENFORCE   # AI decisions are now enforced

In Enforce mode, the AI's decisions become real:

✓
ALLOW
Request proceeds normally
!
CHALLENGE
MFA re-authentication required
×
BLOCK
Access denied immediately
↑
ESCALATE
Held for administrator review

To roll back, change ENFORCE back to SHADOW. Because the property is bound via @ConfigurationProperties, an application restart is required for the change to take effect.

How AI Makes These Decisions →  |  Migration Strategy →

Custom Authentication Configuration in FULL Mode

The following authentication DSL examples are for FULL / CONTEXA_OWNED only. Do not copy them into a legacy host's SANDBOX integration. Define a PlatformConfig bean only when FULL needs a different authentication setup.

Scenario A: REST API Only

Your application exposes only REST APIs — no Form Login needed.

Java 
@Bean
public PlatformConfig platformConfig(IdentityDslRegistry<HttpSecurity> registry) throws Exception {
    return registry
        .global(globalHttpCustomizer)
        .rest(rest -> rest.order(10))
        .session(Customizer.withDefaults())
        .build();
}

Scenario B: Form Login + Zero Trust in FULL Mode

Use this when Contexa owns authentication in FULL mode and configures Form Login with AI-driven security. Register AISessionSecurityContextRepository within that FULL ownership boundary.

Java 
@Bean
public PlatformConfig platformConfig(IdentityDslRegistry<HttpSecurity> registry) throws Exception {
    return registry
        .global(http -> http
            .authorizeHttpRequests(authReq -> authReq
                .requestMatchers("/css/**", "/js/**", "/images/**").permitAll()
                .anyRequest().access(customDynamicAuthorizationManager))
            .securityContext(sc -> sc
                .securityContextRepository(aiSessionSecurityContextRepository)))
        .form(form -> form.defaultSuccessUrl("/dashboard"))
        .session(Customizer.withDefaults())
        .build();
}

Scenario C: Complex Setup — rawHttp() Escape Hatch

When the DSL doesn't cover your needs — custom filters, custom AuthenticationEntryPoint, or advanced configuration — drop down to Spring Security's HttpSecurity directly:

Java 
.form(form -> form
    .rawFormLogin(formLogin -> formLogin
        .authenticationDetailsSource(customDetailsSource)
        .successHandler(customSuccessHandler))
)

This gives you full access to Spring Security's FormLoginConfigurer while still benefiting from Contexa's Zero Trust pipeline.

FULL-mode condition — a custom PlatformConfig must register AISessionSecurityContextRepository inside the FULL ownership boundary. Do not replace the host SecurityContext repository with it in SANDBOX.

Identity DSL Reference →  |  Authentication Flows →  |  Adaptive MFA →