Authenticating with LDAP

LDAP, although a standard, is highly configurable and not always deployed in the same manner across organizations. LogScale 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 LogScale can't search within the LDAP directory service.

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

LogScale 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 Settings

When the user name and password you'd like to use with LogScale 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:

ini
AUTHENTICATION_METHOD=ldap
LDAP_AUTH_PROVIDER_URL=your-url
LDAP_AUTH_PRINCIPAL=your-principal
LDAP_DOMAIN_NAME=your-domain.com
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true

Setting AUTHENTICATION_METHOD equal to ldap enables the more standard LDAP bind method. The 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. For example, it could be something like this: ldap://ldap.forumsys.com:389. We recommend using a secure connection to ensure that authentication credentials are not transmitted in the clear.

Setting LDAP_AUTH_PRINCIPAL is optional. We provide this so that you can transform the username provided to LogScale during login (john@example.com is the LOGSCALEUSERNAME john) into something that your LDAP server will authenticate. To do this, supply a pattern and include the special token LOGSCALEUSERNAME which LogScale 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=LOGSCALEUSERNAME,dc=example,dc=com and attempt to log in to LogScale with the username of john@example.com, LogScale 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 LogScale 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.

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

The LDAP_DOMAIN_NAME variable 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 LogScale 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.

When the AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN is set to true, which by default is set to false, it will create new users in LogScale 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 LogScale.

LDAP with 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 LogScale 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 awk command to do the translation; you can of course use other tools as well.

shell
$ awk '{printf "%s\\n",$0}' CA_file.pem

If before the command the certificate looked like this:

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

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

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

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

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

Important

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 can be tricky; we have a tool available upon request that can make it easier to test the values required to use LogScale outside of running LogScale itself, and with more detailed and helpful messages.