Identity Configuration | Contexa Docs

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

Property	Type	Default	Description
`spring.auth.state-type`	`StateType`	`OAUTH2`	Selects the default state mode. Current enum values are `OAUTH2` and `SESSION`.
`spring.auth.token-transport-type`	`TokenTransportType`	`HEADER`	Controls how tokens are transported. Current enum values are `COOKIE`, `HEADER`, and `HEADER_COOKIE`.
`spring.auth.token-issuer`	`TokenIssuer`	`INTERNAL`	Selects whether Contexa issues tokens itself or expects an external authorization server. Current enum values are `INTERNAL` and `AUTHORIZATION_SERVER`.
`spring.auth.factor-selection-type`	`FactorSelectionType`	`SELECT`	Controls whether MFA factor choice is explicitly presented or automatically selected. Current enum values are `AUTO` and `SELECT`.
`spring.auth.access-token-validity`	`long`	`3600000`	Access token validity in milliseconds.
`spring.auth.refresh-token-validity`	`long`	`604800000`	Refresh token validity in milliseconds.
`spring.auth.refresh-rotate-threshold`	`long`	`43200000`	Threshold after which refresh-token rotation is triggered on use.
`spring.auth.enable-refresh-token`	`boolean`	`true`	Enables refresh token issuance.
`spring.auth.allow-multiple-logins`	`boolean`	`false`	Allows multiple concurrent active logins for the same principal.
`spring.auth.max-concurrent-logins`	`int`	`3`	Concurrent login ceiling when multiple logins are allowed.
`spring.auth.cookie-secure`	`boolean`	`true`	Marks authentication cookies as secure by default.
`spring.auth.token-persistence`	`String`	`memory`	Frontend token persistence mode passed to login and MFA pages. Current OSS client modes are `memory`, `localstorage`, and `sessionstorage`.
`spring.auth.token-prefix`	`String`	`Bearer`	Authorization header prefix.
`spring.auth.roles-claim`	`String`	`roles`	JWT claim name used for roles.
`spring.auth.scopes-claim`	`String`	`scopes`	JWT claim name used for scopes.
`spring.auth.oauth2-csrf`	`boolean`	`false`	Toggles CSRF protection for OAuth2-oriented endpoints.

YAML

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

Property	Default	Description
`spring.auth.urls.single.form-login-processing`	`/login`	Default processing endpoint for non-MFA form login.
`spring.auth.urls.single.form-login-page`	`/login`	Default page for non-MFA form login.
`spring.auth.urls.single.rest-login-processing`	`/api/login`	Default processing endpoint for non-MFA REST login.
`spring.auth.urls.single.login-failure`	`/login?error`	Failure redirect for non-MFA flows.
`spring.auth.urls.single.login-success`	`/`	Success redirect for non-MFA flows.
`spring.auth.urls.single.logout-page`	`/logout`	Logout page for single-factor flows.
`spring.auth.urls.single.ott.request-email`	`/login/ott`	Single-factor OTT request page.
`spring.auth.urls.single.ott.code-generation`	`/ott/generate`	Single-factor OTT code generation endpoint.
`spring.auth.urls.single.ott.code-sent`	`/login/ott/sent`	Single-factor OTT sent page.
`spring.auth.urls.single.ott.challenge`	`/login/ott/verify`	Single-factor OTT verification page.
`spring.auth.urls.single.ott.login-processing`	`/login/ott`	Single-factor OTT verification endpoint.
`spring.auth.urls.single.ott.login-failure`	`/login/ott?error`	Single-factor OTT failure page.
`spring.auth.urls.single.passkey.login-page`	`/login/webauthn`	Single-factor passkey login page.
`spring.auth.urls.single.passkey.login-processing`	`/login/webauthn`	Single-factor passkey verification endpoint.
`spring.auth.urls.single.passkey.login-failure`	`/login/webauthn?error`	Single-factor passkey failure page.
`spring.auth.urls.single.passkey.assertion-options`	`/webauthn/authenticate/options`	Passkey assertion options endpoint.
`spring.auth.urls.single.passkey.registration-options`	`/webauthn/register/options`	Passkey registration options endpoint.
`spring.auth.urls.single.passkey.registration-processing`	`/webauthn/register`	Passkey registration processing endpoint.

