spring-security-auth-review

name

spring-security-auth-review

description

Use when reviewing or hardening authentication and authorization in a Spring Boot service that uses Spring Security, JWT, OAuth2, sessions, refresh tokens, or service-to-service auth. Produces an actionable auth review, findings by severity, trust-boundary analysis, secure Spring Security configuration guidance, and remediation priorities. Do not use for general application security review, non-Spring services, or domain authorization policy design outside the framework layer. Pairs with spring-boot-service-scaffold (actuator and security baseline), backend-architecture (trust boundaries, authorization touchpoints, CSRF/CORS posture, and rate-limit behavior), spring-boot-observability-readiness (auth event logging and redaction), and quality-engineering (security test coverage).

Spring Security Auth Review

When to use

Invoke before shipping any Spring Boot service that handles authenticated requests, or whenever Spring Security, JWT/OAuth2, sessions, refresh tokens, CORS, CSRF, actuator exposure, or service-to-service auth changes materially.

Do not use for general application security review, non-Spring services, frontend-only auth UX, cryptographic protocol design, or domain authorization policy design above the framework layer.

Inputs

Required:

• Spring Boot service source tree.
• Spring Security configuration, including SecurityFilterChain or SecurityWebFilterChain.
• Auth model: JWT, OAuth2 resource server, session, BFF, refresh token, or service-to-service.

Optional:

• OpenAPI spec or endpoint list.
• System design or trust boundary map.
• Token issuer/JWKS details.
• Role/scope model.
• CORS and CSRF requirements.
• Deployment profile configuration.
• Existing security tests.

Operating rules

