Security Configuration

Once you have configured Lenses, it’s time to set up security.

Security has two important parts: authentication and authorization. Authentication is how users login to Lenses whereas authorization governs the rules of what a user can and can not do. Starting with Lenses 3.0, authorization is configured within the Lenses user interface instead of the security configuration file.

The platform supports a cascading set of authentication modules.

Every authentication module that is configured in the security configuration file, is enabled automatically. Since the Lenses Administrator and Basic modules do not require any configuration, they are always active.

Lenses Administrator

A default account with administrator privileges is always active. The default credentials are admin / admin and if left at default, a notification will show in the user interface, informing that the setup is insecure.

The default account username and password may be adjusted as below. For security purposes it is strongly advised to use your password’s SHA256 checksum instead of the plaintext.

# Lenses Administrator settings = "admin"

## For the password you can either use the plaintext = "admin"
## Or you may use the SHA256 checksum (advised) = "sha256:8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"

To create a SHA256 checksum for your password you can use the command line tools available in your Linux server or macOS.

unset HISTFILE # Disable history for the current terminal
echo -n "password" | sha256sum


To disable the Lenses Administrator user, please set an adequately long random password. You can achieve this by using the snippet below:

dd if=/dev/urandom count=1 bs=1024 | sha256sum


In BASIC mode user accounts are managed by Lenses. Once a user successfully logs in, he is linked to one or more groups and therefore inherits all the permissions attached to the groups he belongs to.

To add, manage and delete users for the basic authentication module visit the Admin section in the Lenses web interface. You will need an account with sufficient privileges to manage users. Alternatively you can add users via the command-line, using the Lenses CLI tool.

The internal database is stored on-disk, under the Please keep this directory intact between updates and upgrades.


For this mode, Lenses relies on the LDAP server to handle the user authentication and retrieve the user groups. Since the authentication is deferred, this means users are stored by LDAP and not Lenses. Once the authentication is successful, the next step involves querying LDAP for the user’s groups. All the user’s groups are then matched by name (case sensitive) with the groups stored in Lenses. All the matching groups’ permissions are combined.

Active Directory (AD) and OpenLDAP (with the memberOf overlay) servers are tested and supported in general. Due to the LDAP standard ambiguity, it is impossible to support all the configurations in the wild. The most usual pain point is group mapping. If the default class that extracts and maps LDAP groups to Lenses groups does not work, it is possible to implement your own.

Before setting up an LDAP connection, we advise to familiarize with LDAP and/or have access to your LDAP and/or Active Directory administrators.

An LDAP setup example is shown below:

# LDAP connection details"ldaps://"
## For the LDAP user please use the distinguished name (DN).
## The LDAP user must be able to list users and their groups."cn=lenses,ou=Services,dc=example,dc=com""[PASSWORD]"
## When set to true, it uses the to read the user's groups

# LDAP user search settings"ou=Users,dc=example,dc=com""(&(objectClass=person)(sAMAccountName=<user>))"

# LDAP group search and mapping settings"""(?i)CN=(\\w+),ou=Groups.*""memberOf" = "sn"

In the example above you can distinguish three key sections for LDAP:

  • the connection settings,
  • the user search settings,
  • and the group search settings.

Each key is explained in detail at the LDAP Configuration Options Table.

Lenses uses the connection settings to connect to your LDAP server. The provided account should be able to list users under the base path and their groups. The default group plugin only needs access to the memberOf attributes for each user, but your custom implementation may need different permissions.

When a user tries to login, a query is sent to the LDAP server for all accounts that are under the and match the The result needs to be unique; a distinguished name (DN) —the user that will login to Lenses.

In the example, the application would query the LDAP server for all entities under ou=Users,dc=example,dc=com that satisfy the LDAP filter (&(objectClass=person)(sAMAccountName=<user>)) where <user> would be replaced by the username that tries to login to Lenses. A more simple filter could be cn=<user>, which for user Mark would return the DN cn=Mark,ou=Users,dc=example,dc=com.

Once the user has been verified, Lenses queries the user groups and maps them to Lenses groups. For every LDAP group that matches a Lenses group, the user is granted the selected permissions. This process is done by the Group Extract Plugin. Depending on the LDAP setup, only one of the user or the Lenses service user may be able to retrieve the group memberships. This can be controlled by the option The default value (false) uses the user itself to query for groups. Groups be can created in the admin section of the web interface, or in the command line via the lenses-cli application.

There are those LDAP setups with stricter security levels which do not allowed for a logged user to list his own groups. In this case the user account set via can be used to list the groups for any logged users. Of course that account needs elevated privileges to do so. To enable this behavior set to true.


Set to true to use account to list a logged user groups when your LDAP setup restricts most of the users action to list their groups.

