Integrating Contexa into Your Spring Boot Application

You already have a Spring Boot application with Spring Security. Adding Contexa doesn't replace your security setup — it wraps around it. This page explains exactly what changes, what stays the same, and how to go live safely.

What Happens Under the Hood

When you add @EnableAISecurity to your application class, a four-layer pipeline transforms your declarative configuration into Spring Security filter chains.

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.

The default PlatformConfig gives you Form Login + OTT as the MFA flow, session management, and AISessionSecurityContextRepository for AI trust scores — all without writing a single configuration class.

This is not magic. Internally, Contexa calls the same Spring Security methods you would. It abstracts them through a declarative DSL and adds Zero Trust filters on top. You can bypass the DSL anytime via rawHttp().

Your Existing Security Stays Intact

The most common concern when adopting a new security framework: "Will it break what I already have?"

Before Contexa
Your SecurityFilterChain
Your UserDetailsService
Your AuthenticationProvider
spring.security.* properties
After Contexa
Your SecurityFilterChain (unchanged)
Your UserDetailsService (unchanged)
Your AuthenticationProvider (unchanged)
spring.security.* properties (unchanged)
+ Contexa SecurityFilterChains (added separately)
+ Zero Trust filters (added separately)
+ AI Session Context (added separately)

Why Nothing Breaks

Your Existing Bean After Adding Contexa Mechanism
SecurityFilterChain Unchanged — Contexa chains are added separately BeanDefinitionRegistry + OrderedSecurityFilterChain
UserDetailsService Unchanged — yours takes priority @ConditionalOnMissingBean
AuthenticationProvider Unchanged — Contexa adds its own to the chain AuthenticationManager chain coexistence
CSRF / CORS settings Unchanged — override via global() only if needed Existing config preserved by default
spring.security.* Unchanged — no namespace conflict Contexa uses contexa.* and 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 every request
  • 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 every request
  • Decisions are enforced in real-time
  • ALLOW proceeds normally
  • CHALLENGE triggers MFA
  • BLOCK denies access
YAML 
security:
  zerotrust:
    mode: SHADOW   # AI analyzes every request, enforces nothing

The 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.

Safe for production. Shadow Mode does not alter any request or response. AI analysis runs asynchronously after the request completes, adding no latency. Shadow Mode Guide →

Going Live — Shadow to Enforce

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

YAML 
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 →

When You Need Custom Configuration

The default PlatformConfig includes Form Login + OTT MFA + Session management. Define your own PlatformConfig bean when you need a different 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: Existing Form Login + Zero Trust

Keep your existing authentication and add AI-driven security on top. The critical step: register AISessionSecurityContextRepository.

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.

Required for Zero Trust. When defining a custom PlatformConfig, you must register AISessionSecurityContextRepository in the global() customizer. Without it, AI trust scores are not injected into sessions and Zero Trust will not function.

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