LDAP Connector Interface

Use

The LDAP Connector interface is a collection of function modules with which you can access a directory server using the LDAP Connector. The function modules are geared to the operations available in the LDAP protocol. For an overview of these operations, see the Request for Comments number 2251 at

www.ietf.org/rfc/rfc2251.txt?number=2251.

Prerequisite

·        You have set up the LDAP Connector so that you can use the function modules described here.

·        There is an entry for the external directory server to be used in the LDAP Server view.

General Notes About the Function Modules

·        All exceptions are triggered with an ABAP message.

·        If the export parameter LDAPRC is reset by the calling program, it contains the return code of the directory in accordance with the LDAP standard. If this is a number other than zero, this indicates that there is an error, and should be handled accordingly. If the parameter is not reset, the exception LDAP_FAILURE is triggered. The message from message class LDAPRC corresponding to the error code is returned as a message. This message classes provides a minimum quantity of information text. Since the errors are not, however, the responsibility of the SAP system, the content of this message class is restricted to a conversion of the LDAP error codes (see SAP Note 511141).

·        Some function modules have import parameters with the data type STRING. These functionally replace the parameters with fixed length fields (such as USR_STRING replaces USR in LDAP_SIMPLEBIND), which also still exist. In SAP R/3 4.6B, 4.6C, and 4.6D, the maximum length of the data transferable to the directory is restricted to the field length of the corresponding fixed length fields for technical reasons. If this length is exceeded, the module reacts with the exception OTHER_ERROR and a corresponding error message.

Most Common Exceptions

·        NO_AUTHORIZ: ABAP authorization check failed. The authorization object checked is S_LDAP with the LDAP server used.

·        CONFIG_ERROR: Error in the configuration in the SAP system (for example, a non-existent LDAP server ID was specified).

·        LDAP_FAILURE: If the export parameter LDAPRC is not reset, this exception is triggered, if the directory sent an error code.

·        CONN_OUTDATE: The LDAP connection was terminated due to being inactive for too long.

·        NOT_ALIVE: The connection between the application server and the LDAP Connector has been terminated.

Functions

The following function modules are available:

LDAP_CHECKIN_RFCDEST (Setting the LDAP Connector to Be Used)

You can use this (optional) function to set the LDAP Connector that is used for the subsequent logon attempt. If this function is not called, the system automatically selects for an LDAP Connector (prerequisite: At least one LDAP Connector is entered and active with the target status Active).

Use this function only in test programs. To allow load distribution, you should always automatically select the LDAP Connector in production environments.

·        NEWDEST: Name of the LDAP Connector. The module performs an availability check of the LDAP Connector and reacts with an exception if an error occurs.

...

LDAP_SIMPLEBIND (Logging on to the Directory)

This function should be called before all other functions to create a connection to the directory.

·        SERVERID: Name of the LDAP server that you selected in Customizing for the directory server to be addressed. The connection data (host name, port) and the protocol version to be used are stored there.

·        USR_STRING: The user name for logging on to the directory. This information is passed to the directory unchanged.

·        PWD_STRING: The password for logging on to the directory. Note that the use of an empty password is interpreted as an anonymous logon (empty user name) in accordance with the LDAP standard.

·        HOLDSESS: Maximum permissible inactivity duration in seconds. If this value is not zero, the connection is terminated if it has not been used for longer than the specified time in seconds.

Note:

Ў        When starting the LDAP Connector, you can use the command line parameter "-o" to set a global timeout. If the parameter is not set, a default of 3600 seconds is used. The timeout that applies for an individual connection is the minimum of this time and the value of HOLDSESS set for the connection (if this is set to a value other than zero).

Ў        On the hardware platforms on which the LDAP Connector is not multi-threading-compatible (currently all platforms other than Microsoft Windows), the connection is terminated due to being inactive only at the next access to the LDAP Connector.

·        WAIT_TIME: If an LDAP Connector was not explicitly set using LDAP_CHECKIN_RFCDEST, LDAP_SIMPLEBIND automatically selects the LDAP Connector to be used. If no available LDAP Connector is found, the system waits a second and then tries again. The parameter WAIT_TIME controls how often this step is repeated before an error message with the exception NOMORE_CONNS is triggered. A value of 0 (default setting) corresponds to the previous behavior, where the exception is triggered immediately after the first failed attempt.

