LDAP Connector Interface

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 class 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 (for example, USR_STRING replaces USR in LDAP_SIMPLEBIND). 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 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 is a value other than 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 lower 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 for the directory (user name, password) is not transferred to the module at the interface, but rather edited 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 basic DN of th eselected 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 names and values. The row type of this table is complex and has the following relevant fields:

    • NAME: Attribute name

    • TYP: 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 to be 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, nor 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 TYP 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 and binary formats.

  • If the table contains a row with an asterisk (*) in the NAME field, all attributes are returned in the format specified in the TYP 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

  • TYP: 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 using parameter ATTRIBUTES of LDAP_READ with any notation.

To permit a search in the search result by this attribute, LDAP_READ returns every requested attribute (if it exists in the directory) in the return structure with the same notation, and also take into account the requested type.

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

Request:

          
NAME TYP
          
================
          
sn C
          
SN C
          
CN X
          
cert <space>
          
SN C
            

LDAP_READ Return

          
NAME TYP 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)
            

Request:

          
NAME TYP
          
============
          
cert X
          
SN C
          
* C
            

LDAP_READ Return

          
NAME TYP 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 deleted. This 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 this parameter is filled, it specifies the new superordinate entry. In SAP's experience, this operation is not supported by all directories.

• DELETE_OLD: If this parameter is set to (X), the old entry is deleted after the renaming (moving), otherwise the operation is equivalent to copying.

  Recommendation

  Comparing Attribute Values

  The comparison operation of the LDAP standard (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)

With this function, you close the connection to the directory. You cannot then perform any further directory operations until you log on again.

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 already set the LDAP protocol version in accordance with the Customizing specifications, so that the use of LDAP_OPTIONS is only required in exceptional cases.

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

• OPTIONS_IO: A table with one row for each option that is to be read or written. In the NUM1 field, specify the option number (see below). To write options (WRITEREAD = W), specify the option value to be set in field NUM2. After the function has been successfully called, the NUM2 field contains the read (R) or written (W) option value.

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

The currently-supported options and the corresponding values to set for NUM1 are listed below:

• 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 identifiers from the operating system-side LDAP interfaces. SAP is not responsible for their meaning and effectiveness on the different hardware platforms of the LDAP Connector or the directory.