0
# User Details and Search
1

2
User details services and search implementations for retrieving user information from LDAP directories with comprehensive mapping and customization options.
3

4
## Capabilities
5

6
### LdapUserDetailsService
7

8
Spring Security UserDetailsService implementation that loads user details from LDAP directories.
9

10
```java { .api }
11
/**
12
 * UserDetailsService implementation that loads user details from LDAP
13
 */
14
public class LdapUserDetailsService implements UserDetailsService {
15
    /**
16
     * Creates an LDAP user details service with the specified user search
17
     * @param userSearch the LDAP user search implementation
18
     */
19
    public LdapUserDetailsService(LdapUserSearch userSearch);
20
    
21
    /**
22
     * Creates an LDAP user details service with user search and authorities populator
23
     * @param userSearch the LDAP user search implementation
24
     * @param authoritiesPopulator populator for retrieving user authorities
25
     */
26
    public LdapUserDetailsService(LdapUserSearch userSearch, LdapAuthoritiesPopulator authoritiesPopulator);
27
    
28
    /**
29
     * Loads user details by username from LDAP
30
     * @param username the username to search for
31
     * @return UserDetails object containing user information and authorities
32
     * @throws UsernameNotFoundException if user is not found
33
     */
34
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;
35
    
36
    /**
37
     * Sets the user details context mapper for converting LDAP context to UserDetails
38
     * @param mapper the context mapper to use
39
     */
40
    public void setUserDetailsMapper(UserDetailsContextMapper mapper);
41
}
42
```
43

44
**Usage Examples:**
45

46
```java
47
// Basic user details service
48
FilterBasedLdapUserSearch userSearch = 
49
    new FilterBasedLdapUserSearch("ou=people", "uid={0}", contextSource);
50

51
LdapUserDetailsService userDetailsService = new LdapUserDetailsService(userSearch);
52

53
// With authorities populator
54
DefaultLdapAuthoritiesPopulator authoritiesPopulator = 
55
    new DefaultLdapAuthoritiesPopulator(contextSource, "ou=groups");
56
    
57
LdapUserDetailsService userDetailsService = 
58
    new LdapUserDetailsService(userSearch, authoritiesPopulator);
59

60
// With custom mapper
61
userDetailsService.setUserDetailsMapper(new LdapUserDetailsMapper());
62
```
63

64
### FilterBasedLdapUserSearch
65

66
LDAP user search implementation using configurable LDAP filters to locate users.
67

68
```java { .api }
69
/**
70
 * LDAP user search implementation using filter-based searches to locate users in the directory
71
 */
72
public class FilterBasedLdapUserSearch implements LdapUserSearch, InitializingBean, MessageSourceAware {
73
    /**
74
     * Creates a filter-based user search
75
     * @param searchBase the base DN to search from
76
     * @param searchFilter the LDAP search filter with {0} placeholder for username
77
     * @param contextSource the LDAP context source
78
     */
79
    public FilterBasedLdapUserSearch(String searchBase, String searchFilter, ContextSource contextSource);
80
    
81
    /**
82
     * Searches for a user in LDAP using the configured filter
83
     * @param username the username to search for
84
     * @return DirContextOperations representing the found user
85
     * @throws UsernameNotFoundException if user is not found
86
     */
87
    public DirContextOperations searchForUser(String username);
88
    
89
    /**
90
     * Sets whether to dereference links during search
91
     * @param deref true to dereference links
92
     */
93
    public void setDerefLinkFlag(boolean deref);
94
    
95
    /**
96
     * Sets whether to search the entire subtree or just one level
97
     * @param searchSubtree true to search subtree
98
     */
99
    public void setSearchSubtree(boolean searchSubtree);
100
    
101
    /**
102
     * Sets the search time limit in milliseconds
103
     * @param searchTimeLimit time limit for searches
104
     */
105
    public void setSearchTimeLimit(int searchTimeLimit);
106
    
107
    /**
108
     * Sets additional search controls
109
     * @param searchControls the search controls to use
110
     */
111
    public void setSearchControls(SearchControls searchControls);
112
}
113
```
114

115
### LdapUserDetailsImpl
116

