0
# LDAP Authentication
1

2
Comprehensive LDAP authentication functionality supporting multiple authentication strategies including bind authentication and password comparison for flexible integration with different LDAP server configurations.
3

4
## Capabilities
5

6
### LdapAuthenticationProvider
7

8
Primary authentication provider that orchestrates LDAP authentication using configurable authenticators and authorities populators.
9

10
```java { .api }
11
/**
12
 * Primary LDAP authentication provider that delegates to LdapAuthenticator implementations
13
 * and optionally populates authorities from LDAP groups or attributes
14
 */
15
public class LdapAuthenticationProvider implements AuthenticationProvider, InitializingBean, MessageSourceAware {
16
    /**
17
     * Creates an authentication provider with the specified authenticator
18
     * @param authenticator the LDAP authenticator to use for authentication
19
     */
20
    public LdapAuthenticationProvider(LdapAuthenticator authenticator);
21
    
22
    /**
23
     * Creates an authentication provider with authenticator and authorities populator
24
     * @param authenticator the LDAP authenticator to use
25
     * @param authoritiesPopulator populator for retrieving user authorities
26
     */
27
    public LdapAuthenticationProvider(LdapAuthenticator authenticator, LdapAuthoritiesPopulator authoritiesPopulator);
28
    
29
    /**
30
     * Performs LDAP authentication for the given authentication request
31
     * @param authentication the authentication request
32
     * @return authenticated Authentication object with authorities
33
     * @throws AuthenticationException if authentication fails
34
     */
35
    public Authentication authenticate(Authentication authentication) throws AuthenticationException;
36
    
37
    /**
38
     * Checks if this provider supports the given authentication type
39
     * @param authentication the authentication class
40
     * @return true if UsernamePasswordAuthenticationToken is assignable from the class
41
     */
42
    public boolean supports(Class<?> authentication);
43
    
44
    /**
45
     * Sets the context mapper for mapping LDAP context to UserDetails
46
     * @param mapper the context mapper to use
47
     */
48
    public void setUserDetailsContextMapper(UserDetailsContextMapper mapper);
49
    
50
    /**
51
     * Sets the authorities populator for retrieving user authorities
52
     * @param authoritiesPopulator the authorities populator
53
     */
54
    public void setAuthoritiesPopulator(LdapAuthoritiesPopulator authoritiesPopulator);
55
}
56
```
57

58
**Usage Examples:**
59

60
```java
61
// Basic authentication provider with bind authenticator
62
BindAuthenticator authenticator = new BindAuthenticator(contextSource);
63
authenticator.setUserSearch(userSearch);
64

65
LdapAuthenticationProvider authProvider = new LdapAuthenticationProvider(authenticator);
66

67
// With authorities populator
68
DefaultLdapAuthoritiesPopulator authoritiesPopulator = 
69
    new DefaultLdapAuthoritiesPopulator(contextSource, "ou=groups");
70
authProvider.setAuthoritiesPopulator(authoritiesPopulator);
71

72
// With custom user details mapping
73
authProvider.setUserDetailsContextMapper(new LdapUserDetailsMapper());
74
```
75

76
### BindAuthenticator
77

78
Authenticates users by attempting to bind to the LDAP server using the user's credentials.
79

80
```java { .api }
81
/**
82
 * LDAP authenticator that uses bind authentication - attempts to bind to LDAP using user credentials
83
 */
84
public class BindAuthenticator extends AbstractLdapAuthenticator {
85
    /**
86
     * Creates a bind authenticator with the specified context source
87
     * @param contextSource the LDAP context source
88
     */
89
    public BindAuthenticator(ContextSource contextSource);
90
    
91
    /**
92
     * Authenticates the user by attempting to bind with their credentials
93
     * @param authentication the authentication request containing credentials
94
     * @return DirContextOperations representing the authenticated user
95
     * @throws BadCredentialsException if authentication fails
96
     */
97
    public DirContextOperations authenticate(Authentication authentication);
98
}
99
```
100

101
### PasswordComparisonAuthenticator
102

103
Authenticates users by comparing the provided password with the stored password in LDAP.
104