LDAP_SYSTEMBIND (Logging On to the Directory with Preconfigured Logon Data)

As of SAP R/3 4.6C, this module is available as an alternative to LDAP_SIMPLEBIND. The logon data fort he directory (user name, password) is not transferred to the module at the interface, but rather maintained using the Customizing step LDAP System User. The User ID assigned there is entered in the maintenance view LDAP Server in the User ID field.

·        SERVERID: See LDAP_SIMPLEBIND

·        WRITEREAD: You can use this parameter (possible values : “W“ for "Write" and “R“ for "Read") to determine whether the connection is to access the directory with a read-only access (R) or whether write accesses (W) are also permitted. If you set the parameter to (R) and call a changing operation, an error message is displayed. The parameter has, together with two other indicators from Customizing, the following effect:

Ў        If the Read Anonymously indicator and the parameter "R" are set in the configuration, the logon to the directory is essentially anonymous, that is, with an initial user name, irrespective of whether a system user is entered in the User ID field of the LDAP server Customizing.

Ў        If the Only Read Rights indicator is set in Customizing, changing operations lead to errors, even if the parameter was set to "W".

·        BASEDN_STRING: The basis DN of the selected server is returned using this parameter.

·        HOLDSESS: See LDAP_SIMPLEBIND

·        WAIT_TIME: See LDAP_SIMPLEBIND.

LDAP_CREATE (Creating an Entry that Does Not Yet Exist in the Directory)

·        LDAPE: The input parameter is a complex data type that describes the data of the entry.

Ў        DN: The complete Distinguished Name of the entry to be created.

Ў        ATTRIBUTES: A table with the attribute name and values. The row type of this table is complex and has the following relevant fields:

§         NAME: Attribute name

§         TYPE: Specifies whether this is a text (C) or binary (X) attribute. Only these two values are permissible.

§         VALS: For text attributes, the attribute values are transferred in this table (in the table column VAL).

§         XVALS: For binary attributes, the attribute values are transferred in this table (in the table column VAL).

LDAP_UPDATE (Changing an Entry)

You can use this function to change an existing entry. The interface is identical to that of LDAP_CREATE. For this function, the OPERATION field of the attribute table specifies for each attribute which operation is to be performed:

·        A: "Append". The specified values are to be added to the existing values.

·        D: "Delete". The specified values are deleted from the existing values.

·        R: "Replace". The specified values completely replace the existing values. In accordance with the LDAP standard, replacement with an empty value set is equivalent to deletion. 

LDAP_READ (Reading Entries)

You can use this function to read data from the directory.

·        BASE_STRING: The Distinguished Name of the entry from which the search is to be performed.

·        SCOPE: Search depth.

Permissible values:

Ў        0: The search extends only to the base entry. Choose this search depth to check whether a particular entry exists, or to read attributes of a known entry.

Ў        1: Search one level below the base entry.

Ў        2: The search extends to the base entry and all entries and subtrees below.

·        FILTER_STRING: The search filter in LDAP notation. Example: (&(objectclass=*)(telephoneNumber=12345))

·        TIMEOUT: A structure with the fields SEC and USEC, which define the maximum search time in the directory, if set to a value other than zero. This information is forwarded to the directory. SAP is not responsible for it being taken into account, or for its effects.

·        ATTRIBUTES: You can use this table to specify which attributes are to be read, and in which format (text or binary) they are returned.

Ў        If the table is empty, all attributes are returned in both formats.

Ў        If the table contains a row with an attribute name in the NAME field, this attribute is returned in the format specified in the TYPE field. Permissible values for this field:

§         C: The attribute is only read in text format.

§         X: The attribute is only read in binary format.

§         Empty: The attribute is read in text format and in binary format.

Ў        If the table contains a row with an asterisk (*) in the NAME field, all attributes are returned in the format specified in the TYPE field.

The search results are returned in the ENTRIES table with a complex row structure:

·        DN: The Distinguished Name of the entry found.              

·        ATTRIBUTES: A table containing the found attributes of the entry. The row structure has the following fields:

Ў        NAME: The name of the attribute.

Ў        TYPE: The format in which this attribute was read (C for text, X for binary).

Ў        VALS: For attributes read in text format, this table contains the attribute values.

Ў        XVALS: For attributes read in binary format, this table contains the attribute values.

