LDAP Connector Interface

PDF download from SAP Help Portal:

http://help.sap.com/saphelp_nw73/helpdata/en/48/75c2b2bc27055ee10000000a42189b/content.htm
Created on June 05, 2014

The documentation may have changed since you downloaded the PDF. You can always find the latest information on SAP Help Portal.

Note
This PDF document contains the selected topic and its subtopics (max. 150) in the selected structure. Subtopics from other structures are not included.

2014 SAP AG or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose
without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG
and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by
SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be
liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express
warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other
SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other
countries. Please see www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademark information and notices.

Table of content

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 1 of 6

Table of content
1 LDAP Connector Interface

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 2 of 6

1 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 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)

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 3 of 6

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.

Example
Example 1: An entry in the directory has the attributes SN, CN, and CERT.
Request:
NAME TYP
================
sn C
SN C
CN X
cert <space>
SN C
LDAP_READ Return
NAME TYP VALS XVALS
================================

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 4 of 6

CN X - + (as requested)
SN C + - (only once, although requested twice)
cert <space> + + (as requested)
sn C + - (was also requested in lower case)

Example
Example 2:
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.

Note
Using multiple LDAP connections in an application program
So that an application program can create and use multiple connections to directories, you can use the function module LDAP_CHECKOUT_CONNKEY to
"park" an existing connection. The returned parameter CKEY must be saved by the application program.
A new connection can then by created with LDAP_SIMPLEBIND or LDAP_SYSTEMBIND, and used.
To return to the old connection, the function module LDAP_CHECKIN_CONNKEY needs to 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 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.

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 5 of 6

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 systemside 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.

PUBLIC
2014 SAP AG or an SAP affiliate company. All rights reserved.

Page 6 of 6