/java-security

description: Reviews or implements Spring Security configuration — JWT authentication, OAuth2, method-level security, CORS, and CSRF. Use when user asks to "add authentication", "secure this API", "implement JWT", "configure Spring Security", "add OAuth2 login", "protect endpoints", or "review security config".
argument-hint: "[review | jwt | oauth2 | method-security | cors] [Spring Boot version]"
allowed-tools: Read, Grep, Glob

/java-security — Spring Security Advisor

You are a Spring Security specialist. Review existing security configuration or implement new security features for Spring Boot projects.

> **Quick OWASP vulnerability scan?** Use `/java-security-check` instead.

Step 1 — Detect project context

1. Check Spring Boot version from `pom.xml` / `build.gradle`:

• Spring Boot 3.x → Spring Security 6.x (`jakarta.*`, `SecurityFilterChain` bean, no `WebSecurityConfigurerAdapter`)
• Spring Boot 2.x → Spring Security 5.x (`javax.*`, `WebSecurityConfigurerAdapter` still works but deprecated)

2. Check if `spring-boot-starter-security` is already on the classpath 3. If reviewing: scan for existing `@Configuration` + `@EnableWebSecurity` classes

Step 2 — Determine mode from argument

• **`review`** (default if no arg) → audit existing config, go to Step 3
• **`jwt`** → implement stateless JWT authentication, go to Step 4
• **`oauth2`** → configure OAuth2 resource server or login, go to Step 5
• **`method-security`** → add method-level annotations, go to Step 6
• **`cors`** → configure CORS policy, go to Step 7

---

Step 3 — Review existing security config

Check for these issues and report each with file:line and severity:

**CRITICAL**

• `permitAll()` on sensitive paths (`/admin`, `/actuator`, `/internal`)
• `csrf().disable()` on non-stateless APIs (stateful session apps need CSRF)
• `@CrossOrigin(origins = "*")` in production controllers
• Passwords hashed with MD5, SHA-1, or stored plain

**HIGH**

• `httpBasic()` enabled on production APIs (use JWT or OAuth2)
• Actuator endpoints exposed without authentication (`/actuator/**`)
• Missing `@PreAuthorize` or role checks on admin endpoints
• `antMatchers` / `requestMatchers` ordering issues (broad rules before specific ones)

**MEDIUM**

• No session fixation protection
• Missing security headers (HSTS, X-Frame-Options, X-Content-Type-Options)
• `BCryptPasswordEncoder` strength below 10
• No rate limiting on `/login` endpoint

Use the patterns in `references/patterns.md` to suggest fixes.

---

Step 4 — Implement JWT authentication

Use the templates in `references/patterns.md` (JWT section). Generate in this order:

1. **Dependencies** — add to `pom.xml` / `build.gradle`:

• Spring Boot 3.x: `spring-boot-starter-oauth2-resource-server` (uses built-in JWT support)
• Spring Boot 2.x: `jjwt-api`, `jjwt-impl`, `jjwt-jackson`

2. **`SecurityConfig.java`** — `SecurityFilterChain` bean:

• Stateless session (`SessionCreationPolicy.STATELESS`)
• Permit `/auth/**`, secure everything else
• JWT decoder / filter setup

3. **`JwtService.java`** — generate and validate tokens:

• Sign with `HS256` (symmetric) for simple cases, `RS256` (asymmetric) for multi-service
• Include: `sub` (userId), `iat`, `exp`, `roles`
• Expiry: 15 min for access token, 7 days for refresh token

4. **`AuthController.java`** — `/auth/login` and `/auth/refresh` endpoints

5. **`AuthService.java`** — authenticate against `UserDetailsService`, issue tokens

6. **Version notes:**

• Spring Boot 3.x: use `spring-security-oauth2-resource-server` JWT decoder — no manual filter needed
• Spring Boot 2.x: implement `OncePerRequestFilter` manually

---

Step 5 — Configure OAuth2

For **resource server** (API validates tokens from an external IdP):

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://your-idp.example.com

For **login** (users log in via Google, GitHub, etc.):

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}

Remind: never hardcode client secrets — use environment variables.

---

Step 6 — Method-level security

Enable with `@EnableMethodSecurity` (Spring Security 6) or `@EnableGlobalMethodSecurity` (5):

| Annotation | Use for | |---|---| | `@PreAuthorize("hasRole('ADMIN')")` | Role-based access before method runs | | `@PreAuthorize("hasAuthority('user:write')")` | Fine-grained permission check | | `@PreAuthorize("#userId == authentication.principal.id")` | Owner-only access | | `@PostAuthorize("returnObject.userId == authentication.principal.id")` | Filter after return | | `@Secured("ROLE_ADMIN")` | Simple role check (legacy) |

Generate `@PreAuthorize` annotations for each controller method based on its sensitivity.

---

Step 7 — CORS configuration

// Preferred: global CORS via SecurityFilterChain (Spring Security 6)
http.cors(cors -> cors.configurationSource(corsConfigurationSource()));

@Bean
CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of("https://app.example.com"));  // never "*" in prod
    config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization","Content-Type"));
    config.setAllowCredentials(true);
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", config);
    return source;
}

Flag `@CrossOrigin(origins = "*")` on controllers — replace with global config.

---

Step 8 — Post-implementation checklist

• [ ] Secret keys come from env vars, not hardcoded in code or `application.yml`
• [ ] JWT expiry is set (access ≤ 15 min, refresh ≤ 7 days)
• [ ] Actuator endpoints secured or restricted to internal network
• [ ] `/auth/login` endpoint is rate