How Contexa Works
What Contexa asks about each request, and when it makes and applies the answer (the decision), on one page. It also covers how to turn Contexa on, the three choices to make first, what actually runs under each ownership mode, and how the modules fit together.
What Contexa does
A request that passed sign-in and the permission check can still come from someone who stole the account, or from an insider using their own permission for another purpose. For each request it protects, Contexa asks an AI model "is the owner of this account doing their own work right now?", stores the answer as a decision, and applies it to that user's requests.
A decision is not made while the request waits. It is made in the background after the request has been handled and the response has left, and it applies from the same user's next request. Only a method that needs a decision inside the request (@Protectable(sync=true)) and an agent request with no decision on record are decided on the spot.
Requests from AI agents are told apart from people's requests and decided separately (Agents as security subjects).
- AllowALLOW · go on
- Step-up authenticationCHALLENGE · confirm the account owner again with MFA
- BlockBLOCK · stopped until an administrator releases it
- Held for reviewESCALATE · analysis not settled, wait a moment
- Pending analysisPENDING_ANALYSIS · no stored decision, let through and analyzed
Turning it on
With only the starter dependency (spring-boot-starter-contexa), Contexa stays off and the application runs as before. It is turned on by putting @EnableAISecurity on the main class. The annotation loads AiSecurityConfiguration through AiSecurityImportSelector, and the auto-configurations of each module follow. Even with the annotation, contexa.enabled=false loads nothing.
import io.contexa.contexacommon.annotation.EnableAISecurity;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableAISecurity // no mode means SANDBOX: the application keeps sign-in (HOST_OWNED)
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
A dedicated Contexa database must also be set. If it is empty, the application does not start.
contexa:
datasource:
url: jdbc:postgresql://localhost:5432/contexa # a Contexa database, not the application's
username: contexa
password: ${CONTEXA_DB_PASSWORD}
- The same address as the application database stops the start. Only for a trial (POC), setting both
contexa.datasource.isolation.allow-shared-application-datasourceandcontexa.datasource.isolation.shared-application-datasource-risk-acceptedtotrueallows sharing, and a production profile (prod·production) still refuses it. - Decisions need an AI chat model and a vector store. Without Spring AI
ChatModelandVectorStorebeans (PgVector, with an embedding model for it), Layer 1 and Layer 2 are not created and protected requests stay pending analysis. - A decision applies only after it is recorded in the Contexa database. Each decision is first written as an observation (table
ctxa_ai_security_decision_observation); when that write fails, the decision is not applied. - At start, Contexa checks that the beans it needs exist (
contexa.capability.mode:AUTO·OFF·WARN·FAIL_FAST·STRICT). When something is missing, the defaultAUTOonly logs it for an ordinary application and stops the start for a Contexa-only application (FULLmode and the like) (FAIL_FAST).
The steps from the dependency to the first decision are in Getting started.
The three choices to make first
| Setting | Default | What it decides | When to change it |
|---|---|---|---|
contexa.bridge.ownership( @EnableAISecurity(mode) sets its default) | HOST_OWNED | Authentication ownership: whether the application keeps sign-in (HOST_OWNED) or Contexa owns it (CONTEXA_OWNED). No mode or SANDBOX means HOST_OWNED; FULL means CONTEXA_OWNED. | CONTEXA_OWNED to use Contexa's sign-in and MFA (the request-time filters run in both). FULL treats the application as Contexa-only and, unless the application declares its own DataSource, makes its default DataSource the Contexa database. Differences: What runs under each ownership mode |
contexa.security.zerotrust.mode | ENFORCE | Enforcement mode: DISABLED · OBSERVE (no AI analysis), SHADOW (analyze and record only, nothing stored or applied), ENFORCE (store and apply) | Start with SHADOW to watch the decisions, then switch to ENFORCE. A value saved in the admin console's "System Settings" wins over YAML (no restart). Start safely with enforcement modes |
contexa.infrastructure.mode | standalone | Infrastructure mode: keep the decision store, event delivery and learned state in memory (standalone) or in Redis · Kafka (distributed) | distributed when there are several servers or the learned state must survive a restart. Infrastructure modes |
The two lanes a request goes through
Contexa works in two lanes. The request-time lane reads and applies the decision already stored while the user waits; the asynchronous decision lane makes a new decision and stores it after the response has left. The two lanes meet only at the decision store.
Request timewhile the user waits
- Request arrivesfrom a signed-in user or agent
- Apply the stored decisionstops here on block, step-up or hold
- Application logic and protected method run
@Protectablemethod - Publish an analysis eventafter the method has finished
Asynchronous decisionafter the response has left
- Receive and filter the eventno analysis if a decision is already in force
- One line per user and sessionone at a time
- The AI model decidesLayer 1, and Layer 2 when needed
- Enforce and recordstore, seal the evidence, write the audit record
- Analysis events come from protected methods. With the default settings, analysis events are published by
@Protectablemethod calls and by MFA sign-in success. An ordinary URL request that is not a protected method is not analyzed, and a request an authorization policy denied is kept only as a session fact, without analysis. - The request-time step never calls the AI model. It only reads the store. That is why a new decision usually applies from the next request.
- Before a decision is stored, the user is pending analysis. The request goes on, and the response in flight is wrapped so that a block signal can cut it (under both ownership modes, and the same for an allow).
Following one request from start to end is in The Life of a Request.
What runs under each ownership mode
The default (only @EnableAISecurity) is HOST_OWNED. Contexa then builds no sign-in chain, but it still enforces on every path: the same request-time filters run as servlet filters right after the application's Spring Security chain, with the same responses as under CONTEXA_OWNED, and again in @Protectable methods.
| Feature | CONTEXA_OWNED | HOST_OWNED (default) |
|---|---|---|
| Security filter chain (sign-in, MFA pages, filters) | built by Contexa | Not built (only a chain for the admin console, below). The application's SecurityFilterChain keeps sign-in, sessions, cookies and permissions. If the application declares no chain, Spring Boot's default security requires authentication on every request, and Contexa reports it with a WARN log at start. With no users of the application either, the start is refused |
| Request-time filters (step-up, block and hold responses) | run inside the Contexa chain | run as servlet filters right after the application's chain (bridge, step-up, block and hold), on every path |
Authorities changed to match the decision (ROLE_BLOCKED and so on) | in the session and JWT chains | none |
Stored decisions enforced in @Protectable methods | runs | runs (also where an application that sets the user after Spring Security's filters is enforced) |
#ai expressions in the application's @PreAuthorize | not registered in the application (Contexa's expression handler is used only for the @PreAuthorize of Contexa's own classes) | not registered |
Protection of the admin console /contexa/admin/** | protected by the Contexa chain and method security | protected by a Contexa chain of its own that takes only /contexa/admin/**, with Contexa's administrator sign-in at /contexa/admin/login. The application does not need to protect it; method security (@EnableMethodSecurity) is an optional extra check |
| Agent request gate (call limits, ended delegations, confirmation, narrowed scope) | runs | runs (details) |
| Authentication bridge | reads the sign-in facts inside the chain and fills the security context | reads the application's sign-in facts and only makes stamps (does not fill or save the security context) |
| Answer to a step-up (CHALLENGE) | Contexa's MFA flow | Contexa's verification-only step-up /contexa/step-up (passkey, one-time code by mail, or the application's own re-authentication); the application's sign-in and session stay (details) |
How to choose the ownership mode and add Contexa to an existing Spring Security application: Adding Contexa to a Spring Security application.
The five decisions and their lifetimes
Decisions are stored per user, and each decision has a fixed lifetime. A decision does not stay "until a new analysis replaces it".
| Decision | Lifetime | Where it applies | How it ends |
|---|---|---|---|
| Allow (ALLOW) | 15 minutes (set with contexa.security.zerotrust.allow-validity) | only in the same session, IP and browser it was made for | back to pending analysis when the time passes |
| Step-up authentication (CHALLENGE) | 1,800 s (30 min) | every session of the user | allowed after passing the MFA this decision started, or the time runs out |
| Held for review (ESCALATE) | 300 s (5 min) | every session of the user | an administrator's approval. If unresolved when the time ends, the next request turns it into a block (CONTEXA_OWNED) |
| Block (BLOCK) | no limit | every session of the user | an administrator's approval (the user asks for release after the unblock MFA) |
| Pending analysis (PENDING_ANALYSIS) | — | no stored decision | changes when an analysis stores a decision |
- The stricter decision wins. In the order block > held for review > step-up, a weaker new decision is not stored while a stricter one is in force.
- The responses users get for each decision (HTTP status, the page they are sent to) are in The Life of a Request and Request-time enforcement.
How a decision is made
- 1Layer 1gathers the session flow, differences from the behavioral baseline, company records and past decision records; the AI model decides
- 2Layer 2decides the same request again, only when Layer 1 answered "these facts cannot decide it (ESCALATE)"
- 3Five steps after the decisionmake the decision (50) → enforce (55) → seal evidence (56) → audit (60) → SaaS forwarding (65, only when turned on)
- The AI model chooses the action (allow, step-up, block, hold). The engine only gathers and sends facts. When no answer comes back from the model (provider failure, timeout), the decision ends as step-up and is not passed to Layer 2.
- Shadow mode stores nothing. Only the observation and audit records are written.
- What is learned and when the model's answer is changed: Decision Engine.
Records to check a decision
So that why a decision was made can be checked later, Contexa keeps three things. None of them changes a decision.
ctxa_audit_log, chained to the previous record's hash and signed. The admin console's "Security event log" (/contexa/admin/security-monitor) shows the check result of each recordModules
| Module | What it does | Depends on |
|---|---|---|
contexa-common | Decision types, shared annotations such as @EnableAISecurity and @Protectable, the authentication bridge, the cache abstraction | nothing |
contexa-core | AI model calls (UnifiedLLMOrchestrator), the asynchronous decision (SecurityPlaneAgent and its processing steps), past decision record search, the decision prompt (SecurityDecisionStandardPromptTemplate), sealed evidence and inspection, audit (CentralAuditFacade) | contexa-common (api) |
contexa-identity | Form and REST sign-in, MFA (passkey, OTT), the adaptive MFA policy (AIAdaptiveMfaPolicyProvider), OAuth2, request-time filters, the identity DSL | contexa-core, contexa-common |
contexa-iam | XACML policies (PAP · PDP · PEP · PIP · PRP), @Protectable method enforcement, URL authorization from database policies, the resource scanner that finds the application's endpoints and methods as resources, the admin console | contexa-core, contexa-common |
contexa-autoconfigure | Spring Boot auto-configuration. It keeps the other four modules compileOnly and does not bring them itself | four modules (compileOnly) |
spring-boot-starter-contexa | The one Contexa dependency the application adds | five modules (api) |
Infrastructure modes
The infrastructure mode decides where Contexa keeps its state. Both modes need the dedicated Contexa database (PostgreSQL).
| State | Standalone (standalone, default) | Distributed (distributed) |
|---|---|---|
| Decision store | memory (with a cap on the number of users) | Redis (when a RedisTemplate bean exists) |
| Analysis event delivery | memory inside one server | Kafka (when a KafkaTemplate bean exists) |
| Block signal (cutting a response in flight) | inside one server | to every server over the Redisson channel contexa:security:block-signal (when a RedissonClient bean exists) |
| Learned state (behavioral baselines and so on) | memory. Lost on restart, reported with a WARN log at start | kept in Redis |
Write standalone or distributed in contexa.infrastructure.mode. Connection settings are in First start and deployment.
Optional features and extension points
| Feature | Default | Description |
|---|---|---|
| Contexa SaaS forwarding | off (contexa.saas.enabled) | Sends decisions other than allow and pending analysis to Contexa SaaS. Connecting Contexa SaaS |
| AuthZEN decision API | off (contexa.security.zerotrust.authzen.enabled) | An enforcement point outside Contexa (a gateway, an MCP server) asks for decisions. Protecting tool calls and MCP servers |
| SOAR playbooks and approval | no OSS implementation | OSS has only the interfaces; there is no playbook execution or approval implementation. It is an extension point where the application plugs in its own. SOAR |
| MCP tool permits and approval | needs the enterprise module | OSS has only the data formats |
What to do in the admin console
What operators do in the admin console (/contexa/admin, administrator role). Contexa protects this path in both ownership modes; under HOST_OWNED administrators sign in with a Contexa administrator account, not an application account (table above).
| Menu | Path | What it does |
|---|---|---|
| System Settings | /contexa/admin/system-settings | Change the enforcement mode (a saved value wins over YAML) |
| Security event log | /contexa/admin/security-monitor | See the decision records and the integrity check of each record |
| Blocked Users | /contexa/admin/blacklist | See blocked users and their release requests, and handle them (release) |
| Prompt versions · Inspection Overview · Sealed Prompts · Official Inspection | /contexa/admin/prompt-quality/..., /contexa/admin/prompt-inspection | Make, try, use and roll back prompt versions, see inspection results and sealed evidence |
Where to read next
- Getting started: from the dependency to the first decision
- The Life of a Request: from a request's arrival to its decision and the next request
- Decision Engine: Layer 1 and Layer 2, the processing steps, learning
- Agents as security subjects: how AI agent requests are handled