Group Extract Plugin

The group extract plugin is a class that implements an LDAP query that retrieves a user’s groups and makes any necessary transformation to match the LDAP group to a Lenses group name.

The default class implementation that comes with Lenses is If your LDAP server supports the memberOf functionality, where each user has his/her group memberships added as attributes to his/her entity, you can use it by setting the option to this class:

The configuration settings for the default group extract plugin can be found at the LDAP Configuration Options Table. Below you will see a brief example of its setup.

# Set the full classpath that implements the group extraction""

# The plugin uses the 'memberOf' attribute. If this attribute has a different
# name in your LDAP set it here."memberOf"

# This regular expression should return the group common name. If it matches
# a Lenses group name, the user is granted its permissions.
# As an example if there is a 'memberOf' attribute with value:
#   cn=LensesAdmins,ou=Groups,dn=example,dn=com
# The regular expression will return 'LensesAdmins'.
# Group names are case sensitive."(?i)cn=(\\w+),ou=Groups.*"

# This is the LDAP attribute that holds the user's full name. It's optional. = "sn"

As an example, the memberOf search may return two attributes for user Mark:

attribute  value
---------  ------------------------------------------
memberOf   cn=LensesAdmin,ou=Groups,dc=example,dc=com
memberOf   cn=RandomGroup,ou=Groups,dc=example,dc=com

The regular expression (?i)cn=(\\w+),ou=Groups.* will return these two regex group matches:


If any of these groups exist in Lenses, Mark will be granted the permissions of the matching groups.

To learn more about permissions in Lenses, see the _user_management section.

Custom LDAP Plugin

If your LDAP doesn’t offer the memberOf functionality, or it isn’t enough alone —for example in Active Directory there are groups of groups— you can provide your implementation.

The project template for a custom implementation can be found on GitHub (Lenses LDAP Plugin Template) . Once you build your implementation, drop the jar file into the plugins directory and set the setting to point to your implementation’s full classpath.

Don’t forget to grant to the Lenses LDAP account any permissions it may need for your plugin to work.

Options Table

LDAP Configuration Options Table
Key Description Optional Type Default
The LDAP server URL. TLS, StartTLS and
unencrypted connections are supported.
Example: ldaps://
no string “n/a”
The LDAP account for Lenses. Must be able to
list users and their groups. The distinguished
name (DN) must be used. Example:
no string n/a The LDAP account password. so string n/a
The LDAP base path for querying user accounts.
All user accounts that will be able to access
Lenses should be under this path.
Example: ou=Users,dc=example,dc=com
no string n/a
The LDAP query filter for matching users. Lenses
will request all entries under the base path
that satisfy this filter. The result should be
unique: the user that logs in to Lenses. The
keyword <user> is replaced at runtime with
the Username that requests access.
yes string
The full classpath for the class that implements
the LDAP query for the user’s groups and
maps them to Lenses groups. You can use
if your LDAP setup is supported.
yes string n/a
This key is used by the included LDAP plugin class
LdapMemberOfUserGroupPlugin. It expects the
LDAP user attribute that provides memberOf
information. In most implementations the attribute
has the same name, so you don’t have to set
yes string memberOf
This key is used by the included LDAP plugin class
LdapMemberOfUserGroupPlugin. It expects a
regular expression that will be used to extract
a part of the user’s groups. If this part matches a
Lenses group, the user will be granted all the
permissions of this group.
Lenses checks against the list of memberOf
attribute values and uses the first regex group
that is returned.
yes string (?i)CN=(\\w+),ou=Groups.*
This key is used by the included LDAP plugin class
LdapMemberOfUserGroupPlugin. It expects the
LDAP user attribute that provides the full name
of the user.
yes string sn
If set to true it uses the account to read the
groups of the current logged user. The default
behaviour (false) uses the current logged
user to read group memberships.
yes boolean false


The configuration entries,,, and are specific to the default plugin class that comes with Lenses. A custom implementation may require different entries under

Kerberos (SPNEGO)

In Kerberos mode, your browser will use the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) to login to Lenses.

Before setting up Lenses with SPNEGO, it is important to make sure your browser does support this mechanism, and you are adequately familiar with the protocol and you have access to your Kerberos and/or Active Directory administrators.

Let’s look at an example of a Kerberos security setup:

# Kerberos settings"HTTP/lenses.url[@REALM]"

The SPNEGO-specific configuration is straightforward, you have to point Lenses to a password-less Kerberos keytab and specify the principal to use.

Your system should also provide a system-wide Kerberos configuration. Usually, for Linux distributions, this resides in the file /etc/krb5.conf which is populated with information about your KDC, Kerberos realm and other authentication-related settings. If there isn’t a global krb5.conf that Lenses can use, please ask your Kerberos administrator for one, then point Lenses to it via the LENSES_OPT environment variable:

