Configuration

Setting up a DirX Directory LDAP server for operation as a DLP server requires two configuration tasks:

Configuring the ldapProxyMode attribute in the LDAP server configuration subentry
Setting up the DLP server configuration file

LDAP Proxy Mode Attribute

The ldapProxyMode attribute is an optional single-valued attribute that controls whether the LDAP server runs as:

A normal LDAP server
A DLP server without support for SSL/TLS backends
A DLP server with support for SSL/TLS backends

If the ldapProxyMode attribute is not present in the LDAP configuration subentry, the LDAP server runs as a plain LDAP server.

Specify one of the following integer values:

0 – Run as a normal LDAP server.
1 – Run as a DLP server that does not support SSL/TLS backends. In this mode, the SSL/TLS functionality for the DLP server backend is not initialized which saves time and memory and does not require the configuration of SSL/TLS key material.
2 – Run as a DLP server that supports SSL/TLS backends. This mode requires the presence of valid SSL/TLS key material; in particular, the necessary trusted CA certificates must be provided in order to set up SSL/TLS connection to LDAPS backend servers. If your configuration currently uses plain connections but you expect to upgrade to using SSL/TLS in the near future, we recommend setting this mode and providing the required SSL/TLS key material.

The default value is 0.

You cannot change from mode 1 to mode 2 during DLP server runtime, but you are allowed to change from mode 2 to mode 1 (downgrade) during DLP server runtime. To change the mode from 1 to 2, you must restart the LDAP server process. A value of 0 always switches to plain LDAP server mode.

Note that proxy modes 1 and 2 have no effect on the LDAP frontend’s SSL/TLS connectivity; that is, even if mode 1 is set, LDAP clients can still connect to the DLP server via SSL/TLS. The setting only prohibits the use of SSL/TLS when forwarding the request to the target servers.

Abbreviation

LPROM

LDAP Name(s)

ldapProxyMode

Syntax (DAP)

Integer

Syntax (LDAP)

Integer (LDAP Style)

Example (DAP)

LPROM=1

Example (LDAP)

ldapProxyMode=2

DLP Server Configuration File

To run the LDAP server as a DLP server, its backend configuration must be defined in a JavaScript Object Notation (JSON)-formatted configuration file named ldap_proxy.json which is located by default at install_path/ldap/conf.This file defines:

The LDAP server process to be enabled as a DLP server
The target systems to be used by the DLP server
The defaults to be applied to operations handled by the DLP server
The operation-forwarding and rewriting rules to be applied when running as a DLP server

The next sections describe configuration file syntax and how to debug problems with JSON syntax.

DLP Server Configuration File Syntax

The DLP server configuration file is a text file that you can edit with any common text editor. It consists of object definitions arranged in a single array. The array starts with an opening square bracket ([) and ends with a closing square bracket (]). Array elements (called objects) are separated by commas (,). Each object starts with an open curly brace (\{) and ends with a closing curly brace (}).

Thus, the fundamental layout of the configuration file looks like this:

[ {_O1_},{_O2_},…{On} ]

Where O1…On are JSON objects.The array can have any number of objects in an arbitrary order.Each object can have its own different syntax.

Each single object consists of a list of key-value pairs separated by colons (:).

All keys are strings, while the values can be integers, simple strings or arrays of strings like:

      {
          “key1”    :   “value1”,             // string
          “key2”    :   [ “elem1”, “elem2” ], // array of 2 strings
          “key3”    :   4711,                 // integer
          “key4”    :   “value4”              // another string
      }

Objects can also have values, such as:

      {
          “key5”    :   “value5”,
          “key6”    :   123,
          “key7”    :   {                     // sub-object as value
                          “option1” : 0,
                          “option2” : “foobar”
                        }
      }

Within an object, the order of key-value pairs is arbitrary. Each key-value pair is separated by a comma (,).

You can use C/C++-style comments in the file; that is, if the two characters “//” are found, the JSON parser will ignore the rest of the current line. The same is valid if the two characters “/” are found; in this case, the parser will ignore everything until it finds the two chars “/” (such comments can span multiple lines.)

Locating JSON Syntax Errors

If the DLP server configuration file does not contain valid JSON syntax, the LDAP server will not start. When JSON syntax errors are detected, the JSON parser will report them with messages like:

FATAL! JSON parsing error.
Illegal Proxy-Config file!! (must start as an array of objects)

FATAL: Cannot read PROXY configuration (ldap_proxy.json)!

LDAP Server exit (ExitCode: 19 Reason: FATAL: Cannot process PROXY configuration! Server stopped.)

Unfortunately, the parser does not provide more details about the location of the error. Thus, it requires some manual effort to locate the problem.

The first step should be to look at the JSON file and make sure that all required commas (,) are present. Most of the errors are due to missing commas. Remember that all objects must be separated by commas, all components within an object must be separated by commas and all server arrays must be separated by commas.

Another cause of errors is missing trailing quotation marks for strings; for example, “LDAP2.

Take care, too, that you do not specify integers (for example, 4711) as strings (for example, “4711”).

You can also set the environment variable

DIRX_JSON_DEBUG=1

and then restart the DLP server.This action writes the JSON parsing process to stderr so that you can view the parser’s progress and identify the possible error location where parsing aborts.

If these steps don’t work, you can use an online JSON checker like

http://json.parser.online.fr/

The checker tries to analyze the syntax and show where the problem may exist.Be sure to remove any comments before using the checker, as JSON usually does not allow C/C++ comments.

DLP Server Configuration Objects

The DLP server configuration file supports the following object types for defining the information necessary for DLP server backend operation:

LdapProxy – defines which LDAP server process runs as a DLP server
LdapServer – defines a target server
AttributeList – defines a list of attributes
Defaults – defines explicit defaults to be applied to all operations handled by the DLP server
ProxyRule – defines operation forwarding and LDAP request/result rewriting rules

LdapProxy and LdapServer are mandatory objects.The ProxyRule objects are optional.When specified, they allow the DLP server to redirect LDAP client requests from particular users or with particular operation types to particular LDAP servers and to rewrite incoming client requests and outgoing server results.The Defaults object is also optional; if it is not used, the DLP server uses its internal defaults.Note that no matter what the DLP server configuration file contains, it must be specified as an array of 1 to n objects as required by JSON syntax.

Each object must define two keys:

The object key – the value of this key is a string and defines the object’s type and its components.
The name key – the value of this key is a unique string that gives the object a symbolic name.

Additional key-value pairs may be mandatory depending on the object.

The LdapProxy Object

The LdapProxy object is a mandatory object in the DLP server configuration file and specifies the LDAP server to be enabled as a DLP server at process startup. Here is an example:

{
   "object"      : "LdapProxy",
   "name"        : "ldapConfiguration",
   "LBservers"   : [ "LDAP1", "LDAP2", "LDAP3" ]
}

In the object definition:

The object key is mandatory and must be the string LdapProxy.
The name key is mandatory and must be the LDAP configuration subentry name of the LDAP server to be configured as a DLP server. By default, this name is ldapConfiguration.
The LBservers key is mandatory and defines the target servers (1-n) to which the DLP server can forward requests from users that do not match any of the user-routing or operation-routing rules defined in the DLP server configuration file. Its value is an array of symbolic LDAP server names that must match the names of LdapServer objects defined in the same configuration file. Note that the value must be specified as an array even if only one LDAP server is listed or an error occurs and the LDAP server will not start. If a user is controlled by a user- or operation-routing rule, DLP server ignores the LBservers value(s). The method the DLP server uses to select from a list of LB-servers for forwarding depends on the settings of loadbalance and failover keys in the Defaults object definition. See the description of the Defaults object definition in this guide for details.

The LdapServer Object

The LdapServer object defines a target LDAP server to which the DLP server can forward incoming client requests. Here is an example:

{
   "object"   : "LdapServer",    // this is a target server
   "name"     : "LDAP3”,         // symbolic name
   "protocol" : "ldap",          // use plain connection
   "host"     : "192.168.10.7",  // target host or IP
   "port"     :  389             // target port
}

In the object definition:

The object key is mandatory and must be the string LdapServer.
The name key is mandatory and can have any string value as long as the value is unique. The name is used in other objects in the configuration file (for example, in LdapProxy objects) to refer to a specific target server.
The protocol key is mandatory and defines how the request is forwarded to the target server. The value ldap results in unencrypted plain socket mode. The value ldaps results in an SSL connection to the target server. When ldaps is used, the DLP server must run in ProxyMode=2 and suitable TLS key material must be provided.
The host key is mandatory and defines the IP or DNS name of the target LDAP server.
The port key is mandatory and defines the port of the target LDAP server.

