Articles in this section

See more

LDAP Adapter

Avatar
Trustbuilder Support
Updated
Follow

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).
  • 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.

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

0 comments

Please sign in to leave a comment.

Related articles