117
Default implementation of LdapUserDetails providing LDAP-specific user information.
118

119
```java { .api }
120
/**
121
 * Default implementation of LdapUserDetails containing LDAP-specific user information and attributes
122
 */
123
public class LdapUserDetailsImpl implements LdapUserDetails, CredentialsContainer {
124
    /**
125
     * Gets the user's distinguished name
126
     * @return the DN as a string
127
     */
128
    public String getDn();
129
    
130
    /**
131
     * Gets the user's LDAP attributes
132
     * @return Attributes object containing all user attributes
133
     */
134
    public Attributes getAttributes();
135
    
136
    // UserDetails implementation
137
    /**
138
     * Gets the username used for authentication
139
     * @return the username
140
     */
141
    public String getUsername();
142
    
143
    /**
144
     * Gets the user's password (may be null for security)
145
     * @return the password or null
146
     */
147
    public String getPassword();
148
    
149
    /**
150
     * Gets the user's granted authorities
151
     * @return collection of GrantedAuthority objects
152
     */
153
    public Collection<? extends GrantedAuthority> getAuthorities();
154
    
155
    /**
156
     * Indicates whether the user's account has expired
157
     * @return true if account is non-expired
158
     */
159
    public boolean isAccountNonExpired();
160
    
161
    /**
162
     * Indicates whether the user is locked or unlocked
163
     * @return true if account is non-locked
164
     */
165
    public boolean isAccountNonLocked();
166
    
167
    /**
168
     * Indicates whether the user's credentials have expired
169
     * @return true if credentials are non-expired
170
     */
171
    public boolean isCredentialsNonExpired();
172
    
173
    /**
174
     * Indicates whether the user is enabled or disabled
175
     * @return true if user is enabled
176
     */
177
    public boolean isEnabled();
178
    
179
    /**
180
     * Removes sensitive information (password) from the object
181
     */
182
    public void eraseCredentials();
183
}
184
```
185

186
### LdapUserDetailsMapper
187

188
Default context mapper for converting LDAP context operations to UserDetails objects.
189

190
```java { .api }
191
/**
192
 * Default implementation of UserDetailsContextMapper for mapping LDAP contexts to UserDetails
193
 */
194
public class LdapUserDetailsMapper implements UserDetailsContextMapper {
195
    /**
196
     * Maps user information from LDAP context to UserDetails
197
     * @param ctx the LDAP directory context operations
198
     * @param username the username
199
     * @param authorities the granted authorities
200
     * @return UserDetails object
201
     */
202
    public UserDetails mapUserFromContext(DirContextOperations ctx, String username, 
203
        Collection<? extends GrantedAuthority> authorities);
204
    
205
    /**
206
     * Maps UserDetails back to LDAP context (for updates)
207
     * @param user the UserDetails object
208
     * @param ctx the directory context adapter
209
     */
210
    public void mapUserToContext(UserDetails user, DirContextAdapter ctx);
211
    
212
    /**
213
     * Sets the name of the LDAP password attribute
214
     * @param passwordAttributeName the password attribute name
215
     */
216
    public void setPasswordAttributeName(String passwordAttributeName);
217
    
218
    /**
219
     * Sets the prefix to apply to role names
220
     * @param rolePrefix the role prefix (default: "ROLE_")
221
     */
222
    public void setRolePrefix(String rolePrefix);
223
    
224
    /**
225
     * Sets whether to convert role names to uppercase
226
     * @param convertToUpperCase true to convert to uppercase
227
     */
228
    public void setConvertToUpperCase(boolean convertToUpperCase);
229
}
230
```
231

232
## LDAP Person Classes
233

234
### Person
235

236
Standard LDAP person object class implementation.
237