MFA URL Groups

Property	Default	Description
`spring.auth.urls.primary.form-login-processing`	`/mfa/login`	Primary form-processing URL used inside MFA flows.
`spring.auth.urls.primary.form-login-page`	`/mfa/login`	Primary form page used inside MFA flows.
`spring.auth.urls.primary.rest-login-processing`	`/api/mfa/login`	Primary REST login endpoint used inside MFA flows.
`spring.auth.urls.primary.login-failure`	`/login?error`	Primary failure redirect.
`spring.auth.urls.primary.login-success`	`/`	Primary success redirect.
`spring.auth.urls.primary.logout-page`	`/logout`	Primary logout page.
`spring.auth.urls.mfa.select-factor`	`/mfa/select-factor`	MFA factor selection page.
`spring.auth.urls.mfa.success`	`/mfa/success`	MFA success page.
`spring.auth.urls.mfa.failure`	`/mfa/failure`	MFA failure page.
`spring.auth.urls.mfa.cancel`	`/mfa/cancel`	MFA cancellation endpoint/page.
`spring.auth.urls.mfa.status`	`/mfa/status`	MFA status endpoint.
`spring.auth.urls.mfa.request-ott-code`	`/mfa/request-ott-code`	OTT code request endpoint.
`spring.auth.urls.mfa.config`	`/api/mfa/config`	MFA config endpoint used by the page generator and client code.
`spring.auth.urls.factors.ott.request-code-ui`	`/mfa/ott/request-code-ui`	OTT request page.
`spring.auth.urls.factors.ott.code-generation`	`/mfa/ott/generate-code`	OTT code generation endpoint.
`spring.auth.urls.factors.ott.code-sent`	`/mfa/ott/code-sent`	OTT code-sent page.
`spring.auth.urls.factors.ott.challenge-ui`	`/mfa/challenge/ott`	OTT challenge page.
`spring.auth.urls.factors.ott.login-processing`	`/login/mfa-ott`	OTT login-processing endpoint.
`spring.auth.urls.factors.ott.default-failure`	`/mfa/challenge/ott?error=true`	Default OTT failure redirect.
`spring.auth.urls.factors.ott.single-ott-request-email`	`/loginOtt`	Legacy single-OTT request page path retained by `OttUrls`.
`spring.auth.urls.factors.ott.single-ott-code-generation`	`/login/ott/generate`	Legacy single-OTT generation path retained by `OttUrls`.
`spring.auth.urls.factors.ott.single-ott-challenge`	`/loginOttVerifyCode`	Legacy single-OTT challenge path retained by `OttUrls`.
`spring.auth.urls.factors.ott.single-ott-sent`	`/ott/sent`	Legacy single-OTT sent page path retained by `OttUrls`.
`spring.auth.urls.factors.passkey.rp-id`	`localhost`	Default passkey relying-party ID.
`spring.auth.urls.factors.passkey.rp-name`	`contexa-identity`	Default passkey relying-party name.
`spring.auth.urls.factors.passkey.allowed-origins`	`null`	Comma-separated allowed origins. When unset, the passkey builder falls back to `http://localhost:{server.port}`.
`spring.auth.urls.factors.passkey.login-processing`	`/login/mfa-webauthn`	Passkey authentication endpoint for MFA mode.
`spring.auth.urls.factors.passkey.challenge-ui`	`/mfa/challenge/passkey`	Passkey challenge page.
`spring.auth.urls.factors.passkey.registration-processing`	`/webauthn/register`	Passkey registration endpoint.
`spring.auth.urls.factors.passkey.assertion-options`	`/webauthn/authenticate/options`	Passkey assertion options endpoint.
`spring.auth.urls.factors.passkey.registration-options`	`/webauthn/register/options`	Passkey registration options endpoint.
`spring.auth.urls.factors.recovery-code-login-processing`	`/login/recovery/verify`	Recovery-code verification endpoint.
`spring.auth.urls.factors.recovery-code-challenge-ui`	`/mfa/challenge/recovery`	Recovery-code challenge page.

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

