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). RO: Read-Only RW: Read-Write	x
AdapterUniqueID	Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements: START with a letter or _ (underscore) FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)	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: True: A connection pool can hold a maximum of 20 reusable connections; the size of the pool is not configurable. False: No persistent connection to the LDAP; a new connection will be initiated for each new request.	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: 'base' 'one' 'sub' 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 'sub':
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. 'String': Return as strings 'Binary': return as base64 encoded binary

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.

CODE

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.

CODE

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.

CODE

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.

CODE

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.

CODE

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.

CODE

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.

CODE

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.

CODE

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:

CODE

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:

CODE

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:

CODE

tb.log(JSON.stringify(workItem.ldapOutput.getEntries()))

Returns all the found objects with corresponding attributes.

CODE

[{"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]

CODE

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