Active Directory and LDAP
Active Directory and LDAP can be used as authentication backend and user information backend. Thus, you can choose whether you want to authenticate your uses with LDAP or just want to retrieve roles and attributes by LDAP.
This chapter describes the basic setup of LDAP with Search Guard. This will work in most cases. However, some setups require special configurations for TLS, proxies, or similar things. Please refer to the section Advanced Configuration for this.
To use LDAP, you need to have access to an Active Directory/LDAP server. You need to have credentials which Search Guard can use to perform searches in the LDAP directory. Furthermore, you need to know the LDAP directory structure in order to configure how searches in the LDAP directory are performed.
Search Guard setup
sg_authc.yml using LDAP looks like this:
auth_domains: - type: basic/ldap ldap.idp.hosts: - "ldaps://ldap.example.com"
This way, Search Guard will connect by TLS on port 636 to the LDAP server
ldap.example.com. With this configuration, the LDAP server must allow searches by anonymous connections. If you need to authenticate for doing servers on the LDAP server, you can provide the credentials using the config options
auth_domains: - type: basic/ldap ldap.idp.hosts: - "ldaps://ldap.example.com" ldap.idp.bind_dn: "cn=searchguard,ou=people,dc=example,dc=com" ldap.idp.password: "secret-ldap-password-123"
If you need to special TLS settings for creating TLS connections to the LDAP server, you can use the attributes below
ldap.idp.tls. See the section on advanced configuration options for details on this.
When a user tries to authenticate at Elasticsearch, Search Guard will search the whole LDAP directory tree for an entry where the attribute
sAMAccountName equals the user name provided to Elasticsearch.
If you need to search using a different attribute, you can use the
ldap.user_search.filter.by_attribute option to specify this:
auth_domains: - type: basic/ldap ldap.idp.hosts: - "ldaps://ldap.example.com" ldap.user_search.filter.by_attribute: "uid"
Search Guard allows you to configure all aspects of the user search: The search tree root, the search scope and complex filter expressions. See the section advanced configuration options for LDAP for details.
ldap authentication backend offers two methods for determining the roles of a user:
- Attributes of the LDAP user entry
- The result of an additional LDAP search for groups where the user is member of.
You can choose to use one of the methods or both.
User entry attributes
You can use the standard Search Guard
user_mapping functionality to retrieve roles from the LDAP user entry. Suppose the entries in your LDAP directory look like this:
dn: cn=karlotta,ou=people,dc=example,dc=com objectClass: inetOrgPerson sAMAccountName: karlotta memberOf: cn=devops,ou=groups,dc=example,dc=com memberOf: cn=hr,ou=groups,dc=example,dc=com
To access attributes of the LDAP entry during user mapping, the
ldap authentication backend provides the
ldap_user_entry object. If you want the values of the
memberOf attribute as role names, you can use this user mapping:
auth_domains: - type: basic/ldap [...] user_mapping.roles.from: ldap_user_entry.memberOf
In Search Guard, the logged in users will then have the attribute values entries as backend roles; in the example, these would be the distinguished names
cn=hr,ou=groups,dc=example,dc=com. You can use the role mapping configuration to map these to Search Guard roles.
LDAP group search
If user entry attributes are not a sufficient source for roles, you can search a whole LDAP directory tree for entries where the user is member. The following snippet shows the minimal configuration for this:
auth_domains: - type: basic/ldap [...] ldap.group_search.base_dn: "ou=groups,dc=example,dc=com"
With this configuration, Search Guard will search the directory tree below
ou=groups,dc=example,dc=com for all entries which have a
member attribute which equals the dn of the user logging in. The options of
group_search are similar to
user_search. If you need to search using a different attribute, you can use the
ldap.group_search.filter.by_attribute option. See here for all available configuration options.
By default, the logged in users will then have the distinguished names (“dn”) of the LDAP entries as backend roles. If you want to use a different attribute, you can specify this using
ldap.group_search.role_name_attribute. For advanced mapping, you can also reference the group search result via
user_mapping. See below for more on this.
Recursive group search
Normally, the group search will only search for groups where the user is a direct member. However, in LDAP directories, it might be also possible that groups are member of further groups. If the user shall transitively get the memberships of all the groups they are member in, you need to use recursive group search. This is just activated by the flag
auth_domains: - type: basic/ldap [...] ldap.group_search.base_dn: "ou=groups,dc=example,dc=com" ldap.group_search.recursive.enabled: true
Note: When doing recursive group search, Search Guard has to issue one further LDAP query for each level of recursion. This can slow down the authentication process.
There are a couple of further configuration options to control and limit the recursive group search. See the group search configuration options.
Activate the setup
After having applied the changes to
sgctl to upload the file to Search Guard:
$ ./sgctl.sh update-config sg_authc.yml
That’s it. If you navigate in a browser to your Elasticsearch instance, you should get a basic authentication popup asking for your username and password.
Where to go next
- Check the advanced configuration options for LDAP