Property	Default	Description
`spring.auth.internal.login-uri`	`/api/login`	Internal JWT login endpoint.
`spring.auth.internal.logout-uri`	`/logout`	Internal logout endpoint.
`spring.auth.internal.refresh-uri`	`/api/refresh`	Internal refresh endpoint.

OAuth2 / Authorization-Server Settings

Property	Default	Description
`spring.auth.oauth2.client-id`	`default-client`	OAuth2 client identifier.
`spring.auth.oauth2.client-secret`	`173f8245-5f7d-4623-a612-aa0c68f6da4a`	Default client secret declared by `OAuth2TokenSettings`. Override it in real deployments.
`spring.auth.oauth2.issuer-uri`	`http://localhost:9000`	Issuer base URI.
`spring.auth.oauth2.token-endpoint`	`/oauth2/token`	Token endpoint path.
`spring.auth.oauth2.scope`	`read`	Default scope requested by the runtime.
`spring.auth.oauth2.redirect-uri`	`http://localhost:8080`	Post-authorization redirect URI.
`spring.auth.oauth2.authorized-uri`	`null`	Optional post-authorization redirect override.
`spring.auth.oauth2.jwk-key-store-path`	`null`	Path to the JWK keystore.
`spring.auth.oauth2.jwk-key-store-password`	`null`	Keystore password.
`spring.auth.oauth2.jwk-key-alias`	`null`	Key alias inside the keystore.
`spring.auth.oauth2.jwk-key-password`	`null`	Key password override.

YAML

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.

Property	Type	Default	Description
`spring.auth.mfa.session-timeout-ms`	`long`	`600000`	Overall MFA session timeout.
`spring.auth.mfa.challenge-timeout-ms`	`long`	`300000`	Per-challenge timeout window.
`spring.auth.mfa.inactivity-timeout`	`long`	`900000`	Idle-time cutoff for MFA state.
`spring.auth.mfa.cache-ttl`	`long`	`300000`	TTL for MFA runtime cache entries.
`spring.auth.mfa.session-refresh-interval-ms`	`long`	`30000`	Refresh cadence for active MFA sessions.
`spring.auth.mfa.state-machine-timeout-ms`	`long`	`10000`	Timeout budget for state-machine-aware MFA handlers.
`spring.auth.mfa.max-retry-attempts`	`int`	`5`	Maximum verification retries before lockout logic applies.
`spring.auth.mfa.account-lockout-duration-ms`	`long`	`900000`	Duration of MFA lockout after retry exhaustion.
`spring.auth.mfa.minimum-delay-ms`	`long`	`500`	Minimum timing floor used to reduce response timing variance.
`spring.auth.mfa.device-remember-duration-ms`	`long`	`2592000000`	Remember-device duration.
`spring.auth.mfa.otp-token-validity-seconds`	`int`	`300`	OTP validity window.
`spring.auth.mfa.otp-token-length`	`int`	`6`	OTP code length.
`spring.auth.mfa.sms-resend-interval-seconds`	`int`	`60`	SMS resend throttle.
`spring.auth.mfa.email-resend-interval-seconds`	`int`	`120`	Email resend throttle.
`spring.auth.mfa.state-machine-pool-size`	`int`	`100`	Legacy MFA state-machine pool size setting preserved by `MfaSettings`.
`spring.auth.mfa.state-machine-cache-ttl-ms`	`long`	`300000`	Legacy MFA state-machine cache TTL preserved by `MfaSettings`.
`spring.auth.mfa.circuit-breaker-failure-threshold`	`int`	`5`	Failure threshold before the MFA circuit breaker opens.
`spring.auth.mfa.circuit-breaker-timeout-seconds`	`int`	`30`	Open-state timeout for the MFA circuit breaker.
`spring.auth.mfa.detailed-logging-enabled`	`boolean`	`false`	Enables verbose MFA diagnostics.
`spring.auth.mfa.metrics-enabled`	`boolean`	`true`	Enables MFA metrics.
`spring.auth.mfa.audit-logging-enabled`	`boolean`	`true`	Enables MFA audit logging.
`spring.auth.mfa.session-storage-type`	`String`	`http-session`	Primary MFA session repository label.
`spring.auth.mfa.auto-select-repository`	`boolean`	`false`	Enables automatic repository selection.
`spring.auth.mfa.repository-priority`	`String`	`redis,memory,http-session`	Repository priority order string.
`spring.auth.mfa.fallback-repository-type`	`String`	`http-session`	Fallback repository label.

