Skip to content

Authenticate Using Lightweight Directory Access Protocol (LDAP)

Okera supports LDAP authentication and group resolution.

Note: This document refers to LDAP, but it can be used to connect to Active Directory servers as well.

Configuration Settings

The following configuration settings are used to configure LDAP authentication:

And for LDAP group resolution, use the following configuration settings:

Note: Consult your IT team to determine the actual values for your specific environment for many of these settings.

These configuration parameters are described in the Okera Configuration Parameter Reference.

Configuring LDAP Authentication

To configure LDAP authentication, you will need to know the following values:

  1. Your LDAP server host and port. The port values are typically 389 for non-SSL connections and 636 for SSL ones.
  2. Whether or not your LDAP server uses SSL.
  3. Converting the username to a bindable identifier (e.g. the DN, userPrincipalName, etc).

Converting a username to a bindable identifier

In LDAP, each user is identified by a fully-specified Distinguished Name (DN). This typically includes the full Organizational Unit and other values, and may even contain the user's full name instead of their username.

For example, a DN might be:

CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com

In order to authenticate to an LDAP server (called "binding"), you need either the full DN of a user or another identifier (such as sAMAccount or userPrincipalName) and their password. Since the username that users supply to authenticate does not typically match one of these values, it needs to be converted to one of them.

Okera provides three mechanisms to do the conversion:

  1. LDAP bind template, that provides a string template where the username will be replaced
  2. Base DN, to which the username will be prepended to create a DN.
  3. LDAP Domain, which will be prepended to the user.

Using an LDAP Bind Template

Values for this setting are put in LDAP_BIND_TEMPLATE.

Each bind template should contain a single '%s', which is substituted with the user name trying to authenticate. For example, a bind template of cn=%s,ou=ca,dc=domain,dc=com with the user Alice trying to authenticate, the resulting binding string for the LDAP server would be: cn=Alice,ou=ca,dc=domain,dc=com.

Multiple bind strings can be specified separated by ;. In this case, Okera will try each bind string in order, authenticating the user on the first successful bind. For example, if this config was set to: cn=%s,ou=ca,dc=domain,dc=com;cn=%s,ou=wa,dc=domain,dc=com, again with the user being Alice, Okera will try binding with: cn=Alice,ou=ca,dc=domain,dc=com and if unsuccessful, try with cn=Alice,ou=wa,dc=domain,dc=com. The user can authenticate if any of the binds succeeded and Okera will not try the subsequent templates.

Since some systems do not have the desired username in the DN at all (e.g. if the DN is CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com, you would need to authenticate with Smith, John as the username), you can also typically authenticate with one of userPrincipalName or sAMAccountName.

For example, userPrincipalName for the CN=Smith\, John,OU=All Users,DC=ad,DC=okera,DC=com might be john.smith@okera.com, and so the LDAP_BIND_TEMPLATE would be %s@okera.com and the login user would be john.smith.

Note: This value cannot be set if either LDAP_BASE_DN or LDAP_DOMAIN is set.

Using a Base DN

Values for this setting are put in LDAP_BASE_DN.

In some cases, the username appears in the DN in the Common Name (CN) section, and you can specify the base DN to use.

For example, consider the following DN:

CN=jsmith,DC=ad,DC=okera,DC=com

In this case, the Base DN would be ad.okera.com, and would look like this in the configuration file:

LDAP_BASE_DN: ad.okera.com

When a user logs in (e.g. with username alice), it would construct the following DN:

CN=alice,DC=ad,DC=okera,DC=com

Note: Using LDAP_BIND_TEMPLATE is recommended over LDAP_BASE_DN because it is more flexible. For example, when you need to specify an OU as part of the DN or a non-DN identifier.

Using the LDAP Domain

This is the default domain for users. For example, if set to ALL USERS and a user tries to log in with their username, userid, Okera will authenticate (i.e. bind) with the LDAP server using ALL USERS\\userid. If a domain is explicitly specified when logging in, Okera will ignore this value. For example, in the same identical configuration, if the user explicitly logged in as TEST DOMAIN\\userid, then we will authenticate with LDAP using exactly that login. By default, this is not set and there is no default domain.

Note: Using LDAP_BIND_TEMPLATE or LDAP_BASE_DN is recommended over LDAP_DOMAIN.

Example Configuration

An example LDAP configuration might be:

LDAP_HOST: ldap.company.com
LDAP_PORT: 636
LDAP_USE_SSL: true
LDAP_BIND_TEMPLATE: cn=%s,ou=users,dc=company,dc=com

This would tell Okera to connect to ldap.company.com:636 using an SSL-enabled connection, and to take the passed in username and password and bind to the LDAP server with with cn=<username>,ou=users,dc=company,dc=com.

Verify LDAP authentication using curl

If you have a username and password that you want to test logging into an Okera cluster configured with LDAP authentication, you can check that your configuration is correct using cURL:

$ curl <Okera REST URL>/api/health-authenticated -u <username>
Enter host password for user '<username>':
{
  "health": "ok",
  "token": null,
  "user": "<username>"
}

NOTE: Okera REST URL should take the form of https://<REST HOST or IP>:<REST PORT> or http://<REST HOST or IP>:<REST PORT>, depending on whether SSL is enabled or not (it is typically enabled and strongly recommended).

