Identity Configuration

Auth Context Properties

AuthContextProperties is bound to the spring.auth prefix. It controls authentication state selection, token transport, token issuer mode, URL groups, MFA runtime defaults, and token lifecycle.

Core Authentication Settings

spring:
  auth:
    state-type: oauth2
    token-transport-type: header
    token-issuer: internal
    factor-selection-type: select
    access-token-validity: 3600000
    refresh-token-validity: 604800000
    refresh-rotate-threshold: 43200000
    enable-refresh-token: true
    allow-multiple-logins: false
    max-concurrent-logins: 3
    cookie-secure: true
    token-persistence: memory
    token-prefix: "Bearer "
    roles-claim: roles
    scopes-claim: scopes
    oauth2-csrf: false

Related runtime references: Authentication, Adaptive MFA, and State Management.

URL Configuration Groups

spring.auth.urls is consumed by AuthUrlProvider. For MFA flows, MfaFlowUrlRegistry creates per-flow providers so named flows can safely apply custom prefixes without mutating shared global state.

Single Authentication URLs

MFA URL Groups

Runtime consumers: AuthUrlProvider resolves these paths, while MfaFlowUrlRegistry creates per-flow providers so named MFA flows can safely use different prefixes.

Token Issuer Settings

spring.auth.internal and spring.auth.oauth2 hold the two token-issuer configurations selected by spring.auth.token-issuer.

Internal JWT Endpoints

OAuth2 / Authorization-Server Settings

spring:
  auth:
    token-issuer: authorization_server
    internal:
      login-uri: /api/login
      logout-uri: /logout
      refresh-uri: /api/refresh
    oauth2:
      client-id: default-client
      client-secret: replace-me
      issuer-uri: http://localhost:9000
      token-endpoint: /oauth2/token
      scope: read
      redirect-uri: http://localhost:8080

MFA Runtime Settings

spring.auth.mfa is bound to MfaSettings. It controls challenge lifecycles, retry policy, repository selection, factor delivery defaults, and diagnostics. These defaults are consumed by MFA filters, handlers, and state-machine-aware request handling code.

MFA Repository Settings

MFA Factor Settings

spring:
  auth:
    mfa:
      session-timeout-ms: 600000
      challenge-timeout-ms: 300000
      max-retry-attempts: 5
      repository-priority: redis,memory,http-session
      redis:
        enabled: true
        key-prefix: mfa:session:
        cookie-name: MFA_SID
      memory:
        enabled: true
        max-sessions: 10000
      sms-factor:
        enabled: true
        provider: default
      email-factor:
        enabled: true
        from-address: noreply@company.com

State Machine Properties

StateMachineProperties is bound to contexa.identity.statemachine. It controls the MFA state machine runtime used by the identity module and related filters and handlers.

Core State Machine Settings

Pool, Persistence, Cache, and Events

MFA, Redis, and Distributed Lock

contexa:
  identity:
    statemachine:
      enabled: true
      operation-timeout-seconds: 10
      pool:
        core-size: 10
        max-size: 50
      persistence:
        type: memory
        ttl-minutes: 30
      events:
        enabled: true
        type: local
      mfa:
        max-retries: 3
        session-timeout-minutes: 30
      distributed-lock:
        enabled: true
        timeout-seconds: 10

Related runtime references: Identity DSL, Authentication, Adaptive MFA, and State Management.

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