MFA Repository Settings

Property	Default	Description
`spring.auth.mfa.http-session.enabled`	`true`	Enables the HTTP-session-backed MFA repository.
`spring.auth.mfa.http-session.create-session-if-not-exists`	`true`	Creates an HTTP session on demand.
`spring.auth.mfa.http-session.session-attribute-name`	`MFA_SESSION_ID`	Attribute name used to store the MFA session identifier.
`spring.auth.mfa.redis.enabled`	`true`	Enables the Redis-backed MFA repository.
`spring.auth.mfa.redis.key-prefix`	`mfa:session:`	Redis key prefix for MFA sessions.
`spring.auth.mfa.redis.cookie-name`	`MFA_SID`	Cookie carrying the Redis-backed MFA session identifier.
`spring.auth.mfa.redis.secure-cookie`	`true`	Marks the MFA session cookie as secure.
`spring.auth.mfa.redis.http-only-cookie`	`true`	Marks the MFA session cookie as HTTP-only.
`spring.auth.mfa.redis.same-site`	`Strict`	SameSite cookie attribute.
`spring.auth.mfa.redis.connection-timeout`	`3000`	Redis connection timeout.
`spring.auth.mfa.redis.max-retries`	`3`	Redis retry limit.
`spring.auth.mfa.memory.enabled`	`true`	Enables the in-memory MFA repository.
`spring.auth.mfa.memory.cleanup-interval-minutes`	`5`	Cleanup interval for in-memory MFA sessions.
`spring.auth.mfa.memory.max-sessions`	`10000`	Maximum number of in-memory MFA sessions.
`spring.auth.mfa.memory.enable-metrics`	`true`	Enables repository metrics for the in-memory backend.

MFA Factor Settings

Property	Default	Description
`spring.auth.mfa.sms-factor.provider`	`default`	SMS provider identifier.
`spring.auth.mfa.sms-factor.template-id`	`mfa_sms_template`	SMS template identifier.
`spring.auth.mfa.sms-factor.max-daily-attempts`	`10`	Daily SMS delivery cap.
`spring.auth.mfa.sms-factor.enabled`	`true`	Enables SMS MFA factor support.
`spring.auth.mfa.email-factor.from-address`	`noreply@company.com`	Sender address for email OTP messages.
`spring.auth.mfa.email-factor.template-id`	`mfa_email_template`	Email template identifier.
`spring.auth.mfa.email-factor.max-daily-attempts`	`5`	Daily email delivery cap.
`spring.auth.mfa.email-factor.enabled`	`true`	Enables email MFA factor support.

YAML

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

Property	Type	Default	Description
`contexa.identity.statemachine.enabled`	`boolean`	`true`	Master switch for the MFA state machine runtime.
`contexa.identity.statemachine.operation-timeout-seconds`	`int`	`10`	Timeout budget for state machine operations.
`contexa.identity.statemachine.circuit-breaker.failure-threshold`	`int`	`5`	Failure threshold before the circuit breaker opens.
`contexa.identity.statemachine.circuit-breaker.timeout-seconds`	`int`	`30`	Open-state timeout for the circuit breaker.
`contexa.identity.statemachine.circuit-breaker.half-open-requests`	`int`	`3`	Requests allowed while half-open.

