Spring Security Method Security: @PreAuthorize, @PostAuthorize, @Secured Guide

Method-level security is where Spring Security moves from 'good enough' to 'production-ready.' After years of building payment-processing systems and SaaS billing platforms, I've learned that URL-based security alone is a disaster waiting to happen. You might secure /api/orders, but what about the service layer method that processes refunds? That's where @PreAuthorize, @PostAuthorize, and @Secured come in.

These annotations let you enforce security at the method level, deep inside your business logic. @PreAuthorize evaluates a SpEL expression before the method runs — perfect for checking if the current user has the 'ROLE_ADMIN' or owns the resource. @PostAuthorize runs after the method, giving you access to the return value for fine-grained checks. @Secured is the simpler, older sibling — it just checks roles without SpEL.

In Spring Security 6.0+, you need @EnableMethodSecurity to activate these annotations. If you're still on Spring Security 5.x with @EnableGlobalMethodSecurity, it's time to upgrade — the new approach is cleaner and supports method-level authorization with less boilerplate.

This tutorial covers real-world usage, gotchas from production incidents, and debugging techniques. By the end, you'll know exactly when to use each annotation and how to avoid the mistakes that cause security holes or 403 errors in production.

Setting Up Method Security in Spring Boot 3.x

To use @PreAuthorize, @PostAuthorize, and @Secured, you must first enable method security. In Spring Boot 3.x (Spring Security 6.x), this is done with @EnableMethodSecurity on any @Configuration class. This replaces the older @EnableGlobalMethodSecurity from Spring Security 5.x.

Here's the minimum setup. First, add the dependency. Then create a security configuration class. The @EnableMethodSecurity annotation activates the pre/post annotations by default. If you also want @Secured, you need to set securedEnabled = true.

Important: In Spring Security 6, the default behavior changed. Previously, @EnableGlobalMethodSecurity(prePostEnabled = true) was required. Now, @EnableMethodSecurity is the way to go. If you're migrating from 5.x, remove the old annotation and replace it with this one.

Also note: The annotation works on both interfaces and classes, but I strongly recommend putting it on the implementation class to avoid proxy issues. I've debugged countless issues where @PreAuthorize on an interface method didn't work because of AOP proxy configuration.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableMethodSecurity(securedEnabled = true) // enables @Secured
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic();
        return http.build();
    }
}

What the Official Docs Won't Tell You

The Spring Security reference docs are thorough, but they skip the real-world pain points. Here's what I've learned from production:

First, @PreAuthorize expressions are evaluated against the Authentication object in the SecurityContextHolder. If you're using custom authentication (e.g., JWT tokens), make sure your GrantedAuthority objects are populated correctly. I've seen teams spend hours debugging why hasRole('ADMIN') returns false, only to find they forgot to prefix roles with 'ROLE_' in the token.

Second, @PostAuthorize lets you reference the method return value using the 'returnObject' variable. This is incredibly powerful for data-level security. For example, you can check if the returned entity belongs to the current user. But beware: @PostAuthorize runs after the method, so if your method is expensive (e.g., database query), you're wasting resources if access is denied.

Third, @Secured is often misunderstood. It doesn't support SpEL — it only checks for role names. And it requires the 'ROLE_' prefix. So @Secured("ADMIN") won't work; you need @Secured("ROLE_ADMIN"). This is a common source of bugs.

Finally, method security works via AOP proxies. If you call a method within the same class (self-invocation), the annotation won't trigger. This is the #1 cause of 'why isn't my @PreAuthorize working?' in Stack Overflow questions.

import org.springframework.security.access.prepost.PostAuthorize;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    @PreAuthorize("hasRole('ADMIN') or #orderId == authentication.principal.id")
    public Order getOrder(Long orderId) {
        // fetch order from DB
        return orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
    }

    @PostAuthorize("returnObject.ownerId == authentication.principal.id")
    public Order getOrderPostCheck(Long orderId) {
        // fetch order from DB
        return orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
    }

    // This WON'T trigger @PreAuthorize if called from another method in same class
    public void internalCall(Long orderId) {
        getOrder(orderId); // Self-invocation — no security check!
    }
}

@PreAuthorize Deep Dive: SpEL Expressions and Custom Permission Evaluators

@PreAuthorize is the most flexible annotation because it accepts any SpEL expression that evaluates to a boolean. You can check roles, permissions, method arguments, and even call custom beans.

For complex logic, create a custom PermissionEvaluator and register it with the MethodSecurityExpressionHandler. This keeps your annotations clean and testable.

One production pattern I use: combine @PreAuthorize with a custom @CurrentUser annotation to inject the authenticated user. Then use #user in expressions. This avoids accessing authentication.principal directly, which can be messy with custom principals.

Important: In Spring Security 6, the default role prefix is 'ROLE_'. If you're using custom roles without this prefix, use hasAuthority() instead of hasRole().

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Service;

@Service
public class PaymentService {

