SonarSource/sonarqube · error · IllegalArgumentException

When using SASL - property ldap.bindDn is required

Error message

When using SASL - property ldap.bindDn is required

What it means

testConnection in LdapContextFactory validates that SASL authentication can proceed: SASL requires a bind DN (username). If the username is blank while the authentication scheme is SASL (CRAM-MD5/DIGEST-MD5/GSS-API), it throws IllegalArgumentException with this message before attempting any connection.

Source

Thrown at server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapContextFactory.java:223

  public boolean isSasl() {
    return AUTH_METHOD_DIGEST_MD5.equals(authentication) ||
      AUTH_METHOD_CRAM_MD5.equals(authentication) ||
      AUTH_METHOD_GSSAPI.equals(authentication);
  }

  public boolean isGssapi() {
    return AUTH_METHOD_GSSAPI.equals(authentication);
  }

  /**
   * Tests connection.
   *
   * @throws LdapException if unable to open connection
   */
  public void testConnection() {
    if (StringUtils.isBlank(username) && isSasl()) {
      throw new IllegalArgumentException("When using SASL - property ldap.bindDn is required");
    }
    try {
      createBindContext();
      LOG.info("Test LDAP connection on {}: OK", providerUrl);
    } catch (NamingException e) {
      LOG.info("Test LDAP connection: FAIL");
      throw new LdapException("Unable to open LDAP connection", e);
    }
  }

  public String getProviderUrl() {
    return providerUrl;
  }

  public String getReferral() {
    return referral;
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Set sonar.authenticator.ldap.bindDn (and bindPassword) to the principal used for SASL binding.
2. If you intended simple authentication, set sonar.authenticator.ldap.authentication=simple.
3. For Kerberos/GSS-API, set bindDn to the Kerberos principal name.

Example fix

// before: SASL without bindDn
sonar.authenticator.ldap.authentication: DIGEST-MD5
// after: provide the bind principal
sonar.authenticator.ldap.authentication: DIGEST-MD5
sonar.authenticator.ldap.bindDn: cn=sonar,ou=service,dc=example,dc=org

String auth = config.get("sonar.authenticator.ldap.authentication").orElse("simple");
boolean sasl = auth.equalsIgnoreCase("CRAM-MD5") || auth.equalsIgnoreCase("DIGEST-MD5") || auth.equalsIgnoreCase("GSS-API");
if (sasl && config.get("sonar.authenticator.ldap.bindDn").map(String::isBlank).orElse(true)) {
  throw new IllegalStateException("SASL authentication requires sonar.authenticator.ldap.bindDn");
}

When it happens

Trigger: Calling testConnection when sonar.authenticator.ldap.authentication is sasl (or auto-detected as SASL) but sonar.authenticator.ldap.bindDn is unset or blank.

Common situations: Switching from simple to SASL authentication and forgetting bindDn; relying on GSS-API/Kerberos without setting the principal as bindDn; copying a simple-auth config template that has bindDn commented out.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Callback not supported
• Unable to retrieve groups for user %s in server with key <%s
• Unable to retrieve details for user %s: No user or group map
• Unable to retrieve details for user %s and server key %s: No
• Unable to retrieve details for user <username> in <serverKey

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/c74cbb95dfe6b900. Report an issue: GitHub.