Authenticating 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.
ldapis the more common method and should be tried first.
ldap-searchis 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:
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.
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-Search
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 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.
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
LDAP_GROUP_SEARCH_BIND_FOR_LOOKUP=true # optional, default false, when set to true, the LDAP_SEARCH_BIND_NAME and LDAP_SEARCH_BIND_PASSWORD are used to lookup groups for the user
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, 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))
The optional LDAP_USERNAME_ATTRIBUTE 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 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 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.
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.
$ awk '{printf "%s\\n",$0}' CA_file.pemIf 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-----\nImportant
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; LogScale has a tool available 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.
You can also enable LDAP_VERBOSE_LOGGING to generate log
messages when users sign in, which can be useful when troubleshooting.