Mastering Custom Security Expressions in Spring Security

If you've built any non-trivial Spring Boot application, you've probably used @PreAuthorize("hasRole('ADMIN')") or @PostAuthorize("returnObject.owner == authentication.name"). These built-in SpEL expressions work fine for simple checks — but they fall apart fast when you need multi-tenant authorization, resource-level permissions, or rules that involve external data.

I've seen teams try to cram complex logic into SpEL expressions, resulting in unreadable, untestable messes. One client had a 200-character SpEL expression that checked three different services — it was a debugging nightmare. The better approach: custom security expressions.

In this article, I'll show you how to build, register, and debug custom security expressions in Spring Security 6+. You'll learn the architecture, see real code for a SaaS billing system, and get the hard-won lessons from production incidents. By the end, you'll be able to replace those tangled SpEL expressions with clean, reusable methods that are easy to test and maintain.

Why Custom Security Expressions?

Spring Security provides a handful of built-in expressions like hasRole(), hasAuthority(), and hasPermission(). These work for simple role-based checks, but real-world authorization often requires more nuance. For example, in a multi-tenant SaaS billing system, you might need to check: 'Is this user an admin of the organization that owns this invoice?' Or 'Does this user have the 'REFUND' permission for the payment method used?'

Sure, you could write a service method that performs these checks and call it from your controller. But that scatters authorization logic across your codebase, making it hard to audit and maintain. Custom security expressions let you encapsulate that logic in a single place and use it declaratively with @PreAuthorize.

Here's the hard truth: most teams get this wrong. They either overcomplicate SpEL expressions or give up and write imperative checks everywhere. I've seen a codebase where every single controller method started with if (!permissionService.canAccess(user, resource)) — that's a maintenance nightmare and a security audit's worst enemy.

Custom expressions give you the best of both worlds: declarative security with the full power of Java. You can inject any Spring bean, make database calls, or even call external services from within your expression methods. But with great power comes great responsibility — you need to understand the architecture to avoid the pitfalls we'll cover later.

package com.example.security;

import org.springframework.security.access.expression.SecurityExpressionRoot;
import org.springframework.security.access.expression.method.MethodSecurityExpressionOperations;
import org.springframework.security.core.Authentication;

public class CustomSecurityExpressionRoot extends SecurityExpressionRoot
        implements MethodSecurityExpressionOperations {

    private Object filterObject;
    private Object returnObject;
    private Object target;

    public CustomSecurityExpressionRoot(Authentication authentication) {
        super(authentication);
    }

    public boolean isOrgAdmin(String orgId) {
        // Custom logic: check if authenticated user has ADMIN role for this org
        return authentication.getAuthorities().stream()
                .anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN")
                        && a instanceof GrantedAuthority && ((GrantedAuthority) a).getAuthority().contains(orgId));
    }

    public boolean canAccessInvoice(String invoiceId) {
        // Simulate a service call to check ownership
        return true; // Replace with real logic
    }

    @Override
    public void setFilterObject(Object filterObject) {
        this.filterObject = filterObject;
    }

    @Override
    public Object getFilterObject() {
        return filterObject;
    }

    @Override
    public void setReturnObject(Object returnObject) {
        this.returnObject = returnObject;
    }

    @Override
    public Object getReturnObject() {
        return returnObject;
    }

    @Override
    public Object getThis() {
        return target;
    }

    public void setThis(Object target) {
        this.target = target;
    }
}

Architecture: How Spring Security Evaluates Expressions

Understanding the evaluation pipeline is crucial for debugging. When you annotate a method with @PreAuthorize("@myBean.check(#id)"), Spring Security uses a MethodSecurityInterceptor that evaluates the expression before method invocation. The expression is parsed by SpEL (Spring Expression Language) and executed against a root object that implements MethodSecurityExpressionOperations.

