Advanced LDAP settings

Our LDAP configuration object is a list of configurations of LDAP servers. Each server configuration can hold several attributes. Each of them can be left empty, left out from configuration string or can be set to null. In this case, they will be used by their default values. One server holds the following possible settings:

Attribute name

Attribute type

Default value

Example

Explanation

serverUrl
String
ldap://localhost:389
"ldaps://ldap.mycompany.com:621" or 
"ldap://ldap2.cmp.com/dc=cmp,dc=com"

The URL where the system can reach the LDAP server.

userDNPatterns
List of Strings

[ ]

[ "uid={0},dc=mycompany,dc=com", 
"uid={0},ou=internal,dc=mycompany,dc=com" ]

These patterns will be used to find the User by its distinguished name.

The part between the curly brackets will be replaced by the username.

If this setting is left empty, then user distinguished name won't be used in the user authentication.

groupSearchBase
String
""
"ou=InternalGroups,dc=mycompany,dc=com"

This element of the LDAP tree will be used as the root element during user group search. In case it is left empty, the root of the LDAP tree will be used.

groupSearchFilter
String
""
"ou=ExternalGroups"

Only groups that match this criteria will be resolved after authentication.

userSearchBase
String
""
"ou=Users,dc=mycompany,dc=com"

This element of the LDAP tree will be used as the root element during user search. In case it is left empty, the root of the LDAP tree will be used. If you use userSearchFilter, than you must provide userSearchBase as well.

userSearchFilter
String
""
"sAMAccountName={0}"

In case the users are not found by their distinguished name, user search will happen. The part with the curly brackets will be replaced with the username that used to log in. In case of Active Directory, usually sAMAccountName is required to log in. You can not use userSearchFilter without userSearchBase.

managerDN
String
""
"dn=admin,dc=mycompany,dc=com" or 
"[email protected]"

This is the name of the manager user. This name will be used to bind to the LDAP server. The second format can be used to log in to Active Directory through LDAP.

managerPassword
String
""
"s3cr3tp455w0rd"

This is the password of the manager user.

root
String
""
"dc=mycompany,dc=com"

In case the serverURL does not contain the root of the LDAP search, then it can be set here. If it is left empty, then root from URL will be used. Active Directory usually requests root to be set separately for binding.

Example:

LDAP config
{
"servers" : [{
"serverUrl" : "ldap://ldap1.mycompany.com/dc=mycompany,dc=com",
"userDNPatterns" : ["uid={0},cn=users,dc=mycompany,dc=com", "uid={0},cn=external,dc=mycompany,dc=com"],
"groupSearchBase" : "",
"groupSearchFiler" : "",
"userSearchBase" : "",
"userSearchFilter" : "",
"managerDN" : "uid=admin,cn=sysusers,dc=mycompany,dc=com",
"managerPassword" : "PASSWORD!",
"root" : ""
}, {
"serverUrl" : "ldaps://ad.mycompany.com/dc=cmp,dc=com",
"userDNPatterns" : [],
"groupSearchBase" : "",
"groupSearchFiler" : "",
"userSearchBase" : "dc=cmp,dc=com",
"userSearchFilter" : "sAMAccountName={0}",
"managerDN" : "[email protected]",
"managerPassword" : "other_PASSWORD!",
"root" : "dc=cmp,dc=com"
}
]
}

In the above example, we have a configuration that uses two servers (an LDAP and an Active Directory), and has all attributes. This example means the same as the following:

Shorter Config
{
"servers" : [{
"serverUrl" : "ldap://ldap1.mycompany.com/dc=mycompany,dc=com",
"userDNPatterns" : ["uid={0},cn=users,dc=mycompany,dc=com", "uid={0},cn=external,dc=mycompany,dc=com"],
"managerDN" : "uid=admin,cn=sysusers,dc=mycompany,dc=com",
"managerPassword" : "PASSWORD!"
}, {
"serverUrl" : "ldaps://ad.mycompany.com/dc=cmp,dc=com",
"userSearchBase" : "dc=cmp,dc=com",
"userSearchFilter" : "sAMAccountName={0}",
"managerDN" : "[email protected]",
"managerPassword" : "other_PASSWORD!",
"root" : "dc=cmp,dc=com"
}
]
}

Consider using the sorter config format, since in application.properties, the config must be in one single line, like this:

Config in one line
{"servers" : [{"serverUrl" : "ldap://ldap1.mycompany.com/dc=mycompany,dc=com", "userDNPatterns" : ["uid={0},cn=users,dc=mycompany,dc=com", "uid={0},cn=external,dc=mycompany,dc=com"], "managerDN" : "uid=admin,cn=sysusers,dc=mycompany,dc=com", "managerPassword" : "PASSWORD!"}, { "serverUrl" : "ldaps://ad.mycompany.com/dc=cmp,dc=com", "userSearchBase" : "dc=cmp,dc=com","userSearchFilter" : "sAMAccountName={0}", "managerDN" : "[email protected]", "managerPassword" : "other_PASSWORD!", "root":"dc=cmp,dc=com"}]}