LDAP Configuration

Runtime gives admins the ability to use their local LDAP configuration to authenticate their users' access to the interface. This can be desirable, as this means that their credentials are synchronized, and you can manage their accounts from one central location. Starting in version 4.5 it’s also possible to import LDAP groups, and to use them in the Runtime user permissions system. This chapter of the manual looks into the configuration of the LDAP basics, and how to get the most out of this system. Currently, the group matching system is tuned to work with Active Directory setups, and as such varying results may be experienced when using another LDAP provider. In future updates, broader support for various LDAP platforms may be added.

LDAP Overview

In order to get to the LDAP menu, follow these steps:

Open Runtime
In the left-hand menu, press the User Administration located under the Administration tab
In the User Management screen, navigate to the LDAP tab

You should now be greeted by the following overview:

*Because we assume most users will be using Active Directory, default values shown here align with commonly used AD standards.*

LDAP settings

Below is an overview of all the various fields the user can supply in order to import LDAP users. Currently, all values are required and must be filled. However, if a certain value does not exist within the LDAP environment (such as the user e-mail attribute), the user can supply a non-functioning attribute name. These values will then simply be returned as empty.

Server Configuration	Description
LDAP URL	This is the URL you would use to connect to your LDAP environment. A correct example of this would be the following: `ldap://MyFavouriteLDAPServer:1581`
LDAP username	The username used to connect to the LDAP environment. Generally; this should be an administrator account or one with elevated rights.
LDAP password	The password used to authenticate the user specified above against the LDAP environment.
LDAP base	The LDAP base indicates a starting point from which we eventually start searching for user or group common names. This can be as wide or as narrow as you’d like. An example of this would be the following: `DC=MyCompany,DC=Amsterdam,DC=com` Everything below this specified base will be included in the coming searches.
Synchronization interval (minutes)	After configuration this is the interval of how often the user data in Runtime is synchronized with what is specified in the LDAP environment. If this value is set to 0 no synchronization will occur unless the user manually does so by pressing the Save and synchronize now button.
Users Configuration	Description
Additional user DN	This value is attached to the LDAP base, and then used to search for users in the LDAP environment. It’s important to make sure that this value + the LDAP base lead to your user directory. An example of this would be the following: `OU=MyUsers` This, with the example LDAP base would mean that Runtime searches for users in the following directory: `OU=MyUsers,DC=MyCompany,DC=Amsterdam,DC=com`
User object filter	This setting allows you to filter the resulting users from the above DN configuration based on variables. This can be any variable as provided by the LDAP environment on any given users.
User display name attribute	This value from the LDAP environment will dictate what the user’s Display Name value in Runtime is.
User first name attribute	This value from the LDAP environment will dictate what the user’s First Name value in Runtime is.
User last name attribute	This value from the LDAP environment will dictate what the user’s Last Name value in Runtime is.
User name attribute	This value from the LDAP environment will dictate what the user’s Username value in Runtime is. This is also the value the user will need to provide in order to log into Runtime.
User e-mail attribute	This value from the LDAP environment will dictate what the user’s E-mail value in Runtime is.
User membership attribute	This value will be used to check which groups this user belongs to. Generally, for Active Directory configurations this value refers to a variable that contains the full distinguished name of a given group.
Groups Configuration	Description
Additional group DN	This value is attached to the LDAP base, and then used to search for groups in the LDAP environment. It’s important to make sure that this value + the LDAP base lead to your group directory. An example of this would be the following: `OU=MyGroups` This, with the example LDAP base would mean that Runtime searches for groups in the following directory: `OU=MyGroups,DC=MyCompany,DC=Amsterdam,DC=com`
Group object filter	This setting allows you to filter the resulting groups from the above DN configuration based on variables. This can be any variable as provided by the LDAP environment on any given groups.
Group name attribute	This value from the LDAP environment will dictate what the group’s Name value in Runtime is.
Group description attribute	This value from the LDAP environment will dictate what the group’s Description value in Runtime is.
Group membership attribute	This value will be used to check which users this group contains. Generally, for Active Directory configurations this value refers to a variable that contains the full distinguished name of a user contained within this group.

Save changes

Saves the LDAP configuration as currently defined by the user. This creates or modifies a physical JSON file located within the conf folder in the Runtime data folder named ldap-config.json. This does not trigger a synchronization of LDAP credentials.

Save and synchronize now

Saves the LDAP configuration as currently defined by the user, and then synchronizes Runtime with the LDAP environment. This creates or modifies a physical JSON file located within the conf folder in the Runtime data folder named ldap-config.json.

Test Filter

In order to see which results your current configuration yields, a user can press the Test Filter button to see which results are returned. This will print all fetched information below the LDAP configuration screen, divided into two separate tables: groups and users.

LDAP Default values

As an extra resource, a table of default values for various LDAP implementations is included below. This can be used when configuring LDAP if the existing implementation uses standard LDAP settings.

