{"record":{"id":"1cd32198b2ae5015","repo":"spring-projects/spring-security","slug":"connection-to-ldap-server-failed","errorCode":null,"errorMessage":"Connection to LDAP server failed.","messagePattern":"Connection to LDAP server failed\\.","errorType":"exception","errorClass":"InternalAuthenticationServiceException","httpStatus":null,"severity":"critical","filePath":"ldap/src/main/java/org/springframework/security/ldap/authentication/ad/ActiveDirectoryLdapAuthenticationProvider.java","lineNumber":328,"sourceCode":"\t\tSingleContextSource contextSource = new SingleContextSource(context);\n\t\tLdapClient ldapClient = LdapClient.builder()\n\t\t\t.contextSource(contextSource)\n\t\t\t.defaultSearchControls(() -> searchControls)\n\t\t\t.ignorePartialResultException(true)\n\t\t\t.build();\n\t\ttry {\n\t\t\tLdapQuery query = LdapQueryBuilder.query()\n\t\t\t\t.base(searchRoot)\n\t\t\t\t.searchScope(SearchScope.SUBTREE)\n\t\t\t\t.filter(this.searchFilter, bindPrincipal, username);\n\t\t\tDirContextOperations result = ldapClient.search().query(query).toEntry();\n\t\t\tif (result == null) {\n\t\t\t\tthrow new IncorrectResultSizeDataAccessException(1, 0);\n\t\t\t}\n\t\t\treturn result;\n\t\t}\n\t\tcatch (CommunicationException ex) {\n\t\t\tthrow badLdapConnection(ex);\n\t\t}\n\t\tcatch (IncorrectResultSizeDataAccessException ex) {\n\t\t\t// Search should never return multiple results if properly configured -\n\t\t\tif (ex.getActualSize() != 0) {\n\t\t\t\tthrow ex;\n\t\t\t}\n\t\t\t// If we found no results, then the username/password did not match\n\t\t\tUsernameNotFoundException userNameNotFoundException = UsernameNotFoundException.fromUsername(username, ex);\n\t\t\tthrow badCredentials(userNameNotFoundException);\n\t\t}\n\t\tcatch (org.springframework.ldap.NamingException ex) {\n\t\t\tif (ex.getCause() instanceof NamingException original) {\n\t\t\t\tthrow original;\n\t\t\t}\n\t\t\tthrow badCredentials(ex);\n\t\t}\n\t}\n","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/ldap/src/main/java/org/springframework/security/ldap/authentication/ad/ActiveDirectoryLdapAuthenticationProvider.java#L310-L346","documentation":"ActiveDirectoryLdapAuthenticationProvider.searchForUser translates a Spring LDAP CommunicationException into 'Connection to LDAP server failed.' via badLdapConnection. It means the provider could not establish or maintain a network connection to the Active Directory domain controller while executing the user search, so authentication could not proceed. This is an infrastructure/connectivity failure, not a credentials problem.","triggerScenarios":"Calling authenticate(username, password) on ActiveDirectoryLdapAuthenticationProvider when the underlying LDAP search throws org.springframework.ldap.CommunicationException — e.g. the AD server is unreachable, DNS for the domain fails, the connection was dropped mid-search, or the port is blocked.","commonSituations":"Wrong or unresolvable AD domain/URL configuration; firewall or security group blocking port 389/636; domain controller down or TLS (ldaps://) handshake failing; DNS issues in containers/K8s; missing Java trust store entries for the LDAPS certificate.","solutions":["Verify network reachability of the domain controller: run `nc -zv ad.example.com 636` (or 389) from the application host.","Check the configured domain/rootDn: new ActiveDirectoryLdapAuthenticationProvider(domain, url) — confirm the domain resolves via DNS and the URL uses the correct scheme (ldaps:// for TLS).","If using ldaps://, import the AD certificate into the JVM trust store: keytool -importcert -alias ad -file ad.cer -keystore $JAVA_HOME/lib/security/cacerts.","Ensure the ActiveDirectoryLdapAuthenticationProvider bean is a singleton shared across requests; creating it per-request can exhaust connections.","Review the full CommunicationException stack trace for nested causes (UnknownHostException, SSLHandshakeException, SocketTimeoutException) and fix the specific root cause."],"exampleFix":"// before\nActiveDirectoryLdapAuthenticationProvider provider =\n    new ActiveDirectoryLdapAuthenticationProvider(\"corp.example.com\", \"ldap://wrong-host:389\");\n// after\nActiveDirectoryLdapAuthenticationProvider provider =\n    new ActiveDirectoryLdapAuthenticationProvider(\"corp.example.com\", \"ldaps://dc1.corp.example.com:636\");","handlingStrategy":"try-catch","validationCode":"boolean ldapReachable;\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(\"dc1.corp.example.com\", 636), 3000);\n    ldapReachable = true;\n} catch (IOException e) {\n    ldapReachable = false;\n}","typeGuard":null,"tryCatchPattern":"try {\n    authenticationManager.authenticate(token);\n} catch (CommunicationException | BadCredentialsException e) {\n    if (e.getCause() instanceof ConnectException || e instanceof CommunicationException) {\n        // infrastructure problem: alert ops / retry with backoff\n    } else {\n        // real bad credentials: return 401\n    }\n}","preventionTips":["Add a startup health check that binds to the AD server before accepting traffic.","Use ldaps:// with certificates imported into the JVM trust store.","Reuse a singleton provider bean; configure connection pooling in the embedded context source.","Monitor DNS resolution and DC availability from the app subnet."],"tags":["ldap","active-directory","connection","authentication","network"],"backgroundTag":"connection-refused","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}