export LENSES_OPTS="

Once setup, your users should be automatically logged in whenever they visit the Lenses web interface or make a call to the /api/auth REST endpoint. If you are on a Microsoft Windows system, then logging into your Windows domain is usually sufficient to issue your Kerberos credentials. On a Linux environment, if you use Kerberos with PAM, your Kerberos credentials should be already available to Kerberos-enabled browsers. Otherwise, you will typically need to authenticate to the KDC manually using kinit at the command line and start your browser from the same terminal.

Group Mapping

A shortcoming of Kerberos is that by design it is just an authentication mechanism. It doesn’t provide any information about the user it authenticates except the user’s principal. As such it falls to the Lenses administrator to map users to groups.

This is done by adding the same user id to Lenses and link it to at least one group. To learn more about the permission model of Lenses, see the User Management section.

SPNEGO Principal

The Kerberos principal is not random in the SPNEGO protocol. When your browser tries to connect to a SPNEGO service it needs a ticket for it which is granted by the Key Distribution Center (KDC). In SPNEGO, the browser will always request a key from the KDC in the format HTTP/service.url@REALM. So, if your service is at and your realm is EXAMPLE.COM, your browser will always request a ticket for the principal HTTP/ The realm usually can be omitted as it is part of the system-wide Kerberos settings.

To repeat one more time, if you setup Lenses at, you need to ask your Kerberos or Active Directory administrator to create the principal HTTP/ and provide you with a password-less keytab for it.

Options Table

Kerberos Configuration Options Table
Key Description Optional Type Default
The Kerberos principal Lenses should use.
It must be present in the keytab and in
form below (SPNEGO requirement):
no string n/a
Path to a Kerberos keytab that contains
the service principal. It should not
be password protected.
no string (path) n/a
Enable Java’s JAAS debugging information.
yes boolean false

Custom HTTP

In this mode, a custom, user-provided, class takes over authentication and authorization to Lenses using the users’ HTTP request headers. The authentication layer is separated from Lenses into your authentication solution. As an example, it would be possible to use JSON Web Tokens (JWT) injected via an authentication-proxy in-front of Lenses or any other single sign-on tokens your organization may use. The user-implemented class should process the request HTTP headers to extract the tokens and any other information it needs, ideally verifies them, then provides Lenses with the username and groups of the user.

An example of a security configuration with Custom HTTP:

# Just one setting for CUSTOM_HTTP, the full classpath
# of the security plugin implementation

The only available option for this mode is, which should point to the full Java classpath of the class implementing the required interface (HttpAuthenticationPlugin). Once you build your code, you can drop the required jar(s) inside the plugins directory or a subdirectory under it.

The interface of the Custom HTTP class:

public interface HttpAuthenticationPlugin {
    UserAndGroups authenticate(HttpRequest request);

The return object UserAndGroups should contain the username accepted to log in and the groups the person belongs to or raise an exception if the user is not allowed. To learn more about the permissions model of Lenses, check _user_management. To implement the interface, you need to create a project where this maven dependency needs to be added (here is the example for a Maven project):


Example Code

A sample implementation can be found at GitHub. This code expects the header API_KEY based on which it performs a lookup to a mocked user-store. Let’s explore this example a bit further.

If you check the file inside the repository you will notice that the package has a classpath of, therefore the full java classpath would be

First line of


The expected header key is API_KEY [1]:

First entry under public class in

public class HeaderTokenAuthPlugin implements HttpAuthenticationPlugin {

  private static final String API_HEADER_NAME = "API_KEY";

The expected key values are one of [KEY-ADMIN, KEY-WRITE, KEY-READ]. Each value links to a different pair of user & group as shown under

Entries under public class in

public class UserStore {

    private final Map<String, UserAndGroups> users = new HashMap<>();

        users.put("KEY-ADMIN", new UserAndGroups("AdminUser", Collections.singleton("adminGroup")));
        users.put("KEY-WRITE", new UserAndGroups("WriteUser", Collections.singleton("writeGroup")));
        users.put("KEY-READ", new UserAndGroups("ReadUser", Collections.singleton("readGroup")));
        users.put("KEY-NODATA", new UserAndGroups("NoData", Collections.singleton("nodataGroup")));

The security.conf syntax for the example above could be:

The jar produced should be dropped inside the plugins directory. If you are using Lenses Box for development and testing, you may drop it under /plugins or /opt/lenses/plugins.

To test that everything works as expected, execute the following curl command.

curl --header "API_KEY: KEY-ADMIN" --compressed http://lenses.url/api/auth
[1]HTTP headers are case-insensitive. RFC 2616, section 4.2.