    // Only admins or the owner of the account can process refunds
    @PreAuthorize("hasRole('ADMIN') or #accountId == authentication.principal.accountId")
    public Refund processRefund(Long accountId, BigDecimal amount) {
        // process refund logic
        return new Refund(accountId, amount, RefundStatus.PENDING);
    }

    // Using custom permission evaluator via hasPermission
    @PreAuthorize("hasPermission(#payment, 'REFUND')")
    public Refund processRefundWithPermission(Payment payment, BigDecimal amount) {
        // custom PermissionEvaluator decides if user can refund this payment
        return new Refund(payment.getAccountId(), amount, RefundStatus.PENDING);
    }

    // Multiple conditions with OR/AND
    @PreAuthorize("hasRole('ADMIN') and (#amount.compareTo(T(java.math.BigDecimal).ZERO) > 0)")
    public void validateRefundAmount(BigDecimal amount) {
        // only admins can call, and amount must be positive
    }
}

@PostAuthorize: Securing Return Values and Preventing Data Leakage

@PostAuthorize runs after the method executes, giving you access to the return value via the 'returnObject' variable. This is useful when you can't determine access before execution — for example, when the method returns a list and you need to filter based on the current user.

However, @PostAuthorize has a dark side: it doesn't prevent the method from executing. If your method writes to a database or calls an external API, those side effects happen even if @PostAuthorize throws an AccessDeniedException. This can lead to data corruption or inconsistent state.

Use @PostAuthorize for read-only operations or when the security decision truly depends on the return value. For write operations, always prefer @PreAuthorize.

One advanced pattern: combine @PostAuthorize with a collection return type. You can filter the collection using SpEL, but be warned — this is not lazy. The entire collection is loaded into memory before filtering. For large datasets, this is a performance disaster.

In Spring Security 6, @PostAuthorize also supports the 'returnObject' for reactive types (Mono/Flux) with Project Reactor. But that's a topic for another article.

import org.springframework.security.access.prepost.PostAuthorize;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class DocumentService {

    // Only return the document if the current user is the owner
    @PostAuthorize("returnObject.ownerId == authentication.principal.id")
    public Document getDocument(Long documentId) {
        // Always fetches from DB, even if user is not owner
        return documentRepository.findById(documentId)
            .orElseThrow(() -> new DocumentNotFoundException(documentId));
    }

    // Better: use @PreAuthorize when possible
    @PreAuthorize("@documentPermissionEvaluator.canAccess(#documentId, authentication.principal.id)")
    public Document getDocumentSafe(Long documentId) {
        return documentRepository.findById(documentId)
            .orElseThrow(() -> new DocumentNotFoundException(documentId));
    }

    // Filtering a list — use with caution
    @PostAuthorize("returnObject.stream().allMatch(doc -> doc.ownerId == authentication.principal.id)")
    public List<Document> getAllDocuments() {
        return documentRepository.findAll(); // Could be millions of rows
    }
}

@Secured: The Simple Role-Based Alternative

@Secured is the simplest annotation: it just checks if the current user has one or more roles. No SpEL, no custom expressions. It's perfect for straightforward role-based access where you don't need complex logic.

To use @Secured, you must enable it with securedEnabled = true in @EnableMethodSecurity (or @EnableGlobalMethodSecurity). The annotation takes an array of role names, and the user must have at least one of them.

Important: @Secured requires the 'ROLE_' prefix. If your roles are stored without this prefix (e.g., 'ADMIN' instead of 'ROLE_ADMIN'), use hasAuthority() in @PreAuthorize instead.

When should you use @Secured vs @PreAuthorize? If your requirement is "only users with ROLE_ADMIN can call this method," @Secured is cleaner. If you need "users with ROLE_ADMIN OR users who own the resource," use @PreAuthorize.

In Spring Security 6, @Secured is fully supported but considered less flexible. The trend is toward @PreAuthorize for everything. But for legacy systems or simple apps, @Secured is fine.

One gotcha: @Secured on an interface method may not work if the proxy is JDK dynamic proxy (based on interfaces). Use CGLIB proxies (proxyTargetClass = true) or put the annotation on the implementation class.

import org.springframework.security.access.annotation.Secured;
import org.springframework.stereotype.Service;

@Service
public class AdminService {

    // Only users with ROLE_ADMIN can access
    @Secured("ROLE_ADMIN")
    public void performAdminTask() {
        // admin logic
    }

    // Users with ROLE_ADMIN OR ROLE_SUPERVISOR can access
    @Secured({"ROLE_ADMIN", "ROLE_SUPERVISOR"})
    public void performSupervisedTask() {
        // logic accessible by multiple roles
    }

    // This will NOT work — missing 'ROLE_' prefix
    // @Secured("ADMIN") // Throws IllegalArgumentException at runtime
}

Combining Annotations and Custom Security Expressions

You can combine @PreAuthorize, @PostAuthorize, and @Secured on the same method, but this is rarely necessary. If you do, the order of evaluation is: @Secured first, then @PreAuthorize, then @PostAuthorize. If any check fails, an AccessDeniedException is thrown.

A more practical approach is creating custom security annotations using meta-annotations. For example, you can define @AdminOnly that combines @PreAuthorize with a specific role check. This reduces duplication and makes your code more readable.

