Modern enterprise architectures often involve sophisticated permission management, particularly with in platform or "middle-office" services designed to centralize common functionalities. In such a setup, user authentication and core authorization logic are frequently externalized to dedicated identity and access management (IAM) systems. This allows individual application services to focus on their domain-specific business logic while integrating with the external IAM for security enforcement. A key challenge arises when these application sevrices need to perform granular access checks for specific API endpoints, ensuring that only authorized users can perform certain operations.

Developing a robust system for API access control necessitates avoiding repetitive permission checks scattered throughout controller methods. Hardcoding security logic into every endpoint leads to boilerplate code, reduces maintainability, and makes it difficult to modify access policies. The ideal solution involves a declarative mechanism where required permissions are clearly stated for each operation, with the enforcement logic handled uniformly across the application.

Aspect-Oriented Programming (AOP) coupled with custom annotations offers an elegant solution for implementing this dynamic access control. AOP is perfectly suited for cross-cutting concerns like security, allowing developers to centralize authorization logic in an aspect that intercepts method calls. Custom annotations, on the other hand, provide a clean, declarative way to tag methods with the specific permissions they require.

First, define a custom annotation to mark controller methods that require specific access rights. This annotation will carry the necessary permission identifiers.

package com.example.app.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

@Retention(RetentionPolicy.RUNTIME) // Available at runtime for AOP to read
@Target(ElementType.METHOD) // Applies only to methods
@Documented // Include in Javadoc
public @interface RequiredPermissions {
    String[] value() default {}; // Array of permission keys, e.g., "product:read", "user:delete"
}

Next, create an AOP aspect that intercepts methods annotated with @RequiredPermissions. This aspect will contain the core logic for validating a user's permissions against the ones declared on the method.

package com.example.app.aspects;

import com.example.app.annotations.RequiredPermissions;
import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.Pointcut;
import org.springframework.stereotype.Component;

import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

@Aspect
@Component
public class AuthorizationAspect {

    // Define a pointcut to target any method annotated with @RequiredPermissions
    @Pointcut("@annotation(com.example.app.annotations.RequiredPermissions)")
    private void permissionRequiredOperations() {}

    // Execute this advice before any method matched by the pointcut
    @Before(value = "permissionRequiredOperations() && @annotation(requiredPermissions)")
    public void validateAccess(JoinPoint joinPoint, RequiredPermissions requiredPermissions) throws IllegalAccessException {
        String[] declaredPermissions = requiredPermissions.value();
        System.out.println("Intercepted method: " + joinPoint.getSignature().toShortString() + ". Required permissions: " + Arrays.toString(declaredPermissions));

        // In a real application, retrieve the current user's permissions from a security context (e.g., Spring Security)
        // For this example, we'll simulate a user with a fixed set of permissions.
        Set<String> currentUserPermissions = new HashSet<>(Arrays.asList("product:read", "product:update", "report:view"));

        if (declaredPermissions.length == 0) {
            // If no permissions are specified, assume access is implicitly allowed (or handle as per policy)
            System.out.println("No specific permissions declared. Access granted.");
            return;
        }

        boolean isAuthorized = false;
        for (String requiredPerm : declaredPermissions) {
            if (currentUserPermissions.contains(requiredPerm)) {
                isAuthorized = true;
                break; // User has at least one of the required permissions
            }
        }

        if (!isAuthorized) {
            System.err.println("Access Denied for method: " + joinPoint.getSignature().toShortString() + ". Missing permissions: " + Arrays.toString(declaredPermissions));
            throw new IllegalAccessException("Access Denied: Insufficient permissions for operation. Requires: " + Arrays.toString(declaredPermissions));
        }

        System.out.println("Access Granted: User possesses required permissions.");
    }
}

Finally, apply the custom @RequiredPermissions annotation to your controller methods. This demonstrates how cleanly and declaratively you can specify access requirements for each API endpoint.

package com.example.app.controllers;

import com.example.app.annotations.RequiredPermissions;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
@RequestMapping("/api/dashboard")
public class DashboardController {

    @GetMapping("/summary")
    @RequiredPermissions({"report:view", "user:profile:read"}) // Requires either permission
    public String getDashboardSummary() {
        log.info("Fetching dashboard summary...");
        return "Dashboard summary data.";
    }

    @PostMapping("/settings")
    @RequiredPermissions("admin:manage_settings") // Requires this specific permission
    public String updateDashboardSettings() {
        log.info("Updating dashboard settings...");
        return "Dashboard settings updated.";
    }

    @GetMapping("/public")
    public String getPublicData() {
        log.info("Accessing public data.");
        return "This is public data, no special permissions required.";
    }
}

When DashboardController.getDashboardSummary() is invoked, the AuthorizationAspect intercepts the call. It retrieves the {"report:view", "user:profile:read"} permissions from the annotation, compares them against the simulated currentUserPermissions ({"product:read", "product:update", "report:view"}). Since "report:view" is present in both, access is granted. If a user lacked "admin:manage_settings" and attempted to access /api/dashboard/settings, the validateAccess method would throw an IllegalAccessException, preventing the controller method from executing. This setup centralizes permission enforcement, keeping controllers focused on business logic and making security policies explicit and easily manageable.