LDAP Adapter
The LDAP adapter is used to add, modify, delete, and search entries on local LDAP directories from RunMyProcess DigitalSuite.
LDAP (Lightweight Directory Access Protocol) is a protocol used over TCP/IP for accessing directory services. You can learn more about LDAP at ldap.com.
Prerequisites
The following prerequisites must be fulfilled to install and run the LDAP adapter:
-
You must install the adapter on a local system in your environment. This can either be the system where you have installed the DigitalSuite EnterpriseConnect Agent, or a different one which is able to connect to the Agent's host.
-
You can install the adapter several times in your environment, for example, for testing purposes. The identifier of the adapter (
protocol
setting in thehandler.config
configuration file) must be unique for each of the installations. -
The local LDAP server managing the directory you want to work on must be running and configured to allow access by the adapter.
Installing the Adapter
To install the adapter:
-
Download the following ZIP file:
unified-adapter-[version].zip
[version]
is the current version numberThe ZIP file contains executables, licences, configuration files, and reference files for several adapters.
-
Extract the ZIP file to a local folder. The following path is recommended:
[parent-folder]\adapters\ldap
[parent-folder]
is a folder of your choice. If the EnterpriseConnect Agent is installed on the same machine, use its installation folder as the[parent-folder]
, for example,C:\ProgramFiles (x86)\dsec-agent
. -
Copy the configuration files for the LDAP adapter,
LDAP.config
andhandler.config
, from theconfigFiles\ldap.reference
subfolder to theconfigFiles
folder, for example:copy configFiles\ldap.reference\*.config configFiles
Overwrite existing files in the
configFiles
folder. -
If desired, delete obsolete files. Only the following folders and files are required in the
ldap
folder to use the adapter:ldap ├── configFiles │ ├── handler.config │ └── LDAP.config ├── lib │ └── unified-adapter-[version].jar └── log.properties
In addition, we recommend you keep the following:
runAdapter.bat
batch file for starting the adapter on Microsoft Windowsldap.reference
subfolder in theconfigFiles
for reference purposes
Configuring the Adapter
Configuration settings for the LDAP adapter are required in the following configuration files:
Edit the files with a plain text editor.
handler.config
The handler.config
file contains general configuration settings for connecting the adapter to the EnterpriseConnect Agent:
#Generic Protocol Configuration
protocol = LDAP
protocolClass = org.runmyprocess.sec2.LDAP
agentHost = 127.0.0.1:8080
pingFrequency = 1000
adapterConnectionInterval = 1000
offlineLogsMaxSize = 100
maxNumberOfLogsInBatch = 100
clusterEnabled = false
clusterAgentsHttpAddressList = localhost:8071,localhost:8072,localhost:8073
The settings have the following meaning:
protocol
: The identifier of the adapter. If you install the adapter several times in your environment, the identifier must be unique for each of the installations, for example,LDAP1
andLDAP2
.protocolClass
: The adapter's Java class.agentHost
: The IP address and port of the EnterpriseConnect Agent.pingFrequency
: The frequency in milliseconds in which the adapter pings the EnterpriseConnect Agent.adapterConnectionInterval
: The frequency in milliseconds in which the adapter tries to connect to the EnterpriseConnect Agent.offlineLogsMaxSize
: The maximum number of log entries that the adapter collects locally and sends to the EnterpriseConnect Agent when it re-connects to it after it was disconnected.maxNumberOfLogsInBatch
: The maximum number of log entries the adapter sends to the EnterpriseConnect Agent at a time. A value of0
means that the number of log entries sent at a time is unlimited.clusterEnabled
:true
if the EnterpriseConnect Agent is configured and running as a cluster,false
otherwise.clusterAgentsHttpAddressList
: The IP addresses and ports of the EnterpriseConnect Agent cluster, ifclusterEnabled
is set totrue
.
LDAP.config
The LDAP.config
file contains specific settings for the adapter:
#LDAP Configuration
host=127.0.0.1
port=389
ssl.enabled=false
ssl.trustore.path=configFiles/truststore_ldap.jks
The settings have the following meaning:
host
: The host name or IP address of the LDAP server to be used.port
: The port of the LDAP server.ssl.enabled
:true
if the adapter is to use SSL to connect to the LDAP server,false
otherwise.ssl.trustStore.path
: The path and name of the local truststore that holds the certificate of the LDAP server to be used for SSL connections, ifssl.enabled
is set totrue
. For example:ssl.trustStore.path=configFiles\\truststore_ldap.jks
on Microsoft Windows, orssl.trustStore.path=configFiles/truststore_ldap.jks
on Linux
To create the truststore:
-
On the LDAP server, export the certificate to a file in DER or Base64 encoded format.
-
Create a truststore based on the certificate file, for example, using the Java
keytool
command:keytool -importcert -keystore truststore_ldap.jks -alias truststore_ldap_alias -file .\exported.cer -noprompt
-
Copy the truststore to the
configFiles
subfolder of the adapter's installation folder and adapt the settings in theLDAP.config
file accordingly.
Starting the Adapter
The adapter needs to be running to be able to access the local LDAP directory.
Before you start the adapter, make sure that the DigitalSuite EnterpriseConnect Agent is running.
To start the adapter:
-
Change to the
ldap
installation folder. -
Execute the following command, depending on the operating system:
-
On Microsoft Windows: Execute the
runAdapter.bat
batch file. -
On Linux: Execute the following command directly, or create and execute a corresponding shell script to do so:
java -XX:+UseG1GC -XX:+ExitOnOutOfMemoryError -Djava.util.logging.config.file=./log.properties -cp lib/*: org.runmyprocess.sec2.AdapterHandler
-
Using the Adapter
If everything is configured and running correctly, you can place requests to the local LDAP server from RunMyProcess DigitalSuite through the EnterpriseConnect Agent and the LDAP adapter. Follow the examples below to search, add, modify, or delete LDAP directory entries.
Request: POST
on http://[agent-host]:[port]/
, where [agent-host]
and [port]
are the IP address and port of the EnterpriseConnect Agent.
Content Type: application/json
Accept: application/json
Content (examples):
The message body is a JSON (JavaScript Object Notation) object whose structure depends on the operation to be executed. Each operation requires a nested JSON object with the outer object specifying the protocol, and the inner object defining the operation-specific parameters.
Some examples are described below. You can find similar sample requests in the ldap.reference\InputJSONExample.txt
file in the ldap
installation folder.
SEARCH - searching the LDAP directory
The following parameters can be set for this operation:
Parameter Name | Description |
---|---|
operation | SEARCH |
baseDN | The Distinguished Name to be used as the search base. |
filter | The search criteria. If more that one criterion is required, the logical operators AND and OR can be used. |
scope | The search scope. Can be BASE to search only the base entry, ONE to search the level below baseDN , or SUB to search the subtree underneath baseDN . |
attributes | Specifies which attributes of matching entries to return. |
Examples:
{
"protocol":"LDAP",
"data":{
"operation":"SEARCH",
"baseDN":"DC=example,DC=com",
"filter": "(&(|(objectClass=organizationalUnit)(objectClass=container)))"
}
}
The example above searches the directory at example.com
for objects that belong to the organizationalUnit
or container
object classes.
{
"protocol":"LDAP",
"data":{
"operation":"SEARCH",
"baseDN":"dc=example,dc=com",
"filter": "(&(gn=J*))",
"scope":"SUB",
"attributes":["att1","att2"]
}
}
The example above searches the directory at example.com
for entries where the given name
(gn
) begins with a J
. The search walks through the entire subtree of example.com
and returns two attributes (att1
and att2
) for each matching entry.
ADD - adding an entry to the LDAP directory
The following parameters can be set for this operation:
Parameter Name | Description |
---|---|
operation | ADD |
userDN | The Distinguished Name of the user to be authenticated with the directory. |
password | The password of the user to be authenticated with the directory. |
ldif | An LDIF record containing the data for the new entry. |
Example:
{
"protocol":"LDAP",
"data":{
"operation":"ADD",
"userDN":"cn=admin,dc=example,dc=com",
"password":"password",
"ldif": [
"dn: cn=Malcolm Haslam,ou=People,dc=example,dc=com",
"cn: Malcolm Haslam",
"gidnumber: 503",
"givenname: Malcolm",
"homedirectory: /home/users/3mhaslam",
"objectclass: inetOrgPerson",
"objectclass: posixAccount",
"objectclass: top",
"sn: Haslam",
"uid: mhaslam",
"uidnumber: 1013",
"userpassword: {MD5}jVneVUVGdJTyI25JIfooag=="
]
}
}
The example above authenticates the admin
user with the directory at example.com
and adds a new entry (user account).
MODIFY - changing an entry in the LDAP directory
The following parameters can be set for this operation:
Parameter Name | Description |
---|---|
operation | MODIFY |
userDN | The Distinguished Name of the user to be authenticated with the directory. |
password | The password of the user to be authenticated with the directory. |
ldif | An LDIF record specifying the attributes to change as well as their new values. |
Example:
{
"protocol":"LDAP",
"data":{
"operation":"MODIFY",
"userDN":"cn=admin,dc=example,dc=com",
"password":"password",
"ldif": [
"dn: dc=example,dc=com",
"changetype: modify",
"replace: description",
"description: MODIFY Example"
]
}
}
The example above authenticates the admin
user and changes the description
attribute of example.com
to the new value, MODIFY Example
.
DELETE - deleting an entry from the LDAP directory
The following parameters can be set for this operation:
Parameter Name | Description |
---|---|
operation | DELETE |
userDN | The Distinguished Name of the user to be authenticated with the directory. |
password | The password of the user to be authenticated with the directory. |
deleteDN | The Distinguished Name of the entry to be deleted. |
Example
{
"protocol":"LDAP",
"data":{
"operation":"DELETE",
"userDN":"cn=admin,dc=example,dc=com",
"password":"password",
"deleteDN":"cn=Malcolm Haslam,ou=People,dc=example,dc=com"
}
}
The example above authenticates the admin
user with the directory at example.com
and deletes the entry with the common name (cn
) Malcolm Haslam
in the organizational unit People
.
Response
For each of the operations, the expected return is a JSON object that looks as follows:
{
"SECStatus":200,
"Result":"YOUR LDAP RESULT INFORMATION"
}
Please give details of the problem