LDAP Adapter
Functionality
The LDAP-adapter allows TrustBuilder to perform the following operations on a directory server:
- Authentication
- Search
- Add / Delete
- Modify
- Password manipulations
Prerequisites
TrustStore
A truststore is required if SSL is used for communication to the LDAP. The truststore can be configured on different levels: More information about trust stores refer to the KeyStore and TrustStore chapter.
Configuration
Parameter | Description | Required |
---|---|---|
GLOBAL SETTINGS | ||
Adapter Type | The type of server to connection to. Possible values are RO and RW (default is RW).
|
x |
AdapterUniqueID | Unique name assigned to this adapter; the name is used to reference
the adapter in the workflow.
The ID has following requirements:
|
x |
SERVER SETTINGS | ||
Priority | Loadbalancing chapter | x |
Address | URL or IP of the backend LDAP Server | x |
Port | TCP Port of the backend LDAP Server | x |
Name | Name used for logging purposes | x |
ConnectionPool | A Connection pool is used to enhance the performance by reusing a
previously established connection. The property can have the following values:
|
x |
SecurityProtocol | SSL protocol version to be used for connection to the backend. More information about trust stores refer to the KeyStore and TrustStore chapter. | x |
Authentication | ||
DN | Default bind-DN used to complete the administrative tasks (can be overriden via the request-API) | |
Password | Password corresponding to the bind-DN . The password is automatically encrypted when saving the adapter. |
Workflow Settings
A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:
- Input Property: the variable containing the instructions the adapter have to execute
- Output Property: the variable the adapter will store the response in after execution
- Before Adapter Script: script that will be executed before calling the adapter
- After Adapter Script: script that will be executed after the adapter fulfilled its task
Request - API
Common Request Attributes The following list gives an overview of the attributes used in the request-API; examples on how to use these attributes can be found in the examples throughout this chapter.
Option | Description |
---|---|
dn | BaseDN as the starting point for the search action or entry the action applies to |
Credentials | Username and password overriding these specified in the "adapter configuration" |
Scope | Specifies the search scope:
Search the entire subtree rooted at the named object. If the named object is not a Directory Context, search only the object. If the named object is a Directory Context, search the subtree rooted at the named object, including the named object itself. The search will not cross naming system boundaries. The NamingEnumeration that results from search() using
|
Filter | Search filters enable you to define search criteria and provide more efficient and effective searches |
Attributes | The set of attributes that should be returned as a result of a search action. All the attributes are returned if not specified. |
Bindings | The data that must be added/updated as part of an ADD/MODIFY-action; a data type (LDAP_STRING or LDAP_BINARY) per attribute can be given along. |
IncludeValues | If set to yes: Retrieve attributes only (no values). This is useful when you just want to see if an attribute is present in an entry and are not interested in the specific values. |
defaultType | Indicates the data type of the attributes as a result of a search
action; 'String' is default behavior if not specified.
|
Common
Sometimes it's necessary to encode a parameter from a request into an ldap filter or dn. In which case they should be encoded before going to the ldap. These 2 functions allow encoding the variables.
- ldapEncodeFilter : Encodes a specific variable into a ldap filter
- ldapEncodeRdn : Encode a specific variable into a dn
Authenticate
LdapAuthenticateRequest
Tries an LDAP-bind with the specified DN and corresponding password.
eg.
tb.ldapAuthenticateRequest(dn, password);
LdapAuthenticateSearchRequest The search-request, resulting in one DN, is followed by an authenticate-request by combining: The DN as a result of the search action, the pasword given along in the parameter "password: "
- dn Base DN under which to search (*)
- password password of the result
- scope 'base', 'one' or 'sub' (default = 'base')
- filter The string (avoid spaces) representation of the filter to use to identify matching entries. (*)
- attributes Array containing attributes (eg. {name: 'tel',type: 'String'}) that should be returned as a result of a search action. (default = all)
- defaultType Type of attribute to use by default ('Binary' or 'String') (default = 'String')
- includeValues Boolean indicating if the values should be included or just the keys (default = true)
- credentials Optional object containing 2 keys: user and password which can be used instead of the one used by the adapter.
eg.
var credentials = {'user':'dn','password':"itsme"}; tb.ldapAuthenticateSearchRequest({ baseDn: 'dn', password: 'itsme', scope: LDAP_ONE, filter: "cn=filter", credentials:credentials, });
Search
LdapSearchRequest
The LdapSearchRequest allows to search for entries in the LDAP-directory by specifying a base DN, a scope (one of base, one or sub) and an LDAP filter.
- dn Base DN under which to search (*)
- filter The string (avoid spaces) representation of the filter to use to identify matching entries. (*)
- scope 'base', 'one' or 'sub' (default = 'base')
- attributes Array containing attributes (eg. {name: 'tel',type: 'String'}) that should be returned as a result of a search action. (default = all)
- includeValues Boolean indicating if the values should be included or just the keys (default = true)
- defaultType Type of attribute to use by default ('Binary' or 'String') (default = 'String')
- credentials Optional object containing 2 keys: user and password which can be used instead of the one used by the adapter. The password should be unencrypted.
eg.
var ldapreq = { dn : "<DN>", credentials:{user: "cn=<user>",password: "<password>"}, filter : "(objectClass = inetOrgPerson)" //This will search for every inetOrgPerson object }; tb.ldapSearchRequest(ldapreq);
LdapAddRequest
The ldapAddRequest allows to add objects to the specified DN.
- dn DN to add(*)
- bindings Array containing attributes (eg. {name: 'tel',type: 'String',values:['047...']}) that should be added.
- defaultType Type of attribute to use by default ('Binary' or 'String') in case type is not given in bindings (default = 'String')
- credentials Optional object containing 2 keys: user and password which can be used instead of the one used by the adapter.
eg.
var credentials = {'user':'who','password':"itsme"}; var bindings = [ { "name" : "a", "type" : LDAP_STRING, "values" : [ "x1" ] }, { "name" : "b", "type" : LDAP_BINARY, "values" : [ "something base64 encoded" ] }, { "name" : "c", "values" : [ "z1", "", "z2" ] } ]; tb.ldapAddRequest({ dn: 'dn', bindings: bindings, credentials: credentials });
Password
LdapChangePasswordRequest
The LdapChangePasswordRequest allows clients to change the password of given DN after verifying the current password. The actual operation is performed using the adapter's default credentials.
- dn DN of the entry to change password
- oldPassword Old password
- newPassword New password
eg.
tb.ldapChangePasswordRequest(dn,oldPassword,newPassword)
LdapSetPasswordRequest
The LdapSetPasswordRequest allows clients to set the password of given DN. The actual operation is performed using the adapter's adminstrator credentials.
- dn DN of the entry whose password to set
- password Password to set
eg.
tb.ldapSetPassword(dn,password)
Delete
LdapDeleteRequest
The ldapDeleteRequest is used to delete a given object from the LDAP. The bind uses the adapter's adminstrator credentials, if a bindDN/bindPassword is not specified.
- dn Dn of the entry to delete
- credentials Optional object containing 2 keys: user and password which can be used instead of the one used by the adapter.
e.g.
tb.ldapDeleteRequest({ dn: 'cn=joe', credentials: {user: 'admin',password: 'secret'} })
Modify
LdapModifyRequest
The LdapModifyRequest allows the client to modify one or more attributes of a given DN.
- dn DN to add(*)
- modifications Array containing attributes (eg. {name: ‘tel’,operation: ‘add’,type: ‘String’,values:[‘047…’]}) that should be modified.
- defaultType Type of attribute to use by default (‘Binary’ or ‘String’) in case type is not given in modifications (default = ‘String’)
- credentials Optional object containing 2 keys: user and password which can be used instead of the one used by the adapter.
Three modify operations are supported:
- ‘add’ : adding values to a multi-valued attribute or setting the value of an empty single-valued attribute
- ‘replace’ : changing the value(s) of an attribute
- ‘delete’ : deleting values from a multi-valued attribute or clearing a single-valued attribute.
These operations may be combined into a single request as illustrated below.
eg.
tb.ldapModifyRequest({ dn: 'dn', scope: scope, modifications:[ { operation:LDAP_ADD, name:'Token', values:["Some Value"]}, { operation:LDAP_REPLACE, name:'Status', values:["status value"]}, ] });
Response - API
Common Properties The response API can be applied to the variable specified in the “output property” (see “Workflow Settings”): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.
All responses have four properties in common:
- status Status flag indicating whether the response is ok (0) or not (1).
- substatus Response specific number indicating what the problem was, eg. http status code
- message Response specific message in case there was a problem (can be null)
- rc Return Code, a human readable code based on the substatus
The status flag indicates whether a request was valid yes or no; consequently, the message or return code (rc) can be used to give the end-user a reasonable explanation or send the information to the underlying logging system.
Adapter Specific Properties
- getEntries()
Returns the entries found as a result of a search-request. The resulting object contains the following attributes:
- dn: DN of the entry
- attributes: Array of objects containing
- name
- type
- value (first value)
- values (array of strings)
To extract a value of a certain property, use:
- getAttributeValue(indexOrName): first value for an index or name
- getAttributeValues(indexOrName): array of values for an index or name
- getAttributeValueByteArrays(name): array of bytearrays for a name (does not work for an index)
Example:
var entries = workItem.ldapOutput.getEntries(); workItem.output = tb.generateResponse("<h1>CN: " + entries[0].getAttributeValue("cn") + "</h1>");
Response Codes
If all is ok, the status is zero, for non-zero statusses, the substatus defines what is wrong.
- 1 LDAP error
- 2 LDAP Authentication error
- 3 No permission
- 4 Not Found
- 5 Invalid name
- 6 Schema violation
- 7 Existing name
- 8 Invalid Attribute value
- 9 No such attribute
- 10 Attribute in use
- 11 Attribute modification error
- 100 Unsupported
- 101 No results
- 102 Communication error
- 103 Service unavailable
- 104 Connection error
- 105 Socket timeout
- 106 SSL Handshake error
Note: Some types of problems may result in one of several related errors. An attempt to connect to a server with invalid port, for instance, should result in a connection timeout error, but may occassionally result in a socket timeout error as well.
Example
The script function “createLDAPRequest” prepares an LDAP-search request with following properties:
base-DN: "o=securit,c=be" search scope: LDAP_SUB filter: cn=jdoe function createLDAPRequest(workItem){ workItem.ldapInput = tb.ldapSearchRequest({ dn: "o=securit,c=be", scope: LDAP_SUB, filter: "(cn=jdoe)", }); }
Response
The script function “processLDAPResponse” does the following:
tb.log(JSON.stringify(workItem.ldapOutput.getEntries()))
Returns all the found objects with corresponding attributes.
[{"dn":"cn=jdoe,ou=users,o=securit,c=be","attributes":[{"name":"objectClass","type":"String","values":["top","person","organizationalPerson","inetOrgPerson","ePerson"],"value":"top"},{"name":"cn","type":"String","values":["jdoe"],"value":"jdoe"},{"name":"sn","type":"String","values":["Doe"],"value":"Doe"},{"name":"userPassword","type":"String","values":["test1234"],"value":"test1234"},{"name":"uid","type":"String","values":["jdoe"],"value":"jdoe"},{"name":"givenName","type":"String","values":["John"],"value":"John"},{"name":"mail","type":"String","values":["jdoe@securit.biz"],"value":"jdoe@securit.biz"}]},{"dn":"cn=jdoe,ou=users,ou=sp,o=securit,c=be","attributes":[{"name":"objectClass","type":"String","values":["top","person","organizationalPerson","inetOrgPerson","ePerson"],"value":"top"},{"name":"cn","type":"String","values":["jdoe"],"value":"jdoe"},{"name":"sn","type":"String","values":["Doe"],"value":"Doe"},{"name":"userPassword","type":"String","values":["test1234"],"value":"test1234"},{"name":"uid","type":"String","values":["jdoe"],"value":"jdoe"}]}]
While entries[0].getAttributeValue(“cn”) returns the value of attribute CN from the entry [0]
function processLdapResponse(workItem){ if(workItem.ldapOutput.status == 0){ tb.log(JSON.stringify(workItem.ldapOutput.getEntries())); var entries = workItem.ldapOutput.getEntries(); workItem.output = tb.generateResponse("<h1>CN: " + entries[0].getAttributeValue("cn") + "</h1>"); } else { workItem.output = tb.generateResponse("<h1>Error in LDAP-Adapter</h1>"); } }
Comments
Please sign in to leave a comment.