Auto-Configuration

CoSec uses Spring Boot's auto-configuration mechanism to automatically wire up all security components based on classpath presence and property configuration. This allows applications to add CoSec by simply including the dependency with minimal configuration.

Auto-Configuration Overview

All 19 CoSec auto-configuration classes are registered as independent, flat entries in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports -- there is no parent/child hierarchy among them. What ties them together is the shared @ConditionalOnCoSecEnabled gate (cosec.enabled, default true); several classes layer additional conditions on top (for example, CoSecAuthorizationAutoConfiguration also requires @ConditionalOnAuthorizationEnabled, and CoSecGatewayAuthorizationAutoConfiguration additionally requires @ConditionalOnGatewayEnabled and @ConditionalOnClass(AuthorizationGatewayFilter::class)). The one exception is CoSecEndpointAutoConfiguration, which is activated purely by classpath presence.

graph TD
    G["@ConditionalOnCoSecEnabled<br>(cosec.enabled=true)"]
    G --> A["CoSecAutoConfiguration"]
    G --> B["CoSecAuthenticationAutoConfiguration"]
    G --> C["CoSecSocialAuthenticationAutoConfiguration"]
    G --> D["CoSecPolicyCacheAutoConfiguration"]
    G --> E["CoSecPermissionCacheAutoConfiguration"]
    G --> F["CoSecRequestParserAutoConfiguration"]
    G --> H["CoSecAuthorizationAutoConfiguration"]
    G --> I["CoSecGatewayAuthorizationAutoConfiguration"]
    G --> J["InjectSecurityContextAutoConfiguration"]
    G --> K["CoSecTokenRevocationCacheAutoConfiguration"]
    G --> L["CoSecJwtAutoConfiguration"]
    G --> M["CoSecOpenTelemetryAutoConfiguration"]
    G --> N["Ip2RegionAutoConfiguration"]
    G --> O["CoSecOpenAPIAutoConfiguration"]
    G --> Q["CoSecRedisRateLimiterAutoConfiguration"]
    G --> R["CoSecKafkaAuditAutoConfiguration"]
    G --> S["CoSecAuditAutoConfiguration"]
    G --> T["CoSecAuditFallbackAutoConfiguration"]
    P["CoSecEndpointAutoConfiguration<br>(classpath-only gate)"]

    style G fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style A fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style B fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style C fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style D fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style E fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style F fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style H fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style I fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style J fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style K fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style L fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style M fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style N fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style O fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style Q fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style R fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style S fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style T fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style P fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

CoSecAutoConfiguration

The root auto-configuration class. It runs before JacksonAutoConfiguration to ensure the CoSec JSON module is registered early.

@ConditionalOnCoSecEnabled
@AutoConfiguration(before = [JacksonAutoConfiguration::class])
@EnableConfigurationProperties(CoSecProperties::class)
class CoSecAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    fun coSecModule(): CoSecModule = CoSecModule()

    @Bean
    fun matcherFactoryRegister(
        applicationContext: ApplicationContext
    ): MatcherFactoryRegister = MatcherFactoryRegister(applicationContext)
}

Registers two beans (the coSecModule bean backs off via @ConditionalOnMissingBean when the application defines its own):

1. CoSecModule -- Jackson module for serializing CoSec types (policies, statements, matchers).
2. MatcherFactoryRegister -- Spring SmartLifecycle that registers all ActionMatcherFactory and ConditionMatcherFactory beans from the application context.

Conditional Annotations

CoSec defines a hierarchy of conditional annotations that control which auto-configuration classes are activated:

graph TD
    A["@ConditionalOnCoSecEnabled<br>(cosec.enabled=true)"] --> B["@ConditionalOnAuthorizationEnabled<br>(cosec.authorization.enabled=true)"]
    A --> C["@ConditionalOnJwtEnabled<br>(cosec.jwt.enabled=true)"]
    A --> D["@ConditionalOnAuthenticationEnabled<br>(cosec.authentication.enabled=true)"]
    A --> E["@ConditionalOnIp2RegionEnabled<br>(cosec.ip2region.enabled=true)"]
    B --> F["@ConditionalOnGatewayEnabled<br>(cosec.authorization.gateway.enabled=true)"]

    style A fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style B fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style C fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style D fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style E fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style F fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

All annotations are built on Spring's @ConditionalOnProperty. The root @ConditionalOnCoSecEnabled uses matchIfMissing = true, so CoSec is enabled by default.

Annotation	Property	Default
@ConditionalOnCoSecEnabled	cosec.enabled	true
@ConditionalOnAuthorizationEnabled	cosec.authorization.enabled	true
@ConditionalOnJwtEnabled	cosec.jwt.enabled	true
@ConditionalOnAuthenticationEnabled	cosec.authentication.enabled	true
@ConditionalOnIp2RegionEnabled	cosec.ip2region.enabled	true
@ConditionalOnGatewayEnabled	cosec.authorization.gateway.enabled	true

CoSecAuthorizationAutoConfiguration

Wires up the core authorization components:

graph TD
    A["CoSecAuthorizationAutoConfiguration"] --> B["securityContextParser<br>(DefaultSecurityContextParser)"]
    A --> C["cosecAuthorization<br>(SimpleAuthorization)"]
    A --> D["blacklistChecker<br>(BlacklistChecker.NoOp)"]
    A --> E["localPolicyLoader<br>(local-policy.enabled)"]
    A --> F["localPolicyInitializer<br>(local-policy.init-repository)"]
    A --> K["localPolicyInitializerLifecycle<br>(local-policy.init-repository)"]
    A --> G["WebFlux config"]
    A --> H["WebMVC config"]
    G --> I["reactiveAuthorizationFilter<br>(ReactiveAuthorizationFilter)"]
    H --> J["authorizationFilter<br>(AuthorizationFilter)"]

    style A fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style B fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style C fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style D fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style E fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style F fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style K fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style G fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style H fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style I fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style J fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

The nested WebFlux and WebMVC configurations are conditionally activated based on classpath presence:

• WebFlux: activated when ReactiveAuthorizationFilter is on the classpath AND Spring Cloud Gateway is NOT.
• WebMVC: activated when AuthorizationFilter is on the classpath.
• Gateway: handled by the separate CoSecGatewayAuthorizationAutoConfiguration, activated via @ConditionalOnClass(AuthorizationGatewayFilter::class); the plain WebFlux reactiveAuthorizationFilter bean itself carries @ConditionalOnMissingClass("org.springframework.cloud.gateway.filter.GlobalFilter"), so it backs off when Spring Cloud Gateway is on the classpath.

The localPolicyLoader and localPolicyInitializer beans are off by default: each is guarded by @ConditionalOnProperty (cosec.authorization.local-policy.enabled and cosec.authorization.local-policy.init-repository respectively) with matchIfMissing = false, so both beans are only created when explicitly enabled. The localPolicyInitializerLifecycle bean is guarded by the same init-repository property; it is a SmartLifecycle whose phase runs right after MatcherFactoryRegister, so local policies are initialized exactly once, after all SPI matcher factories have been registered.

CoSecJwtAutoConfiguration

Configures JWT token handling:

• Algorithm: Supports HMAC256, HMAC384, HMAC512 via JwtProperties.
• TokenConverter: Creates JWT access and refresh tokens with configurable validity periods.
• TokenVerifier: Verifies JWT signatures.
• TokenCompositeAuthentication: Wraps CompositeAuthentication with token generation (when authentication is enabled).

CoSecProperties

Root configuration properties:

cosec:
  enabled: true          # Master switch for all CoSec features
  # Sub-properties follow the same pattern:
  # cosec.authorization.enabled
  # cosec.jwt.enabled
  # cosec.authentication.enabled
  # cosec.ip2region.enabled

