Skip to main content
Skip table of contents

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

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.

  1. dn Dn of the entry to delete

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.