git:20260814.06a777d to git:20260816.892f6cd

---

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)

```kotlin

// gradle/libs.versions.toml

[versions]

[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" }

```

```kotlin

// 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

```xml

<dependencyManagement>

<dependencies>

<dependency>

<groupId>me.ahoo.cosec</groupId>

<artifactId>cosec-bom</artifactId>

<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

```yaml

cosec:

enabled: true # master switch (default: true)

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:

secret: your-256-bit-secret-key # required for HMAC algorithms

```

### Property Reference

| Property | Default | Description |

|----------|---------|-------------|

| `cosec.enabled` | `true` | Master enable/disable switch |

| `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 |

## 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

```json

{

"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

```json

{

"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.

```kotlin

@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:

```yaml

# application.yaml

cosec:

authentication:

enabled: false # Gateway relies on token injection from upstream

jwt:

algorithm: hmac256

secret: ${COSEC_JWT_SECRET:change-me-in-production}

authorization:

local-policy:

enabled: true

init-repository: true

```

Gateway-specific dependencies:

```kotlin

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:

```yaml

cosec:

enabled: false # disable everything

authorization:

enabled: false # disable only authorization

jwt:

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