Pool, Persistence, Cache, and Events

Property	Default	Description
`contexa.identity.statemachine.pool.core-size`	`10`	Core state-machine executor size.
`contexa.identity.statemachine.pool.max-size`	`50`	Maximum state-machine executor size.
`contexa.identity.statemachine.pool.keep-alive-time`	`10`	Keep-alive time for pooled workers.
`contexa.identity.statemachine.pool.expansion-threshold`	`0.8`	Expansion threshold for worker scaling.
`contexa.identity.statemachine.pool.shrink-threshold`	`0.2`	Shrink threshold for worker scaling.
`contexa.identity.statemachine.persistence.type`	`memory`	Persistence backend label.
`contexa.identity.statemachine.persistence.enable-fallback`	`true`	Enables fallback persistence.
`contexa.identity.statemachine.persistence.ttl-minutes`	`30`	Persistence TTL in minutes.
`contexa.identity.statemachine.persistence.enable-compression`	`true`	Enables compressed persistence payloads.
`contexa.identity.statemachine.persistence.compression-threshold`	`1024`	Compression threshold in bytes.
`contexa.identity.statemachine.cache.max-size`	`1000`	In-memory cache size for state-machine snapshots.
`contexa.identity.statemachine.cache.ttl-minutes`	`5`	Cache TTL in minutes.
`contexa.identity.statemachine.cache.enable-warmup`	`false`	Enables cache warmup on startup.
`contexa.identity.statemachine.events.enabled`	`true`	Enables state-machine event publishing.
`contexa.identity.statemachine.events.type`	`local`	Event transport type.
`contexa.identity.statemachine.events.batch-size`	`100`	Event batch size.
`contexa.identity.statemachine.events.batch-interval-ms`	`100`	Event batch interval.
`contexa.identity.statemachine.events.backpressure-threshold`	`1000`	Backpressure threshold.

MFA, Redis, and Distributed Lock

Property	Default	Description
`contexa.identity.statemachine.mfa.enable-metrics`	`true`	Enables state-machine MFA metrics.
`contexa.identity.statemachine.mfa.max-retries`	`3`	Retry ceiling used by the state machine.
`contexa.identity.statemachine.mfa.session-timeout-minutes`	`30`	Session timeout in minutes.
`contexa.identity.statemachine.mfa.max-concurrent-sessions`	`1000`	Concurrent state-machine session ceiling.
`contexa.identity.statemachine.mfa.transition-timeout-seconds`	`30`	Transition timeout per state change.
`contexa.identity.statemachine.redis.enabled`	`false`	Enables Redis-backed state-machine storage.
`contexa.identity.statemachine.redis.ttl-minutes`	`30`	Redis TTL in minutes.
`contexa.identity.statemachine.redis.key-prefix`	`mfa:statemachine:`	Redis key prefix for state-machine entries.
`contexa.identity.statemachine.redis.connection-timeout-ms`	`2000`	Redis connection timeout.
`contexa.identity.statemachine.redis.command-timeout-ms`	`1000`	Redis command timeout.
`contexa.identity.statemachine.distributed-lock.enabled`	`true`	Enables distributed locking around state transitions.
`contexa.identity.statemachine.distributed-lock.timeout-seconds`	`10`	Distributed lock timeout.
`contexa.identity.statemachine.distributed-lock.max-retry-attempts`	`3`	Retry ceiling for lock acquisition.
`contexa.identity.statemachine.distributed-lock.retry-interval-ms`	`100`	Retry interval for lock acquisition.
`contexa.identity.statemachine.distributed-lock.enable-deadlock-detection`	`true`	Enables deadlock detection for distributed locking.

YAML

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.