Spring Security: the filter chain, 401 and 403

Spring Security is a chain of servlet filters that every request passes through before it reaches the DispatcherServlet. One filter registered with the servlet container (DelegatingFilterProxy) hands the request to Spring's FilterChainProxy, which picks the matching SecurityFilterChain and runs its filters: one reads credentials and authenticates, one translates security exceptions into responses, and the last one checks authorization. A request rejected there never reaches a controller.

Add spring-boot-starter-security and, until you declare your own SecurityFilterChain, Boot secures every endpoint, enables form login and HTTP Basic, and logs a generated password for a user named user at startup. Your own configuration replaces that:

@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**", "/actuator/health").permitAll()
            .requestMatchers("/admin/**").hasRole("ADMIN")
            .requestMatchers(HttpMethod.POST, "/orders/**").hasAuthority("SCOPE_orders.write")
            .anyRequest().authenticated())
        .httpBasic(Customizer.withDefaults());
    return http.build();
}

First match wins

The rules are checked in the order declared, and the first matcher that fits the request decides. A broad rule placed early shadows every narrower rule after it; Spring Security only guards one case for you and refuses to start if anything is declared after anyRequest(). Order rules from most specific to least specific.

1import java.util.*;2 3public class Solution {4    record Rule(String prefix, String requirement) {}5 6    static String decide(List<Rule> rules, String path, Set<String> authorities) {7        for (Rule r : rules) {8            if (path.startsWith(r.prefix())) {        // first matching rule decides9                boolean ok = switch (r.requirement()) {10                    case "authenticated" -> true;      // this user is logged in11                    default -> authorities.contains(r.requirement());12                };13                return path + " matched " + r.prefix() + "** -> " + (ok ? "200" : "403");14            }15        }16        return path + " -> no rule";17    }18 19    public static List<String> run() {20        Set<String> user = Set.of("ROLE_USER");21        List<Rule> broadFirst = List.of(new Rule("/api/", "authenticated"), new Rule("/api/admin/", "ROLE_ADMIN"));22        List<Rule> specificFirst = List.of(new Rule("/api/admin/", "ROLE_ADMIN"), new Rule("/api/", "authenticated"));23        return List.of(24            "broad first: " + decide(broadFirst, "/api/admin/purge", user),25            "specific first: " + decide(specificFirst, "/api/admin/purge", user),26            "specific first: " + decide(specificFirst, "/api/orders", user));27    }28}

401 or 403

• 401 Unauthorized really means unauthenticated: the request carries no valid identity, and the response invites the client to authenticate (for HTTP Basic, with a WWW-Authenticate header).
• 403 Forbidden means the user is known but lacks the required authority. Logging in again will not help.

When an anonymous request is denied, Spring Security starts authentication (401, or a redirect to a login page for form login); when an authenticated user is denied, it answers 403.

Roles are authorities with a prefix

A user's permissions are a list of GrantedAuthority strings. hasAuthority("SCOPE_orders.write") compares the string exactly. hasRole("ADMIN") is shorthand for hasAuthority("ROLE_ADMIN") — the ROLE_ prefix is added for you, so a user whose authority is the bare string ADMIN does not pass hasRole("ADMIN").

Beyond URL rules, @EnableMethodSecurity enables @PreAuthorize("hasRole('ADMIN')") on service methods — implemented by a proxy, so self-invocation skips it just as it skips @Transactional.

Two more defaults worth knowing: CSRF protection is on, which matters for cookie-based sessions and is commonly disabled for a stateless API authenticated by bearer tokens; and passwords are stored through a PasswordEncoder such as BCrypt, never in plain text.