Spring Security 403 Forbidden Error Debugging

When a request hits a secured endpoint, Spring Security's FilterChainProxy passes it through a chain of filters. The last filter is FilterSecurityInterceptor, which calls the AccessDecisionManager. The AccessDecisionManager uses voters (e.g., RoleVoter, AuthenticatedVoter) to decide if the user has the required authorities.

The 403 is thrown when the AccessDecisionManager denies access. By default, AffirmativeBased is used, which grants access if any voter approves. If all voters abstain or deny, access is denied. The key insight: RoleVoter adds the ROLE_ prefix to the configured attribute (e.g., from http.authorizeRequests().antMatchers("/admin").hasRole("ADMIN")) but does NOT add prefix when using hasAuthority(). Method-level annotations like @PreAuthorize use expression-based access control, which relies on SecurityExpressionRoot's hasRole method – that method does add the prefix. This inconsistency is a common source of bugs.

Set logging.level.org.springframework.security=DEBUG in application.properties. The key log lines include: 'SecurityContextHolder contents: ...' showing the current authentication object; 'Authorization failure' with the exception; and 'Voter: ... voted to deny' showing which voter rejected. For method security, look for 'PreInvocationAuthorizationAdvice' logs that show the expression and the authentication.

If TRACE level is enabled, you'll see the exact required authorities and the voter decisions. Use grep to filter: grep "Access is denied" or "Authorization failure". This often reveals that the required authority string does not match the user's granted authorities.

The @PreAuthorize("hasRole('ADMIN')") annotation uses the expression handler, which internally calls hasRole('ADMIN') -> hasAuthority('ROLE_ADMIN'). This works if the user's authority is stored as 'ROLE_ADMIN'. But if you use @PreAuthorize("hasAuthority('ADMIN')") without the prefix, it will not match a user with ROLE_ADMIN. Conversely, if you use hasRole('ROLE_ADMIN'), it becomes hasAuthority('ROLE_ROLE_ADMIN'), which almost certainly fails.

The fix: standardize your authorities. I recommend always storing authorities without the ROLE_ prefix (e.g., 'ADMIN') and then use hasAuthority('ADMIN') or hasRole('ADMIN') consistently. But if you use the default UserDetailsService that returns GrantedAuthority objects with ROLE_ prefix (like SimpleGrantedAuthority), then use hasRole('ADMIN') because it adds the prefix. The critical point: check the actual authority strings in your UserDetails implementation.

If you implement a custom AccessDecisionManager or voter, you must ensure that the voter's logic aligns with the attribute passed by FilterSecurityInterceptor or the expression handler. The attribute string comes from the security configuration. For http.authorizeRequests(), the attribute is the role name without prefix (if using hasRole), and the voter is expected to add the prefix. For method security with @PreAuthorize, the attribute is the result of the expression evaluation – it's already a full authority string (with prefix if hasRole was used).

I've seen teams write a custom voter that does a simple string comparison against the authority, forgetting that http.authorizeRequests() passes the role name without prefix. The fix is to either let the voter add the prefix or use hasAuthority in the configuration. Always test with a simple unit test that prints the attribute value.

Write a Spring Boot test using @WebMvcTest and SecurityMockMvcRequestPostProcessors. For example: mockMvc.perform(get("/api/admin").with(user("admin").roles("ADMIN"))).andExpect(status().isOk()). The roles() method adds the ROLE_ prefix automatically. If your test fails with 403, it reveals the mismatch early.

You can also use @WithMockUser(username="admin", roles={"ADMIN"}) at class level. If the test passes but production fails, the issue is likely in the UserDetailsService or authentication filter. If the test fails, your method security annotation is wrong.