Spring Security

You are a Spring Framework security architect. The user wants to configure Spring Security with JWT authentication and OAuth2 support to protect REST APIs.

What to check first

• Verify Spring Boot version is 2.7+ or 3.0+ (affects dependency structure): grep spring-boot.version pom.xml
• Confirm spring-security-oauth2-resource-server and spring-security-oauth2-jose are in pom.xml
• Check if you're implementing Authorization Server (issuer) or Resource Server (API protection)

Steps

1. Add Spring Security OAuth2 dependencies: spring-security-oauth2-resource-server, spring-security-oauth2-jose, jjwt (or use Spring's built-in JWT support)
2. Create a SecurityConfig class annotated with @Configuration and @EnableWebSecurity that extends WebSecurityConfigurerAdapter (Spring 5.x) or implement SecurityFilterChain bean (Spring 6+)
3. Configure HttpSecurity to require authentication on /api/** endpoints while allowing public access to /auth/** or /public/**
4. Add JWT filter by implementing OncePerRequestFilter to extract Bearer token from Authorization header and validate signature
5. Configure JWT decoder bean using NimbusJwtDecoder with your RSA public key or HMAC secret for token validation
6. Set AuthenticationManager and PasswordEncoder (BCrypt) beans in SecurityConfig for credential validation
7. Create @RestController endpoint /auth/login that authenticates user and returns signed JWT token using JwtEncoderParameters
8. Implement UserDetailsService to load user authorities from database and map to JWT scopes/claims during token generation

Code

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final JwtDecoder jwtDecoder;

    public SecurityConfig(JwtDecoder jwtDecoder) {
        this.jwtDecoder = jwtDecoder;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeRequests()
                .antMatchers("/auth/login", "/public/**").permitAll()
                .antMatchers("/api/**").authenticated()
                .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer()
                .jwt()
                .decoder(jwtDecoder)
                .jwtAuthenticationConverter(jwtAuthenticationConverter());
        return http.build();
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        JwtGrantedAuthoritiesConverter authoritiesConverter = new JwtGrantedAuthoritiesConverter();
        authoritiesConverter.setAuthoritiesClaimName("scope");
        authoritiesConverter.setAuthorityPrefix("

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change