tl;dr
ldapsearch and ldapwhoami are your friends! You need to make sure users have simple user/password BIND access to the LDAP/AD server over TLS encrypted connection (ldaps://) instead using external auth (via kerberos tickets are similar)
Diagnosing Sensu LDAP auth providers
Both the LDAP and AD auth provider types in Sensu use the same fundamental mechanism, they bind to an ldap server implementation and do searches. The only real different between the LDAP and AD providers are some of the defaults used for the ldap search settings.
LDAP is really flexible in terms of what attributes you can store information, so the default user and group search settings Sensu provides might not work for your org’s LDAP schema. if as a Sensu admin, you need to integrate with an ldap server implemented by another part of your internal org, it might not be clear what search settings to use, especially if the default settings Sensu provides aren’t working. The best way I’ve found to figure this out is to use ldapsearch and ldapwhoami on the system where sensu-backend is expected to operate.
If you can construct ldapsearch and ldapwhoami commandline operations that work then you have all the information you need to translate into a working LDAP or AD auth provider configuration in Sensu.
When using LDAP auth provider, Sensu does 4 steps to authenticate with the LDAP server
- Binds with privileged user
- Performs a user search using privileged user to make sure user exists
- Performs a group search using a privileged user to pull group info to be optionally used in RBAC
- Binds with login user to authenticate provided user/password credentials
The privileged LDAP user
The privileged LDAP user has permissions to perform LDAP searchers for users and groups.
You may need to specifically ask the LDAP/AD admin for an LDAP account that will allow you to perform ldapsearch commands. Specifically you’ll need the Distinguished Name (aka dn) and password for the privileged user.
For the following examples I’m going to assume a privileged user with a Distinguished Name of
“cn=sensuldap,dc=example,dc=com”
Security Settings
You’ll have to discuss with your LDAP/AD admin as to whether or not they are using TLS secured ldap, and if they require a custom CA or client certificates. Both ldapsearch and sensu-backend support these options. For brevity I’m not going to go into the details of cert signing or the installation of a custom CA. For the purposes of the following ldapseach examples I’m going to assume the LDAP server is using secure ldap and that the TLS_CACERT TLS_CERT and TLS_KEY environment variables are set appropriately if needed. If the LDAP server you are connecting to requires client certs, you’ll definitely need to discuss the configuration with your LDAP admin.
The user search command
Once you have the privileged user credentials and have your TLS environment setup you can use ldapsearch to mimic how Sensu will search for users and groups. Let’s assume that you want to login into Sensu web-ui using an LDAP user with a uid attribute of sensu-admin. We want to be able to login to the Sensuy web-ui be entering the uid and password. We can construct the search Sensu will perform using an ldapsearch command similar to this:
ldapsearch -x -H "ldaps://ldap.example.com" -D “cn=sensuldap,dc=example,dc=com” -b "dc=example,dc=com" "(&(objectClass=person)(uid=sensu-admin))"
If this is a valid unique search, you should get the result indicating numEntries: 1. If you are getting more than 1 match, you’ll need to review and see if you can adjust the search. Maybe you need to change the base search by including one or more Organizational Units (ou) attributes. Once you have the search base tailored to provide an unique match you should see the details of the matching LDAP record including the Distinguished Name attribute for the user:
dn: uid=sensu-admin,dc=example,dc=com
The value of the dn attribute is what Sensu uses when authenticating the user trying to login by binding to the LDAP server after the privileged searches are done.
This search command binds to LDAP server as the privileged user and asks for the privileged user’s password. The -D option holds privileged user’s Distinguished Name and corresponds to the Sensu LDAP auth provider binding.user_dn setting
The user search is restricted by the -b option which represents a search base, its a subset of the available distinguished name LDAP attribute (dn) that must match. You’ll want to confirm the correct search base with your LDAP admin. This search base corresponds to the Sensu LDAP auth provider user_Search.base_dn setting.
Lastly comes the search filters. Sensu uses two LDAP search filters. A filter on ObjectClass, where the value is configurable and a definable user attribute filter, where both the attribute name and value are configurable.
Here’s the Sensu LDAP auth provider user settings that correspond to the ldapsearch command above:
spec:
servers:
- binding:
password: <<privileged_user_password>>
user_dn: cn=sensuldap,dc=example,dc=com
host: ldaps.example.com
insecure: false
port: 636
security: tls
user_search:
attribute: uid
base_dn: dc=example,dc=com
name_attribute: uid
object_class: person
Once you are more familiar with the contents of your LDAP records you’ll probably end up using a different value for name_attribute. The name_attribute is used to display the user info inside Sensu, and is not part of the ldap query. When starting out I find its easier to set this to the same value as attribute setting, but once you have everything working you may change this to the LDAP attribute that hold the full name or something else.
The group search command
Once Sensu does the user search, it goes on to perform a search for all groups that a particular user is a member of. The search Sensu will perform will look similar to this ldapsearch command:
ldapsearch -x -H "ldaps://ldap.example.com" -D “cn=sensuldap,dc=example,dc=com” -b "ou=Groups,dc=example,dc=com" "(&(objectClass=groupOfNames)(member=sensu-admin))"
As before using the privileged user Distinguished Name and search base options. What’s different here are the search filters. ObjectClass filter is still being used, but not we are only matching for groupOfNames. The second filter is the group attribute filter, here we are choosing to match the attribute named member, and the value is the same as the uid from the user search since we are trying to find which groups the sensu-admin user belongs to.
Note the search base for groups may be different than the search base most appropriate for users due to the use of Organization Unit (ou) attributes in the dn.
Translating the group search into the Sensu LDAP auth configuration settings:
group_search:
attribute: member
base_dn: ou=Groups,dc=example,dc=com
name_attribute: cn
object_class: groupOfNames
For the group_search.attribute, you’ll want to make sure are selecting the attribute that corresponds to the user’s login name you are trying to use. The group will have multiple version of the attribute, indicating membership to the group for multiple users. Because of the flexibility of LDAP, you may need to talk to your LDAP admin as to what group search attribute and object class to use. Or you can do some exploratory searches with different filters to explore your LDAP records.
The ldapwhoami command
Once you have established the user and group search settings for your Sensu LDAP/AD auth provider configuration, you’ll want to also make sure that your target user that you want to authenticate is able to bind to the LDAP server. You may have to work with your LDAP admin to correctly set permission for the users you want to use LDAP authentication. Part of this is making sure the user has an ldap password defined (hint: ldappasswd command) but also that the user has permissions to bind to the ldap server. The easiest way to for you test that the target user has the necessary credentials and permissions is to use the ldapwhoami command and successfully bind to the LDAP server.
Lets take the Distiguished Name from the user search example from above and use it in the ldapwhoami command
ldapwhoami -x -H "ldaps://ldap.example.com" -D “uid=sensu-admin,dc=example,dc=com”
If the entered password is correct, output should look like this
dn:uid=sensu-admin,dc=spaleta,dc=local
If you run into an error, you may need to talk to the LDAP/AD admin to ensure your user has simple bind access with user/password instead of relying on an external kerberos server to provide user authentication.
As an aside, if you have time the history of why kerberos exists is sort of fascinating. I’d wager that if we had mutual TLS as as network security standard, something like kerberos wouldn’t have been widely adopted.