KX Control can be configured to integrate with LDAP to perform basic authentication and user group management. The functionality is especially useful in large systems where maintaining in KX Control a new set of credentials for each user becomes onerous.
Instead system administrators can configure KX Control to interface with their existing LDAP server and users can log in with those credentials. When a user logs into the system, they will be authenticated against the server instead of within KX Control. The functionality can also be configured to maintain user group membership on the system to mirror their LDAP roles.
To enable this functionality, the user can set the
DELTACONTROL_LDAP environment variable during installation. The variable should point to a configuration text file, usually stored in
delta-bin/config. If the system has already been installed, it can be added to the
delta.profile, and restarted to pick up the change.
The functionality leverages OpenLDAP to communicate with the server, so these libraries must be installed on the server.
The configuration file contains key-value pairs and typical values are shown in the table below.
|uri||ldap://10.18.1.11:389,ldap:10.18.1.12:389||Y||Comma-separated list of servers to communicate with. Use ldaps for encryption|
|timeout||3||N||Timeout (in seconds) for connection and search attempts. Default value is 3|
|bind||sAMAccountName||Y||Determines the authentication format to the server|
|domain||KX||N||Required if using AD and multi-domain mode is disabled|
|multidomain||no||N||Set to yes when using Active Directory and users split across multiple domains|
|globdn||dc=Kx,dc=com||Y||Base node of the LDAP tree to search for users|
|groupdn||ou=Groups,dc=Kx,dc=com||N||Base node to search for groups. Will default to globdn if not specified|
|groups||cn=Support,ou=Groups,dc=Kx,dc=com;cn=Dev..||N||List of group locations to check membership for.|
|checkgroups||no||N||Reject logins if user is not a member of any configured groups.|
|groupClass||group||N||Object type to look for when checking groups. Usually set to group for Active Directory and groupOfNames otherwise|
|memberClass||member||N||Field used to identify members within groups. Default is member|
|groupsFromUser||no||N||Check group membership by querying user when set to yes. Otherwise query each group|
|groupFieldInUser||memberOf||N||When group checking by user, the field to get groups from|
|userFilter||(objectCategory=person)||N||Filter to apply when searching for a users user groups|
A sample file is included below. Assumes the system is connecting to an Active Directory server, using a single-domain setup.
uri=ldap://10.18.1.11:389,ldap:10.18.1.12:389 bind=sAMAccountName domain=Kx multidomain=no globdn=dc=Kx,dc=com groupdn=ou=Groups,dc=Kx,dc=com groups=cn=Support,ou=Groups,dc=Kx,dc=com; cn=Dev Team,ou=Groups,dc=Kx,dc=com checkgroups=yes groupsFromUser=yes
From 4.6.0 LDAP can be configured to use multiple forests. This can be configured with minor changes to the LDAP configuration parameters.
By appending a distinct suffix to the field
globdn a grouping can be created to distinguish between forests.
bind can be treated in the same way.
uri_A=ldap://10.18.1.11:389,ldap:10.18.1.12:389 globdn_A=dc=Kx,dc=com bind_A=sAMAccountName domain_A=Kx uri_B=ldap://ds.example.com:389 globdn_B=dc=example,dc=com bind_B=CN domain_B=Kx multidomain=no groupdn=ou=Groups,dc=Kx,dc=com groups=cn=Support,ou=Groups,dc=Kx,dc=com; cn=Dev Team,ou=Groups,dc=Kx,dc=com checkgroups=yes groupsFromUser=yes
uri key specifies the LDAP server details. A comma-separated list is allowed to specify multiple. If one is unavailable, the login will attempt the other servers in order.
The connection can be encrypted by using
ldaps://. However this requires appropriate certs to be setup outside the application in order to communicate secure the connection.
timeout parameter tells the application how long to wait before aborting a connection attempt or query.
The configuration is slightly different depending on the LDAP server type.
Active Directory supports logins using a user's account name and domain, i.e.
Kx\jbloggs. The application can be configured to support single- or multi-domain setups. Assuming all users are placed in the tree under a single location, the
globdn should be set to encompass all of them.
- dc=example,dc=com - ou=people - dn=jbloggs - dn=jdoe - ou=placements - dn=msmith ..
The user should login to the application using just their account name, e.g.
jbloggs. The application will append the domain automatically.
bind=sAMAccountName domain=Kx globdn=dc=example,dc=com
The user should login with their domain and account, i.e.
bind=sAMAccountName multidomain=yes globdn=dc=example,dc=com
When using multi-domain mode, there is a Global Catalog that contains information across all domains in the LDAP forest. This should be used for the connection details so all users can be authenticated from the same server. The port of this server is usually 3268 so the
uri should be updated. The
groupdn may need to be updated to blank in order to search correctly.
With non-Active Directory servers, the users are generally stored in a flat structure in the tree.
- dc=example,dc=com - ou=people - uid=jbloggs - uid=jdoe ..
For this setup, use the parameters below in the configuration file. The
globdn needs to be set to the location containing all the users. There is no need to set values for
If the application is configured with LDAP groups, it can be used to mirror group membership on the LDAP server and setup local copies of these. This helps distinguish users in the application and establish role-based permissions. On startup Control will create local copies of each of the groups and when a user logs in, their local membership will mirror the upstream memberships. The membership check on the server, downloads the user's groups and adds them to the groups they're a member of and removes them from the others.
Once the local groups are created, the system administrators can setup the role permissions. The application will not download any role permissions from the server.
There are two modes of membership check with different configurations. The recommended approach looks up the user object and pulls the group membership from there. This approach should be more performant with less chance of permissions problems. The other approach searches for groups and checks the members of each against the login user.
The configuration would look like below. The application would look up the user, extract all the groups and match those against the
groups=cn=Support,ou=Groups,dc=Kx,dc=com;cn=Dev Team,ou=Groups,dc=Kx,dc=com groupsFromUser=yes groupFieldInUser=memberOf
The recommended approach uses the
groupFieldInUser to specify what field stores the group names. For example, if
jbloggs was a member of
Dev Team, the user object would contain.
memberOf=cn=Support,ou=Groups,dc=Kx,dc=com memberOf=cn=Dev Team,ou=Groups,dc=Kx,dc=com
The second approach extracts the user from each of the groups. The search works in a couple of steps;
- Searches for objects matching each of the specified
groupsparameter and where the object class matches
- Search performed under the
globdnif not specified
- Extracts the members from each group using the
- Compare the user list against the login user.
groups=cn=Support,ou=Groups,dc=Kx,dc=com;cn=Dev Team,ou=Groups,dc=Kx,dc=com groupsFromUser=no groupClass=group memberClass=member groupdn=ou=Groups,dc=Kx,dc=com
From version 4.0.2 of KX Control, generic APIs are provided to search the server to extract object attributes. The functions will search from a base location for specific objects and extract attributes. An example use case would be for extracting the username of all user objects under one tree node.
To get the username of all users that are members of groups
memberOf attribute can be used to filter via the API.
The underlying OpenLDAP call from KX Control uses
- KX Control must be configured to use LDAP
- The server connection must be initialized (by an initialization call using user credentials)
- The OpenLDAP libs have a maximum result size (external to KX Control configuration)
- Specific fields and paths will vary across installations and may change depending on what LDAP implementation is being used.
For details of the API signatures, please see the LDAP section of the Template API documentation.
For LDAP users authentication is offloaded to a LDAP server. In KX Control therefore the Authentication & Access Control tab will be unavailable for these users.
An email address can now be saved for LDAP users. This will be persisted in KX Control as well as on export and import of LDAP users.