2 Developing Applications with Standard LDAP APIs

2.3.1 Naming Model

The LDAP naming model enables directory information to be referenced and organized. Each entry in a directory is uniquely identified by a distinguished name (DN). The DN tells you exactly where an entry resides in the directory hierarchy. A directory information tree (DIT) is used to represent this hierarchy.

Figure 2-1 illustrates the relationship between a distinguished name and a directory information tree.

Figure 2-1 A Directory Information Tree

The DIT in Figure 2-1 shows entries for two employees of Example Corporation who are both named Anne Smith. It is structured along geographical and organizational lines. The Anne Smith represented by the left branch works in the Sales division in the United States. Her counterpart works in the Server Development division in the United Kingdom.

The Anne Smith represented by the right branch has the common name (cn) Anne Smith. She works in an organizational unit (ou) named Server Development, in the country (c) of United Kingdom of Great Britain and Northern Ireland (uk), in the organization (o) Example. The DN for this Anne Smith entry looks like this:

cn=Anne Smith,ou=Server Development,c=uk,o=example

Note that the conventional format for a distinguished name places the lowest DIT component at the left. The next highest component follows, on up to the root.

Within a distinguished name, the lowest component is called the relative distinguished name (RDN). In the DN just presented, the RDN is cn=Anne Smith. The RDN for the entry immediately above Anne Smith's RDN is ou=Server Development. And the RDN for the entry immediately above ou=Server Development is c=uk, and so on. A DN is thus a sequence of RDNs separated by commas.

To locate a particular entry within the overall DIT, a client uniquely identifies that entry by using the full DN—not simply the RDN—of that entry. To avoid confusion between the two Anne Smiths in the global organization depicted in Figure 2-1, you use the full DN for each. If there are two employees with the same name in the same organizational unit, you can use other mechanisms. You may, for example, use a unique identification number to identify these employees.

2.3.2 Information Model

The LDAP information model determines the form and character of information in the directory. This model uses the concept of entries as its defining characteristic. In a directory, an entry is a collection of information about an object. A telephone directory, for example, contains entries for people. A library card catalog contains entries for books. An online directory may contain entries for employees, conference rooms, e-commerce partners, or shared network resources such as printers.

In a typical telephone directory, a person entry contains an address and a phone number. In an online directory, each of these pieces of information is called an attribute. A typical employee entry contains attributes for a job title, an e-mail address, and a phone number.

In Figure 2-2, the entry for Anne Smith in Great Britain (uk) has several attributes. Each provides specific information about her. Those listed in the balloon to the right of the tree are emailaddrs, printername, jpegPhoto, and app preferences. Note that the rest of the bullets in Figure 2-2 are also entries with attributes, although these attributes are not shown.

Figure 2-2 Attributes of the Entry for Anne Smith

Each attribute consists of an attribute type and one or more attribute values. The attribute type is the kind of information that the attribute contains—jobTitle, for instance. The attribute value is the actual information. The value for the jobTitle attribute, for example, might be manager.

2.3.3 Functional Model

The LDAP functional model determines what operations can be performed on directory entries. Table 2-1 lists and describes the three types of functions:

2.3.4 Security Model

The LDAP security model enables directory information to be secured. This model has several parts:

• Authentication

  Ensuring that the identities of users, hosts, and clients are correctly validated

• Access Control and Authorization

  Ensuring that a user reads or updates only the information for which that user has privileges

• Data Integrity: Ensuring that data is not modified during transmission

• Data Privacy

  Ensuring that data is not disclosed during transmission

• Password Policies

  Setting rules that govern how passwords are used

2.4.1 API Usage Model

Typically, an application uses the functions in the API in four 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-3 illustrates these steps.

Figure 2-3 Steps in Typical DBMS_LDAP Usage

2.4.2 Getting Started with the C API

When you build applications with the C API, you must include the header file ldap.h, located at $ORACLE_HOME/ldap/public. In addition, you must dynamically link to the library located at $ORACLE_HOME/lib/libclntsh.so.10.1.

2.4.3 Getting Started with the DBMS_LDAP Package

The DBMS_LDAP package enables PL/SQL applications to access data located in enterprise-wide LDAP servers. The names and syntax of the function calls are similar to those of the C API. These functions comply with current recommendations of the Internet Engineering Task Force (IETF) for the C API. Note though that the PL/SQL API contains only a subset of the functions available in the C API. Most notably, only synchronous calls to the LDAP server are available in the PL/SQL API.

To begin using the PL/SQL LDAP API, use this command sequence to load DBMS_LDAP into the database:

1. Log in to the database, using SQL*Plus. Run the tool in the Oracle home in which your database is present. Connect as SYSDBA.

   SQL> CONNECT / AS SYSDBA
   

2. Load the API into the database, using this command:

   SQL> @?/rdbms/admin/catladap.sql
   

2.4.4 Getting Started with the Java API

Java developers can use the Java Naming and Directory Interface (JNDI) from Sun Microsystems to gain access to information in Oracle Internet Directory. The JNDI is found at this link:

http://java.sun.com/products/jndi

