Securing REST APIs with Spring Security

From Default Security to Custom Configuration

When you add a Spring Security dependency to your project, it adopts a "secure by default" posture. Any attempt to access an endpoint will be met with an authentication challenge. While excellent for preventing accidental exposure, this default behavior—which often involves login forms and server-side sessions—is not what we need for a stateless REST API.

Our goal is to create a custom configuration that explicitly tells Spring Security to:

1. Not manage user sessions (be stateless).
2. Expect a JWT in the Authorization header of incoming requests.
3. Know how to validate that JWT to confirm the user's identity.

To do this, we create a special configuration class.

As the video explains, we define a Java class annotated with @Configuration and @EnableWebSecurity. Inside this class, we declare a Bean of type SecurityFilterChain. This bean is a method that takes an HttpSecurity object as a parameter and returns the configured result. By defining this bean, we take full control from Spring's default setup.

Building the Security Filter Chain

The HttpSecurity object is our main tool. We use a builder pattern to chain together configuration methods, defining a pipeline of security rules. Here is the typical structure for a stateless API:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                // Step 1: Disable CSRF
                .csrf(csrf -> csrf.disable())

                // Step 2: Configure session management to be stateless
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                
                // Step 3: Define authorization rules
                .authorizeHttpRequests(auth -> auth
                        .anyRequest().authenticated() // For now, all requests require authentication
                )
                
                // Step 4: Configure JWT support
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
                
                .build();
    }
}

Let's break down each part of this chain.

1. Disabling CSRF (Cross-Site Request Forgery)

CSRF is an attack that tricks a user's browser into making an unwanted request to a site where they are already authenticated (e.g., via a session cookie). Spring Security's CSRF protection works by requiring a unique token with each state-changing request.

However, in a stateless API that uses JWTs, the client is responsible for acquiring and sending the token with every request, usually in a header. This mechanism itself prevents CSRF, so the built-in protection is not needed and can be safely disabled.

2. Stateless Session Management

This is the most critical line for achieving our stateless architecture.
sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
This command tells Spring Security not to create or use any HttpSession. Each request must be authenticated independently based on the information it carries (i.e., the JWT), perfectly aligning with the principles we discussed in the last lesson.

3. Defining Authorization Rules

The authorizeHttpRequests block defines which endpoints are public and which are protected. For now, we are keeping it simple: anyRequest().authenticated(). This rule means that every single request to our API, regardless of the path, must be authenticated. In a later lesson, we will modify this to permit unauthenticated access to our login and registration endpoints.

4. Configuring JWT Support

The line .oauth2ResourceServer(oauth2 -> oauth2.jwt(...)) is where we integrate JWT validation. This configures our application as an OAuth2 Resource Server, which is the standard way to protect an API that accepts bearer tokens. By specifying .jwt(), we are telling it that the bearer tokens will be JWTs.

When we add this configuration, Spring Security knows it needs to look for a JWT in the Authorization: Bearer <token> header. However, it still doesn't know how to validate the token's signature. If you run the application with this configuration, it will fail to start, complaining that it can't find a JwtDecoder bean.

Providing the JWT Decoder

To validate a JWT's signature, the server needs the correct key. As discussed previously, the recommended approach is asymmetric encryption using an RSA key pair (a private key for signing and a public key for verification).

Our Spring Security configuration needs access to the public key to create a JwtDecoder. The decoder's job is to parse the incoming token and verify its signature using that public key.

The following video from Dan Vega provides a complete, practical walkthrough of this entire process, from setting up the project to configuring the decoder.

The Complete SecurityConfig

After following the steps in the video, your project structure will include the generated keys and updated properties.

src/main/resources/application.properties:

rsa.public-key=classpath:certs/public.pem
rsa.private-key=classpath:certs/private.pem

You'll have a new record to hold these properties:
RsaKeyProperties.java:

@ConfigurationProperties(prefix = "rsa")
public record RsaKeyProperties(RSAPublicKey publicKey, RSAPrivateKey privateKey) {
}

And your final SecurityConfig class will look like this, bringing everything together. Notice how we inject the RsaKeyProperties and use them to build the decoder and encoder beans (we'll use the encoder in the next lesson).

import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.SecurityContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final RsaKeyProperties rsaKeys;

    public SecurityConfig(RsaKeyProperties rsaKeys) {
        this.rsaKeys = rsaKeys;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .csrf(csrf -> csrf.disable())
                .authorizeHttpRequests(auth -> auth
                        .anyRequest().authenticated()
                )
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
                .build();
    }

    @Bean
    JwtDecoder jwtDecoder() {
        return NimbusJwtDecoder.withPublicKey(rsaKeys.publicKey()).build();
    }

    @Bean
    JwtEncoder jwtEncoder() {
        JWK jwk = new RSAKey.Builder(rsaKeys.publicKey()).privateKey(rsaKeys.privateKey()).build();
        JWKSource<SecurityContext> jwks = new ImmutableJWKSet<>(new JWKSet(jwk));
        return new NimbusJwtEncoder(jwks);
    }
}

Note: We have also included a JwtEncoder bean. While the JwtDecoder is used for validating incoming tokens, the JwtEncoder will be used in our next lesson to create and sign new tokens during login.

Conclusion

Congratulations! You have successfully configured Spring Security for a stateless, JWT-based REST API. This is a foundational and highly marketable skill for a backend developer. With this setup in place, our application is ready to validate JWTs, but it has no way to issue them yet. Any request sent to it will result in a 401 Unauthorized error because we can't provide a valid token.

Key Takeaways:

• A custom SecurityFilterChain bean is used to override Spring Security's defaults.
• For a stateless API, you must disable CSRF protection and set the session creation policy to STATELESS.
• .oauth2ResourceServer().jwt() configures the application to act as a resource server that validates JWT bearer tokens.
• This configuration requires a JwtDecoder bean, which needs a public key to verify the token's signature.
• Asymmetric RSA keys (public/private pair) are the recommended standard for signing JWTs, and you can generate them using openssl.

In the next lesson, we will build upon this foundation. We will implement the user registration and login endpoints. At the login step, we will use the JwtEncoder we defined today to generate a signed JWT and send it back to the client, finally completing our authentication loop.