contexa-core contexa-identity contexa-iam

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

The five decisionsA user (or agent) is always in one of these five states.
  • 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-datasource and contexa.datasource.isolation.shared-application-datasource-risk-accepted to true allows sharing, and a production profile (prod · production) still refuses it.
  • Decisions need an AI chat model and a vector store. Without Spring AI ChatModel and VectorStore beans (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 default AUTO only logs it for an ordinary application and stops the start for a Contexa-only application (FULL mode and the like) (FAIL_FAST).

The steps from the dependency to the first decision are in Getting started.

The three choices to make first

SettingDefaultWhat it decidesWhen to change it
contexa.bridge.ownership
(@EnableAISecurity(mode) sets its default)
HOST_OWNEDAuthentication 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.modeENFORCEEnforcement 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.modestandaloneInfrastructure 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 time and asynchronous decisionThe request-time lane never calls the AI model; the asynchronous lane never holds the request.

Request timewhile the user waits

  1. Request arrivesfrom a signed-in user or agent
  2. Apply the stored decisionstops here on block, step-up or hold
  3. Application logic and protected method run@Protectable method
  4. Publish an analysis eventafter the method has finished
← read decision
Decision storeper user, each decision with its lifetime
write decision →

Asynchronous decisionafter the response has left

  1. Receive and filter the eventno analysis if a decision is already in force
  2. One line per user and sessionone at a time
  3. The AI model decidesLayer 1, and Layer 2 when needed
  4. Enforce and recordstore, seal the evidence, write the audit record
RequestHost applicationContexaStoreAI model
  • Analysis events come from protected methods. With the default settings, analysis events are published by @Protectable method 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.

FeatureCONTEXA_OWNEDHOST_OWNED (default)
Security filter chain (sign-in, MFA pages, filters)built by ContexaNot 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 chainrun 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 chainsnone
Stored decisions enforced in @Protectable methodsrunsruns (also where an application that sets the user after Spring Security's filters is enforced)
#ai expressions in the application's @PreAuthorizenot 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 securityprotected 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)runsruns (details)
Authentication bridgereads the sign-in facts inside the chain and fills the security contextreads 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 flowContexa'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".

DecisionLifetimeWhere it appliesHow it ends
Allow (ALLOW)15 minutes (set with contexa.security.zerotrust.allow-validity)only in the same session, IP and browser it was made forback to pending analysis when the time passes
Step-up authentication (CHALLENGE)1,800 s (30 min)every session of the userallowed after passing the MFA this decision started, or the time runs out
Held for review (ESCALATE)300 s (5 min)every session of the useran administrator's approval. If unresolved when the time ends, the next request turns it into a block (CONTEXA_OWNED)
Block (BLOCK)no limitevery session of the useran administrator's approval (the user asks for release after the unblock MFA)
Pending analysis (PENDING_ANALYSIS)—no stored decisionchanges 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

The order of one decisionThe numbers are the order of execution. The details are on the Decision Engine page.
  1. 1
    Layer 1gathers the session flow, differences from the behavioral baseline, company records and past decision records; the AI model decides
  2. 2
    Layer 2decides the same request again, only when Layer 1 answered "these facts cannot decide it (ESCALATE)"
  3. 3
    Five 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.

What stays after a decisionThe audit record is kept for every decision; sealed evidence for a sample of the decisions an AI model made.
Audit recordThe record of the decisionThe proposed and final actions are written to 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 record
Sealed evidenceThe prompt exactly as sent to the modelThe prompt, its inputs and the decision are bound by a hash and kept (Sealed evidence and official verification)
Prompt versions and inspectionWhich prompt askedEach decision is drawn with a prompt version (v1.0, v2.0 …) chosen on the admin console. Sealed prompts are compared with the facts apart from the decision (The Decision Prompt, Prompt Versions, Prompt Inspection and Replay)

Modules

Modules and dependenciesOf these, the application adds only the starter, which brings all five modules.
spring-boot-starter-contexadependency bundle
brings the five modules as api
contexa-autoconfigureauto-configuration
creates the beans whose conditions holdthe other four modules are compileOnly
contexa-identity · contexa-iamauthentication · authorization
identity DSL · MFA · OAuth2request-time filtersXACML policies@Protectableadmin console
contexa-coredecision engine
asynchronous decision · learningprompt versionsevidence · inspectionaudit
contexa-commonshared
decision typesannotationsauthentication bridgecache
ModuleWhat it doesDepends on
contexa-commonDecision types, shared annotations such as @EnableAISecurity and @Protectable, the authentication bridge, the cache abstractionnothing
contexa-coreAI 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-identityForm and REST sign-in, MFA (passkey, OTT), the adaptive MFA policy (AIAdaptiveMfaPolicyProvider), OAuth2, request-time filters, the identity DSLcontexa-core, contexa-common
contexa-iamXACML 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 consolecontexa-core, contexa-common
contexa-autoconfigureSpring Boot auto-configuration. It keeps the other four modules compileOnly and does not bring them itselffour modules (compileOnly)
spring-boot-starter-contexaThe one Contexa dependency the application addsfive modules (api)

Infrastructure modes

The infrastructure mode decides where Contexa keeps its state. Both modes need the dedicated Contexa database (PostgreSQL).

StateStandalone (standalone, default)Distributed (distributed)
Decision storememory (with a cap on the number of users)Redis (when a RedisTemplate bean exists)
Analysis event deliverymemory inside one serverKafka (when a KafkaTemplate bean exists)
Block signal (cutting a response in flight)inside one serverto 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 startkept in Redis

Write standalone or distributed in contexa.infrastructure.mode. Connection settings are in First start and deployment.

Optional features and extension points

FeatureDefaultDescription
Contexa SaaS forwardingoff (contexa.saas.enabled)Sends decisions other than allow and pending analysis to Contexa SaaS. Connecting Contexa SaaS
AuthZEN decision APIoff (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 approvalno OSS implementationOSS 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 approvalneeds the enterprise moduleOSS 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).

MenuPathWhat it does
System Settings/contexa/admin/system-settingsChange the enforcement mode (a saved value wins over YAML)
Security event log/contexa/admin/security-monitorSee the decision records and the integrity check of each record
Blocked Users/contexa/admin/blacklistSee 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-inspectionMake, try, use and roll back prompt versions, see inspection results and sealed evidence

Where to read next