Although no Java APIs are provided in this chapter, the section immediately following, "Initializing the Session by Using JNDI", shows you how to use wrapper methods for the Sun JNDI to establish a basic connection.

2.5.1 Initializing the Session by Using the C API

The C function ldap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing options to be set after initialization.

ldap_init has the following syntax:

LDAP *ldap_init
(

const char      *hostname,
int             portno

);

Table 2-3 lists and defines the function parameters.

hostname

portno

ldap_init() and ldap_open() both return a session handle, or pointer, to an opaque structure that must be passed to subsequent calls to the session. These routines return NULL if the session cannot be initialized. You can check the error reporting mechanism for your operating system to determine why the call failed.

2.5.2 Initializing the Session by Using DBMS_LDAP

In the PL/SQL API, the function DBMS_LDAP.init() initiates an LDAP session. This function has the following syntax:

FUNCTION init (hostname IN VARCHAR2, portnum  IN PLS_INTEGER )

RETURN SESSION;

The function init requires a valid host name and port number to establish an LDAP session. It allocates a data structure for this purpose and returns a handle of the type DBMS_LDAP.SESSION to the caller. The handle returned from the call should be used in all subsequent LDAP operations defined by DBMS_LDAP for the session. The API uses these 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, although the number of simultaneous active connections is limited to 64. One database session typically has multiple LDAP sessions when data must be obtained from multiple servers simultaneously or when open sessions that use multiple LDAP identities are required.

2.5.3 Initializing the Session by Using JNDI

The oracle.ldap.util.jndi package supports basic connections by providing wrapper methods for the JNDI implementation from Sun Microsystems. If you want to use the JNDI to establish a connection, see the following link:

http://java.sun.com/products/jndi

Here is an implementation of oracle.ldap.util.jndi that establishes a non-SSL connection:

import oracle.ldap.util.jndi
import javax.naming.*;

public static void main(String args[])
{
  try{
       InitialDirContext ctx = ConnectionUtil.getDefaultDirCtx(args[0], // host
                                                         args[1],  // port
                                                         args[2],  // DN
                                                         args[3];  // password)
       // Do work
     }
  catch(NamingException ne)
  {
    // javax.naming.NamingException is thrown when an error occurs
  }
}

2.6.1 Authenticating an LDAP Session by Using the C API

The C function ldap_simple_bind_s() enables users and applications to authenticate to the directory server using a DN and password.

The function ldap_simple_bind_s() has this syntax:

int ldap_simple_bind_s
(
LDAP* ld,
char* dn,
char* passwd
);

Table 2-4 lists and describes the parameters for this function.

ld

dn

passwd 

If the dn and passwd parameters for are NULL, the LDAP server assigns a special identity, called anonymous, to the user or application.

2.6.2 Authenticating an LDAP Session by Using DBMS_LDAP

The PL/SQL function simple_bind_s enables users and applications to use a DN and password to authenticate to the directory. simple_bind_s has this syntax:

FUNCTION simple_bind_s ( ld IN SESSION, dn IN VARCHAR2, passwd IN VARCHAR2)

RETURN PLS_INTEGER;

Note that this function requires as its first parameter the LDAP session handle obtained from init.

The following PL/SQL code snippet shows how the PL/SQL initialization and authentication functions just described might be implemented.

DECLARE

retval    PLS_INTEGER;
my_session       DBMS_LDAP.session;

BEGIN

retval    := -1;
-- Initialize the LDAP session
my_session       := DBMS_LDAP.init('yow.example.com',3060);
--Authenticate to the directory
retval  :=DBMS_LDAP.simple_bind_s(my_session,'cn=orcladmin',          'welcome');

In the previous example, an LDAP session is initialized on the LDAP server yow.example.com. This server listens for requests at TCP/IP port number 3060. The identity cn=orcladmin, whose password is welcome, is then authenticated. After authentication is complete, regular LDAP operations can begin.

2.7.1 Program Flow for Search Operations

The programming required to initiate a typical search operation and retrieve results can be broken down into the following steps:

1. Decide what attributes must be returned; then place them into an array.

2. Initiate the search, using the scope options and filters of your choice.

3. Obtain an entry from result set.

4. Obtain an attribute from the entry obtained in step 3.

5. Obtain the values of the attributes obtained in step 4; then copy these values into local variables.

6. Repeat step 4 until all attributes of the entry are examined.

7. Repeat Step 3 until there are no more entries

Figure 2-4 uses a flowchart to represent these steps.

Figure 2-4 Flow of Search-Related Operations

2.7.2 Search Scope

The scope of a search determines how many entries the directory server examines relative to the search base. You can choose one of the three options described in Table 2-5 and illustrated in Figure 2-5.

SCOPE_BASE

SCOPE_ONELEVEL

SCOPE_SUBTREE

Figure 2-5 The Three Scope Options

In Figure 2-5, the search base is the shaded circle. The shaded rectangle identifies the entries that are searched.

2.7.3 Filters

A search filter is an expression that enables you to confine your search to certain types of entries. The search filter required by the search_s() and search_st() functions follows the string format defined in RFC 1960 of the Internet Engineering Task Force (IETF). As Table 2-6 shows, there are six kinds of search filters. These are entered in the format attribute operator value.

(att=value)

(sn=Keaton)

(att~=value)

(sn~=Ketan)

(attr=[leading]*[any]*[trailing]

(sn=*keaton*)

(sn=keaton*)

(sn=*keaton)

(sn=ke*at*on)

attr>=value

(sn>=Keaton)

(attr<=value)

(sn<=Keaton)

(attr=*)

(sn=*)

attr[:dn]:=value

(sn:dn:=Mary Smith)

You can use boolean operators and prefix notation to combine these filters to form more complex filters. Table 2-7 provides examples. In these examples, the & character represents AND, the | character represents OR, and the ! character represents NOT.

(&(filter1)(filter2)). . .)

(&(sn=keaton)(objectclass=inetOrgPerson))

(|(filter1)(filter2)). . .)

