cosec-integration

name	cosec-integration
description	Use when adding CoSec to a Spring Boot application, choosing WebFlux/WebMVC/Gateway modules, configuring JWT authentication, authorization filters, local policies, Redis policy caching, social login, IP enrichment, OpenAPI, or OpenTelemetry integration.

CoSec Integration Guide

This skill guides you through integrating CoSec into a Spring Boot application. CoSec is a reactive, multi-tenant RBAC + Policy-based security framework built on Spring Boot and Project Reactor.

Step 1: Add Dependencies

CoSec modules are published to Maven Central under the me.ahoo.cosec group. Use the BOM for version management.

Gradle (Kotlin DSL)

// gradle/libs.versions.toml
[versions]
cosec = "4.3.6"  // check latest at https://central.sonatype.com/artifact/me.ahoo.cosec/cosec-bom

[libraries]
cosec-bom = { module = "me.ahoo.cosec:cosec-bom", version.ref = "cosec" }
cosec-spring-boot-starter = { module = "me.ahoo.cosec:cosec-spring-boot-starter" }
cosec-webflux = { module = "me.ahoo.cosec:cosec-webflux" }
cosec-webmvc = { module = "me.ahoo.cosec:cosec-webmvc" }
cosec-gateway = { module = "me.ahoo.cosec:cosec-gateway" }
cosec-jwt = { module = "me.ahoo.cosec:cosec-jwt" }
cosec-cocache = { module = "me.ahoo.cosec:cosec-cocache" }
cosec-social = { module = "me.ahoo.cosec:cosec-social" }
cosec-ip2region = { module = "me.ahoo.cosec:cosec-ip2region" }
cosec-opentelemetry = { module = "me.ahoo.cosec:cosec-opentelemetry" }
cosec-openapi = { module = "me.ahoo.cosec:cosec-openapi" }

// build.gradle.kts
dependencies {
    implementation(platform(libs.cosec.bom))
    implementation(libs.cosec.spring.boot.starter)
    implementation(libs.cosec.webflux)   // for WebFlux apps
    // implementation(libs.cosec.webmvc)  // for Servlet apps
    // implementation(libs.cosec.gateway) // for Spring Cloud Gateway
    implementation(libs.cosec.jwt)       // JWT token handling
    // implementation(libs.cosec.cocache) // Redis policy caching
}

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>me.ahoo.cosec</groupId>
            <artifactId>cosec-bom</artifactId>
            <version>4.3.6</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>me.ahoo.cosec</groupId>
        <artifactId>cosec-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>me.ahoo.cosec</groupId>
        <artifactId>cosec-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>me.ahoo.cosec</groupId>
        <artifactId>cosec-jwt</artifactId>
    </dependency>
</dependencies>

Module Selection Guide

Use Case	Required Modules
Basic WebFlux app	cosec-spring-boot-starter + cosec-webflux
Servlet/WebMVC app	cosec-spring-boot-starter + cosec-webmvc
API Gateway	cosec-spring-boot-starter + cosec-gateway
JWT authentication	add cosec-jwt
Redis policy caching	add cosec-cocache
Social OAuth login	add cosec-social
IP geolocation conditions	add cosec-ip2region
Authorization tracing	add cosec-opentelemetry
OpenAPI/Swagger integration	add cosec-openapi

Step 2: Configure application.yaml

