0
# Spring Security ACL
1

2
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.
3

4
## Package Information
5

6
**Group ID:** `org.springframework.security`  
7
**Artifact ID:** `spring-security-acl`  
8
**Package:** `org.springframework.security.acls`
9

10
## Maven Dependency
11

12
```xml { .api }
13
<dependency>
14
    <groupId>org.springframework.security</groupId>
15
    <artifactId>spring-security-acl</artifactId>
16
    <version>6.5.1</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java { .api }
23
import org.springframework.security.acls.AclPermissionEvaluator;
24
import org.springframework.security.acls.model.AclService;
25
import org.springframework.security.acls.model.MutableAclService;
26
import org.springframework.security.acls.model.Permission;
27
import org.springframework.security.acls.model.Sid;
28
import org.springframework.security.acls.model.ObjectIdentity;
29
import org.springframework.security.acls.model.Acl;
30
import org.springframework.security.acls.domain.BasePermission;
31
import org.springframework.security.acls.domain.PrincipalSid;
32
import org.springframework.security.acls.domain.GrantedAuthoritySid;
33
import org.springframework.security.acls.domain.ObjectIdentityImpl;
34
```
35

36
## Basic Usage Example
37

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

40
```java { .api }
41
@Service
42
public class DocumentService {
43
    
44
    @PreAuthorize("hasPermission(#document, 'READ')")
45
    public Document getDocument(Document document) {
46
        return document;
47
    }
48
    
49
    @PreAuthorize("hasPermission(#document, 'WRITE')")
50
    public void updateDocument(Document document) {
51
        // Update document
52
    }
53
    
54
    @PreAuthorize("hasPermission(#documentId, 'com.example.Document', 'DELETE')")
55
    public void deleteDocument(Long documentId) {
56
        // Delete document
57
    }
58
    
59
    @PostAuthorize("hasPermission(returnObject, 'READ')")
60
    public Document findDocument(Long id) {
61
        return documentRepository.findById(id);
62
    }
63
    
64
    @PostFilter("hasPermission(filterObject, 'READ')")
65
    public List<Document> getUserDocuments() {
66
        return documentRepository.findAll();
67
    }
68
}
69
```
70

71
## Architecture
72

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

75
### Core Components
76

77
- **AclService**: Read access to ACL data
78
- **MutableAclService**: Create/modify ACL data  
79
- **AclPermissionEvaluator**: Integration with Spring Security expressions
80
- **Acl**: Represents permissions for a domain object
81
- **ObjectIdentity**: Identifies domain object instances
82
- **Sid**: Security identities (users/roles)
83
- **Permission**: Specific permission types
84

85
### Data Flow
86

87
1. **Permission Check**: `@PreAuthorize` triggers permission evaluation
88
2. **Object Identity**: Extract identity from domain object
89
3. **Security Identity**: Get current user's SIDs (principal + authorities)
90
4. **ACL Lookup**: Query ACL data for object and SIDs
91
5. **Permission Decision**: Check if required permission is granted
92

93
## Capabilities
94

95
### Core Domain Model
96
The ACL module provides a rich domain model for representing permissions:
97

98
```java { .api }
99
// Domain object identity
100
ObjectIdentity identity = new ObjectIdentityImpl(Document.class, documentId);
101

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

106
// Built-in permissions
107
Permission read = BasePermission.READ;
108
Permission write = BasePermission.WRITE;
109
Permission delete = BasePermission.DELETE;
110
```
111

112
[Learn more about the domain model →](domain-model.md)
113

114
### ACL Services
115
Programmatic access to ACL data for reading and modification:
116

117
```java { .api }
118
@Autowired
119
private MutableAclService aclService;
120

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

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

128
// Read ACL
129
Acl existingAcl = aclService.readAclById(objectIdentity);
130
```
131

132
[Learn more about ACL services →](acl-services.md)
133

134
### Permission Evaluation  
135
Modern annotation-based approach with caching and optimization:
136

137
```java { .api }
138
@Configuration
139
@EnableGlobalMethodSecurity(prePostEnabled = true)
140
public class SecurityConfig {
141
    
142
    @Bean
143
    public PermissionEvaluator permissionEvaluator(AclService aclService) {
144
        AclPermissionEvaluator evaluator = new AclPermissionEvaluator(aclService);
145
        evaluator.setPermissionFactory(permissionFactory());
146
        return evaluator;
147
    }
148
}
149
```
150

151
[Learn more about permission evaluation →](permission-evaluation.md)
152

153
### Configuration & Setup
154
Complete Spring configuration with database setup and security integration:
155

156
```java { .api }
157
@Configuration
158
@EnableJpaRepositories
159
public class AclConfig {
160
    
161
    @Bean
162
    public AclService aclService() {
163
        JdbcMutableAclService service = new JdbcMutableAclService(
164
            dataSource(), lookupStrategy(), aclCache());
165
        service.setClassIdentityQuery("SELECT @@IDENTITY");
166
        service.setSidIdentityQuery("SELECT @@IDENTITY");  
167
        return service;
168
    }
169
}
170
```
171

172
[Learn more about configuration →](configuration.md)
173

174
### Caching & Performance
175
Advanced caching and performance optimization features for production deployments:
176

177
```java { .api }
178
@Bean
179
public AclCache aclCache() {
180
    return new SpringCacheBasedAclCache(
181
        cacheManager().getCache("aclCache"),
182
        permissionGrantingStrategy(),
183
        aclAuthorizationStrategy()
184
    );
185
}
186

187
@Bean  
188
public PermissionCacheOptimizer permissionCacheOptimizer(AclService aclService) {
189
    return new AclPermissionCacheOptimizer(aclService);
190
}
191
```
192

193
[Learn more about caching & performance →](caching-performance.md)
194

195
### Strategy Interfaces
196
Extensible strategy interfaces for customizing ACL behavior:
197

198
```java { .api }
199
// Custom object identity retrieval
200
@Bean
201
public ObjectIdentityRetrievalStrategy objectIdentityRetrievalStrategy() {
202
    return new CustomObjectIdentityRetrievalStrategy();
203
}
204

205
// Custom SID retrieval with groups
206
@Bean
207
public SidRetrievalStrategy sidRetrievalStrategy() {
208
    return new GroupAwareSidRetrievalStrategy();
209
}
210

211
// Custom permission evaluation logic
212
@Bean
213
public PermissionGrantingStrategy permissionGrantingStrategy() {
214
    return new CustomPermissionGrantingStrategy(auditLogger());
215
}
216
```
217

218
[Learn more about strategy interfaces →](strategy-interfaces.md)
219

220
## Key Features
221

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

230
## Standards Compliance
231

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

237
## Next Steps
238

239
1. [Understand the domain model](domain-model.md) - Core interfaces and their relationships
240
2. [Set up ACL services](acl-services.md) - Configure AclService implementations  
241
3. [Implement permission evaluation](permission-evaluation.md) - Use modern annotation-based approach
242
4. [Complete configuration](configuration.md) - Database setup and Spring integration
243
5. [Customize with strategies](strategy-interfaces.md) - Extensible strategy interfaces for custom behavior
244
6. [Optimize performance](caching-performance.md) - Caching and performance tuning for production
245

246
## Version Information
247

248
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.