Concepts 2-11
About the Oracle Internet Directory API
The Oracle Internet Directory API is available as a C API and as a PL/SQL API.
The PL/SQL API is contained in a PL/SQL package called DBMS_LDAP. This package enables PL/SQL applications to access data located in enterprise-wide LDAP servers. The naming and syntax of the function calls are similar to those of the Oracle Internet Directory C API functions and comply with the current recommendations from theInternet Engineering Task Force (IETF) for the LDAP C-API. However, the PL/SQL API contains only a subset of the functions available in the C API. In particular, only synchronous calls to the LDAP server are available in the PL/SQL API.
About the Oracle Internet Directory API
Figure 2–3 illustrates the overall placement of the DBMS_LDAP API in the runtime environment of a client.
Figure 2–3 Applications Sharing LDAP Server Data
AsFigure 2–3 shows, the API allows multiple different applications—in this example, Human Resources and Financials—to share employee address book information and user profiles by using an LDAP server.
Storing such information in an LDAP server enables other non-database
applications that are LDAP-enabled to retrieve the same information. InFigure 2–3, the Email Clients application uses the same employee address book data to find the employee for a given email address. Because LDAP offers a centralized repository
Human Resources Database
About the Oracle Internet Directory API
Concepts 2-13 In summary, the Oracle Internet Directory API enables Oracle database applications to:
■ Read from the LDAP server information that is published by other programs in the enterprise
■ Publish in the LDAP server new information that can be used later by the same application or other applications
■ Modify or update existing information in the LDAP server based on certain pre-defined conditions
Typically, an application or trigger uses the functions in the API in four simple steps:
1. Initialize the library and obtain an LDAP session handle.
2. Authenticate to the LDAP server if necessary.
3. Perform some LDAP operations and obtain results and errors if any.
4. Close the session.
Figure 2–4 illustrates these steps.
Figure 2–4 Steps in Typical DBMS_LDAP Usage
The following sections explain the important features of the API with respect to each of these steps.
Initialize Session init
Authenticate Session bind_s, simple_bind_s
Perform LDAP Operations
Terminate Session unbind
Initializing an LDAP Session
Initializing an LDAP Session
All LDAP operations require clients to establish an LDAP session with the LDAP server. To perform LDAP operations, a database session must first initialize and open an LDAP session.
Initializing the Session by Using the C API
ldap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization.
Syntax
LDAP *ldap_init (
const char *hostname, int portno )
;
Parameters
Table 2–1 Parameters for ldap_init() Parameter Description
hostname Contains a space-separated list of hostnames or dotted strings
representing the IP address of hosts running an LDAP server to connect to. Each hostname in the list MAY include a port number which is separated from the host itself with a colon (:) character. The hosts will be tried in the order listed, stopping with the first one to which a successful connection is made.
Note: A suitable representation for including a literal IPv6[10] address in the hostname parameter is desired, but has not yet been determined or implemented in practice.
portno Contains the TCP port number to connect to. The default LDAP port of 389 can be obtained by supplying the constant LDAP_PORT. If a host includes a port number then this parameter is ignored.
Initializing an LDAP Session
Concepts 2-15 ldap_init() and ldap_open() both return a session handle, that is, a pointer to an opaque structure that MUST be passed to subsequent calls pertaining to the session.
These routines return NULL if the session cannot be initialized in which case the operating system error reporting mechanism can be checked to see why the call failed.
Note that if you connect to an LDAPv2 server, one of the LDAP bind calls described below SHOULD be completed before other operations can be per formed on the session. LDAPv3 does not require that a bind operation be completed before other operations can be performed.
The calling program can set various attributes of the session by calling the routines described in the next section.
Initializing the Session by Using DBMS_LDAP
Initialization occurs by means of a call to the functionDBMS_LDAP.init(). The function ‘init’ has the following syntax:
FUNCTION init (hostname IN VARCHAR2, portnum IN PLS_INTEGER ) RETURN SESSION;
To establish an LDAP session, the functioninit requires a valid hostname and a port number. It allocates a data structure for the LDAP session and returns a handle of the typeDBMS_LDAP.SESSIONto the caller. The handle returned from the call to init should be used in all subsequent LDAP operations with the API. The DBMS_
LDAP API uses the LDAP session handles to maintain state about open connections, outstanding requests, and other information.
A single database session can obtain as many LDAP sessions as required. Typically, multiple LDAP sessions within the same database session are opened if:
■ There is a requirement to get data from multiple LDAP servers simultaneously
■ There is a requirement to have open sessions using multiple LDAP identities
Note: The handles returned from calls toDBMS_LDAP.init() are dynamic constructs: They do not persist across multiple database sessions. Attempting to store their values in a persistent form, and to reuse stored values at a later stage, can yield
unpredictable results.