105
```java { .api }
106
/**
107
 * LDAP authenticator that compares the authentication password with the value stored in LDAP
108
 */
109
public class PasswordComparisonAuthenticator extends AbstractLdapAuthenticator {
110
    /**
111
     * Creates a password comparison authenticator with the specified context source
112
     * @param contextSource the LDAP context source
113
     */
114
    public PasswordComparisonAuthenticator(ContextSource contextSource);
115
    
116
    /**
117
     * Authenticates by comparing passwords
118
     * @param authentication the authentication request
119
     * @return DirContextOperations representing the authenticated user
120
     * @throws BadCredentialsException if authentication fails
121
     */
122
    public DirContextOperations authenticate(Authentication authentication);
123
    
124
    /**
125
     * Sets the password encoder for encoding comparison passwords
126
     * @param passwordEncoder the password encoder to use
127
     */
128
    public void setPasswordEncoder(PasswordEncoder passwordEncoder);
129
    
130
    /**
131
     * Sets the name of the LDAP attribute containing the password
132
     * @param passwordAttribute the password attribute name (default: "userPassword")
133
     */
134
    public void setPasswordAttributeName(String passwordAttribute);
135
    
136
    /**
137
     * Sets whether to use password comparison instead of bind authentication
138
     * @param usePasswordComparison true to use password comparison
139
     */
140
    public void setUsePasswordComparison(boolean usePasswordComparison);
141
}
142
```
143

144
### AbstractLdapAuthenticator
145

146
Base class for LDAP authenticators providing common functionality.
147

148
```java { .api }
149
/**
150
 * Base class for LDAP authenticators providing common configuration and user lookup functionality
151
 */
152
public abstract class AbstractLdapAuthenticator implements LdapAuthenticator, InitializingBean, MessageSourceAware {
153
    /**
154
     * Creates an authenticator with the specified context source
155
     * @param contextSource the LDAP context source
156
     */
157
    protected AbstractLdapAuthenticator(ContextSource contextSource);
158
    
159
    /**
160
     * Sets the user search strategy for locating users in LDAP
161
     * @param userSearch the user search implementation
162
     */
163
    public void setUserSearch(LdapUserSearch userSearch);
164
    
165
    /**
166
     * Sets user DN patterns for direct user lookup without search
167
     * @param userDnPatterns array of DN patterns with {0} placeholder for username
168
     */
169
    public void setUserDnPatterns(String[] userDnPatterns);
170
    
171
    /**
172
     * Gets the distinguished names for a username using configured patterns or search
173
     * @param username the username to look up
174
     * @return collection of DN strings
175
     */
176
    protected Collection<String> getUserDns(String username);
177
}
178
```
179

180
### AbstractLdapAuthenticationProvider
181

182
Base class for LDAP authentication providers providing common functionality.
183

184
```java { .api }
185
/**
186
 * Base class for standard LdapAuthenticationProvider and ActiveDirectoryLdapAuthenticationProvider
187
 */
188
public abstract class AbstractLdapAuthenticationProvider implements AuthenticationProvider, InitializingBean, MessageSourceAware {
189
    /**
190
     * Performs authentication using the configured authenticator
191
     * @param authentication the authentication request
192
     * @return authenticated Authentication object with authorities
193
     * @throws AuthenticationException if authentication fails
194
     */
195
    public Authentication authenticate(Authentication authentication) throws AuthenticationException;
196
    
197
    /**
198
     * Checks if this provider supports the given authentication type
199
     * @param authentication the authentication class
200
     * @return true if supported
201
     */
202
    public boolean supports(Class<?> authentication);
203
    
204
    /**
205
     * Sets the authorities mapper for mapping authorities
206
     * @param authoritiesMapper the authorities mapper
207
     */
208
    public void setAuthoritiesMapper(GrantedAuthoritiesMapper authoritiesMapper);
209
    
210
    /**
211
     * Sets the user details context mapper
212
     * @param userDetailsContextMapper the context mapper
213
     */
214
    public void setUserDetailsContextMapper(UserDetailsContextMapper userDetailsContextMapper);
215
    
216
    /**
217
     * Sets whether to use the authentication name in the returned Authentication object
218
     * @param useAuthenticationRequestCredentials true to use authentication name
219
     */
220
    public void setUseAuthenticationRequestCredentials(boolean useAuthenticationRequestCredentials);
221
}
222
```
223

224
### ActiveDirectoryLdapAuthenticationProvider
225

226
Specialized authentication provider for Microsoft Active Directory integration.
227

228
```java { .api }
229
/**
230
 * Specialized authentication provider for Microsoft Active Directory environments
231
 */
232
public class ActiveDirectoryLdapAuthenticationProvider implements AuthenticationProvider, InitializingBean, MessageSourceAware {
233
    /**
234
     * Creates an Active Directory authentication provider
235
     * @param domain the Active Directory domain
236
     * @param url the LDAP URL for the domain controller
237
     */
238
    public ActiveDirectoryLdapAuthenticationProvider(String domain, String url);
239
    
240
    /**
241
     * Creates an Active Directory authentication provider with additional URLs
242
     * @param domain the Active Directory domain
243
     * @param url the primary LDAP URL
244
     * @param rootDn the root DN for searches
245
     */
246
    public ActiveDirectoryLdapAuthenticationProvider(String domain, String url, String rootDn);
247
    
248
    /**
249
     * Performs Active Directory authentication
250
     * @param authentication the authentication request
251
     * @return authenticated Authentication object
252
     * @throws AuthenticationException if authentication fails
253
     */
254
    public Authentication authenticate(Authentication authentication) throws AuthenticationException;
255
    
256
    /**
257
     * Sets whether to convert sub-error codes to exceptions
258
     * @param convertSubErrorCodesToExceptions true to convert sub-errors
259
     */
260
    public void setConvertSubErrorCodesToExceptions(boolean convertSubErrorCodesToExceptions);
261
    
262
    /**
263
     * Sets the search filter for finding users in Active Directory
264
     * @param searchFilter the LDAP search filter
265
     */
266
    public void setSearchFilter(String searchFilter);
267
    
268
    /**
269
     * Sets whether to use bind authentication or password comparison
270
     * @param useAuthenticationRequestCredentials true to use bind authentication
271
     */
272
    public void setUseAuthenticationRequestCredentials(boolean useAuthenticationRequestCredentials);
273
}
274
```
275