• Review service-level auth even if an API gateway exists. Gateway-only authorization is not enough.
• Treat authentication and authorization separately. Authenticated does not mean authorized.
• Fail closed. Reject broad permitAll, wildcard CORS with credentials, unpinned JWT algorithms, missing audience validation, and hardcoded secrets.
• Match the Spring stack and version. Servlet and reactive security have different configuration and propagation risks.
• Never log raw tokens, credentials, authorization headers, credential cookies, or full JWT claims.
• Findings must be actionable, evidence-backed, severity-classified, and confidence-marked (Confirmed / Probable / Suspected).
• Detect Spring Security version before reviewing. If the service uses WebSecurityConfigurerAdapter or authorizeRequests (Security 5.x), record a Blocker finding ("obsolete API; upgrade to Spring Security 6 lambda DSL required before further hardening") and adapt the rest of the review to the actual API surface in use — do not write Security 6 recommendations against a Security 5 codebase.
• Halt the review if the service has no SecurityFilterChain/SecurityWebFilterChain bean and no JWT/OAuth2 dependency. An auth review is not a substitute for missing auth — recommend running spring-boot-service-scaffold first to produce a baseline.
• Always scan committed configuration for secrets (application*.yml, bootstrap*.yml, .env*, src/main/resources/**). Found secrets are Blocker severity regardless of presumed harmlessness.

Output contract

The review measures the service against security-standards. That standard is authoritative for:

• AuthN: OAuth2/OIDC default, short-lived service tokens, MFA for production access.
• AuthZ: RBAC at the gateway, ABAC at the service that owns the resource, 401 vs 403 distinction.
• Secrets: zero secrets in source control (Blocker), managed store, rotation cadences.
• Data protection: TLS 1.3, at-rest encryption, no PII/tokens in logs.
• Vulnerability management: SCA, SAST, container scan, CVE SLOs.

Findings reference the specific clause in security-standards they violate. Auth event logging and redaction also conform to observability-standards. CSRF / CORS / RATE_LIMITED posture is consistent with api-standards.

Progressive references

• Read references/trust-boundaries-and-filter-chain.md when mapping actors, trust boundaries, SecurityFilterChain/SecurityWebFilterChain, request matchers, actuator exposure, and filter ordering.
• Read references/jwt-oauth-token-lifecycle.md when reviewing JWT/OAuth2 validation, audience checks, algorithms, JWKS caching, refresh tokens, sessions, token storage, secrets, and key rotation.
• Read references/authorization-browser-and-exposure.md when reviewing endpoint authorization, method security, tenant isolation, service-to-service auth, CSRF, CORS, cookies, and information leakage.
• Read references/observability-testing-and-reporting.md when reviewing audit logging, metrics, security tests, severity classification, and required review artifacts.
• Read references/auth-review-quality-rubric.md before finalizing and use it as the validation checklist.
• Use assets/auth-review.template.md for auth-review.md.
• Use assets/security-config.template.java when emitting or recommending SecurityConfig.java.

Process

Progress:

• Step 1: Pre-flight gate. Confirm the service has at least one SecurityFilterChain/SecurityWebFilterChain bean and a JWT/OAuth2/session dependency on the classpath. If neither exists, halt and recommend spring-boot-service-scaffold. Then map trust boundaries: actors, clients, tokens, issuers, gateways, services, protected resources, tenant boundaries, and machine-to-machine paths. Create a minimal map if none exists.
• Step 2: Identify Spring Boot and Spring Security versions and the stack (servlet vs reactive). If WebSecurityConfigurerAdapter or authorizeRequests is in use, record a Blocker finding and adapt the rest of the review to that API surface. Otherwise review filter chains, matchers, authorization rules, exception handling, filter ordering, method-security enablement, and actuator exposure against the Security 6 lambda DSL.
• Step 3: Review JWT/OAuth2 validation: algorithm pinning, issuer, audience, expiry, not-before, clock skew, JWKS cache behavior, and key-fetch failure mode.
• Step 4: Review authorization enforcement: endpoint scopes/roles, method-level checks, ownership checks, tenant scoping, confused deputy risk, and gateway-only assumptions.
• Step 5: Review refresh token, session, token storage, secret, and key management strategy.
• Step 6: Review CSRF, CORS, cookie settings, browser flows, and environment-specific exposure rules.
• Step 7: Review error handling and information leakage: 401/403 behavior, login failures, token validation messages, stack traces, and token logging.
• Step 8: Review observability and auditability: auth logs, metrics, JWKS failures, refresh anomalies, and sensitive-data redaction.
• Step 9: Review security testing: unauthenticated, malformed/expired/wrong-audience token, insufficient scope, CSRF, CORS, actuator, refresh replay, and key rotation tests.
• Step 10: Secrets scan (mandatory). Run grep -rE 'password|secret|token|api[_-]?key' src/main/resources/ **/application*.yml .env* (or ripgrep equivalent). Recommend trufflehog or gitleaks against git history. Any committed secret is a Blocker finding with file:line evidence.

Outputs

• auth-review.md with verdict, trust boundary map, findings table, severity, evidence, remediation, and prioritized fixes.
• Optional SecurityConfig.java or .kt hardening example when the user needs generated config.

Optional outputs when appropriate:

• Threat model notes.
• Token lifecycle diagram.
• RBAC or scope matrix.
• JWKS caching guidance.
• Refresh token schema recommendations.
• Key rotation runbook.

Output rules:

• Lead with blockers and high-risk findings.
• Include code/config evidence for every finding.
• Prefer precise remediation over generic advice.
• Do not expose secrets, raw tokens, or sensitive claims in review output.
• Clearly separate verified findings from assumptions and open questions.

Quality checks

• references/auth-review-quality-rubric.md was loaded before finalizing.
• auth-review.md follows assets/auth-review.template.md.
• Every finding has severity, component, evidence, impact, and remediation.
• Spring Security version and Servlet vs reactive stack are identified.
• The configuration could realistically survive production exposure.

References

• references/trust-boundaries-and-filter-chain.md
• references/jwt-oauth-token-lifecycle.md
• references/authorization-browser-and-exposure.md
• references/observability-testing-and-reporting.md
• references/auth-review-quality-rubric.md
• assets/auth-review.template.md
• assets/security-config.template.java