(|(sn~=ketan)(cn=*keaton))

(!(filter))

(!(mail=*))

The complex filters in Table 2-7 can themselves be combined to create even more complex, nested filters.

2.7.4 Searching the Directory by Using the C API

The C function ldap_search_s() performs a synchronous search of the directory.

The syntax for ldap_search_s()looks like this:

int ldap_search_s
(
LDAP*         ld,
char*         base,
int           scope,
char*         filter
int           attrsonly,
LDAPMessage** res
);

ldap_search_s works with several supporting functions to refine the search. The steps that follow show how all of these C functions fit into the program flow of a search operation. Chapter 8, "C API Reference", examines all of these functions in depth.

1. Decide what attributes must be returned; then place them into an array of strings. The array must be null terminated.

2. Initiate the search, using ldap_search_s(). Refine your search with scope options and filters.

3. Obtain an entry from the result set, using either the ldap_first_entry() function or the ldap_next_entry() function.

4. Obtain an attribute from the entry obtained in step 3. Use either the ldap_first_attribute() function or the ldap_next_attribute() function for this purpose.

5. Obtain all the values for the attribute obtained in step 4; then copy these values into local variables. Use the ldap_get_values() function or the ldap_get_values_len() function for this purpose.

6. Repeat step 4 until all attributes of the entry are examined.

7. Repeat step 3 until there are no more entries.

ld

base

scope

filter

attrs

attrso

res

2.7.5 Searching the Directory by Using DBMS_LDAP

You use the function DBMS_LDAP.search_s()to perform directory searches if you use the PL/SQL API.

Here is the syntax for DBMS_LDAP.search_s():

FUNCTION search_s

(
ld       IN  SESSION,
base     IN  VARCHAR2,
scope    IN  PLS_INTEGER,
filter   IN  VARCHAR2,
attrs    IN  STRING_COLLECTION,
attronly IN  PLS_INTEGER,
res      OUT MESSAGE
)

RETURN PLS_INTEGER;

The function takes the arguments listed and described in Table 2-9.

ld

base

scope

filter

attrs

attronly

res

search_s works with several supporting functions to refine the search. The steps that follow show how all of these PL/SQL functions fit into the program flow of a search operation.

1. Decide what attributes need to be returned; then place them into the DBMS_LDAP.STRING_COLLECTION data-type.

2. Perform the search, using either DBMS_LDAP.search_s()or DBMS_LDAP.search_st(). Refine your search with scope options and filters.

3. Obtain an entry from the result set, using eitherDBMS_LDAP.first_entry() or DBMS_LDAP.next_entry().

4. Obtain an attribute from the entry obtained in step 3. Use either DBMS_LDAP.first_attribute() or DBMS_LDAP.next_attribute() for this purpose.

5. Obtain all the values for the attribute obtained in step 4; then copy these values into local variables. Use either DBMS_LDAP.get_values() or DBMS_LDAP.get_values_len() for this purpose.

6. Repeat step 4 until all attributes of the entry are examined.

7. Repeat step 3 until there are no more entries.

2.8.1 Terminating the Session by Using the C API

After an LDAP session handle is obtained and all directory-related work is complete, the LDAP session must be destroyed. In the C API, the ldap_unbind_s() function is used for this purpose.

ldap_unbind_s() has this syntax:

int ldap_unbind_s
(
        LDAP*    ld
);

A successful call to ldap_unbind_s()closes the TCP/IP connection to the directory. It de-allocates system resources consumed by the LDAP session. Finally it returns the integer LDAP_SUCCESS to its callers. After ldap_unbind_s()is invoked, no other LDAP operations are possible. A new session must be started with ldap_init().

2.8.2 Terminating the Session by Using DBMS_LDAP

The DBMS_LDAP.unbind_s() function destroys an LDAP session if the PL/SQL API is used. unbind_s has the following syntax:

FUNCTION unbind_s (ld IN SESSION )  RETURN PLS_INTEGER;

unbind_s closes the TCP/IP connection to the directory. It de-allocates system resources consumed by the LDAP session. Finally it returns the integer DBMS_LDAP.SUCCESS to its callers. After the unbind_s is invoked, no other LDAP operations are possible. A new session must be initiated with the init function.