To verify if the LDAP related values are set as intended, and for LDAP related debugging, look for the following logs in your REST service.

The logs to look for will follow this general format

LDAP configurations initialized
LDAP Server: <LDAP_HOST>:<LDAP_PORT>
LDAP Server Base DN: <base DN in 'dc=x' format>

An example log output assuming your LDAP server is at 127.0.0.4:389 and LDAP_BASE_DN is "example.com":

LDAP configurations initialized
LDAP Server: 127.0.0.4:389
LDAP Server Base DN: dc=example,dc=com

If the above lines are not present, your REST service did not start with LDAP authentication enabled.

Configuring LDAP Group Resolution

LDAP authentication will allow users to authenticate to the Web UI and REST API using their normal credentials, but it will not tell Okera what groups those users belong to. In order to get this information, LDAP group resolution needs to be used, which allows Okera to find all the groups a particular user belongs to.

To configure LDAP group resolution, you will need to know the following values:

  1. Your LDAP server host and port. The port values are typically 389 for non-SSL connections and 636 for SSL ones.
  2. Whether or not your LDAP server uses SSL.

  3. A service account to use to connect to the LDAP server to run queries (both the username and password).

    Note: The LDAP username and password can be specified as clear text (plaintext). However, Okera discourages the use of clear text. Okera recommends, instead, the use of secret files with the Okera configuration parameters set to the paths to secret files.

  4. A templatized search filter to locate a specific user.

  5. A search filter to search only groups.
  6. The field name in a group object that has membership information.

Configuration Example

An example LDAP configuration might be:

GROUP_RESOLVER_LDAP_HOST: "ldaps://ldap.company.com"
GROUP_RESOLVER_LDAP_PORT: 636
GROUP_RESOLVER_LDAP_USE_SSL: true
GROUP_RESOLVER_LDAP_BASE_DN: "OU=ldap,DC=company,DC=com"
GROUP_RESOLVER_LDAP_USER_SEARCH_FILTER: "(&amp;(objectClass=Person)(userPrincipalName={0}@company.com))"
GROUP_RESOLVER_LDAP_GROUP_SEARCH_FILTER: "(objectClass=groupOfNames)"
GROUP_RESOLVER_LDAP_MEMBER_FIELD_NAME: "member"
GROUP_RESOLVER_LDAP_USER: "cn=svc_account,dc=ldap,dc=company,dc=com"
GROUP_RESOLVER_LDAP_PASSWORD: "SuperGreatPassword"

This would tell Okera to:

  • Connect to ldap.company.com:636 using an SSL-enabled connection.
  • Bind to it using svc_account/SuperGreatPassword as the username/password.
  • When a <username> needs to be resolved, find it's DN by running the query (&amp;(objectClass=Person)(userPrincipalName=<username>@company.come)) on the base path OU=ldap,DC=company,DC=com.
  • Take the found DN for that username, and find all groups it is a member of using the (objectClass=groupOfNames) filter and member field.

Service Account

Okera needs to be able to convert arbitrary usernames to DNs without having the credentials of those users, and thus requires a service account to run these queries. The service account should have permissions to see information about any user in the system.

Note: The LDAP username and password can be specified as clear text (plaintext). However, Okera discourages the use of clear text. Okera recommends, instead, the use of secret files with the Okera configuration parameters set to the paths to secret files.

User Search Filter

The user search filter is a templatized string, used to convert a username into a query that will uniquely resolve a user (and thus find that user's DN). The templatized value takes the form of {0}.

For example, if the username is alice and it is identified in LDAP by it's userPrincipalName of alice@company.com, the user search filter might be:

(&amp;(objectClass=Person)(userPrincipalName={0}@company.com))

Note: Okera escapes XML characters (e.g. & becomes &amp;).

Group Search Filter

The group search filter is used to limit LDAP queries to only return group-type objects. In most LDAP configurations, a query of (objectClass=groupOfNames) is sufficient.

Member Field

When running the search to find all groups, Okera limits it to find only groups that the particular user is a member of. This is done by specifying an extra constraint on the field inside the group object that contains a member. This field is typically called member.

Using ldapsearch

Finding the right values for these settings can be tricky, and typically requires some knowledge of your LDAP setup. You can use the ldapsearch tool to try and find what the values might be, assuming that you know your LDAP host/port and whether it uses SSL or not.

NOTE: ldapsearch may not be preinstalled on your machine, and you should use your system's package manager to install it.

If your LDAP server does not use SSL, use the following pattern:

ldapsearch -H ldap://<ldap server> -p <ldap port> -x -D "<bind name>" -b "<search directory>" "<bind name>" -vvv -W

If it uses SSL, use the following pattern:

LDAPTLS_REQCERT=never ldapsearch -Z -H ldaps://<ldap host>:<ldap port> -x -D "<bind name>" -b "<search directory>" "<bind name>" -vvv -W

For the following examples, we will use the non-SSL version.

For example, if you were to set LDAP_BIND_TEMPLATE to %s@okera.com, you could have the following invocation for the alice user:

ldapsearch -H ldap://ad.okera.com -p 389 -x -D "alice@okera.com" -b "dc=okera,dc=com" "(userPrincipalName=alice@okera.com)" -vvv -W

This should give you an output that allows you to see the full LDAP object for this user, including their DN.