Spring Auto-Configuration Registration

CoSec uses Spring Boot's META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file to register all auto-configuration classes. This is the modern replacement for spring.factories. The starter registers all 19 auto-configuration classes as flat, independent entries:

me.ahoo.cosec.spring.boot.starter.CoSecAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authentication.CoSecAuthenticationAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authentication.social.CoSecSocialAuthenticationAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.cache.CoSecPolicyCacheAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.cache.CoSecPermissionCacheAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.CoSecRequestParserAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.CoSecAuthorizationAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.gateway.CoSecGatewayAuthorizationAutoConfiguration
me.ahoo.cosec.spring.boot.starter.inject.InjectSecurityContextAutoConfiguration
me.ahoo.cosec.spring.boot.starter.jwt.CoSecTokenRevocationCacheAutoConfiguration
me.ahoo.cosec.spring.boot.starter.jwt.CoSecJwtAutoConfiguration
me.ahoo.cosec.spring.boot.starter.opentelemetry.CoSecOpenTelemetryAutoConfiguration
me.ahoo.cosec.spring.boot.starter.ip2region.Ip2RegionAutoConfiguration
me.ahoo.cosec.spring.boot.starter.actuate.CoSecEndpointAutoConfiguration
me.ahoo.cosec.spring.boot.starter.openapi.CoSecOpenAPIAutoConfiguration
me.ahoo.cosec.spring.boot.starter.authorization.limiter.CoSecRedisRateLimiterAutoConfiguration
me.ahoo.cosec.spring.boot.starter.audit.kafka.CoSecKafkaAuditAutoConfiguration
me.ahoo.cosec.spring.boot.starter.audit.CoSecAuditAutoConfiguration
me.ahoo.cosec.spring.boot.starter.audit.CoSecAuditFallbackAutoConfiguration

The audit entries are additionally guarded by @ConditionalOnAuditEnabled (CoSecAuditAutoConfiguration.kt:39).

sequenceDiagram
    autonumber
    participant Boot as Spring Boot
    participant Meta as AutoConfiguration.imports
    participant Root as CoSecAutoConfiguration
    participant Auth as CoSecAuthorizationAutoConfiguration
    participant Jwt as CoSecJwtAutoConfiguration
    participant GW as CoSecGatewayAuthorizationAutoConfiguration

    Boot->>Meta: Load auto-configuration list
    Meta-->>Boot: List of configuration classes
    Boot->>Root: Evaluate @ConditionalOnCoSecEnabled
    alt CoSec enabled
        Root->>Root: Register CoSecModule + MatcherFactoryRegister
        Boot->>Auth: Evaluate @ConditionalOnAuthorizationEnabled
        Auth->>Auth: Register Authorization beans
        Boot->>Jwt: Evaluate @ConditionalOnJwtEnabled
        Jwt->>Jwt: Register JWT beans
        Boot->>GW: Evaluate @ConditionalOnGatewayEnabled
        GW->>GW: Register AuthorizationGatewayFilter
    end

References

• cosec-spring-boot-starter/src/main/kotlin/.../CoSecAutoConfiguration.kt:37 -- Root auto-configuration
• cosec-spring-boot-starter/src/main/kotlin/.../CoSecProperties.kt:30 -- Configuration properties
• cosec-spring-boot-starter/src/main/kotlin/.../ConditionalOnCoSecEnabled.kt:23 -- Conditional annotation
• cosec-spring-boot-starter/src/main/kotlin/.../CoSecAuthorizationAutoConfiguration.kt:48 -- Authorization auto-configuration
• cosec-spring-boot-starter/src/main/kotlin/.../CoSecJwtAutoConfiguration.kt:47 -- JWT auto-configuration

Related Pages

• Custom Matchers
• Spring WebFlux Integration
• Spring Cloud Gateway Integration
• Deployment