SEC-LDAP Adapter
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.
The LDAP Adapter allows you to add, modify, delete and search for entries on local LDAP directories from RunMyProcess. It requires the Connector agent and the Protocol Manager to be installed and running. Please follow the SEC - Installation Guide.
1 Prerequisites
This guide assumes that the following is already in place:
- The SEC manager is running on the server and a tunnel is open and configured. You can find instructions on how to install and configure the SEC here
- The server has Java installed.
- The ping port on the manager is 4444 (this can be configured in the adapter and the manager).
- The manager is running on the same server as the adapter (127.0.0.1).
2 Installing and Configuring the Adapter
- Download and unzip the SEC LDAP zip file on your local server.
- You must navigate to [install-path]/configFiles and modify the handler.config and the LDAP.config files.
NOTE: It is recommended that the Adapter be installed in an "Adapters" folder inside the SEC installation path.
The handler.config file should look like this :
1 2 3 4 5 6 7 8 | #Generic Protocol Configuration protocol = LDAP protocolClass = com.runmyprocess.sec.LDAP handlerHost = 127.0.0.1 connectionPort = 5832 managerHost = 127.0.0.1 managerPort = 4444 pingFrequency = 300 |
Where :
- protocol is the name to identify our Adapter.
- protocolClass is the class of the Adapter.
- handlerHost is where the Adapter is running.
- connectionPort is the port of the adapter where data will be received and returned.
- managerHost is where the SEC is running.
- managerPort is the port where the SEC is listening for ping registrations.
- pingFrequency is the frequency in which the manager will be pinged (at least three times shorter than what's configured in the manager).
The LDAP.config file should look like this :
1 2 3 | #SMTP Configuration host=127.0.0.1 port=389 |
Where :
- host is the IP address of where the LDAP server is hosted
- post is the port on were the LDAP is running
3 Running the Adapter
You can now run the Adapter by executing the ldap.jar in the installed path :
1 | java -jar ldap.jar |
Note: Make sure that you have launched the Protocol Manager and that it's running on port 8080.
If everything is configured correctly, you can now place a request from RunMyProcess to search, add, modify or delete LDAP directory entries.
4 Testing the Adapter with a local directory
You can test the LDAP Adapter by submitting a POST request to http://127.0.0.1:8080/ with the following header fields:
Content-Type: **application/json**
Accept: **application/json**
and setting the content to be one of the example JSONObjects given in section 5.
5 Using the Adapter
To use the LDAP Adapter you should submit a POST to the ip address of the LDAP server with the following header fields:
Content-Type: **application/json**
Accept: **application/json**
The message body will be a JSONObject whose structure will depend on the operation you are trying to execute. JSON (JavaScript Object Notation) objects are declared within curly braces with object properties declared as "name":"value" pairs, separated by commas.
Each operation will require a nested JSONObject with the outer object specifying the protocol (LDAP) and the inner object specifying the operation specific parameters.
Each operation is considered below.
5.1 Searching a directory
The following properties can be set for this operation:
Property Name | Description |
---|---|
operation | This should be set to "SEARCH" |
baseDN | This is used to specify the Distinguished Name to be used as the search base. |
filter | This is the search criteria. If more that one criterion is required, the logical operators AND and OR can be used. |
scope | This specifies the search scope and can be "BASE" (search only the base entry), "ONE" (search entries in the level below the baseDN) or "SUB" (search the subtree underneath the baseDN). |
attributes | This specifies which attributes of matching entries to return. |
Examples
1 2 3 4 5 6 7 8 9 | ##SEARCH { "protocol":"LDAP", "data":{ "operation":"SEARCH", "baseDN":"DC=example,DC=com", "filter": "(&(|(objectClass=organizationalUnit)(objectClass=container)))" } } |
This example will search the directory at example.com for objects that belong to objectClass 'organizationalUnit' or 'container'.
1 2 3 4 5 6 7 8 9 10 11 12 | :::JSONRMP ##SEARCH { "protocol":"LDAP", "data":{ "operation":"SEARCH", "baseDN":"dc=example,dc=com", "filter": "(&(gn=J*))", "scope":"SUB", "attributes":["att1","att2"] } } |
This example will search the directory at example.com
for entries where the given name begins with a J
. It will search the entire subtree and return two attributes (att1
and att2
) for each matching entry.
5.2 Adding an entry to a directory
The following properties can be set for this operation:
Property Name | Description |
---|---|
operation | This should be set to "ADD" |
userDN | This is used to specify the Distinguished Name of the user that will authenticate to the directory. |
password | This is used to specify the password of the user that will authenticate to the directory. |
ldif | An LDIF record containing the data for the new entry. |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | ##ADD { "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==" ] } } |
This example will authenticate as an 'admin' user on the directory at example.com
and add a new entry (a new user account).
5.3 Changing an entry in a directory
The following properties can be set for this operation:
Property Name | Description |
---|---|
operation | This should be set to "MODIFY" |
userDN | This is used to specify the Distinguished Name of the user that will authenticate to the directory. |
password | This is used to specify the password of the user that will authenticate to the directory. |
ldif | An LDIF record specifying which attributes to change and their new values. |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | ##MODIFY { "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" ] } } |
This example will authenticate as an 'admin' user and modify the 'description' attribute with the new value 'MODIFY Example'.
5.4 Deleting an entry from a directory
The following properties can be set for this operation:
Property Name | Description |
---|---|
operation | This should be set to "DELETE" |
userDN | This is used to specify the Distinguished Name of the user that will authenticate to the directory. |
password | This is used to specify the password of the user that will authenticate to the directory. |
deleteDN | This is used to specify the Distinguished Name of the entry to be deleted. |
Example
1 2 3 4 5 6 7 8 9 10 | ##DELETE { "protocol":"LDAP", "data":{ "operation":"DELETE", "userDN":"cn=admin,dc=example,dc=com", "password":"password", "deleteDN": "cn=Malcolm Haslam,ou=People,dc=example,dc=com" } } |
This example will authenticate as an admin
user on the directory at example.com
and will delete the entry that has the Common Name 'Malcolm Haslam' at the Organizational Unit 'People'.
5.5 Response
The expected return is a JSON object that should look like this:
1 2 3 4 | { "SECStatus":200, "Result":"YOUR LDAP RESULT INFORMATION" } |
6 Troubleshooting
If you are having problems, make sure that:
- the Protocol Manager and the LDAP Adapter have the same ping port configuration (4444 by default).
- the Protocol Manager is running on the port you are posting to (8080 by default) with no errors on the console.
- navigating to http://127.0.0.1:8080/ on your browser returns a success message and the LDAP adapter.
7 Automatic launching.
In order to access adapter resources from RunMyProcess, the Connector Agent, Protocol Manager and the required adapters must be running. You can create a script (shell script or bat file) to launch all resources. For example, in windows, you can create a bat file that looks like this:
1 2 3 4 5 6 7 | @echo off cd %SECPATH%\data-connector-agent\bin call start "Tunnel" runagent.bat cd %SECPATH%\jetty7.6.11 start "Manager" java -jar start.jar cd %SECPATH%\Adapters\LDAP start "LDAPAdapter" java -jar LDAP.jar |
Note: for the example presented note that the %SECPATH% environment variable should point to the installation path of the SEC. Also note that the Adapter is inside an "Adapters" folder in the SEC installation folder. This path structure is the recommended best practice.
Please give details of the problem