Mastering Spring Security Expressions: hasRole, hasAuthority, Custom Matchers

If you've ever stared at a Spring Security configuration and wondered why hasRole('ADMIN') works but hasAuthority('ADMIN') doesn't (or vice versa), you're not alone. I've seen production incidents where a misconfigured expression locked out entire admin teams—or worse, allowed unauthorized access to sensitive endpoints.

Spring Security expressions are the gatekeepers of your application. They control who can access what, down to the method call or HTTP endpoint. But the documentation can be misleading, and the subtle differences between hasRole, hasAuthority, and custom matchers have bitten many teams.

In this article, I'll break down exactly how each expression works, when to use which, and what the official docs gloss over. We'll build a realistic example—a SaaS billing system—and implement role-based and permission-based access control. By the end, you'll be able to write expressions that are both secure and maintainable.

Let's dive into the trenches.

Understanding hasRole and hasAuthority

Spring Security provides two primary methods for checking if a user has a specific role or authority: hasRole and hasAuthority. At first glance, they seem interchangeable, but the difference is subtle and critical.

hasRole('ADMIN') internally checks for a GrantedAuthority with the name ROLE_ADMIN. It automatically prepends ROLE_ to the argument. So hasRole('ADMIN') is equivalent to hasAuthority('ROLE_ADMIN').

hasAuthority('ADMIN') checks for an exact match—no prefix added. If your authorities are stored as ROLE_ADMIN, then hasAuthority('ADMIN') will never match.

Here's a common pitfall: if you use a custom UserDetailsService that returns authorities without the ROLE_ prefix (e.g., SimpleGrantedAuthority('ADMIN')), then hasRole('ADMIN') will fail because it looks for ROLE_ADMIN. Conversely, if you store roles with the prefix, hasAuthority('ADMIN') will fail.

Best practice: Decide on a convention and stick to it. I recommend using the ROLE_ prefix for roles and using hasRole consistently. For fine-grained permissions (like 'WRITE_PRIVILEGE'), use hasAuthority without a prefix. This keeps the semantics clear.

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

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .requestMatchers("/api/billing/**").hasAuthority("BILLING_ACCESS")
                .anyRequest().authenticated()
            )
            .httpBasic();
        return http.build();
    }
}

Using hasAnyRole and hasAnyAuthority

When you need to allow multiple roles or authorities, use hasAnyRole or hasAnyAuthority. These accept a varargs of strings and return true if the user has at least one.

hasAnyRole('ADMIN', 'MANAGER') checks for ROLE_ADMIN or ROLE_MANAGER. hasAnyAuthority('ROLE_ADMIN', 'PERM_EDIT') checks for exact matches.

Performance note: These methods are O(n) where n is the number of authorities the user has. For most applications, this is negligible, but if you have thousands of authorities per user (unlikely but possible), consider using a SecurityExpressionRoot override.

Real-world example: In a multi-tenant SaaS application, you might have roles like TENANT_ADMIN and SUPER_ADMIN. Using hasAnyRole('TENANT_ADMIN', 'SUPER_ADMIN') is clean and readable.

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

@Service
public class BillingService {

    @PreAuthorize("hasAnyRole('ADMIN', 'BILLING_MANAGER')")
    public void generateInvoice(Long tenantId) {
        // Generate invoice logic
    }

    @PreAuthorize("hasAnyAuthority('ROLE_ADMIN', 'PERM_VIEW_INVOICES')")
    public List<Invoice> getInvoices(Long tenantId) {
        // Return invoices
        return List.of();
    }
}

Custom Security Matchers with PermissionEvaluator

Sometimes, role-based checks aren't enough. For example, in a billing system, you might want to allow a user to edit an invoice only if they are the owner. This requires access to the domain object and the current user's identity.

Spring Security provides PermissionEvaluator for this purpose. You implement hasPermission(Authentication, Object, Object) and then use the hasPermission expression in your annotations.

Step 1: Create a custom PermissionEvaluator. Step 2: Register it with the MethodSecurityExpressionHandler. Step 3: Use @PreAuthorize("hasPermission(#invoice, 'EDIT')").

Here's a concrete example from a SaaS billing platform:

import org.springframework.security.access.PermissionEvaluator;
import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Component;

