LDAP Engine

From ESM Wiki
Jump to: navigation, search

Contents

Introduction

LDAP engine is an engine that encapsulates different methods for working with LDAP directory. LDAP engine element is <ldap>:

<mppd>
    <engines>
        <ldap id="dir">
            ...
        </ldap>
    </engines>
</mppd>

Common options

Common options affect all methods of an engine that depend on them. In the following XML all common options are specified. Their meaning and properties are specified as comments under corresponding option:

<mppd>
    <engines>
        <ldap id="dir">

            <!-- Specifies: static options for controlling binds (connections) cache. -->
            <cache>

                <!-- Specifies: Maximum number of binds in cache. -->
                <!-- Value: Unsigned integer. Zero will desable cacheing at all. Static option. -->
                <!-- Default: 1 -->
                <binds_max>1</binds_max>

                <!-- Specifies: Maximum time that a bind is held in cache. -->
                <!-- Value: Unsigned integer (seconds). Static option. -->
                <!-- Default: 600 -->
                <binds_lifetime>600</binds_lifetime>

                <!-- Specifies: Maximum number of failed bind configs in cache. -->
                <!-- Value: Unsigned integer. Static option. -->
                <!-- Default: 100 -->
                <failures_max>100</failures_max>

                <!-- Specifies: Maximum time that a failed bind config is held in cache. -->
                <!-- Value: Unsigned integer (seconds). Static option. -->
                <!-- Default: 600 -->
                <failures_lifetime>600</failures_lifetime>
 
                <!-- Specifies: Maximum number of failures for a bind to be blocked. -->
                <!-- Value: Unsigned integer. Static option. -->
                <!-- Default: 5 -->
                <failures_block_count>5</failures_block_count>

                <!-- Specifies: Period of time a bind will be blocked after exceeding maximum of failures. -->
                <!-- Value: Unsigned integer (seconds). Static option. -->
                <!-- Default: 30 -->
                <failures_block_period>30</failures_block_period>

             </cache>

             <!-- Specifies: dynamic options for binding to LDAP server (see man ldap_bind for more details). --> 
             <bind>
                 
                <!-- Specifies: URI of LDAP server. -->
                <!-- Value: String (URI). Dynamic option. -->
                <!-- Default: no default - mandatory -->
                 <uri>ldap://localhost.localdomain:389</uri>
                 
                <!-- Specifies: Distinguish name of a user to authenticate to. -->
                <!-- Value: String (DN). Dynamic option. -->
                <!-- Default: no user -->
                 <who>cn=Manager,dc=localhost,dc=localdomain</who>
                 
                <!-- Specifies: User's credentials. Structure depends on method:-->
                <!--                * for LDAP_AUTH_NONE it is just ignored -->
                <!--                * for LDAP_AUTH_SIMPLE it is password -->
                <!-- Value: String (DN). Dynamic option. -->
                <!-- Default: no credentials -->
                 <cred>secret</cred>
                 
                <!-- Specifies: Authentication method. -->
                <!-- Value: Enumeration. Dynamic option. -->
                <!--            * LDAP_AUTH_NONE - no authentication; -->
                <!--            * LDAP_AUTH_SIMPLE - authentication with password -->
                <!-- Default: no credentials -->
                 <method>LDAP_AUTH_NONE</method>
 
                <!-- Specifies: Timeout for binding. -->
                <!-- Value: Unsigned integer (milliseconds). Dynamic option. -->
                <!-- Default: 30000 -->
                 <timeout>30000</timeout>

             </bind> 

        </ldap>
    </engines>
</mppd>

Common macros

Macros in this section can be used in the scope of entire ldap engine (including <bind> dynamic options).

$ldap_escape_dn

Description: Escape a string for DN. This macro is important to apply to all strings comming from outside world to prevent LDAP injection.
Arguments: 1) String to escape.

$ldap_escape_filter

Description: Escape a string for search filter. This macro is important to apply to all strings comming from outside world to prevent LDAP injection.
Arguments: 1) String to escape.

Search method

Search method performs LDAP search operation. It does the following:

  • evaluates bind templates;
  • check if bind is not blocked;
  • retrieves bind from cache or do binding if nothing in cache;
  • evaluates search method templates and queries LDAP server;
  • reads and processes response from LDAP server;
  • provides embeded mechanisms for extracting data from response table and exporting it as engine results.

In the following XML all search method options are specified. Their meaning and properties are specified as comments under corresponding option:

<mppd>
    <engines>
        <ldap id="dir">
            ...
 
            <!-- Specifies: Search method dynamic options. See man ldap_search for details. -->
            <search id="search_id">
 
                <!-- Specifies: Base DN to start search from. -->
                <!-- Value: String (DN). Dynamic option. -->
                <!-- Default: no base -->
                <base>${wrap dc=$#{,} ${ldap_escape_dn $recipient.domain.part}}</base>
 
                <!-- Specifies: Search scope. -->
                <!-- Value: Enumeration. Dynamic option. -->
                <!-- Default: LDAP_SCOPE_SUBTREE -->
                <scope>LDAP_SCOPE_SUBTREE</scope>
 
                <!-- Specifies: Search filter. -->
                <!-- Value: String. Dynamic option. -->
                <!-- Default: no filter -->
                <filter>mail=*</filter>
 
                <!-- Specifies: Restrict a set of attributes to retrieve. -->
                <!-- Value: Space- or comma- separated list of attributes. Dynamic option. -->
                <!-- Default: no restriction (all attributes are retrieved). -->
                <attrs>mail, email</attrs>
 
                <!-- Specifies: Whether to retieve only attribute names and skip values. -->
                <!-- Value: Integer. Dynamic option. -->
                <!--         0 - retrieve only attribute names / retrieve values as well -->
                <!--         1 - retrieve attribute values as well -->
                <!-- Default: no restriction (all attributes are retrieved). -->
                <attrsonly>0</attrsonly>
 
                <!-- Specifies: Timeout for search request to complete. -->
                <!-- Value: Unsigned integer (milliseconds). Dynamic option. -->
                <!-- Default: 30000 -->
                <timeout>30000</timeout>
   
                <!-- Specifies: Maximum number of entries to retrieve. -->
                <!-- Value: Unsigned integer. Dynamic option. -->
                <!-- Default: 100 -->
                <sizelimit>100</sizelimit>

            </search>
 
        </ldap>
    </engines>
</mppd>

Search method uses usual format for preconditions and result with validation. Several method specific macros are available in the scope of a method or results. They are described further.

Search method macros

Macros in this section can be applied in the scope of search method results.

$ldap_status

Description: LDAP operation result status. This may be bind failure status (if it is failed) or actual search status. Macro evaluates to status strings such as: LDAP_SUCCESS, LDAP_OPERATIONS_ERROR, etc. (see OpenLDAP documentation for details).

$ldap_entry.dn

Description: DN (distiguish name) of a retieved entry(ies).
Dimensions: $engines.engine_id.method_id.ldap_entry

$ldap_entry.attribute.name

Description: Attribute name(s).
Dimensions: $engines.engine_id.method_id.ldap_entry, $engines.engine_id.method_id.ldap_entry.attribute

$ldap_entry.attribute.value

Description: Attribute value(s).
Dimensions: $engines.engine_id.method_id.ldap_entry, $engines.engine_id.method_id.ldap_entry.attribute, $engines.engine_id.method_id.ldap_entry.attribute.value
Personal tools