Immutable. This exact content is served forever at /api/v1/blob/30f146c7e11435c2.
---
name: cosec-integration
description: Integrate CoSec into Spring Boot by selecting WebFlux, WebMVC, or Gateway support and configuring JWT, local policies, Redis, auditing, or optional integrations. Do not use for policy-only authoring or diagnosis.
---
# CoSec Spring Boot Integration
Make the smallest integration that fits the target application. Preserve its build tool, dependency-management style, HTTP stack, configuration format, and existing security boundaries.
## Inspect first
Determine:
- Spring WebFlux, Spring MVC, or Spring Cloud Gateway; add exactly the matching CoSec transport.
- The CoSec version already managed by a BOM, version catalog, parent, or lockfile. Never copy a version from this skill.
- Whether policies are local-only or must initialize a shared repository.
- Whether Redis, OAuth, IP enrichment, tracing, OpenAPI, Kafka, or token revocation is actually required.
The starter already brings `cosec-core` and `cosec-jwt`. Prefer its Gradle feature capabilities because they include the integration and its runtime dependencies:
| Need | Starter capability | CoSec module |
|---|---|---|
| Spring MVC | `webmvc-support` | `cosec-webmvc` |
| Spring WebFlux | `webflux-support` | `cosec-webflux` |
| Spring Cloud Gateway | `gateway-support` | `cosec-gateway` |
| Social OAuth | `oauth-support` | `cosec-social` |
| Redis cache, revocation, distributed limiters | `cache-support` | `cosec-cocache` |
| IP region | `ip2region-support` | `cosec-ip2region` |
| OpenTelemetry | `opentelemetry-support` | `cosec-opentelemetry` |
| OpenAPI | `openapi-support` | `cosec-openapi` |
| Kafka audit sink | `kafka-support` | `cosec-kafka` |
For Gradle, select a capability on the starter dependency:
```kotlin
implementation(platform(libs.cosec.bom))
implementation("me.ahoo.cosec:cosec-spring-boot-starter") {
capabilities {
requireCapability("me.ahoo.cosec:webflux-support")
}
}
```
Declare the starter again for each additional capability. The module column is a mapping, not a complete dependency set. With Maven or a build that cannot select Gradle variants, use the BOM, starter, one transport module, and mirror the selected feature's runtime dependencies. In the current build, cache support also needs `org.springframework.boot:spring-boot-data-redis` and `me.ahoo.cocache:cocache-spring-boot-starter`, OpenAPI support needs `org.springframework.boot:spring-boot-starter-actuator` and `org.springdoc:springdoc-openapi-starter-common`, and Kafka support needs `org.springframework.boot:spring-boot-starter-kafka`.
## Minimal configuration
```yaml
cosec:
jwt:
algorithm: hmac256
secret: ${COSEC_JWT_SECRET}
authorization:
local-policy:
enabled: true
init-repository: true
locations:
- classpath:cosec-policy/*-policy.json
```
Keep the JWT secret outside source control. A blank secret fails startup while JWT is enabled. Supported algorithms are `hmac256`, `hmac384`, and `hmac512`; issuer and verifier must agree.
`LocalPolicyLoader` only parses files; authorization reads `PolicyRepository`. This bootstrap configuration therefore initializes the repository at startup and requires `PolicyRepository` and `AppRolePermissionRepository` beans. The cache capability supplies Redis-backed implementations; otherwise provide them explicitly.
Create policies under `src/main/resources/cosec-policy/` using the configured pattern. A safe complete skeleton is:
```json
{
"id": "service-access",
"name": "Service Access",
"category": "access",
"description": "Service endpoint access",
"type": "global",
"tenantId": "(platform)",
"statements": [
{
"name": "Health",
"action": "/actuator/health"
}
]
}
```
Use `$cosec-policy-author` when the requested policy is more than this bootstrap rule.
## Optional behavior
- `local-policy.init-repository` is `false` by default. The bootstrap above enables it because the repository is not otherwise populated from local files. Disable it only when policies are already stored elsewhere; use `force-refresh` only when overwriting repository state is intended.
- `cosec.jwt.token-revocation.enabled=true` needs a real `TokenStore`; the cache capability supplies the Redis-backed implementation. Without it, logout does not revoke tokens and the starter logs a warning.
- The cache capability and a `StringRedisTemplate` enable `redisRateLimiter` and `redisGroupedRateLimiter`. Spring registers these factories after `LocalPolicyInitializer` runs, so bootstrapped local files cannot use them; prepopulate those policies in the repository or register the factories before local initialization. Configure their shared prefix with `cosec.limiter.key-prefix`; use per-policy `strictFailure` when Redis outage behavior must fail closed.
- With the starter's auto-configured `Authorization`, audit logging is enabled by default. The logging sink records denies at WARN and allows at DEBUG under `me.ahoo.cosec.audit`; the Kafka capability replaces it when a unique Kafka template is available. A custom `Authorization` bean is not wrapped automatically, so compose it with `AuditingAuthorization` explicitly.
- Set `cosec.authorization.remote-ip.max-trusted-index` to the real trusted-proxy depth. `0` ignores `X-Forwarded-For`.
## Verification
Start the application or run its context test, then verify:
- policy resources are loaded with no skipped-file errors;
- an allowed anonymous request succeeds;
- an unmatched anonymous request returns 401;
- an authenticated but denied request returns 403;
- a tripped limiter returns 429;
- Redis-backed features work from more than one instance when cluster-wide behavior is required.
In a CoSec checkout, treat `cosec-spring-boot-starter/build.gradle.kts` and the `*Properties.kt` / auto-configuration classes under `cosec-spring-boot-starter/src/main/kotlin` as the source of truth for capabilities, defaults, and activation conditions.