238
```java { .api }
239
/**
240
 * Represents a person entry in LDAP directory implementing the person object class
241
 */
242
public class Person extends DirContextAdapter implements LdapUserDetails, CredentialsContainer {
243
    /**
244
     * Default constructor creating an empty person
245
     */
246
    public Person();
247
    
248
    /**
249
     * Creates a person with specified DN and object class
250
     * @param dn the distinguished name
251
     * @param objectClass the LDAP object class
252
     */
253
    public Person(String dn, String objectClass);
254
    
255
    // Person attributes
256
    /**
257
     * Gets the person's common name (cn)
258
     * @return the common name
259
     */
260
    public String getCn();
261
    
262
    /**
263
     * Sets the person's common name (cn)
264
     * @param cn the common name
265
     */
266
    public void setCn(String cn);
267
    
268
    /**
269
     * Gets the person's surname (sn)
270
     * @return the surname
271
     */
272
    public String getSn();
273
    
274
    /**
275
     * Sets the person's surname (sn)
276
     * @param sn the surname
277
     */
278
    public void setSn(String sn);
279
    
280
    /**
281
     * Gets the person's description
282
     * @return the description
283
     */
284
    public String getDescription();
285
    
286
    /**
287
     * Sets the person's description
288
     * @param description the description
289
     */
290
    public void setDescription(String description);
291
    
292
    /**
293
     * Gets the person's telephone number
294
     * @return the telephone number
295
     */
296
    public String getTelephoneNumber();
297
    
298
    /**
299
     * Sets the person's telephone number
300
     * @param telephoneNumber the telephone number
301
     */
302
    public void setTelephoneNumber(String telephoneNumber);
303
    
304
    // LdapUserDetails and UserDetails implementation methods inherited
305
}
306
```
307

308
### LdapUserDetailsManager
309

310
UserDetailsManager implementation that provides CRUD operations for LDAP user entries.
311

312
```java { .api }
313
/**
314
 * UserDetailsManager implementation that allows CRUD operations on LDAP user entries
315
 */
316
public class LdapUserDetailsManager implements UserDetailsManager {
317
    /**
318
     * Creates an LDAP user details manager
319
     * @param contextSource the LDAP context source
320
     */
321
    public LdapUserDetailsManager(ContextSource contextSource);
322
    
323
    /**
324
     * Creates a new user in the LDAP directory
325
     * @param user the UserDetails object containing user information
326
     */
327
    public void createUser(UserDetails user);
328
    
329
    /**
330
     * Updates an existing user in the LDAP directory
331
     * @param user the UserDetails object with updated information
332
     */
333
    public void updateUser(UserDetails user);
334
    
335
    /**
336
     * Deletes a user from the LDAP directory
337
     * @param username the username of the user to delete
338
     */
339
    public void deleteUser(String username);
340
    
341
    /**
342
     * Changes the password for a user
343
     * @param oldPassword the current password
344
     * @param newPassword the new password
345
     */
346
    public void changePassword(String oldPassword, String newPassword);
347
    
348
    /**
349
     * Checks if a user exists in the LDAP directory
350
     * @param username the username to check
351
     * @return true if the user exists
352
     */
353
    public boolean userExists(String username);
354
    
355
    /**
356
     * Loads a user by username
357
     * @param username the username
358
     * @return UserDetails object
359
     * @throws UsernameNotFoundException if user not found
360
     */
361
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;
362
    
363
    /**
364
     * Sets the password encoder for password operations
365
     * @param passwordEncoder the password encoder
366
     */
367
    public void setPasswordEncoder(PasswordEncoder passwordEncoder);
368
    
369
    /**
370
     * Sets the user DN patterns for user entry creation
371
     * @param userDnPatterns array of DN patterns
372
     */
373
    public void setUserDnPatterns(String[] userDnPatterns);
374
}
375
```
376

377
### PersonContextMapper and InetOrgPersonContextMapper
378

379
Context mappers for Person and InetOrgPerson objects.
380