Connection Between Requested and Returned Attribute Names and Types:

Attribute names are not case-sensitive, in accordance with the LDAP standard. You can therefore request an attribute in any case using the parameter ATTRIBUTES of LDAP_READ.

To permit a search fort his attribute in the search result, LDAP_READ returns every requested attribute (if it exists in the directory) in the same notation in the return structure, and also take into account the requested type when doing so.

If you used the placeholder asterisk (*) to address all attributes, these are returned in upper case.

Example 1:

An entry has the attributes SN, CN, and CERT in the directory.

Request:

NAME     TYPE

================

sn       C

SN       C

CN       X

cert     <space>

SN       C

Return of LDAP_READ

NAME    TYPE        VALS   XVALS

================================

CN      X           -      +  (as requested)

SN      C           +      -  (only once, although requested twice)

cert    <space>     +      +  (as requested)

sn      C           +      -  (was also requested in lower case)  

Example 2:

Request:

NAME     TYPE

============   

cert     X       

SN       C     

*        C     

Return of LDAP_READ

NAME    TYPE        VALS   XVALS

================================

CERT    C           +      -  (result of "*")

CN      C           +      -  (result of "*")

N      C           +      -  (directly requested)

cert    X           -      +  (directly requested)

LDAP_DELETE (Deleting Entries)

·        DN_STRING: The complete Distinguished Name of the entry to be deleted.

·        SUBTREE: If this parameter is set to (X), all entries below the Distinguished Name are also deleted. The function therefore allows the deletion of an entire subtree.

LDAP_RENAME (Renaming Entries)

·        DN_STRING: The complete Distinguished Name of the entry to be renamed.

·        NEW_RDN_STRING: The new Relative Distinguished Name for the entry.

·        NEW_PARENT_STRING: If the parameter is filled, it specifies a new superordinate entry. SAP’s experience is that this operation is not supported by all directories.

·        DELETE_OLD: If this parameter is set to (X), the old entry is deleted after being renamed (replacement), otherwise the operation corresponds to copying.

Comparing attribute values

The comparison operation of the LDAP standards (ldap_compare_s) is not supported. We recommend that you use LDAP_READ to read the desired attribute and perform the comparison in ABAP.

LDAP_UNBIND (Logging Off from the Directory)

You can terminate your connection to the directory with this function. You can then no longer perform any more directory operations, until you log on again.

Use multiple LDAP connections in an application program.

You can use the function module LDAP_CHECKOUT_CONNKEY to “park” an existing connection so that an application program can create and use multiple connections. The returned parameter CKEY must be stored by the application program.

A new connection can then be created and used with LDAP_SIMPLEBIND or LDAP_SYSTEMBIND.

To return to the old connection, the function module LDAP_CHECKIN_CONNKEY must be called with the stored value of CKEY.

LDAP_OPTIONS (Reading/Changing Options of the LDAP Interface)        

You can use this function to read or change the option values of the operating system-side LDAP interface.

The functions LDAP_SIMPLEBIND and LDAP_SYSTEMBIND set the LDAP log version in accordance with the settings from Customizing, meaning that the use of LDAP_OPTIONS is only required in exceptional cases.

·        WRITEREAD: This parameter controls whether the options are to be read (R) or written (W).

·        OPTIONS_IO: A table with one row per option that is to be read or written. In the field NUM1, specify the option number to be specified (see below) to write options (WRITEREAD = W), specify the option value to be set in field NUM2. After you have successfully called the function, the field NUM2 contains the read (R) or set (W) option value.

The output table can have fewer rows than the input table. In this case, the LDAP Connector deleted options, which are not supported either by the operating system-side LDAP interface or the protocol version.

The currently supported options and the values to be used for NUM1 for them are:

·        2: LDAP_OPT_DEREF

·        3: LDAP_OPT_SIZELIMIT

·        4: LDAP_OPT_TIMELIMIT

·        8: LDAP_OPT_REFERRALS

·        9: LDAP_OPT_RESTART

·        17: LDAP_OPT_PROTOCOL_VERSION

·        49: LDAP_OPT_ERROR_NUMBER

The option names are the names from the operating system-side LDAP interface. Their meaning and effect on the different hardware platforms of the LDAP Connector or the directory are not the responsibility of SAP.