By default, Spring Security uses SecurityExpressionRoot as the root object. To add custom methods, you need to: 1. Extend SecurityExpressionRoot (or implement MethodSecurityExpressionOperations directly). 2. Create a custom MethodSecurityExpressionHandler that returns your root object. 3. Register that handler as a bean.

Here's the part that trips up many developers: the expression handler must be registered as a bean, and the root object must be created fresh for each evaluation. I once spent three hours debugging a case where the root object was reused across threads — the Authentication object was stale, causing random 403s.

Spring Security 6 introduced @EnableMethodSecurity which simplifies method security configuration. But it also changed how custom handlers are discovered. In older versions, you could just define a bean of type MethodSecurityExpressionHandler and it would be picked up automatically. In Spring Security 6, you need to be more explicit, especially if you're using the annotation-based approach.

Let's look at the registration code.

package com.example.config;

import com.example.security.CustomSecurityExpressionRoot;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler;
import org.springframework.security.access.expression.method.MethodSecurityExpressionHandler;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public MethodSecurityExpressionHandler methodSecurityExpressionHandler() {
        DefaultMethodSecurityExpressionHandler handler = new DefaultMethodSecurityExpressionHandler() {
            @Override
            protected SecurityExpressionOperations createSecurityExpressionRoot(
                    Authentication authentication, MethodInvocation invocation) {
                CustomSecurityExpressionRoot root = new CustomSecurityExpressionRoot(authentication);
                root.setThis(invocation.getThis());
                return root;
            }
        };
        return handler;
    }
}

Injecting Services into Custom Expressions

The real power of custom expressions comes from injecting Spring beans into your root object. For example, you might need a UserRepository to look up user permissions, or a BillingService to check subscription status.

The trick is to make your root object a Spring-managed bean itself, or to inject dependencies via the handler. I prefer the latter because it keeps the root object focused on evaluation and avoids circular dependencies.

Here's the pattern: make your root class a @Component with injected services, then in the handler, get an instance of the root from the application context. But be careful — the root object should be prototype-scoped because each evaluation needs a fresh instance with the current Authentication.

Let me show you the cleanest approach I've used in production.

@Bean
public MethodSecurityExpressionHandler methodSecurityExpressionHandler() {
    DefaultMethodSecurityExpressionHandler handler = new DefaultMethodSecurityExpressionHandler() {
        @Override
        protected SecurityExpressionOperations createSecurityExpressionRoot(
                Authentication authentication, MethodInvocation invocation) {
            CustomSecurityExpressionRoot root = applicationContext.getBean(CustomSecurityExpressionRoot.class);
            root.setAuthentication(authentication);
            root.setThis(invocation.getThis());
            return root;
        }
    };
    return handler;
}

Using Custom Expressions in Controllers and Services

Once your custom expression handler is set up, using the expressions is straightforward. You reference them by method name in @PreAuthorize, @PostAuthorize, @PreFilter, or @PostFilter.

Here's the syntax: @PreAuthorize("isOrgAdmin(#orgId)") where #orgId is a method parameter. Spring Security automatically maps method parameters to SpEL variables.

But there's a nuance: if your method name conflicts with a built-in expression like hasPermission, you'll need to be explicit. I recommend using a prefix like my or your company abbreviation to avoid clashes.

Let's see this in action with a real controller for a billing API.

package com.example.controller;

import com.example.model.Invoice;
import com.example.service.InvoiceService;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/invoices")
public class InvoiceController {

    private final InvoiceService invoiceService;

    public InvoiceController(InvoiceService invoiceService) {
        this.invoiceService = invoiceService;
    }

    @GetMapping("/{invoiceId}")
    @PreAuthorize("hasPermissionOnInvoice(#invoiceId)")
    public Invoice getInvoice(@PathVariable String invoiceId) {
        return invoiceService.findById(invoiceId);
    }

    @PostMapping
    @PreAuthorize("isOrgAdmin(#invoice.orgId)")
    public Invoice createInvoice(@RequestBody Invoice invoice) {
        return invoiceService.create(invoice);
    }