381
```java { .api }
382
/**
383
 * Context mapper for Person objects
384
 */
385
public class PersonContextMapper implements UserDetailsContextMapper {
386
    /**
387
     * Maps LDAP context to Person object
388
     * @param ctx the directory context operations
389
     * @param username the username
390
     * @param authorities the granted authorities
391
     * @return Person object with mapped attributes
392
     */
393
    public UserDetails mapUserFromContext(DirContextOperations ctx, String username, 
394
        Collection<? extends GrantedAuthority> authorities);
395
    
396
    /**
397
     * Maps Person object back to LDAP context
398
     * @param user the Person object
399
     * @param ctx the directory context adapter
400
     */
401
    public void mapUserToContext(UserDetails user, DirContextAdapter ctx);
402
}
403

404
/**
405
 * Context mapper for InetOrgPerson objects
406
 */
407
public class InetOrgPersonContextMapper implements UserDetailsContextMapper {
408
    /**
409
     * Maps LDAP context to InetOrgPerson object
410
     * @param ctx the directory context operations
411
     * @param username the username
412
     * @param authorities the granted authorities
413
     * @return InetOrgPerson object with mapped attributes
414
     */
415
    public UserDetails mapUserFromContext(DirContextOperations ctx, String username, 
416
        Collection<? extends GrantedAuthority> authorities);
417
    
418
    /**
419
     * Maps InetOrgPerson object back to LDAP context
420
     * @param user the InetOrgPerson object
421
     * @param ctx the directory context adapter
422
     */
423
    public void mapUserToContext(UserDetails user, DirContextAdapter ctx);
424
}
425
```
426

427
### LdapAuthority
428

429
LDAP-specific authority implementation that includes distinguished name information.
430

431
```java { .api }
432
/**
433
 * LDAP-specific GrantedAuthority implementation that stores the authority name and DN
434
 */
435
public class LdapAuthority implements GrantedAuthority {
436
    /**
437
     * Creates an LDAP authority with role and DN
438
     * @param role the role name
439
     * @param dn the distinguished name of the authority source
440
     */
441
    public LdapAuthority(String role, String dn);
442
    
443
    /**
444
     * Gets the authority name
445
     * @return the authority string
446
     */
447
    public String getAuthority();
448
    
449
    /**
450
     * Gets the distinguished name of the authority source
451
     * @return the DN string
452
     */
453
    public String getDn();
454
    
455
    /**
456
     * Gets the first attribute value from the DN
457
     * @return the first attribute value
458
     */
459
    public String getFirstAttributeValue();
460
}
461
```
462

463
### InetOrgPerson
464

465
Extended person class implementing the inetOrgPerson object class with additional attributes.
466

467
```java { .api }
468
/**
469
 * Represents an inetOrgPerson entry in LDAP directory with extended organizational attributes
470
 */
471
public class InetOrgPerson extends Person {
472
    /**
473
     * Default constructor creating an empty inetOrgPerson
474
     */
475
    public InetOrgPerson();
476
    
477
    // Extended organizational attributes
478
    /**
479
     * Gets the person's email address (mail)
480
     * @return the email address
481
     */
482
    public String getMail();
483
    
484
    /**
485
     * Sets the person's email address (mail)
486
     * @param mail the email address
487
     */
488
    public void setMail(String mail);
489
    
490
    /**
491
     * Gets the person's employee number
492
     * @return the employee number
493
     */
494
    public String getEmployeeNumber();
495
    
496
    /**
497
     * Sets the person's employee number
498
     * @param employeeNumber the employee number
499
     */
500
    public void setEmployeeNumber(String employeeNumber);
501
    
502
    /**
503
     * Gets the person's display name
504
     * @return the display name
505
     */
506
    public String getDisplayName();
507
    
508
    /**
509
     * Sets the person's display name
510
     * @param displayName the display name
511
     */
512
    public void setDisplayName(String displayName);
513
    
514
    /**
515
     * Gets the person's department number
516
     * @return the department number
517
     */
518
    public String getDepartmentNumber();
519
    
520
    /**
521
     * Sets the person's department number
522
     * @param departmentNumber the department number
523
     */
524
    public void setDepartmentNumber(String departmentNumber);
525
    
526
    /**
527
     * Gets the person's car license
528
     * @return the car license
529
     */
530
    public String getCarLicense();
531
    
532
    /**
533
     * Sets the person's car license
534
     * @param carLicense the car license
535
     */
536
    public void setCarLicense(String carLicense);
537
    
538
    /**
539
     * Gets the person's home phone number
540
     * @return the home phone number
541
     */
542
    public String getHomePhone();
543
    
544
    /**
545
     * Sets the person's home phone number
546
     * @param homePhone the home phone number
547
     */
548
    public void setHomePhone(String homePhone);
549
}
550
```
551

552
## Search Interfaces
553

554
### LdapUserSearch
555

