Add LDAP Lookup-Bind mode (#11318)

This change allows the MinIO server to be configured with a special (read-only) LDAP account to perform user DN lookups. The following configuration parameters are added (along with corresponding environment variables) to LDAP identity configuration (under `identity_ldap`): - lookup_bind_dn / MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN - lookup_bind_password / MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD - user_dn_search_base_dn / MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN - user_dn_search_filter / MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER This lookup-bind account is a service account that is used to lookup the user's DN from their username provided in the STS API. When configured, searching for the user DN is enabled and configuration of the base DN and filter for search is required. In this "lookup-bind" mode, the username format is not checked and must not be specified. This feature is to support Active Directory setups where the DN cannot be simply derived from the username. When the lookup-bind is not configured, the old behavior is enabled: the minio server performs LDAP lookups as the LDAP user making the STS API request and the username format is checked and configuring it is required.
2025-11-09 21:49:46 -05:00 · 2021-01-25 14:26:10 -08:00
parent 7e266293e6
commit 5f51ef0b40
3 changed files with 281 additions and 122 deletions
--- a/cmd/config/identity/ldap/config.go
+++ b/cmd/config/identity/ldap/config.go
@@ -32,6 +32,8 @@ import (

 const (
 	defaultLDAPExpiry = time.Hour * 1
+
+	dnDelimiter = ";"
 )

 // Config contains AD/LDAP server connectivity information.
@@ -48,31 +50,43 @@ type Config struct {
 	UsernameFormat  string   `json:"usernameFormat"`
 	UsernameFormats []string `json:"-"`

+	// User DN search parameters
+	UserDNSearchBaseDN string `json:"userDNSearchBaseDN"`
+	UserDNSearchFilter string `json:"userDNSearchFilter"`
+
+	// Group search parameters
 	GroupSearchBaseDistName  string   `json:"groupSearchBaseDN"`
 	GroupSearchBaseDistNames []string `json:"-"`
 	GroupSearchFilter        string   `json:"groupSearchFilter"`
 	GroupNameAttribute       string   `json:"groupNameAttribute"`

+	// Lookup bind LDAP service account
+	LookupBindDN       string `json:"lookupBindDN"`
+	LookupBindPassword string `json:"lookupBindPassword"`
+
 	stsExpiryDuration time.Duration // contains converted value
 	tlsSkipVerify     bool          // allows skipping TLS verification
-	serverInsecure    bool          // allows plain text connection to LDAP Server
-	serverStartTLS    bool          // allows plain text connection to LDAP Server
+	serverInsecure    bool          // allows plain text connection to LDAP server
+	serverStartTLS    bool          // allows using StartTLS connection to LDAP server
+	isUsingLookupBind bool
 	rootCAs           *x509.CertPool
 }

 // LDAP keys and envs.
 const (
-	ServerAddr           = "server_addr"
-	STSExpiry            = "sts_expiry"
-	UsernameFormat       = "username_format"
-	UsernameSearchFilter = "username_search_filter"
-	UsernameSearchBaseDN = "username_search_base_dn"
-	GroupSearchFilter    = "group_search_filter"
-	GroupNameAttribute   = "group_name_attribute"
-	GroupSearchBaseDN    = "group_search_base_dn"
-	TLSSkipVerify        = "tls_skip_verify"
-	ServerInsecure       = "server_insecure"
-	ServerStartTLS       = "server_starttls"
+	ServerAddr         = "server_addr"
+	STSExpiry          = "sts_expiry"
+	LookupBindDN       = "lookup_bind_dn"
+	LookupBindPassword = "lookup_bind_password"
+	UserDNSearchBaseDN = "user_dn_search_base_dn"
+	UserDNSearchFilter = "user_dn_search_filter"
+	UsernameFormat     = "username_format"
+	GroupSearchFilter  = "group_search_filter"
+	GroupNameAttribute = "group_name_attribute"
+	GroupSearchBaseDN  = "group_search_base_dn"
+	TLSSkipVerify      = "tls_skip_verify"
+	ServerInsecure     = "server_insecure"
+	ServerStartTLS     = "server_starttls"

 	EnvServerAddr         = "MINIO_IDENTITY_LDAP_SERVER_ADDR"
 	EnvSTSExpiry          = "MINIO_IDENTITY_LDAP_STS_EXPIRY"
@@ -80,9 +94,13 @@ const (
 	EnvServerInsecure     = "MINIO_IDENTITY_LDAP_SERVER_INSECURE"
 	EnvServerStartTLS     = "MINIO_IDENTITY_LDAP_SERVER_STARTTLS"
 	EnvUsernameFormat     = "MINIO_IDENTITY_LDAP_USERNAME_FORMAT"
+	EnvUserDNSearchBaseDN = "MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN"
+	EnvUserDNSearchFilter = "MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER"
 	EnvGroupSearchFilter  = "MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER"
 	EnvGroupNameAttribute = "MINIO_IDENTITY_LDAP_GROUP_NAME_ATTRIBUTE"
 	EnvGroupSearchBaseDN  = "MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN"
+	EnvLookupBindDN       = "MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN"
+	EnvLookupBindPassword = "MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD"
 )

 // DefaultKVS - default config for LDAP config
@@ -97,11 +115,11 @@ var (
 			Value: "",
 		},
 		config.KV{
-			Key:   UsernameSearchFilter,
+			Key:   UserDNSearchBaseDN,
 			Value: "",
 		},
 		config.KV{
-			Key:   UsernameSearchBaseDN,
+			Key:   UserDNSearchFilter,
 			Value: "",
 		},
 		config.KV{
@@ -132,17 +150,26 @@ var (
 			Key:   ServerStartTLS,
 			Value: config.EnableOff,
 		},
+		config.KV{
+			Key:   LookupBindDN,
+			Value: "",
+		},
+		config.KV{
+			Key:   LookupBindPassword,
+			Value: "",
+		},
 	}
 )

-const (
-	dnDelimiter = ";"
-)
-
 func getGroups(conn *ldap.Conn, sreq *ldap.SearchRequest) ([]string, error) {
 	var groups []string
 	sres, err := conn.Search(sreq)
 	if err != nil {
+		// Check if there is no matching result and return empty slice.
+		// Ref: https://ldap.com/ldap-result-code-reference/
+		if ldap.IsErrorWithCode(err, 32) {
+			return nil, nil
+		}
 		return nil, err
 	}
 	for _, entry := range sres.Entries {
@@ -153,15 +180,19 @@ func getGroups(conn *ldap.Conn, sreq *ldap.SearchRequest) ([]string, error) {
 	return groups, nil
 }

-// bind - Iterates over all given username formats and expects that only one
-// will succeed if the credentials are valid. The succeeding bindDN is returned
-// or an error.
+func (l *Config) lookupBind(conn *ldap.Conn) error {
+	return conn.Bind(l.LookupBindDN, l.LookupBindPassword)
+}
+
+// usernameFormatsBind - Iterates over all given username formats and expects
+// that only one will succeed if the credentials are valid. The succeeding
+// bindDN is returned or an error.
 //
 // In the rare case that multiple username formats succeed, implying that two
 // (or more) distinct users in the LDAP directory have the same username and
 // password, we return an error as we cannot identify the account intended by
 // the user.
-func (l *Config) bind(conn *ldap.Conn, username, password string) (string, error) {
+func (l *Config) usernameFormatsBind(conn *ldap.Conn, username, password string) (string, error) {
 	var bindDistNames []string
 	var errs = make([]error, len(l.UsernameFormats))
 	var successCount = 0
@@ -175,13 +206,13 @@ func (l *Config) bind(conn *ldap.Conn, username, password string) (string, error
 		}
 	}
 	if successCount == 0 {
-		var errStrings []string = []string{"All username formats failed with: "}
+		var errStrings []string
 		for _, err := range errs {
 			if err != nil {
 				errStrings = append(errStrings, err.Error())
 			}
 		}
-		outErr := strings.Join(errStrings, "; ")
+		outErr := fmt.Sprintf("All username formats failed with: %s", strings.Join(errStrings, "; "))
 		return "", errors.New(outErr)
 	}
 	if successCount > 1 {
@@ -192,6 +223,32 @@ func (l *Config) bind(conn *ldap.Conn, username, password string) (string, error
 	return bindDistNames[0], nil
 }

+// lookupUserDN searches for the DN of the user given their username. conn is
+// assumed to be using the lookup bind service account. It is required that the
+// search result in at most one result.
+func (l *Config) lookupUserDN(conn *ldap.Conn, username string) (string, error) {
+	filter := strings.Replace(l.UserDNSearchFilter, "%s", ldap.EscapeFilter(username), -1)
+	searchRequest := ldap.NewSearchRequest(
+		l.UserDNSearchBaseDN,
+		ldap.ScopeWholeSubtree, ldap.NeverDerefAliases, 0, 0, false,
+		filter,
+		[]string{}, // only need DN, so no pass no attributes here
+		nil,
+	)
+
+	searchResult, err := conn.Search(searchRequest)
+	if err != nil {
+		return "", err
+	}
+	if len(searchResult.Entries) == 0 {
+		return "", fmt.Errorf("User DN for %s not found", username)
+	}
+	if len(searchResult.Entries) != 1 {
+		return "", fmt.Errorf("Multiple DNs for %s found - please fix the search filter", username)
+	}
+	return searchResult.Entries[0].DN, nil
+}
+
 // Bind - binds to ldap, searches LDAP and returns the distinguished name of the
 // user and the list of groups.
 func (l *Config) Bind(username, password string) (string, []string, error) {
@@ -201,11 +258,42 @@ func (l *Config) Bind(username, password string) (string, []string, error) {
 	}
 	defer conn.Close()

-	bindDN, err := l.bind(conn, username, password)
-	if err != nil {
-		return "", nil, err
+	var bindDN string
+	if l.isUsingLookupBind {
+		// Bind to the lookup user account
+		if err = l.lookupBind(conn); err != nil {
+			return "", nil, err
+		}
+
+		// Lookup user DN
+		bindDN, err = l.lookupUserDN(conn, username)
+		if err != nil {
+			errRet := fmt.Errorf("Unable to find user DN: %s", err)
+			return "", nil, errRet
+		}
+
+		// Authenticate the user credentials.
+		err = conn.Bind(bindDN, password)
+		if err != nil {
+			errRet := fmt.Errorf("LDAP auth failed for DN %s: %v", bindDN, err)
+			return "", nil, errRet
+		}
+	} else {
+		// Verify login credentials by checking the username formats.
+		bindDN, err = l.usernameFormatsBind(conn, username, password)
+		if err != nil {
+			return "", nil, err
+		}
+
+		// Bind to the successful bindDN again.
+		err = conn.Bind(bindDN, password)
+		if err != nil {
+			errRet := fmt.Errorf("LDAP conn failed though auth for DN %s succeeded: %v", bindDN, err)
+			return "", nil, errRet
+		}
 	}

+	// User groups lookup.
 	var groups []string
 	if l.GroupSearchFilter != "" {
 		for _, groupSearchBase := range l.GroupSearchBaseDistNames {
@@ -221,7 +309,8 @@ func (l *Config) Bind(username, password string) (string, []string, error) {
 			var newGroups []string
 			newGroups, err = getGroups(conn, searchRequest)
 			if err != nil {
-				return "", nil, err
+				errRet := fmt.Errorf("Error finding groups of %s: %v", bindDN, err)
+				return "", nil, errRet
 			}

 			groups = append(groups, newGroups...)
@@ -298,6 +387,8 @@ func Lookup(kvs config.KVS, rootCAs *x509.CertPool) (l Config, err error) {
 		l.STSExpiryDuration = v
 		l.stsExpiryDuration = expDur
 	}
+
+	// LDAP connection configuration
 	if v := env.Get(EnvServerInsecure, kvs.Get(ServerInsecure)); v != "" {
 		l.serverInsecure, err = config.ParseBool(v)
 		if err != nil {
@@ -316,15 +407,45 @@ func Lookup(kvs config.KVS, rootCAs *x509.CertPool) (l Config, err error) {
 			return l, err
 		}
 	}
+
+	// Lookup bind user configuration
+	lookupBindDN := env.Get(EnvLookupBindDN, kvs.Get(LookupBindDN))
+	lookupBindPassword := env.Get(EnvLookupBindPassword, kvs.Get(LookupBindPassword))
+	if lookupBindDN != "" && lookupBindPassword != "" {
+		l.LookupBindDN = lookupBindDN
+		l.LookupBindPassword = lookupBindPassword
+		l.isUsingLookupBind = true
+
+		// User DN search configuration
+		userDNSearchBaseDN := env.Get(EnvUserDNSearchBaseDN, kvs.Get(UserDNSearchBaseDN))
+		userDNSearchFilter := env.Get(EnvUserDNSearchFilter, kvs.Get(EnvUserDNSearchFilter))
+		if userDNSearchFilter == "" || userDNSearchBaseDN == "" {
+			return l, errors.New("In lookup bind mode, userDN search base DN and userDN search filter are both required")
+		}
+		l.UserDNSearchBaseDN = userDNSearchBaseDN
+		l.UserDNSearchFilter = userDNSearchFilter
+	}
+
+	// Username format configuration.
 	if v := env.Get(EnvUsernameFormat, kvs.Get(UsernameFormat)); v != "" {
 		if !strings.Contains(v, "%s") {
 			return l, errors.New("LDAP username format doesn't have '%s' substitution")
 		}
 		l.UsernameFormats = strings.Split(v, dnDelimiter)
-	} else {
-		return l, fmt.Errorf("'%s' cannot be empty and must have a value", UsernameFormat)
 	}

+	// Either lookup bind mode or username format is supported, but not
+	// both.
+	if l.isUsingLookupBind && len(l.UsernameFormats) > 0 {
+		return l, errors.New("Lookup Bind mode and Username Format mode are not supported at the same time")
+	}
+
+	// At least one of bind mode or username format must be used.
+	if !l.isUsingLookupBind && len(l.UsernameFormats) == 0 {
+		return l, errors.New("Either Lookup Bind mode or Username Format mode is required.")
+	}
+
+	// Group search params configuration
 	grpSearchFilter := env.Get(EnvGroupSearchFilter, kvs.Get(GroupSearchFilter))
 	grpSearchNameAttr := env.Get(EnvGroupNameAttribute, kvs.Get(GroupNameAttribute))
 	grpSearchBaseDN := env.Get(EnvGroupSearchBaseDN, kvs.Get(GroupSearchBaseDN))
@@ -341,6 +462,7 @@ func Lookup(kvs config.KVS, rootCAs *x509.CertPool) (l Config, err error) {
 	if allSet {
 		l.GroupSearchFilter = grpSearchFilter
 		l.GroupNameAttribute = grpSearchNameAttr
+		l.GroupSearchBaseDistName = grpSearchBaseDN
 		l.GroupSearchBaseDistNames = strings.Split(l.GroupSearchBaseDistName, dnDelimiter)
 	}

--- a/cmd/config/identity/ldap/help.go
+++ b/cmd/config/identity/ldap/help.go
@@ -27,30 +27,46 @@ var (
 			Type:        "address",
 		},
 		config.HelpKV{
-			Key:         UsernameFormat,
-			Description: `";" separated list of username bind DNs e.g. "uid=%s,cn=accounts,dc=myldapserver,dc=com"`,
-			Type:        "list",
+			Key:         STSExpiry,
+			Description: `temporary credentials validity duration in s,m,h,d. Default is "1h"`,
+			Optional:    true,
+			Type:        "duration",
 		},
 		config.HelpKV{
-			Key:         UsernameSearchFilter,
-			Description: `user search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"`,
+			Key:         LookupBindDN,
+			Description: `DN for LDAP read-only service account used to perform DN and group lookups`,
+			Optional:    true,
 			Type:        "string",
 		},
+		config.HelpKV{
+			Key:         LookupBindPassword,
+			Description: `Password for LDAP read-only service account used to perform DN and group lookups`,
+			Optional:    true,
+			Type:        "string",
+		},
+		config.HelpKV{
+			Key:         UserDNSearchBaseDN,
+			Description: `Base LDAP DN to search for user DN`,
+			Optional:    true,
+			Type:        "string",
+		},
+		config.HelpKV{
+			Key:         UserDNSearchFilter,
+			Description: `Search filter to lookup user DN`,
+			Optional:    true,
+			Type:        "string",
+		},
+		config.HelpKV{
+			Key:         UsernameFormat,
+			Description: `";" separated list of username bind DNs e.g. "uid=%s,cn=accounts,dc=myldapserver,dc=com"`,
+			Optional:    true,
+			Type:        "list",
+		},
 		config.HelpKV{
 			Key:         GroupSearchFilter,
 			Description: `search filter for groups e.g. "(&(objectclass=groupOfNames)(memberUid=%s))"`,
-			Type:        "string",
-		},
-		config.HelpKV{
-			Key:         GroupSearchBaseDN,
-			Description: `";" separated list of group search base DNs e.g. "dc=myldapserver,dc=com"`,
-			Type:        "list",
-		},
-		config.HelpKV{
-			Key:         UsernameSearchBaseDN,
-			Description: `";" separated list of username search DNs`,
-			Type:        "list",
 			Optional:    true,
+			Type:        "string",
 		},
 		config.HelpKV{
 			Key:         GroupNameAttribute,
@@ -59,10 +75,10 @@ var (
 			Type:        "string",
 		},
 		config.HelpKV{
-			Key:         STSExpiry,
-			Description: `temporary credentials validity duration in s,m,h,d. Default is "1h"`,
+			Key:         GroupSearchBaseDN,
+			Description: `";" separated list of group search base DNs e.g. "dc=myldapserver,dc=com"`,
 			Optional:    true,
-			Type:        "duration",
+			Type:        "list",
 		},
 		config.HelpKV{
 			Key:         TLSSkipVerify,
@@ -76,6 +92,12 @@ var (
 			Optional:    true,
 			Type:        "on|off",
 		},
+		config.HelpKV{
+			Key:         ServerStartTLS,
+			Description: `use StartTLS connection to AD/LDAP server, defaults to "off"`,
+			Optional:    true,
+			Type:        "on|off",
+		},
 		config.HelpKV{
 			Key:         config.Comment,
 			Description: config.DefaultComment,