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

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.

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.

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.

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":["[email protected]"],"value":"[email protected]"}]},{"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>");
    }
}