Authenticating with LDAP

LDAP, although a standard, is highly configurable and not always deployed in the same manner across organizations. Humio provides two ways to authenticate, using LDAP and fetch group membership.

  • ldap is the more common method and should be tried first.
  • ldap-search is useful when the user authenticating with Humio can’t search within the LDAP directory service.

Prerequisites

Before configuring LDAP you need to ensure that a root account exists on the system. You can do this either by adding the user name (the full name including domain name) through the User Administration Page in the Web UI, or using the API: root access.

Configuration File Location

Humio can be run within Docker or as any other application. When we refer to setting environment variables below, you’ll either be editing a file in the /etc/humio directory and restarting the server, or changing the content of the file you provided to the --env-file= parameter when launching Docker.

The file in /etc/humio is named server.conf or server_all.conf if you are not on a multi-socket NUMA system and running one JVM per CPU socket.

For simplicity we’ll assume below that you are using Docker and have named your configuration file humio-config.env.

LDAP

When the user name and password you’d like to use with Humio is one that can log in to and search the LDAP (or Active Directory) service then this method is likely to be the right one to configure.

Set the following parameters in humio-config.env:

AUTHENTICATION_METHOD=ldap
LDAP_AUTH_PROVIDER_URL=your-url             # example: ldap://ldap.forumsys.com:389
LDAP_AUTH_PRINCIPAL=your-principal          # optional, example: cn=HUMIOUSERNAME,dc=example,dc=com
LDAP_DOMAIN_NAME=your-domain.com            # optional, example: example.com
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true   # default is false

AUTHENTICATION_METHOD=ldap enables this more standard LDAP bind method.

LDAP_AUTH_PROVIDER_URL is the URL to connect to. It can start with either ldap:// or ldaps://, which selects unencrypted or TLS/SSL transport respectively. We recommend using a secure connection to ensure that authentication credentials are not transmitted in the clear.

LDAP_AUTH_PRINCIPAL is optional. We provide this so that you can transform the username provided to Humio during login (john@example.com is the HUMIOUSERNAME john) into something that your LDAP server will authenticate. To do this, supply a pattern and include the special token HUMIOUSERNAME which Humio will replace with the username provided at login before attempting to bind to the LDAP server. This is how you can specify the principal provided to your LDAP server. So, if you provide cn=HUMIOUSERNAME,dc=example,dc=com and attempt to log in to Humio with the username of john@example.com, Humio will bind using a principal name cn=john,dc=example,dc=com and the password provided at the login prompt. If you have users in more than one location within LDAP you can separate the multiple patterns and Humio will try to authenticate in order the options you’ve provided. Split the value set in LDAP_AUTH_PRINCIPAL using the LDAP_AUTH_PRINCIPALS_REGEX pattern. This doesn’t apply when using the ldap-search method.

LDAP_AUTH_PRINCIPALS_REGEX=';'
LDAP_AUTH_PRINCIPAL='cn=HUMIOUSERNAME,dc=example,dc=com;cn=HUMIOUSERNAME,dc=foo,dc=com;cn=HUMIOUSERNAME,dc=bar,dc=com'

LDAP_DOMAIN_NAME can be used if your directory service is only hosting a single domain (like example.com) and you’d like to allow your users to log in to Humio with their username and not domain name (such as john rather than john@example.com). If so, set this to the common domain name for all users (like example.com in this case). While this makes use of the domain name optional, you can still add domain when logging in, as long as it matches.

AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN (default is false) when true will create new users in Humio on successful login if that user didn’t already exist. Otherwise, only manually added users who can authenticate with LDAP will be allowed to log in to Humio.

LDAP-search (using a bind user)

If LDAP/AD requires login with the exact DN, then it is possible to first do a search for the DN using a low-privileged bind username, and then successively do the login with the discovered DN. Put a different way, when you configure Humio to use the ldap-search method it then uses a blind user you supply to search for the given user’s DN and then that DN is used to authenticate and discover group membership. Config settings prefixed with LDAP_SEARCH_... are used in the first stage to log in and search for the DN for a given user.

To enable this, use this alternative property set:

AUTHENTICATION_METHOD=ldap-search
LDAP_AUTH_PROVIDER_URL=your-url             # example: ldap://ldap.forumsys.com:389
LDAP_DOMAIN_NAME=your-domain                # example: example.com
LDAP_SEARCH_BASE_DN=search-prefix           # example: ou=DevOps,dc=example,dc=com
LDAP_SEARCH_BIND_NAME=bind-principal        # example: cn=Bind User,dc=example,dc=com
LDAP_SEARCH_BIND_PASSWORD=bind-password     # the password for the LDAP_SEARCH_BIND_NAME
LDAP_SEARCH_FILTER=custom-search-filter     # optional, example: (& (|(userPrincipalName={0})(sAMAccountName={0})) (objectClass=user))
LDAP_USERNAME_ATTRIBUTE=uid                 # optional, when not set defaults to the user's email address
LDAP_GROUPNAME_ATTRIBUTE=gid                # optional, when not set defaults to the group's distinguished name
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true   # default is false

If LDAP_SEARCH_FILTER is not set, these two default filters are tried in the following order. Most LDAP compliant directory servers will work with one of these two filters.

"(& (userPrincipalName={0})(objectClass=user))"
"(& (sAMAccountName={0})(objectClass=user))"

Put another way, Humio will attempt the two searches above within the directory server. First it will search for:

  • (& (userPrincipalName=john@example.com)(objectClass=user))
  • (& (sAMAccountName=john)(objectClass=user))

assuming the username provided to Humio at login was john@example.com. Both searches are restricted to the subtree specified by the value of LDAP_SEARCH_BASE_DN and will use the bind-principal and password provided to Humio at login.

If either of those searches returns a result with a distinguished name, then the DN is used to login (bind) with the end-user provided password. A search for (& (dn={0})(objectClass=user)) is then performed in the new context, with the{0} replaced with the DN found as further validation of that context.

When specifying LDAP_SEARCH_FILTER the username provided will not be expanded into an email address unless you also configure the LDAP_SEARCH_DOMAIN_NAME so the above searches will instead be:

  • (& (userPrincipalName=john)(objectClass=user))
  • (& (sAMAccountName=john)(objectClass=user))

The optional LDAP_USERNAME_ATTRIBUTE allows administrators to choose some attribute in the LDAP user record as the username in Humio. Normally Humio will default to an email address, but in your LDAP you may have assigned user IDs and for uniformity in your organization it’s desirable to use those rather than the email address. This option allows for that case.

The optional LDAP_GROUPNAME_ATTRIBUTE allows administrators to choose an alternate attribute on the group record in LDAP for use as the group name in Humio’s RBAC configuration. When not set, Humio will default to the full distinguished name for the group, which can be lengthy. This allows Humio administrators to use an alternate name for group identity.

How to Configure LDAP to use TLS/SSL

If you are enabling TLS/SSL-secured communications to the LDAP server (for example, when you configure the provider URL with ldaps:) some TLS negotiations will require that you provide a certificate in the key exchange process. To do that with Humio you’ll need to specify LDAP_AUTH_PROVIDER_CERT to be the PEM-format value of the certificate.

There is one further complication when using Docker. Docker does not support newlines in environment variables. The workaround is to replace newlines with \n. Here is an example using the sed command to do the translation; you can of course use other tools as well.

cat my.crt | sed -e 's/\n/\\n/g'

If before the command the certificate looked like this:

-----BEGIN CERTIFICATE-----
MII...gWc=
-----END CERTIFICATE-----

Then after running this command it will be reformatted to look like this:

-----BEGIN CERTIFICATE-----\nMII...gWc=\n-----END CERTIFICATE-----\n

And then within the humio-config.env file it will be a single line like this:

LDAP_AUTH_PROVIDER_CERT=-----BEGIN CERTIFICATE-----\nMII...gWc=\n-----END CERTIFICATE-----\n

Note that it should be one line containing \n where there were newlines before and that it must end in \n (and not % which is often added by the shell).

If you are using Docker and choose not to provide this config parameter, trust is established using the Docker container’s regular CA authority infrastructure.

LDAP Configuration Help

LDAP can be tricky; we have a tool available upon request that can make it easier to test the values required to use Humio outside of running Humio itself, and with more detailed and helpful messages. Join the MeetHumio Slack, reach out for help, and we’ll provide that tool to you and get your configuration working.