0
# Spring Security LDAP
1
2
Spring Security LDAP is a comprehensive Java library that provides LDAP (Lightweight Directory Access Protocol) authentication and authorization capabilities for Spring Security applications. It enables seamless integration with LDAP directory servers for user authentication, user details retrieval, and role-based access control, supporting both traditional and modern enterprise environments.
3
4
## Package Information
5
6
- **Package Name**: org.springframework.security:spring-security-ldap
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven dependencies:
10
11
```xml
12
<dependency>
13
<groupId>org.springframework.security</groupId>
14
<artifactId>spring-security-ldap</artifactId>
15
<version>6.5.1</version>
16
</dependency>
17
```
18
19
For Gradle:
20
21
```gradle
22
implementation 'org.springframework.security:spring-security-ldap:6.5.1'
23
```
24
25
## Core Imports
26
27
```java
28
import org.springframework.security.ldap.authentication.LdapAuthenticationProvider;
29
import org.springframework.security.ldap.DefaultSpringSecurityContextSource;
30
import org.springframework.security.ldap.userdetails.LdapUserDetailsService;
31
import org.springframework.security.ldap.search.FilterBasedLdapUserSearch;
32
import org.springframework.security.ldap.LdapUsernameToDnMapper;
33
import org.springframework.security.ldap.DefaultLdapUsernameToDnMapper;
34
```
35
36
## Basic Usage
37
38
```java
39
import org.springframework.security.ldap.DefaultSpringSecurityContextSource;
40
import org.springframework.security.ldap.authentication.LdapAuthenticationProvider;
41
import org.springframework.security.ldap.authentication.BindAuthenticator;
42
import org.springframework.security.ldap.search.FilterBasedLdapUserSearch;
43
44
// Configure LDAP context source
45
DefaultSpringSecurityContextSource contextSource =
46
new DefaultSpringSecurityContextSource("ldap://localhost:389/dc=springframework,dc=org");
47
contextSource.setUserDn("cn=manager,dc=springframework,dc=org");
48
contextSource.setPassword("password");
49
50
// Configure user search
51
FilterBasedLdapUserSearch userSearch =
52
new FilterBasedLdapUserSearch("ou=people", "uid={0}", contextSource);
53
54
// Configure authenticator
55
BindAuthenticator authenticator = new BindAuthenticator(contextSource);
56
authenticator.setUserSearch(userSearch);
57
58
// Create authentication provider
59
LdapAuthenticationProvider authProvider = new LdapAuthenticationProvider(authenticator);
60
```
61
62
## Architecture
63
64
Spring Security LDAP is organized around several key architectural components:
65
66
- **Context Management**: `DefaultSpringSecurityContextSource` manages LDAP connections and context operations
67
- **Authentication Strategies**: Multiple authentication approaches including bind authentication and password comparison
68
- **User Details Services**: Integration with Spring Security's UserDetailsService for user information retrieval
69
- **Search Strategies**: Flexible user search implementations for locating users in LDAP directories
70
- **Authorities Population**: Automatic role and authority mapping from LDAP groups and attributes
71
- **Server Integration**: Support for embedded LDAP servers for testing and development
72
- **Enterprise Features**: Password policy support, Active Directory integration, and modern serialization
73
74
## Capabilities
75
76
### LDAP Authentication
77
78
Core authentication functionality supporting multiple authentication strategies including bind authentication and password comparison for flexible integration with different LDAP server configurations.
79
80
```java { .api }
81
public class LdapAuthenticationProvider implements AuthenticationProvider {
82
public LdapAuthenticationProvider(LdapAuthenticator authenticator);
83
public Authentication authenticate(Authentication authentication) throws AuthenticationException;
84
public void setUserDetailsContextMapper(UserDetailsContextMapper mapper);
85
public void setAuthoritiesPopulator(LdapAuthoritiesPopulator authoritiesPopulator);
86
}
87
```
88
89
[LDAP Authentication](./authentication.md)
90
91
### User Details and Search
92
93
User details services and search implementations for retrieving user information from LDAP directories with comprehensive mapping and customization options.
94
95
```java { .api }
96
public class LdapUserDetailsService implements UserDetailsService {
97
public LdapUserDetailsService(LdapUserSearch userSearch);
98
public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;
99
public void setUserDetailsMapper(UserDetailsContextMapper mapper);
100
}
101
102
public interface LdapUserSearch {
103
DirContextOperations searchForUser(String username);
104
}
105
```
106
107
[User Details and Search](./user-details.md)
108
109
### Context Management
110
111
LDAP context source and template classes for managing connections to LDAP servers with support for authentication, connection pooling, and operation execution.
112
113
```java { .api }
114
public class DefaultSpringSecurityContextSource implements InitializingBean, DisposableBean {
115
public DefaultSpringSecurityContextSource(String providerUrl);
116
public void setUserDn(String userDn);
117
public void setPassword(String password);
118
public DirContext getReadOnlyContext() throws NamingException;
119
public DirContext getReadWriteContext() throws NamingException;
120
}
121
122
public class SpringSecurityLdapTemplate {
123
public SpringSecurityLdapTemplate(ContextSource contextSource);
124
public DirContextOperations searchForSingleEntry(String base, String filter, Object[] params);
125
public boolean authenticate(String base, String filter, Object[] params, String password);
126
}
127
```
128
129
[Context Management](./context-management.md)
130
131
### Authorities Population
132
133
Authority and role mapping from LDAP groups and attributes with customizable population strategies for complex authorization scenarios.
134
135
```java { .api }
136
public interface LdapAuthoritiesPopulator {
137
Collection<? extends GrantedAuthority> getGrantedAuthorities(
138
DirContextOperations userData, String username);
139
}
140
141
public class DefaultLdapAuthoritiesPopulator implements LdapAuthoritiesPopulator {
142
public DefaultLdapAuthoritiesPopulator(ContextSource contextSource, String groupSearchBase);
143
public void setGroupSearchFilter(String groupSearchFilter);
144
public void setGroupRoleAttribute(String groupRoleAttribute);
145
}
146
```
147
148
[Authorities Population](./authorities.md)
149
150
### Embedded Server Support
151
152
Embedded LDAP server containers for testing and development environments with support for Apache Directory Server and UnboundID implementations.
153
154
```java { .api }
155
public class ApacheDSContainer implements InitializingBean, DisposableBean, Lifecycle {
156
public ApacheDSContainer(String root, String ldifs);
157
public void start();
158
public void stop();
159
public int getPort();
160
public void setPort(int port);
161
}
162
```
163
164
[Embedded Server Support](./embedded-server.md)
165
166
### Password Policy Support
167
168
LDAP password policy controls and exception handling for enterprise environments requiring advanced password management features.
169
170
```java { .api }
171
public class PasswordPolicyControl extends BasicControl {
172
public static final String OID = "1.3.6.1.4.1.42.2.27.8.5.1";
173
public PasswordPolicyControl();
174
public PasswordPolicyControl(boolean criticality);
175
}
176
177
public enum PasswordPolicyErrorStatus {
178
PASSWORD_EXPIRED, ACCOUNT_LOCKED, CHANGE_AFTER_RESET,
179
PASSWORD_MOD_NOT_ALLOWED, MUST_SUPPLY_OLD_PASSWORD,
180
INSUFFICIENT_PASSWORD_QUALITY, PASSWORD_TOO_SHORT,
181
PASSWORD_TOO_YOUNG, PASSWORD_IN_HISTORY;
182
}
183
```
184
185
[Password Policy Support](./password-policy.md)
186
187
### JSON Serialization Support
188
189
Jackson JSON serialization support for Spring Security LDAP classes enabling serialization and deserialization of LDAP user details and authorities.
190
191
```java { .api }
192
public class LdapJackson2Module extends SimpleModule {
193
public LdapJackson2Module();
194
public void setupModule(SetupContext context);
195
}
196
```
197
198
[JSON Serialization Support](./json-serialization.md)
199
200
## Types
201
202
```java { .api }
203
public interface LdapUserDetails extends UserDetails {
204
String getDn();
205
Attributes getAttributes();
206
}
207
208
public class LdapUserDetailsImpl implements LdapUserDetails, CredentialsContainer {
209
public String getDn();
210
public Attributes getAttributes();
211
// UserDetails implementation methods
212
public String getUsername();
213
public String getPassword();
214
public Collection<? extends GrantedAuthority> getAuthorities();
215
public boolean isAccountNonExpired();
216
public boolean isAccountNonLocked();
217
public boolean isCredentialsNonExpired();
218
public boolean isEnabled();
219
}
220
221
public interface UserDetailsContextMapper {
222
UserDetails mapUserFromContext(DirContextOperations ctx, String username,
223
Collection<? extends GrantedAuthority> authorities);
224
void mapUserToContext(UserDetails user, DirContextAdapter ctx);
225
}
226
227
public interface LdapAuthenticator {
228
DirContextOperations authenticate(Authentication authentication);
229
}
230
231
public interface LdapAuthoritiesPopulator {
232
Collection<? extends GrantedAuthority> getGrantedAuthorities(
233
DirContextOperations userData, String username);
234
}
235
236
public class LdapAuthority implements GrantedAuthority {
237
private final String role;
238
private final String dn;
239
240
public LdapAuthority(String role, String dn);
241
public String getAuthority();
242
public String getDn();
243
}
244
245
public interface LdapUsernameToDnMapper {
246
LdapName buildLdapName(String username);
247
@Deprecated
248
DistinguishedName buildDn(String username);
249
}
250
251
public class DefaultLdapUsernameToDnMapper implements LdapUsernameToDnMapper {
252
public DefaultLdapUsernameToDnMapper(String userDnBase, String usernameAttribute);
253
public LdapName buildLdapName(String username);
254
}
255
```