Spring Security also supports custom method security expressions. By implementing MethodSecurityExpressionOperations, you can add custom methods like 'isMemberOfTenant()' or 'canApprovePayment()'. Register them via a custom MethodSecurityExpressionHandler.

In production, I've found that custom expressions are invaluable for multi-tenant systems. Instead of repeating @PreAuthorize("authentication.principal.tenantId == #tenantId") everywhere, I create a @CurrentTenant annotation and a custom expression like '@tenantSecurity.isCurrentTenant(#tenantId)'.

One warning: custom expressions require careful testing. A bug in your expression handler can silently grant or deny access. Write unit tests for every custom expression.

import org.springframework.security.access.prepost.PreAuthorize;
import java.lang.annotation.*;

// Custom meta-annotation for admin-only access
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@PreAuthorize("hasRole('ADMIN')")
public @interface AdminOnly {
}

// Usage
@Service
public class TenantService {

    @AdminOnly
    public void deleteTenant(Long tenantId) {
        // only admins can delete tenants
    }

    // Using custom bean in SpEL
    @PreAuthorize("@tenantSecurity.isCurrentTenant(#tenantId, authentication.principal)")
    public Tenant getTenant(Long tenantId) {
        return tenantRepository.findById(tenantId)
            .orElseThrow(() -> new TenantNotFoundException(tenantId));
    }
}

// Custom security bean
@Component("tenantSecurity")
public class TenantSecurity {
    public boolean isCurrentTenant(Long tenantId, Principal principal) {
        if (principal instanceof CustomUser) {
            return ((CustomUser) principal).getTenantId().equals(tenantId);
        }
        return false;
    }
}

Testing Method Security: Unit and Integration Tests

Testing method security is non-negotiable. I've seen too many bugs slip into production because developers only tested controller-level security. You need to test the annotations at the service layer.

For unit tests, use Spring's SecurityTestUtils or Mockito to set up the SecurityContext. You can mock an Authentication object with specific roles and call the service method directly. But be aware: method security only works if the service is a Spring proxy. In a plain unit test without Spring context, @PreAuthorize won't fire.

For integration tests, use @WithMockUser or @WithUserDetails to simulate authenticated users. The @SpringBootTest annotation will load the full application context, including AOP proxies. This is the most reliable way to test method security.

Spring Security 6.1 introduced @WithAnonymousUser for testing unauthenticated access. Use it to verify that your methods are properly secured against anonymous users.

One advanced technique: test negative cases. Verify that users without the required role get an AccessDeniedException. Don't just test the happy path. In a payment system, we once found that a @PreAuthorize expression had a typo — 'hasRole('ADMIN')' was written as 'hasRole('ADMIN')' (same, but the bean method had a bug). Only negative testing caught it.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;

@SpringBootTest
@SpringJUnitConfig
public class PaymentServiceTest {

    @Autowired
    private PaymentService paymentService;

    @Test
    @WithMockUser(roles = "ADMIN")
    void testAdminCanProcessRefund() {
        Refund refund = paymentService.processRefund(123L, new BigDecimal("100.00"));
        assertNotNull(refund);
    }

    @Test
    @WithMockUser(roles = "USER")
    void testUserCannotProcessRefund() {
        assertThrows(AccessDeniedException.class, () -> {
            paymentService.processRefund(123L, new BigDecimal("100.00"));
        });
    }

    @Test
    @WithMockUser(username = "owner", roles = "USER")
    void testOwnerCanAccessOwnOrder() {
        // Assuming principal.id matches order owner
        Order order = orderService.getOrder(1L);
        assertNotNull(order);
    }
}

Common Pitfalls and Production Debugging

After years of debugging Spring Security issues, here are the most common problems with method security and how to fix them.

1. Annotation not working: Most likely, you forgot @EnableMethodSecurity. Check your configuration class. Also verify that the method is called through a Spring proxy (not self-invocation).
2. AccessDeniedException even with correct role: Check the role prefix. hasRole('ADMIN') expects 'ROLE_ADMIN' in the GrantedAuthority. If your authorities don't have the prefix, use hasAuthority('ADMIN').
3. SpEL parsing errors: Syntax errors in SpEL cause IllegalArgumentException at runtime. Use a SpEL parser like SpelExpressionParser to test expressions offline.
4. @PostAuthorize not filtering: Remember that @PostAuthorize doesn't modify the return value. It only throws an exception if the expression is false. For filtering collections, you need to implement custom logic.
5. Performance issues: Complex SpEL expressions on high-traffic methods can degrade performance. Profile with Spring Boot Actuator or a profiler like async-profiler.

For debugging, enable DEBUG logging for org.springframework.security.access. This shows which annotations are evaluated and why access is denied. Also, use SecurityContextHolder.getContext().getAuthentication() in your code to inspect the current authentication state.

# Enable debug logging for method security
logging:
  level:
    org.springframework.security.access: DEBUG
    org.springframework.security.access.expression: TRACE
    org.springframework.security.access.intercept: DEBUG