276
**Usage Examples:**
277

278
```java
279
// Active Directory authentication
280
ActiveDirectoryLdapAuthenticationProvider adProvider = 
281
    new ActiveDirectoryLdapAuthenticationProvider("corp.example.com", "ldap://dc.corp.example.com:389/");
282
adProvider.setConvertSubErrorCodesToExceptions(true);
283
adProvider.setUseAuthenticationRequestCredentials(true);
284

285
// Password comparison authentication
286
PasswordComparisonAuthenticator passwordAuth = new PasswordComparisonAuthenticator(contextSource);
287
passwordAuth.setPasswordEncoder(new BCryptPasswordEncoder());
288
passwordAuth.setPasswordAttributeName("userPassword");
289

290
LdapAuthenticationProvider provider = new LdapAuthenticationProvider(passwordAuth);
291
```
292

293
## Authentication Interfaces
294

295
### LdapAuthenticator
296

297
Strategy interface for LDAP authentication implementations.
298

299
```java { .api }
300
/**
301
 * Strategy interface for LDAP authentication implementations
302
 */
303
public interface LdapAuthenticator {
304
    /**
305
     * Performs LDAP authentication for the given authentication request
306
     * @param authentication the authentication request containing credentials
307
     * @return DirContextOperations representing the authenticated user context
308
     * @throws AuthenticationException if authentication fails
309
     */
310
    DirContextOperations authenticate(Authentication authentication);
311
}
312
```
313

314
### NullLdapAuthoritiesPopulator
315

316
No-operation authorities populator that returns empty authorities collection.
317

318
```java { .api }
319
/**
320
 * Implementation of LdapAuthoritiesPopulator that returns an empty authorities collection
321
 */
322
public class NullLdapAuthoritiesPopulator implements LdapAuthoritiesPopulator {
323
    /**
324
     * Returns an empty collection of granted authorities
325
     * @param userData LDAP context operations for the user
326
     * @param username the username
327
     * @return empty collection of authorities
328
     */
329
    public Collection<GrantedAuthority> getGrantedAuthorities(DirContextOperations userData, String username);
330
}
331
```
332

333
## Configuration Examples
334

335
### Basic Bind Authentication Setup
336

337
```java
338
@Configuration
339
@EnableWebSecurity
340
public class LdapSecurityConfig {
341
    
342
    @Bean
343
    public DefaultSpringSecurityContextSource contextSource() {
344
        DefaultSpringSecurityContextSource contextSource = 
345
            new DefaultSpringSecurityContextSource("ldap://localhost:389/dc=springframework,dc=org");
346
        contextSource.setUserDn("cn=manager,dc=springframework,dc=org");
347
        contextSource.setPassword("password");
348
        return contextSource;
349
    }
350
    
351
    @Bean
352
    public FilterBasedLdapUserSearch userSearch() {
353
        return new FilterBasedLdapUserSearch("ou=people", "uid={0}", contextSource());
354
    }
355
    
356
    @Bean
357
    public BindAuthenticator authenticator() {
358
        BindAuthenticator authenticator = new BindAuthenticator(contextSource());
359
        authenticator.setUserSearch(userSearch());
360
        return authenticator;
361
    }
362
    
363
    @Bean
364
    public LdapAuthenticationProvider authenticationProvider() {
365
        return new LdapAuthenticationProvider(authenticator());
366
    }
367
}
368
```
369

370
### Password Comparison Authentication
371

372
```java
373
@Bean
374
public PasswordComparisonAuthenticator passwordAuthenticator() {
375
    PasswordComparisonAuthenticator authenticator = 
376
        new PasswordComparisonAuthenticator(contextSource());
377
    authenticator.setPasswordEncoder(new BCryptPasswordEncoder());
378
    authenticator.setPasswordAttributeName("userPassword");
379
    authenticator.setUserSearch(userSearch());
380
    return authenticator;
381
}
382
```