556
Strategy interface for LDAP user search implementations.
557

558
```java { .api }
559
/**
560
 * Strategy interface for locating users in LDAP directories
561
 */
562
public interface LdapUserSearch {
563
    /**
564
     * Searches for a user in the LDAP directory
565
     * @param username the username to search for
566
     * @return DirContextOperations representing the found user
567
     * @throws UsernameNotFoundException if the user cannot be found
568
     */
569
    DirContextOperations searchForUser(String username);
570
}
571
```
572

573
### UserDetailsContextMapper
574

575
Strategy interface for mapping between LDAP contexts and UserDetails objects.
576

577
```java { .api }
578
/**
579
 * Strategy interface for mapping between LDAP directory contexts and Spring Security UserDetails
580
 */
581
public interface UserDetailsContextMapper {
582
    /**
583
     * Maps user information from LDAP context to UserDetails object
584
     * @param ctx the LDAP directory context operations containing user data
585
     * @param username the username being mapped
586
     * @param authorities the collection of granted authorities for the user
587
     * @return UserDetails object containing mapped user information
588
     */
589
    UserDetails mapUserFromContext(DirContextOperations ctx, String username, 
590
        Collection<? extends GrantedAuthority> authorities);
591
    
592
    /**
593
     * Maps UserDetails information back to LDAP context for directory updates
594
     * @param user the UserDetails object to map
595
     * @param ctx the directory context adapter to populate
596
     */
597
    void mapUserToContext(UserDetails user, DirContextAdapter ctx);
598
}
599
```
600

601
## Configuration Examples
602

603
### Complete User Details Service Setup
604

605
```java
606
@Configuration
607
public class LdapUserDetailsConfig {
608
    
609
    @Bean
610
    public LdapUserSearch userSearch() {
611
        FilterBasedLdapUserSearch search = new FilterBasedLdapUserSearch(
612
            "ou=people", "uid={0}", contextSource());
613
        search.setSearchSubtree(true);
614
        search.setDerefLinkFlag(false);
615
        return search;
616
    }
617
    
618
    @Bean
619
    public LdapUserDetailsService userDetailsService() {
620
        LdapUserDetailsService service = new LdapUserDetailsService(userSearch());
621
        
622
        // Custom mapper for additional attributes
623
        LdapUserDetailsMapper mapper = new LdapUserDetailsMapper();
624
        mapper.setPasswordAttributeName("userPassword");
625
        mapper.setRolePrefix("ROLE_");
626
        service.setUserDetailsMapper(mapper);
627
        
628
        return service;
629
    }
630
}
631
```
632

633
### Custom UserDetailsContextMapper
634

635
```java
636
@Component
637
public class CustomLdapUserDetailsMapper implements UserDetailsContextMapper {
638
    
639
    @Override
640
    public UserDetails mapUserFromContext(DirContextOperations ctx, String username, 
641
            Collection<? extends GrantedAuthority> authorities) {
642
        
643
        // Create InetOrgPerson with additional attributes
644
        InetOrgPerson person = new InetOrgPerson();
645
        person.setDn(ctx.getDn().toString());
646
        person.setCn(ctx.getStringAttribute("cn"));
647
        person.setSn(ctx.getStringAttribute("sn"));
648
        person.setMail(ctx.getStringAttribute("mail"));
649
        person.setEmployeeNumber(ctx.getStringAttribute("employeeNumber"));
650
        
651
        // Set Spring Security attributes
652
        person.setUsername(username);
653
        person.setAuthorities(authorities);
654
        person.setEnabled(true);
655
        person.setAccountNonExpired(true);
656
        person.setAccountNonLocked(true);
657
        person.setCredentialsNonExpired(true);
658
        
659
        return person;
660
    }
661
    
662
    @Override
663
    public void mapUserToContext(UserDetails user, DirContextAdapter ctx) {
664
        if (user instanceof InetOrgPerson) {
665
            InetOrgPerson person = (InetOrgPerson) user;
666
            ctx.setAttributeValue("cn", person.getCn());
667
            ctx.setAttributeValue("sn", person.getSn());
668
            ctx.setAttributeValue("mail", person.getMail());
669
        }
670
    }
671
}
672
```