Defaults	Active Directory	OpenLDAP	OpenLDAP (Read-Only Posix Schema)	Apache Directory Server	Apple Open Directory	FedoroDS	Generic Directory Server	Novell eDirectory Server	OpenDS	Generic Posix/RFC2307 Directory (Read-only)	Sun Directory Server Enterprise Edition
User Object Class	user	inetorgperson	posixAccount	inetorgperson	posixAccount	posixAccount	inetorgperson	inetOrgPerson	inetorgperson	posixAccount	inetorgperson
User Object Filter	(&(objectCategory=Person)(sAMAccountName=*))	(objectclass=inetorgperson)	(objectclass=posixAccount)	(objectclass=inetorgperson)	(objectclass=posixAccount)	(objectclass=posixAccount)	(objectclass=inetorgperson)	(objectclass=inetorgperson)	(objectclass=inetorgperson)	(objectclass=posixAccount)	(objectclass=inetorgperson)
User Name Attribute	sAMAccountName	cn	uid	cn	uid	uid	cn	cn	uid	uid	cn
User Name RDN Attribute	cn	cn		cn			cn	cn	uid		cn
User First Name Attribute	givenName	givenName	givenName	givenName	givenName	givenName	givenName	givenName	givenName	givenName	givenName
User Last Name Attribute	sn	sn	sn	sn	sn	sn	sn	sn	sn	sn	sn
User Display Name Attribute	displayName	displayName	displayName	displayName	displayName	displayName	displayName	displayName	cn	displayName	displayName
User Email Attribute	mail	mail	mail	mail	mail	mail	mail	mail	mail	mail	mail
User Password Attribute	unicodePwd	userPassword	userPassword	userPassword	userPassword	userPassword	userPassword	userPassword	userPassword	userPassword	userPassword
User Unique ID Attribute	objectGUID	entryUUID	entryUUID	entryUUID	entryUUID	entryUUID	entryUUID	GUID	entryUUID	entryUUID	entryUUID

Group Object Class	group	groupOfUniqueNames	groupOfUniqueNames	groupOfUniqueNames	groupOfUniqueNames	groupOfUniqueNames	groupOfUniqueNames	groupOfNames	groupOfUniqueNames	groupOfUniqueNames	groupOfUniqueNames
Group Object Filter	(objectCategory=Group)	(objectclass=groupOfUniqueNames)	(objectclass=posixGroup)	(objectclass=groupOfUniqueNames)	(objectclass=posixGroup)	(objectclass=posixGroup)	(objectclass=groupOfUniqueNames)	(objectclass=groupOfNames)	(objectclass=groupOfUniqueNames)	(objectclass=posixGroup)	(objectclass=groupOfUniqueNames)
Group Name Attribute	cn	cn	cn	cn	cn	cn	cn	cn	cn	cn	cn
Group Description Attribute	description	description	description	description	description	description	description	description	description	description	description

Group Members Attribute	member	uniqueMember	memberUid	uniqueMember	memberUid	memberUid	uniqueMember	member	uniqueMember	memberUid	uniqueMember
User Membership Attribute	memberOf	memberOf	memberOf	memberOf	memberOf	memberOf	memberOf	groupMembership	memberOf	memberOf	memberOf

Using LDAP over SSL

LDAP over SSL is supported, but without configuration Runtime will return the following error:

[Root exception is javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]

In order to use secure LDAP, you will need to import the certificate used for SSL into your JRE cacerts file. This file can be found in your runtime installation under runtime\jdk\lib\security. Copy your SSL certificate to this folder.

extending our path to include the keytool

CODE

## By default, the keytool is not a part of PATH. We will need to add it. 

set path=%path%;<your file explorer's path to the runtime folder>\jdk\bin

example: 
set path=%path%;C:\Users\yoeri\Documents\DATPROF\Runtime\runtime-4.3.0\jdk\bin

Now that we can use the keytool, let's make the security folder our active directory.

Moving our current directory

CODE

cd <your system path to the Runtime security folder> 

example:

cd C:\Users\yoeri\Documents\DATPROF\Runtime\runtime-4.3.0\jdk\lib\security

You can use the cacerts file to store your certificates.

The cacerts file is protected by a password. The default password of the cacerts file is changeit. You should change this password into your own password for security reasons!

Changing the keystore password

BASH

keytool -storepasswd -keystore cacerts
Enter keystore password:  changeit
New keystore password:  new-password
Re-enter new keystore password:  new-password

Now, let's list the contents of our cacerts file.

Listing existing cacerts content

CODE

keytool -list -v -keystore cacerts

enter keystore password:new-password

You should now see a large amount of text print. These are all the existing certificates in cacerts. Now, we'll add our certificate.

Importing our certificate into cacerts

CODE

keytool -import -alias <the name of your certificate without its file extension> -keystore cacerts -file <the full file name of your certificate + extension>

example:

keytool -import -alias certificate -keystore cacerts -file certificate.crt

>Trust this certificate? [no]: yes
Certificate was added to keystore

Alternatively you can store your certificate elsewhere and supply a system path to this location for the -file command.

After this has been done, and your LDAP settings in Runtime have been adjusted to the right connection strings, LDAP over SSL will work. Restart Runtime to load your changes.

Don't forget to change your LDAP port to 636 (the default SSL port), and to change the LDAP url in your Runtime configuration to start with ldaps:// instead of ldap://