cosec:
  enabled: true                        # master switch (default: true)
  authentication:
    enabled: true                      # enable authentication
  authorization:
    enabled: true                      # enable authorization (default: true)
    local-policy:
      enabled: true                    # load policies from local JSON files
      locations: classpath:cosec-policy/*-policy.json
      init-repository: true            # push local policies to repository on startup
  jwt:
    algorithm: hmac256                 # hmac256, hmac384, hmac512, rsa256, etc.
    secret: your-256-bit-secret-key    # required for HMAC algorithms

Property Reference

Property	Default	Description
cosec.enabled	true	Master enable/disable switch
cosec.authentication.enabled	—	Enable/disable authentication
cosec.authorization.enabled	true	Enable/disable authorization
cosec.authorization.local-policy.enabled	false	Load policies from local JSON files
cosec.authorization.local-policy.locations	classpath:cosec-policy/*-policy.json	Resource patterns for policy files
cosec.authorization.local-policy.init-repository	false	Push local policies to repository on startup
cosec.jwt.algorithm	—	JWT algorithm (hmac256, rsa256, etc.)
cosec.jwt.secret	—	JWT secret key (for HMAC algorithms)
cosec.ip2region.enabled	false	Enable IP geolocation
cosec.openapi.enabled	false	Enable OpenAPI integration

Step 3: Create Policy Files

Place policy JSON files in src/main/resources/cosec-policy/. Files must match the pattern *-policy.json.

Minimal Example — Public Health Endpoint

{
  "id": "(health-probe)",
  "name": "Health Probe",
  "type": "global",
  "tenantId": "(platform)",
  "statements": [
    {
      "name": "actuator",
      "action": [
        "/actuator/health",
        "/actuator/health/readiness",
        "/actuator/health/liveness"
      ]
    }
  ]
}

Typical Example — API with Auth

{
  "id": "api-policy",
  "name": "API Policy",
  "type": "global",
  "tenantId": "(platform)",
  "statements": [
    {
      "name": "PublicEndpoints",
      "action": ["/auth/login", "/auth/register"]
    },
    {
      "name": "AuthenticatedApi",
      "action": "/api/**",
      "condition": { "authenticated": {} }
    },
    {
      "name": "AdminEndpoints",
      "action": "/admin/**",
      "condition": { "inRole": { "value": "admin" } }
    }
  ]
}

See the cosec-policy-author skill for full policy JSON reference.

Step 4: Spring Boot Application

No special annotations or configuration classes needed. CoSec auto-configures everything based on classpath and properties.

@SpringBootApplication
class MyApp

fun main(args: Array<String>) {
    runApplication<MyApp>(*args)
}

The auto-configuration automatically registers:

• ReactiveAuthorizationFilter (WebFlux) or AuthorizationFilter (WebMVC) or AuthorizationGatewayFilter (Gateway)
• SecurityContextParser for extracting security context from requests
• SimpleAuthorization for policy evaluation
• LocalPolicyLoader / LocalPolicyInitializer for loading local policy files
• JWT token converter and verifier (if cosec-jwt is on classpath)
• Request parsers for both reactive and servlet environments

Gateway Server Reference

The cosec-gateway-server module is a complete reference implementation. Key configuration:

# application.yaml
cosec:
  authentication:
    enabled: false          # Gateway relies on token injection from upstream
  jwt:
    algorithm: hmac256
    secret: FyN0Igd80Gas8stTavArGKOYnS9uLWGA_
  authorization:
    local-policy:
      enabled: true
      init-repository: true

Gateway-specific dependencies:

implementation(libs.cosec.cocache)        // Redis caching
implementation(libs.cosec.gateway)         // Gateway filter
implementation(libs.cosec.opentelemetry)   // Tracing
implementation(libs.cosec.ip2region)       // IP geolocation
implementation("org.springframework.cloud:spring-cloud-starter-gateway-server-webflux")

Disabling Features

Use conditional properties to disable specific features:

cosec:
  enabled: false              # disable everything
  authorization:
    enabled: false            # disable only authorization
  jwt:
    # not configuring jwt disables JWT auto-config
  ip2region:
    enabled: false

Each auto-configuration class has a corresponding @ConditionalOn*Enabled annotation that checks these properties.

Troubleshooting

• 403 on all requests: Check that policy files exist and match the locations pattern. Enable debug logging: logging.level.me.ahoo.cosec.authorization.SimpleAuthorization=debug
• JWT token not recognized: Verify cosec.jwt.secret and cosec.jwt.algorithm match what the token issuer uses
• Policies not loading: Ensure cosec.authorization.local-policy.enabled=true and files are in the correct classpath location
• Root user bypasses everything: This is by design. Root user ID defaults to "cosec" (configurable via cosec.root system property)