Skip to content
LogScale Self-Hosted
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

## 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.

### Secure connection required from 1.238

From version 1.238, using LDAP for connection to LogScale will require a secure connection (ldaps).

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. From version 1.238, using LDAP for connection to LogScale will require a secure connection (ldaps). | 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-Search

The LDAP-Search method is useful when the authenticating user cannot search within the LDAP directory service. It first searches for the user's Distinguished Name (DN) with a low-privileged bind username using a service account before authenticating with the discovered DN. Put a different way, when you configure LogScale 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.

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-search LogScale->>LDAP: Bind with service account<br/>(LDAP_SEARCH_BIND_NAME/PASSWORD) LDAP->>LogScale: Bind successful LogScale->>LDAP: Search for user DN using filters<br/>within LDAP_SEARCH_BASE_DN Note over LogScale: Default filters tried:<br/>1. (&(userPrincipalName={0})(objectClass=user))<br/>2. (&(sAMAccountName={0})(objectClass=user)) LDAP->>LogScale: Return user's Distinguished Name (DN) LogScale->>LDAP: Bind with found DN and user's password 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_SEARCH_BASE_DN` | Base DN for searching user entries | ou=DevOps,dc=example,dc=com
`LDAP_SEARCH_BIND_NAME` | Service account DN for binding to LDAP server | cn=Bind User,dc=example,dc=com
`LDAP_SEARCH_BIND_PASSWORD` | Password for service account | (password)
`LDAP_SEARCH_FILTER` | Optional. Custom search filter for finding users | (&(userPrincipalName={0})(objectClass=user))
`LDAP_USERNAME_ATTRIBUTE` | Optional. LDAP attribute to use as username in LogScale. Allows administrators to choose some attribute in the LDAP user record as the username in LogScale. Normally LogScale will default to an email address, but in your LDAP you may have assigned user IDs and for uniformity in your organization; then it's desirable to use those rather than the email address. This option allows for that case. | uid (defaults to user's email address if not set)
`LDAP_GROUPNAME_ATTRIBUTE` | Optional. LDAP attribute to use as group name in LogScale. Allows administrators to choose an alternate attribute on the group record in LDAP for use as the group name in LogScale's RBAC configuration. When not set, LogScale will default to the full distinguished name for the group, which can be lengthy. This allows LogScale administrators to use an alternate name for group identity. | gid (defaults to group's distinguished name if not set)
`LDAP_GROUP_SEARCH_BIND_FOR_LOOKUP` | Optional. Whether to use service account for group lookups. When set to true, the `LDAP_SEARCH_BIND_NAME` and `LDAP_SEARCH_BIND_PASSWORD` are used to lookup groups for the user . | true or false (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.

init

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

Put another way, LogScale 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 LogScale 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 LogScale 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))`

### 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.

#### Enter search term