or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

acl-services.md caching-performance.md configuration.md domain-model.md index.md permission-evaluation.md strategy-interfaces.md

tile.json

tessl/maven-org-springframework-security--spring-security-acl

Spring Security ACL provides instance-based security for domain objects through a comprehensive Access Control List implementation

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/org.springframework.security/spring-security-acl@6.5.x

To install, run

npx @tessl/cli install tessl/maven-org-springframework-security--spring-security-acl@6.5.0

Spring Security ACL

Spring Security's Access Control List (ACL) module provides domain object instance-based security. It enables fine-grained permission controls where different users can have different permissions on individual instances of domain objects.

Package Information

Group ID: org.springframework.security
Artifact ID: spring-security-acl
Package: org.springframework.security.acls

Maven Dependency

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-acl</artifactId>
    <version>6.5.1</version>
</dependency>

Core Imports

import org.springframework.security.acls.AclPermissionEvaluator;
import org.springframework.security.acls.model.AclService;
import org.springframework.security.acls.model.MutableAclService;
import org.springframework.security.acls.model.Permission;
import org.springframework.security.acls.model.Sid;
import org.springframework.security.acls.model.ObjectIdentity;
import org.springframework.security.acls.model.Acl;
import org.springframework.security.acls.domain.BasePermission;
import org.springframework.security.acls.domain.PrincipalSid;
import org.springframework.security.acls.domain.GrantedAuthoritySid;
import org.springframework.security.acls.domain.ObjectIdentityImpl;

Basic Usage Example

The modern approach uses Spring Security's expression-based access control with AclPermissionEvaluator:

@Service
public class DocumentService {
    
    @PreAuthorize("hasPermission(#document, 'READ')")
    public Document getDocument(Document document) {
        return document;
    }
    
    @PreAuthorize("hasPermission(#document, 'WRITE')")
    public void updateDocument(Document document) {
        // Update document
    }
    
    @PreAuthorize("hasPermission(#documentId, 'com.example.Document', 'DELETE')")
    public void deleteDocument(Long documentId) {
        // Delete document
    }
    
    @PostAuthorize("hasPermission(returnObject, 'READ')")
    public Document findDocument(Long id) {
        return documentRepository.findById(id);
    }
    
    @PostFilter("hasPermission(filterObject, 'READ')")
    public List<Document> getUserDocuments() {
        return documentRepository.findAll();
    }
}

Architecture

Spring Security ACL provides a flexible, extensible architecture for domain object security:

Core Components

AclService: Read access to ACL data
MutableAclService: Create/modify ACL data
AclPermissionEvaluator: Integration with Spring Security expressions
Acl: Represents permissions for a domain object
ObjectIdentity: Identifies domain object instances
Sid: Security identities (users/roles)
Permission: Specific permission types

Data Flow

Permission Check: @PreAuthorize triggers permission evaluation
Object Identity: Extract identity from domain object
Security Identity: Get current user's SIDs (principal + authorities)
ACL Lookup: Query ACL data for object and SIDs
Permission Decision: Check if required permission is granted

Capabilities

Core Domain Model

The ACL module provides a rich domain model for representing permissions:

// Domain object identity
ObjectIdentity identity = new ObjectIdentityImpl(Document.class, documentId);

// Security identities
Sid principalSid = new PrincipalSid("john.doe");
Sid roleSid = new GrantedAuthoritySid("ROLE_ADMIN");

// Built-in permissions
Permission read = BasePermission.READ;
Permission write = BasePermission.WRITE;
Permission delete = BasePermission.DELETE;

Learn more about the domain model →

ACL Services

Programmatic access to ACL data for reading and modification:

@Autowired
private MutableAclService aclService;

// Create ACL for new object
MutableAcl acl = aclService.createAcl(objectIdentity);

// Grant permission
acl.insertAce(0, BasePermission.READ, principalSid, true);
aclService.updateAcl(acl);

// Read ACL
Acl existingAcl = aclService.readAclById(objectIdentity);

Learn more about ACL services →

Permission Evaluation

Modern annotation-based approach with caching and optimization:

@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig {
    
    @Bean
    public PermissionEvaluator permissionEvaluator(AclService aclService) {
        AclPermissionEvaluator evaluator = new AclPermissionEvaluator(aclService);
        evaluator.setPermissionFactory(permissionFactory());
        return evaluator;
    }
}

Learn more about permission evaluation →

Configuration & Setup

Complete Spring configuration with database setup and security integration:

@Configuration
@EnableJpaRepositories
public class AclConfig {
    
    @Bean
    public AclService aclService() {
        JdbcMutableAclService service = new JdbcMutableAclService(
            dataSource(), lookupStrategy(), aclCache());
        service.setClassIdentityQuery("SELECT @@IDENTITY");
        service.setSidIdentityQuery("SELECT @@IDENTITY");  
        return service;
    }
}

Learn more about configuration →

Caching & Performance

Advanced caching and performance optimization features for production deployments:

@Bean
public AclCache aclCache() {
    return new SpringCacheBasedAclCache(
        cacheManager().getCache("aclCache"),
        permissionGrantingStrategy(),
        aclAuthorizationStrategy()
    );
}

@Bean  
public PermissionCacheOptimizer permissionCacheOptimizer(AclService aclService) {
    return new AclPermissionCacheOptimizer(aclService);
}

Learn more about caching & performance →

Strategy Interfaces

Extensible strategy interfaces for customizing ACL behavior:

// Custom object identity retrieval
@Bean
public ObjectIdentityRetrievalStrategy objectIdentityRetrievalStrategy() {
    return new CustomObjectIdentityRetrievalStrategy();
}

// Custom SID retrieval with groups
@Bean
public SidRetrievalStrategy sidRetrievalStrategy() {
    return new GroupAwareSidRetrievalStrategy();
}

// Custom permission evaluation logic
@Bean
public PermissionGrantingStrategy permissionGrantingStrategy() {
    return new CustomPermissionGrantingStrategy(auditLogger());
}

Learn more about strategy interfaces →

Key Features

Fine-grained Security: Per-instance permissions on domain objects
Hierarchical ACLs: Support for parent-child ACL inheritance
Flexible Permissions: Built-in permissions (READ, WRITE, CREATE, DELETE, ADMINISTRATION) with support for custom permissions
Multiple Security Identities: Support for both principal-based and authority-based permissions
Performance Optimized: Batch loading, caching, and SID filtering for efficient permission checks
Database Agnostic: JDBC-based implementation works with any SQL database
Spring Integration: Seamless integration with Spring Security's expression language

Standards Compliance

Consistent with Spring Security patterns: Uses standard Spring Security interfaces and annotations
Database portable: ANSI SQL compatible implementation
Extensible design: Pluggable strategies for object identity retrieval, SID management, and permission handling
Audit support: Built-in auditing capabilities for permission grant/deny events

Next Steps

Understand the domain model - Core interfaces and their relationships
Set up ACL services - Configure AclService implementations
Implement permission evaluation - Use modern annotation-based approach
Complete configuration - Database setup and Spring integration
Customize with strategies - Extensible strategy interfaces for custom behavior
Optimize performance - Caching and performance tuning for production

Version Information

This documentation covers Spring Security ACL version 6.x. The ACL module has been part of Spring Security since version 2.0 and maintains backward compatibility while encouraging migration to the modern annotation-based approach.