LDAP adapter
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.
| 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>");
}
}