Infrastructure Configuration

Contexa Core Properties (Summary)

The top-level ContexaProperties class (prefix contexa) contains the master switches for infrastructure mode, Redis, Kafka, and observability. These properties are fully documented on the Configuration Overview page. Key infrastructure-related entries include:

See the Configuration Overview for the complete ContexaProperties reference.

Cache Properties

Properties under contexa.cache, bound to ContexaCacheProperties. Controls the multi-tier caching subsystem used throughout Contexa for identity, policy, and behavioral data. Supports local (Caffeine), Redis, and hybrid caching strategies with optional pub/sub-based cache invalidation.

General Settings

Domain-Specific TTL

Each cache domain can have independent TTL values for local and Redis tiers. This allows fine-grained control — for example, frequently changing policy data can use shorter TTLs while stable HCAD baseline data uses longer ones.

Each domain entry is a TtlConfig object with local-ttl-seconds and redis-ttl-seconds fields. Override any domain independently:

contexa:
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "myapp:contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 60
      hcad:
        local-ttl-seconds: 43200
        redis-ttl-seconds: 86400

Bridge Properties

BridgeProperties is bound to contexa.bridge. It controls the bridge layer that maps user, authority, delegation, and session information bidirectionally between an external (legacy) authentication system and Contexa. The properties define SecurityContext extraction keys, session attribute candidates, request-attribute keys, HTTP header names, sync policy, and the trusted-proxy list.

Bridge Core Toggles

Synchronization (Sync)

Trusted Proxies (Network)

Authentication SecurityContext Keys

Properties under contexa.bridge.authentication.security-context, bound to Authentication.SecurityContext. Defines the candidate keys used to extract display name, principal type, authentication method, assurance level, MFA state, authentication time, and additional attributes from the external token's claims/attributes. The first matching key wins.

Authentication Session Keys

Properties under contexa.bridge.authentication.session, bound to the shared Bridge.Session class. When an external system stores the authenticated user object as an HTTP session attribute, these keys define which attribute names to try and which keys to use to extract principal id, display name, authorities, authentication method, MFA state, authentication time, and additional attributes from that object.

Authentication RequestAttributes Keys

Properties under contexa.bridge.authentication.request-attributes, bound to the shared Bridge.RequestAttributes class. Defines which attribute candidates to try when an external filter stores the user object on HttpServletRequest, which keys to read from that object, and which flat key names Contexa uses when re-exposing values back as request attributes.

Discovery / Extraction (13 shared)

Flat authentication attribute keys (flat-*, 8)

Single key names Contexa uses when flattening values back onto request attributes so downstream components can read them directly.

Authorization mapping keys (7)

Delegation mapping keys (11)

Authentication HTTP Header Names

Properties under contexa.bridge.authentication.headers, bound to the shared Bridge.Headers class. Defines which header names Contexa reads from (and emits onto) HTTP traffic when a reverse proxy or gateway propagates authentication, authorization, or delegation context. All header names are configurable.

Toggle

Authentication headers (8)

Authorization headers (7)

Delegation headers (11)

Authorization SecurityContext Keys

Properties under contexa.bridge.authorization.security-context, bound to Authorization.SecurityContext. When an external system stores authorization decisions (effect, policy ID, authorities, etc.) as attributes on the Spring SecurityContext Authentication, these keys define which candidate names Contexa tries to read that information. The first matching key wins.

Authorization Session Keys

Properties under contexa.bridge.authorization.session, bound to Authorization.Session. When an external system stores authorization decisions on a session-scoped user object, these keys define which attribute candidates to try and which keys to read for effect, policy, scope, role, and authority extraction.

Authorization RequestAttributes / Headers

Authorization reuses the same shared Bridge.RequestAttributes / Bridge.Headers classes. Key structure and defaults are identical to the Authentication RequestAttributes Keys and Authentication HTTP Header Names tables — only the prefix differs:

• contexa.bridge.authorization.request-attributes.* — 39 fields, same table
• contexa.bridge.authorization.headers.* — 27 fields, same table

The tables are not duplicated because BridgeProperties.java references a single class from three locations — keeping the documentation single-sourced.

Delegation Session Keys

Properties under contexa.bridge.delegation.session, bound to Delegation.Session. When an external system stores agent-delegation context — agent ID, objective, allowed operations/resources, approval requirement, expiry — on a session-scoped user object, these keys define which attribute candidates to try and which keys to read.

Delegation RequestAttributes / Headers

Delegation reuses the same shared Bridge.RequestAttributes / Bridge.Headers classes. Key structure and defaults match the Authentication RequestAttributes Keys and Authentication HTTP Header Names tables — only the prefix differs:

• contexa.bridge.delegation.request-attributes.* — 39 fields, same table
• contexa.bridge.delegation.headers.* — 27 fields, same table

Security Kafka Properties

Properties under contexa.security.kafka, bound to SecurityKafkaProperties. Configures Kafka topic names for Contexa's security event pipeline.

security:
  kafka:
    topic:
      authorization: security-authorization-events
      authentication: auth-events
      incident: security-incident-events
      threat: threat-indicators
      audit: security-audit-events
      general: security-events
      dlq: security-events-dlq
      soar-action: soar-action-events
    dlq:
      max-retries: 3
      retry-delay-ms: 5000
      alert-threshold: 10

Related: Zero Trust Security Reference | SOAR Automation Reference

OpenTelemetry Properties

Properties under contexa.opentelemetry, bound to OpenTelemetryProperties. Configures the OpenTelemetry integration for distributed tracing, metrics export, and observability.

contexa:
  opentelemetry:
    enabled: true
    service-name: "my-application"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

Security Plane Properties

Properties under contexa.security.plane, bound to SecurityPlaneProperties. The class configures the distributed security-plane agent, Kafka topics, Redis relay settings, monitoring batches, deduplication windows, and the LLM executor pool used by asynchronous security analysis.

security:
  plane:
    agent:
      name: SecurityPlaneAgent-1
      auto-start: true
      organization-id: default-org
      execution-mode: ASYNC
      auto-approve-low-risk: false
      event-timeout-ms: 30000
      max-deferred-retries: 3
    llm-executor:
      core-pool-size: 2
      max-pool-size: 2
      queue-capacity: 50
    deduplication:
      enabled: true
      window-minutes: 5
      cache-size: 10000

Related: Zero Trust Flow, SOAR Reference

Router Properties

Properties under contexa.security.router, bound to SecurityRouterProperties. Defines the score thresholds used when routing security events (SOAR automation / block / analysis confidence / pass-through).

Event Properties

Properties under contexa.security.event, bound to SecurityEventProperties. Configures event publishing gates, the asynchronous executor pool, per-tier latency budgets, and the deduplication cache.

Cold-Path Properties

Properties under contexa.security.coldpath, bound to SecurityColdPathProperties. Defines per-layer baseline confidence values for the asynchronous LLM analysis path.

Pipeline Properties

Properties under contexa.security.pipeline, bound to SecurityPipelineProperties. Configures the Redis · Kafka transport channels of the security event pipeline.

Note: contexa.security.pipeline.redis is an empty marker group. Actual Redis behavior is configured under contexa.security.plane.redis and security.zerotrust.redis.

Security Redis Properties

Properties under contexa.security.redis, bound to SecurityRedisProperties. Configures Redis pub/sub channel names, Redis stream keys, TTL, and memory thresholds for Contexa's security events.

Scheduler Lock Properties

Properties under contexa.scheduler.lock, bound to ContexaSchedulerLockProperties (record). Controls the ShedLock auto-configuration that ensures single execution of @Scheduled + @SchedulerLock methods across multiple JVMs. Single-instance deployments may keep the defaults — locks always succeed and the overhead is negligible.

DataSource Properties

Properties under contexa.datasource, bound to ContexaDataSourceProperties. Defines the database connection Contexa uses for its own metadata (policies, users, audit log, etc.). Can be isolated from the host application's spring.datasource.

Full Configuration Example

A production-ready application.yml combining all infrastructure properties for a distributed deployment with Redis, Kafka, and an external OpenTelemetry collector.

# Infrastructure configuration for Contexa distributed deployment
contexa:
  enabled: true
  infrastructure:
    mode: DISTRIBUTED
    redis:
      enabled: true
    kafka:
      enabled: true
    observability:
      enabled: true
      open-telemetry-enabled: true

  # Multi-tier caching
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      roles:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      permissions:
        local-ttl-seconds: 14400
        redis-ttl-seconds: 28800
      groups:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 120
      soar:
        local-ttl-seconds: 900
        redis-ttl-seconds: 900
      hcad:
        local-ttl-seconds: 86400
        redis-ttl-seconds: 86400

  # OpenTelemetry
  opentelemetry:
    enabled: true
    service-name: "contexa-production"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

  # Security Infrastructure
  security:
    kafka:
      topic:
        dlq: "security-events-dlq"
    redis:
      ttl:
        minutes: 60
      memory:
        max-mb: 1024
    plane:
      agent:
        organization-id: "default-org"
        execution-mode: "ASYNC"
      llm-executor:
        core-pool-size: 2
        max-pool-size: 2
      deduplication:
        enabled: true
        window-minutes: 5
        cache-size: 10000