Authenticate with LDAP

LDAP authentication can be configured in LogScale using two methods: standard LDAP bind and LDAP-search. Both methods require environment variables setup, TLS/SSL configuration, and group membership handling. Learn about essential security requirements and configuration parameters, and find specific examples for implementing LDAP authentication in both Docker and traditional environments, with options for customizing username attributes and group naming conventions.

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 cannot search within the LDAP directory service.

The following diagram shows how LogScale supports two methods for LDAP authentication: Standard LDAP Bind and LDAP-Search. Both methods allow users to authenticate using their LDAP credentials and retrieve group membership information.

flowchart TD User([User]) --> LogScale[LogScale Server] LogScale --> Methods{Authentication Method?} Methods -->|LDAP Bind| StandardBind[Standard LDAP Bind] Methods -->|LDAP Search| SearchMethod[LDAP-Search Method] StandardBind --> LDAP[(LDAP/Active Directory)] SearchMethod --> LDAP LDAP --> Authenticate{Authenticated?} Authenticate -->|Yes| GroupMembership[Get Group Membership] Authenticate -->|No| Reject[Access Denied] GroupMembership --> Authorization[Apply Authorization] Authorization --> Access[Grant Access to LogScale] classDef user fill:#f9f,stroke:#333,stroke-width:2px classDef server fill:#bbf,stroke:#33f,stroke-width:2px classDef decision fill:#ff9,stroke:#333,stroke-width:2px classDef action fill:#9f9,stroke:#333,stroke-width:2px classDef database fill:#fcf,stroke:#333,stroke-width:2px class User user class LogScale,StandardBind,SearchMethod server class Methods,Authenticate decision class GroupMembership,Authorization,Access,Reject action class LDAP database

Before configuring LDAP, 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 Manage Users in the user interface, or using the API for root access.

Configuration

LogScale can be run within Docker or as any other application. Setting environment variables requires either editing a file in the /etc/humio directory and restarting the server, or changing the content of the file 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, this content assumes that you are using Docker and have named your configuration file humio-config.env. To learn more about setting configuration, see Configuration Settings.

The general environment variables to set in humio-config.env are:

Environment variable Description Example
AUTHENTICATION_METHOD Specifies the authentication method ldap for the more standard bind method, or ldap-search for the LDAP Search method.
LDAP_AUTH_PROVIDER_URL URL to connect to for LDAP authentication. It can start with either ldap:// for unencrypted transport, or ldaps:// for TLS/SSL transport. LogScale recommends using a secure connection to ensure that authentication credentials are not transmitted in the clear. ldap://ldap.example.com:389 or ldaps://ldap.example.com:636
LDAP_DOMAIN_NAME Allows users to log in without specifying domain. 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, the user can still add domain when logging in, as long as it matches. example.com
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN Create users in LogScale upon successful authentication 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. true or false (default is false)
LDAP_AUTH_PROVIDER_CERT PEM-format certificate for TLS/SSL connections -----BEGIN CERTIFICATE-----\nMII...gWc=\n-----END CERTIFICATE-----\n

Configuration of additional environment variables depends on which method you choose to run. The additional environment variables are described in the respective sections.

LDAP Settings

The Standard LDAP Bind method is the more common approach and should be tried first. 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. In this method, LogScale binds directly to the LDAP server using the transformed username/password.

sequenceDiagram actor User participant LogScale as LogScale Server participant LDAP as LDAP/Active Directory User->>LogScale: Login with username/password Note over LogScale: Configuration:<br/>AUTHENTICATION_METHOD=ldap LogScale->>LogScale: Transform username using<br/>LDAP_AUTH_PRINCIPAL pattern<br/>(if configured) Note over LogScale: Example: If LDAP_AUTH_PRINCIPAL=cn=LOGSCALEUSERNAME,dc=example,dc=com<br/>username "john" becomes "cn=john,dc=example,dc=com" LogScale->>LDAP: Bind request with transformed<br/>credentials over TLS/SSL alt Successful Authentication LDAP->>LogScale: Bind successful LogScale->>LDAP: Query for group membership LDAP->>LogScale: Return group membership alt AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true LogScale->>LogScale: Create user if doesn't exist end LogScale->>User: Grant access (based on permissions) else Authentication Failed LDAP->>LogScale: Bind failed LogScale->>User: Access denied end

Besides the standard environment variables to set for LDAP, set the following additional parameters in humio-config.env:

Environment variable Description Example
LDAP_AUTH_PRINCIPAL Optional. Pattern to transform username for LDAP authentication. LogScale provides this so that you can transform the username provided to LogScale during login. (for example, 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. cn=LOGSCALEUSERNAME,dc=example,dc=com
LDAP_AUTH_PRINCIPALS_REGEX Separator for multiple LDAP_AUTH_PRINCIPAL patterns. If you have users in more than one location within LDAP you can separate the multiple patterns and LogScale will try to authenticate the options you've provided in order. 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. ;

A full example of how to use the LDAP_AUTH_PRINCIPALS_REGEX with LDAP_AUTH_PRINCIPAL is:

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'

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 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 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 it must end with \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.

Test the LDAP integration setup

LDAP can be tricky; LogScale has a tool available upon request to support 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.

Troubleshoot LDAP

LDAP issues can be tricky to debug. The LogScale LDAP testing tool can make it easier to test the values required to use LogScale outside of running LogScale itself, and with more detailed and helpful messages.

You can also enable LDAP_VERBOSE_LOGGING to generate log messages when users sign in, which can be useful when troubleshooting.

Otherwise, contact support for additional assistance.