If the target server is to be addressed via SSL/TLS, the ssl key must also be defined. Here is an example:

{       // Defines an SSL LDAP server
   "object"   : "LdapServer",
   "name"     : "LDAP2",
   "protocol" : "ldaps",        // use SSL/TLS
   "host"     : "192.168.10.8",
   "port"     :  636,           // secure port
   "ssl"      : {
       "trusted_ca_file" : "C:/Program Files/DirX/Directory/conf/testCA.pem",
       "ssl_protocol"    : "TLSv12",
       "ssl_cipher"      : "HIGH"
   }
}

The value of the ssl key is a sub-object (enclosed in curly braces (\{ }) with the following mandatory components:

ssl_protocol – defines which SSL/TLS protocol to use. Possible values are TLSv10, TLSv11, TLSv12 or TLSv13. The value is case sensitive. Make sure that the target server supports and allows the selected protocol.
ssl_cipher – a string that defines the cipher list. The DLP server uses OpenSSL to contact target servers via SSL/TLS. The recommended value for TLS versions ⇐ TLSv12 is HIGH, which typically excludes unsafe ciphers from being selected. If TLSv13 is chosen special ciphers must be selected. See the OpenSSL documentation for information on possible cipher values.
trusted_ca_files – defines the full qualified PEM file name that contains the chains of trusted public CA certificates used to verify the received server certificates from the target servers during the SSL handshake.

The DLP server currently supports only server-based SSL/TLS authentication against the backend, which means that the client verifies the server’s certificate but not vice versa. Client-based SSL/TLS authentication against the backend is not supported. Thus, target servers that require client-based authentication should not be configured as target servers.

The AttributeList Object

You can use the AttributeList object to define a list of attributes for the showonly action of the search.res.attributes token of a rewriting rule in operations handled by the DLP server. Here is an example:

{       // Defines AttributeLists
   {
      "object"     : "AttributeList",
      "name"       : "ATTRLIST1",
      "attributes" : [ "sn", "surName", "cn", "commonName", "tn",
                       "telephoneNumber", "title", "dxidummy" ]
   },
   {
      "object"     : "AttributeList",
      "name"       : "ATTRLIST2",
      "attributes" : [
                       "tn",
                       "telephoneNumber",
                       "title",
                       "dxidummy",
                       "description
                     ]
   }
}

In the object definition:

The object key is mandatory and must be the string AttributeList.
The name key is mandatory and must be a unique string within multiple AttributeList definitions.
The attributes key is a list of LDAP attribute names separated by a comma (,) and enclosed in square brackets [ ]. If an attribute has multiple LDAP names, for example, telephoneNumber and tn, all LDAP names must be specified to ensure the visibility in the result. OIDs cannot be specified instead of the LDAP name.

Attribute lists are only supported for the showonly action.

Keep in mind that the order of multiple actions is important that is the output of an action is the input of the subsequent action.

The Defaults Object

You can use the Defaults object to define explicit defaults to be applied to all operations handled by the DLP server. If used, the Defaults object must be the first object defined in the DLP server configuration file.

All of the values in the Defaults object are integers. Here is an example:

{
   "object"     : "Defaults",
   "LdapProxy"  : {
       "lb_failover"  : 1,
       "lb_balance"   : 1
   }
   "TLSLogging"       : 0,
   "Tracing"          : 0,
   "ConnectTimeout"   : 5,
   "OfflineRetryTime" : 30
   "JSONCodeSet"      : 1
   "NotifyRewrite"    : 1
   "NullParamStr"     : "NULL"
   "DiscloseTarget"   : 1
}

In the Defaults object definition, the object key value is mandatory and must be Defaults. Although the other keys are optional, we recommend specifying all of them in the object definition. These keys include:

LdapProxy.lb_failover, which determines whether or not the DLP server contacts the next server from the LBServer list defined in the LdapProxy object using a round-robin scheme. By default (LdapProxy.lb_failover is set to 1), if more than one LB-server is configured and an I/O error occurs to a selected target server, the DLP server fails over to the next server. If this one also fails, it fails over to the next, and so on until all servers have been tried. To change this behavior, set the property LdapProxy.lb_failover to 0. Now the operation returns an error if the selected target server raises an I/O error.
The LdapProxy.lb_balance, which determines whether or not the DLP server applies a round-robin scheme to select the primary server from the LBserver list specified in the LdapProxy object definition. By default (LdapProxy.lb_balance set to of 1), if more than one LB-server is configured, each user that has no other governing rule is forwarded to one of the LB-servers using round-robin selection. For example, suppose C1, C2, C3, C4 are LDAP client users that are not controlled by other rules (the numbers indicate the time sequence in which the users perform their binds) and LBservers lists LDAP1, LDAP2, and LDAP 3 servers. DLP server forwarding will be C1 to LDAP1, C2 to LDAP2, C3 to LDAP3, C4 to LDAP1. To change this default behavior, set the LdapProxy.lb_balance property to 0. Now the DLP server forwards every user request that has no governing rule to the same primary server (the first server in the LBserver list, which is LDAP1 in this case).
TLSLogging, which controls whether (1) or not (0) the DLP server generates a readable log file install_path*/ldap/log/proxyssl*pid*.txt* where pid is the PID of the DLP server process. (The default value is 0.) Note that enabling TLSLogging will slow down performance significantly and is only intended for error analysis.
Tracing, which controls whether (1, 2 or 3) or not (0) tracing information is sent to stderr and the verbosity of tracing information sent (1, 2 or 3). The higher the value, the more verbose the tracing information generated. (The default value is 0.) Enabling Tracing will slow down performance noticeably.
ConnectTimeout, which defines the number of seconds the DLP server waits for a TCP connect to succeed before it tries another server (if available and failover is allowed) or the operation fails. The default value is 5 seconds. Be careful not to supply a value that’s too low, as it may lead to frequent timeouts when network performance is poor or the contacted target server is under high load. For a description of how this setting affects DLP server operation, see the section "Connect Timeout".
OfflineRetryTimeout, which defines the number of seconds for which the DLP server disables a failed target server for further selection. The default value is 60 seconds. For a description of how this setting affects DLP server operation, see the section "Offline Handling and Server Retry".
JSONCodeSet, which specifies the code set in which the DLP server configuration file is encoded (the configuration file is a JSON file, as described in the “Configuration” chapter). A value of 0 indicates to the DLP server that the configuration file is encoded in Latin-1 and needs to be converted to UTF-8 format for LDAP, which only supports the UTF-8 code set. A value of 1 indicates that the configuration file is encoded in UTF-8 and needs no conversion. The default value is 1 (UTF-8). For a description of how this setting affects DLP server operation, see the “Operations” chapter.
NotifyRewrite, which controls whether (1) or not (0) notification of request/result rewriting is included in the LDAP response error message. When set to 1, the client receives a string like Proxy-Modified=yes, which indicates that the DLP server has modified the request or the result. Set this key to 0 to hide information from clients about DLP server changes to requests and results.
NullParamStr, which defines a placeholder string for an empty rewrite action parameter in a DLP server rewriting rule. The default placeholder string is NULL. For a description of how this setting applies to DLP server rewriting rules, see the section “Protocol-Specific Actions” in the chapter “Proxy Rules”.
DiscloseTarget, which controls whether (1) or not (0) the DLP server identifies the target server that processed the LDAP request in the LDAP response message. For example, when set to 1, the following output is returned for the following dirxcp command:

dirxcp> bind -prot ldapv3 -user cn=richter,ou=sales,o=pqr -auth simple -address localhost:8080 -pass abc123
{{LDAP-Result: Bind succeeded. (Proxy-Target:LDAP2)}}

Note that TLSLogging and Tracing produce a lot of output and slow down performance drastically. They are intended to be used only for error analysis and not for normal operation.

The ProxyRule Object

The ProxyRule object is an optional object in the DLP server configuration file that specifies a rule to be applied to an LDAP operation. A ProxyRule object can specify:

Rules for operation forwarding based on the user’s DN or on the operation type
Rules for rewriting an LDAP client request or the result returned by the target LDAP server.

Here are examples of ProxyRule object definitions for each of these rules:

{
   // user-routing rule: redirect user ‘richter’ to LDAP1
   "object"      : "ProxyRule",
   "ruleType"    : "UserRouting",
   "name"        : "USERROUTING1",
   "condition"   : "(user=cn=richter,ou=sales,o=pqr)",
   "actions"     : [ "forwardto(LDAP1)" ],
   "loadbalance" : 1,
   "failover"    : 1
},

{
   // operation-routing rule: redirect ADDs to LDAP2
   "object"    : "ProxyRule",
   "ruleType"  : "OprRouting",
   "name"      : "OPRROUTING2",
   "condition" : "opr.req.type=add",
   "actions"   : [ "singleforwardto(LDAP2)" ],
   "failover"  : 0,
   "keepconn"  : 1
},

{
    // request rewriting rule: change o=my-company to o=pqr for search bases
   "object"    :  "ProxyRule",
   "ruleType"  :  "ReqRewrite",
   "name"      :  "ReqRewrite1",
   "condition" :  "opr.req.type=search",
   "actions"   :  [ "search.req.baseObject.replace(o=my-company,o=pqr,NULL)" ]
}

{
   // result rewriting rule: remove sn=Digger from any search result
   // add description=blabla to all result entries
   "object"    :  "ProxyRule",
   "ruleType"  :  "ResRewrite",
   "name"      :  "Test 04",
   "condition" :  "opr.req.type=search",
   "actions"   :  [ "search.res.attributes.del(sn,Digger,NULL)",
                 "search.res.attributes.add(description,blabla,NULL)" ]
}

In the object definition:

The object key is mandatory and must be the string ProxyRule.
The ruleType key is mandatory and must be one of the following strings:
UserRouting - defines a rule for operation forwarding based on the user’s DN
OprRouting - defines a rule for operation forwarding based on the operation type
ReqRewrite – defines a rule for modifying the data in an incoming client request
ResRewrite – defines a rule for modifying the data in an outgoing result of a client request
The name key is mandatory and can have any string value as long as the value is unique.
The condition key is mandatory and specifies the selection criteria that an LDAP operation must satisfy in order for the actions specified in the actions key to be executed on the operation. Condition values are specified in LDAP filter string format; the value depends on the value of the ruleType key:
UserRouting, OprRouting - the condition value selects for forwarding the LDAP operation to a target server
ReqRewrite, ResRewrite - the condition value selects for modifying a component of the LDAP operation

Rule conditions follow the syntax of LDAP strings and are evaluated just like LDAP filters (including nested filters with and/or/not). The only difference is that the assignments in the filter are well-defined keywords (for example, wcuser or opr.req.type) instead of attribute types. See the chapter “Proxy Rules” for details on how to specify rule conditions for each rule type.

The actions key is mandatory and defines the operations to be performed on the LDAP operation if it matches the rule condition selection criteria. An action is defined as a JSON array; the value depends on the ruleType value:
UserRouting, OprRouting – the action is a forwarding operation to a selected set of LDAP servers or a general action, such as denying the request. See the descriptions of the user- and operation-routing rules in the chapter “Proxy Rules” for details on how to specify a forwarding action.
ReqRewrite, ResRewrite – the action is a rewriting operation for a specific component of an LDAP operation – for example, to change the base object of an incoming search request - or a general action, such as denying the request. Multiple actions can be defined for an individual rule and are executed in the order in which they are defined. See the description of the rewriting rules in the chapter “Proxy Rules” for details on how to specify rewriting actions.

A ProxyRule object definition can contain additional keys depending on the value of the ruleType key. See the descriptions of the different rule types in the chapter “Proxy Rules” for details.

The configuration file can contain any number of ProxyRule object definitions. More than one rule may be applied to an operation if it matches multiple rule conditions. Rules are evaluated and executed in the order in which they appear in the configuration file. See the chapter “Proxy Rules” for examples of this process.

The DLP server allows Latin-1 characters like the German umlaut to be used in proxy rule conditions and actions and converts them to UTF-8 format before passing them to LDAP, which only supports the UTF-8 encoding. The value of the JSONCodeSet key in the Defaults object definition indicates to the DLP server whether or not it should make this conversion. Consequently, the ProxyRule object definitions in a DLP server configuration file must all be in the same character set.

Rule conditions and actions may need to use characters that LDAP, JSON or the proxy rule action syntax define as special characters. These characters require special handling in the proxy rule definition. See the section “Handling Special Characters in Rule Conditions and Actions” in the chapter “Proxy Rules” for a description of these special characters and how to specify them in proxy rule definitions.