212 lines
7.4 KiB
HTML
212 lines
7.4 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>LDAP API Overview</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>LDAP API Overview</h2>
|
||
|
|
|
||
|
|
<p>Lightweight Directory Access Protocol (LDAP) is an Internet protocol to
|
||
|
|
access directory servers. The directories on the Internet may be "pure" LDAP
|
||
|
|
directories; that is, they only communicate through LDAP, or they may be X.500
|
||
|
|
or other types of servers that allow access through LDAP. Access to servers
|
||
|
|
that are not pure LDAP servers is accomplished through an LDAP gateway.
|
||
|
|
Gateways from LDAP to other protocols also are common. Client programs that
|
||
|
|
allow a user to access an LDAP directory are called LDAP clients. Applications
|
||
|
|
that extract information from an LDAP directory are referred to as <strong>
|
||
|
|
LDAP-enabled</strong>.</p>
|
||
|
|
|
||
|
|
<p> The LDAP client is part of the i5/OS<SUP>(TM)</SUP>. The LDAP client is used by i5/OS
|
||
|
|
and customer applications for access to LDAP-enabled directories in the
|
||
|
|
network. The directories being accessed may or may not be located on an i5/OS
|
||
|
|
server. The applications access the LDAP client by using these client APIs.
|
||
|
|
TCP/IP is always used to access remote directories, and the administrator can
|
||
|
|
configure the connection to use the Secure Sockets Layer (SSL). Also, the
|
||
|
|
administrator can select to use Kerberos.</p>
|
||
|
|
|
||
|
|
<p>The LDAP APIs are designed to provide a suite of functions that can be used
|
||
|
|
to develop directory enabled applications. Directory-enabled applications
|
||
|
|
typically connect to one or more directories and perform various
|
||
|
|
directory-related operations, such as:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Adding entries</li>
|
||
|
|
|
||
|
|
<li>Searching the directory and obtaining the resulting list of entries</li>
|
||
|
|
|
||
|
|
<li>Deleting entries</li>
|
||
|
|
|
||
|
|
<li>Modifying entries</li>
|
||
|
|
|
||
|
|
<li>Renaming entries</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
The type of information that is managed in the directory depends on the nature
|
||
|
|
of the application. Directories are often used to provide public access to
|
||
|
|
information about people, including:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Phone numbers</li>
|
||
|
|
|
||
|
|
<li>E-mail addresses</li>
|
||
|
|
|
||
|
|
<li>Fax numbers</li>
|
||
|
|
|
||
|
|
<li>Mailing addresses</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Increasingly, directories are being used to manage and publish other types
|
||
|
|
of information, including:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Configuration information</li>
|
||
|
|
|
||
|
|
<li>Public key certificates (managed by certification authorities)</li>
|
||
|
|
|
||
|
|
<li>Access control information</li>
|
||
|
|
|
||
|
|
<li>Locating information (how to find a service)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The LDAP APIs provide for both synchronous and asynchronous access to a
|
||
|
|
directory. Asynchronous access makes it easy for your application to do other
|
||
|
|
work while waiting for the results of a potentially lengthy directory operation
|
||
|
|
to be returned by the server.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Typical API Usage</h3>
|
||
|
|
|
||
|
|
<p>The basic interaction is as follows. A connection is made to an LDAP server
|
||
|
|
by calling <strong>ldap_init</strong> (or <strong>ldap_ssl_init</strong>, which
|
||
|
|
is used to establish a secure connection over Secure Sockets Layer (SSL)).</p>
|
||
|
|
|
||
|
|
<p>An LDAP bind operation is performed by calling <strong>
|
||
|
|
ldap_simple_bind</strong> or <strong>ldap_sasl_bind</strong>. The bind
|
||
|
|
operation is used to authenticate to the directory server. Note that the LDAP
|
||
|
|
V3 API and protocol permits the bind to be skipped, in which case the access
|
||
|
|
rights associated with anonymous access are obtained.</p>
|
||
|
|
|
||
|
|
<p>Next, other operations are performed by calling one of the synchronous or
|
||
|
|
asynchronous routines (that is, <strong>ldap_search_s</strong> or <strong>
|
||
|
|
ldap_search</strong> followed by <strong>ldap_result</strong>).</p>
|
||
|
|
|
||
|
|
<p>Results returned from these routines are interpreted by calling the LDAP
|
||
|
|
parsing routines, which include operations such as:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>ldap_first_entry, ldap_next_entry</li>
|
||
|
|
|
||
|
|
<li>ldap_get_dn</li>
|
||
|
|
|
||
|
|
<li>ldap_first_attribute, ldap_next_attribute</li>
|
||
|
|
|
||
|
|
<li>ldap_get_values</li>
|
||
|
|
|
||
|
|
<li>ldap_parse_result (new for LDAP V3)</li>
|
||
|
|
|
||
|
|
<li>etc.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The LDAP connection is terminated by calling ldap_unbind.</p>
|
||
|
|
|
||
|
|
<p>The ldap_set_rebind_proc routine can be used to define the entry-point of a
|
||
|
|
routine to be called when an LDAP bind operation needs to occur when handling a
|
||
|
|
client referral to another server.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Displaying Results</h3>
|
||
|
|
|
||
|
|
<p>Results obtained from the ldap search routines can be accessed by calling
|
||
|
|
<strong>ldap_first_entry</strong> and <strong>ldap_next_entry</strong> to step
|
||
|
|
through the entries returned, <strong>ldap_first_attribute</strong> and
|
||
|
|
<strong>ldap_next_attribute</strong> to step through an entry's attributes,
|
||
|
|
<strong>ldap_get_values</strong> to retrieve a given attribute's value, and
|
||
|
|
then calling printf or some other display or usage method to display the
|
||
|
|
values.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Uniform Resource Locators (URLS)</h3>
|
||
|
|
|
||
|
|
<p>The <strong>ldap_is_ldap_url</strong> routines can be used to test a URL to
|
||
|
|
see if it is an LDAP URL, to parse LDAP URLs into their component pieces, and
|
||
|
|
to initiate searches directly using an LDAP URL.</p>
|
||
|
|
|
||
|
|
<p>Examples of these routines are ldap_url_parse, ldap_url_search_s, and
|
||
|
|
ldap_is_ldap_url.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Secure Socket Layer (SSL) Support</h3>
|
||
|
|
|
||
|
|
<p>The LDAP APIs have been extended to support connections that are protected
|
||
|
|
by the Secure Socket Layer (SSL) protocol. This can be used to provide strong
|
||
|
|
authentication between the client and server, as well as data encryption of
|
||
|
|
LDAP messages that flow between the client and the LDAP server. The
|
||
|
|
ldap_ssl_client_init() and ldap_ssl_init() APIs are provided to initialize the
|
||
|
|
SSL function, and to create a secure SSL connection (respectively).</p>
|
||
|
|
|
||
|
|
<p>When using <a href="ldap_ssl_client_init.htm">ldap_ssl_client_init()</a>,
|
||
|
|
the application ID used is QIBM_GLD_DIRSRV_CLIENT, identified as client
|
||
|
|
application "Directory Services Client" in Digital Certificate Manager (DCM).
|
||
|
|
To use i5/OS application IDs other than the default which have an association
|
||
|
|
to a certificate store and a particular certificate in that store, the
|
||
|
|
following i5/OS-specific APIs are provided:</p>
|
||
|
|
|
||
|
|
<p> Version 2 API</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>ldap_app_ssl_start_np() (deprecated)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p> Version 3 API</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>ldap_app_ssl_client_init_np()</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>When using ldap_ssl_init(), the server is not contacted until the connection
|
||
|
|
is used; that is, by ldap_bind() or ldap_search(). If an SSL error occurs while
|
||
|
|
trying to connect, the SSL error code can be retrieved for the connection with
|
||
|
|
the <a href="ldap_get_option.htm">ldap_get_option()</a> API using the <strong>
|
||
|
|
LDAP_OPT_EXT_ERROR</strong> option.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center">
|
||
|
|
<a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href="dirserv1.htm">Directory Server APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|