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):
```yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://your-idp.example.com
```

For **login** (users log in via Google, GitHub, etc.):
```yaml
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

```java
// 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-limited (suggest Bucket4j or Spring's built-in)
- [ ] Run `/java-security-check` to verify no OWASP issues remain

## Next Steps

- Full OWASP scan → `/java-security-check`
- Deep security audit → `java-security-reviewer` agent
- Generate tests for auth flows → `/java-test`