    @DeleteMapping("/{invoiceId}")
    @PreAuthorize("hasRole('ADMIN') and hasPermissionOnInvoice(#invoiceId)")
    public void deleteInvoice(@PathVariable String invoiceId) {
        invoiceService.delete(invoiceId);
    }
}

What the Official Docs Won't Tell You

The Spring Security reference documentation is good, but it glosses over several critical details that you'll only discover in production. Here are the gotchas I've accumulated over the years.

1. Lazy initialization of expression handlers If you define your MethodSecurityExpressionHandler bean in a configuration class that's loaded lazily, your custom expressions won't be available at startup. I once saw an application where the security config was in a @ConditionalOnProperty class that wasn't active in certain profiles — resulting in default expressions being used silently.

2. The @EnableMethodSecurity order matters If you have multiple @Configuration classes with @EnableMethodSecurity, the last one processed wins. This can override your custom handler. Always define your handler in the same class as @EnableMethodSecurity or use @Order to control precedence.

3. SpEL variable resolution with proxy methods When using @PreAuthorize on methods in a class that's proxied (e.g., @Transactional), the parameter names might not be available. Spring resolves parameters using the MethodInvocation object, but if the proxy is a CGLIB proxy without debug info, parameter names become arg0, arg1, etc. Always compile with -parameters flag or use @Param annotation.

4. Thread-local leaks in async scenarios If you use @Async methods with @PreAuthorize, the SecurityContext is propagated via SecurityContextHolder. But if your custom expression accesses request-scoped beans (like HttpServletRequest), those beans won't be available in the async thread. I've debugged cases where expressions worked in the main thread but failed in async tasks.

5. Expression caching Spring Security caches parsed SpEL expressions by default. If your expression uses dynamic values (like method parameters), this is fine. But if your expression logic changes based on external state (e.g., a feature flag), the cached expression might evaluate incorrectly. In that case, disable caching by setting spring.security.expression.caching.enabled=false or implement a custom cache key.

# Ensure parameter names are preserved for SpEL resolution
# Add to pom.xml or build.gradle:
# <plugin>
#   <groupId>org.apache.maven.plugins</groupId>
#   <artifactId>maven-compiler-plugin</artifactId>
#   <configuration>
#     <parameters>true</parameters>
#   </configuration>
# </plugin>

# Disable expression caching if needed
spring.security.expression.caching.enabled=false

Testing Custom Security Expressions

Testing is where custom expressions really shine. Because they're plain Java methods, you can unit test them with mocked dependencies. Integration testing with @WithMockUser or custom security context is also straightforward.

Here's a common pattern I use: create a test configuration that registers the expression handler, then write tests that verify access control for different scenarios.

But there's a trap: if your expression method calls a service that itself uses @PreAuthorize, you can get into infinite recursion. Always ensure your expression methods don't trigger security checks on the same method.

package com.example.security;

import com.example.service.PermissionService;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.security.authentication.TestingAuthenticationToken;
import org.springframework.security.core.Authentication;

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
class CustomSecurityExpressionRootTest {

    @Mock
    private PermissionService permissionService;

    @InjectMocks
    private CustomSecurityExpressionRoot root;

    @BeforeEach
    void setUp() {
        Authentication auth = new TestingAuthenticationToken("user", "pass", "ROLE_USER");
        root.setAuthentication(auth);
    }

    @Test
    void testHasPermissionOnInvoice_Allowed() {
        when(permissionService.canAccessInvoice("user", "inv123")).thenReturn(true);
        assertTrue(root.hasPermissionOnInvoice("inv123"));
    }

    @Test
    void testHasPermissionOnInvoice_Denied() {
        when(permissionService.canAccessInvoice("user", "inv456")).thenReturn(false);
        assertFalse(root.hasPermissionOnInvoice("inv456"));
    }
}