--- name: spring-ldap description: | Spring LDAP for LDAP/Active Directory integration and authentication. Covers LdapTemplate, @Entry mapping, LdapRepository, and Spring Security integration. USE WHEN: user mentions "LDAP", "Active Directory", "AD authentication", "LdapTemplate", "@Entry", "directory services", "enterprise authentication" DO NOT USE FOR: OAuth2/OIDC - use `spring-security` or `oauth2` skill, simple auth - use Spring Security with database allowed-tools: Read, Grep, Glob, Write, Edit --- # Spring LDAP - Quick Reference > **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `spring-ldap` for comprehensive documentation. ## Dependencies ```xml org.springframework.boot spring-boot-starter-data-ldap com.unboundid unboundid-ldapsdk test ``` ## Configuration ### application.yml ```yaml spring: ldap: urls: ldap://ldap.example.com:389 base: dc=example,dc=com username: cn=admin,dc=example,dc=com password: ${LDAP_PASSWORD} # For Active Directory # urls: ldap://ad.company.com:389 # base: dc=company,dc=com # username: CN=service_account,OU=Service Accounts,DC=company,DC=com # Embedded LDAP for development ldap: embedded: base-dn: dc=example,dc=com ldif: classpath:test-server.ldif port: 8389 ``` ## LDAP Entry Mapping ### Person Entry ```java @Entry(base = "ou=people", objectClasses = {"person", "inetOrgPerson"}) public class Person { @Id private Name dn; @Attribute(name = "uid") private String uid; @Attribute(name = "cn") private String fullName; @Attribute(name = "sn") private String lastName; @Attribute(name = "givenName") private String firstName; @Attribute(name = "mail") private String email; @Attribute(name = "telephoneNumber") private String phone; @Attribute(name = "memberOf") private List groups; @DnAttribute(value = "uid", index = 0) private String username; } ``` ### Group Entry ```java @Entry(base = "ou=groups", objectClasses = {"groupOfNames"}) public class Group { @Id private Name dn; @Attribute(name = "cn") private String name; @Attribute(name = "description") private String description; @Attribute(name = "member") private Set members; } ``` ## Repository Pattern ```java public interface PersonRepository extends LdapRepository { Person findByUid(String uid); List findByLastName(String lastName); List findByEmailContaining(String emailPart); @Query("(&(objectClass=person)(|(cn=*{0}*)(mail=*{0}*)))") List searchByNameOrEmail(String query); } public interface GroupRepository extends LdapRepository { Group findByName(String name); @Query("(&(objectClass=groupOfNames)(member={0}))") List findByMember(Name memberDn); } ``` ## LdapTemplate Operations ```java @Service @RequiredArgsConstructor public class LdapService { private final LdapTemplate ldapTemplate; // Search public List findAllPeople() { return ldapTemplate.findAll(Person.class); } public Person findByDn(String dn) { return ldapTemplate.findByDn(LdapUtils.newLdapName(dn), Person.class); } // Search with filter public List searchPeople(String query) { LdapQuery ldapQuery = LdapQueryBuilder.query() .base("ou=people") .where("objectClass").is("person") .and("cn").like("*" + query + "*"); return ldapTemplate.find(ldapQuery, Person.class); } // Create public void createPerson(Person person) { ldapTemplate.create(person); } // Update public void updatePerson(Person person) { ldapTemplate.update(person); } // Delete public void deletePerson(Person person) { ldapTemplate.delete(person); } // Bind (authenticate) public boolean authenticate(String username, String password) { LdapQuery query = LdapQueryBuilder.query() .where("uid").is(username); return ldapTemplate.authenticate(query, password); } } ``` ## Active Directory Integration ```java @Configuration public class ActiveDirectoryConfig { @Bean public LdapContextSource contextSource() { LdapContextSource contextSource = new LdapContextSource(); contextSource.setUrl("ldap://ad.company.com:389"); contextSource.setBase("dc=company,dc=com"); contextSource.setUserDn("CN=service_account,OU=Service Accounts,DC=company,DC=com"); contextSource.setPassword(adPassword); contextSource.setReferral("follow"); // AD specific settings Map env = new HashMap<>(); env.put("java.naming.ldap.attributes.binary", "objectGUID"); contextSource.setBaseEnvironmentProperties(env); return contextSource; } @Bean public LdapTemplate ldapTemplate(LdapContextSource contextSource) { return new LdapTemplate(contextSource); } } ``` ### AD User Search ```java public List searchAdUsers(String query) { LdapQuery ldapQuery = LdapQueryBuilder.query() .base("OU=Users,DC=company,DC=com") .where("objectClass").is("user") .and("objectCategory").is("person") .and(LdapQueryBuilder.query() .where("sAMAccountName").like("*" + query + "*") .or("displayName").like("*" + query + "*") .or("mail").like("*" + query + "*")); return ldapTemplate.search(ldapQuery, new AdUserAttributesMapper()); } ``` ## Spring Security Integration ```java @Configuration @EnableWebSecurity public class LdapSecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth -> auth .requestMatchers("/public/**").permitAll() .anyRequest().authenticated() ) .formLogin(Customizer.withDefaults()) .ldapAuthentication(ldap -> ldap .userDnPatterns("uid={0},ou=people") .groupSearchBase("ou=groups") .contextSource(contextSource()) .passwordCompare(password -> password .passwordEncoder(new BCryptPasswordEncoder()) .passwordAttribute("userPassword") ) ); return http.build(); } @Bean public LdapContextSource contextSource() { return new LdapContextSource() {{ setUrl("ldap://localhost:8389"); setBase("dc=example,dc=com"); }}; } } ``` ### Active Directory Authentication ```java @Bean public ActiveDirectoryLdapAuthenticationProvider adAuthProvider() { ActiveDirectoryLdapAuthenticationProvider provider = new ActiveDirectoryLdapAuthenticationProvider( "company.com", "ldap://ad.company.com:389", "dc=company,dc=com" ); provider.setConvertSubErrorCodesToExceptions(true); provider.setUseAuthenticationRequestCredentials(true); provider.setSearchFilter("(&(objectClass=user)(sAMAccountName={1}))"); return provider; } ``` ## Connection Pooling ```java @Bean public LdapContextSource contextSource() { LdapContextSource contextSource = new LdapContextSource(); contextSource.setUrl("ldap://ldap.example.com:389"); contextSource.setBase("dc=example,dc=com"); contextSource.setUserDn("cn=admin,dc=example,dc=com"); contextSource.setPassword(ldapPassword); contextSource.setPooled(true); return contextSource; } @Bean public PoolingContextSource poolingContextSource(LdapContextSource contextSource) { PoolingContextSource poolingContextSource = new PoolingContextSource(); poolingContextSource.setContextSource(contextSource); poolingContextSource.setDirContextValidator(new DefaultDirContextValidator()); poolingContextSource.setTestOnBorrow(true); poolingContextSource.setTestWhileIdle(true); return poolingContextSource; } ``` ## Testing with Embedded LDAP ### test-server.ldif ```ldif dn: dc=example,dc=com objectClass: top objectClass: domain dc: example dn: ou=people,dc=example,dc=com objectClass: organizationalUnit ou: people dn: ou=groups,dc=example,dc=com objectClass: organizationalUnit ou: groups dn: uid=john,ou=people,dc=example,dc=com objectClass: person objectClass: inetOrgPerson uid: john cn: John Doe sn: Doe givenName: John mail: john@example.com userPassword: password123 dn: cn=developers,ou=groups,dc=example,dc=com objectClass: groupOfNames cn: developers member: uid=john,ou=people,dc=example,dc=com ``` ### Test Class ```java @SpringBootTest @TestPropertySource(properties = { "spring.ldap.embedded.base-dn=dc=example,dc=com", "spring.ldap.embedded.ldif=classpath:test-server.ldif", "spring.ldap.embedded.port=8389" }) class LdapServiceTest { @Autowired private PersonRepository personRepository; @Test void shouldFindPerson() { Person person = personRepository.findByUid("john"); assertThat(person.getFullName()).isEqualTo("John Doe"); } } ``` ## Best Practices | Do | Don't | |----|-------| | Use connection pooling | Create new connections per request | | Use paged results for large queries | Fetch all entries at once | | Encrypt with LDAPS (port 636) | Use plain LDAP in production | | Use service accounts | Use user credentials for app | | Handle referrals appropriately | Ignore AD referrals | ## Production Checklist - [ ] LDAPS (TLS) enabled - [ ] Service account with minimal permissions - [ ] Connection pooling configured - [ ] Paged results for large queries - [ ] Proper error handling - [ ] Timeout configuration - [ ] Failover for HA - [ ] Credentials secured (Vault/secrets) - [ ] Audit logging enabled - [ ] Search filters sanitized (injection prevention) ## When NOT to Use This Skill - **OAuth2/OIDC** - Use `spring-security` or `oauth2` skills - **Simple authentication** - Use Spring Security with database - **Cloud-native apps** - Consider Keycloak or Auth0 - **Small applications** - LDAP may be overkill ## Anti-Patterns | Anti-Pattern | Problem | Solution | |--------------|---------|----------| | New connection per request | Performance issues | Use connection pooling | | Plain LDAP in production | Credentials exposed | Use LDAPS (port 636) | | User credentials for app | Security risk | Use service account | | Fetching all entries | Memory/timeout | Use paged results | | Unsanitized filters | LDAP injection | Escape filter parameters | ## Quick Troubleshooting | Problem | Diagnostic | Fix | |---------|------------|-----| | Connection refused | Check URL/port | Verify LDAP server accessibility | | Authentication failed | Check bind DN | Verify service account credentials | | Entries not found | Check base DN | Verify search base configuration | | Slow queries | Check filter | Add indexes, limit scope | | SSL handshake failed | Check certificates | Import CA cert to truststore | ## Reference Documentation - [Spring LDAP Reference](https://docs.spring.io/spring-ldap/reference/)