import java.io.Serializable;

@Component
public class InvoicePermissionEvaluator implements PermissionEvaluator {

    @Override
    public boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission) {
        if (targetDomainObject instanceof Invoice invoice) {
            String username = authentication.getName();
            // Check if the user is the owner of the invoice
            return invoice.getOwner().equals(username);
        }
        return false;
    }

    @Override
    public boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission) {
        // For simplicity, not implemented in this example
        return false;
    }
}

What the Official Docs Won't Tell You

The Spring Security reference documentation is thorough, but it leaves out several hard-earned lessons from production.

1. The ROLE_ prefix is not optional when using hasRole. If you store roles without the prefix, hasRole will never match. The docs mention this, but it's easy to overlook. I've seen teams waste hours debugging this.

2. hasPermission with domain objects can cause LazyInitializationExceptions. If your domain object is a JPA entity that hasn't been fully loaded, accessing its properties inside hasPermission might throw an exception. Always ensure the object is fully initialized or use a DTO.

3. Expression caching can lead to stale results. By default, Spring Security caches the evaluation of expressions per method. If your permission logic depends on mutable state (e.g., user's last login time), you might get stale results. Use @PreAuthorize with @PostAuthorize carefully.

4. Custom matchers in HTTP security are order-sensitive. If you define a matcher for /api/admin/ after a more general matcher like /api/, the more specific rule might never be applied. Always order from most specific to least specific.

5. Testing expressions is non-trivial. The docs show basic tests, but they don't cover edge cases like null authentication or empty authorities. Always test with @WithMockUser and also with an anonymous user to ensure your expressions handle all states.

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;

@Configuration
public class MethodSecurityConfig {

    private final InvoicePermissionEvaluator invoicePermissionEvaluator;

    public MethodSecurityConfig(InvoicePermissionEvaluator invoicePermissionEvaluator) {
        this.invoicePermissionEvaluator = invoicePermissionEvaluator;
    }

    @Bean
    public MethodSecurityExpressionHandler methodSecurityExpressionHandler() {
        DefaultMethodSecurityExpressionHandler handler = new DefaultMethodSecurityExpressionHandler();
        handler.setPermissionEvaluator(invoicePermissionEvaluator);
        return handler;
    }
}

Combining Expressions with Logical Operators

Spring Security expressions support logical operators: and, or, and negation via ! or not. You can combine them to create complex rules.

For example: @PreAuthorize("hasRole('ADMIN') or (hasRole('MANAGER') and #invoice.owner == authentication.name)")

Order of precedence: and has higher precedence than or, just like in Java. Use parentheses to make your intention clear.

Performance: Complex expressions are evaluated at runtime. If you have many conditions, consider extracting the logic into a custom method in a bean and using @myBean.check(#invoice, authentication) for better readability and testability.

@PreAuthorize("hasRole('ADMIN') or " +
                "(hasRole('MANAGER') and #invoice.owner == authentication.name)")
public void updateInvoice(Invoice invoice) {
    // Update logic
}

Testing Security Expressions

Testing is where the rubber meets the road. You can't rely on manual testing to catch all edge cases. Use Spring's test support to write integration tests.

Key annotations: - @WithMockUser — simulates a user with given roles/authorities. - @WithAnonymousUser — simulates an unauthenticated user. - @WithUserDetails — uses a custom UserDetailsService.

What to test: - Happy path: user with correct role can access. - Negative path: user without role gets 403. - Edge cases: null authentication, empty authorities, expired tokens.

Example test for our BillingService:

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 static org.junit.jupiter.api.Assertions.assertThrows;

@SpringBootTest
public class BillingServiceTest {

    @Autowired
    private BillingService billingService;

    @Test
    @WithMockUser(roles = "ADMIN")
    void testAdminCanGenerateInvoice() {
        billingService.generateInvoice(1L);
    }

    @Test
    @WithMockUser(roles = "USER")
    void testUserCannotGenerateInvoice() {
        assertThrows(AccessDeniedException.class, () -> {
            billingService.generateInvoice(1L);
        });
    }

    @Test
    @WithMockUser(authorities = "ROLE_ADMIN")
    void testWithAuthority() {
        billingService.generateInvoice(1L);
    }
}