Skip Headers

Oracle Internet Directory Application Developer's Guide
Release 2 (9.0.2)

Part Number A95193-01
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Overview of Oracle Extensions

This chapter explains how to directory-enable your applications. It contains these topics:

The LDAP Access Model

Most directory-enabled applications are middle-tiers that handle multiple user requests simultaneously. Figure 5-1 shows the usage of LDAP in such middle-tier environments.

Figure 5-1 Oracle Internet Directory in a Middle-Tier Environment

Text description of oiddg007.gif follows
Text description of the illustration oiddg007.gif

As Figure 5-1 shows, applications act as middle-tiers, or backend programs, that multiple users can access. If a user request needs an LDAP operation to be performed, then these applications perform the operation by using a smaller set of pre-created connections to Oracle Internet Directory.

This section tells you how to implement this access model. It contains these sections:

Application Installation Logic

  1. Create in Oracle Internet Directory an identity corresponding to the application. The application uses this identity to perform a majority of the LDAP operations.

  2. Give this identity certain LDAP authorizations, by making it part of the correct LDAP groups, so that it can:

    • Accept user credentials and authenticate them against Oracle Internet Directory

    • Impersonate a user--that is, become a proxy user--if certain LDAP operations have to be performed on behalf of the user

Application Startup and Bootstrap Logic

The application must retrieve the credentials to authenticate itself to Oracle Internet Directory.

If the application stores configuration metadata in Oracle Internet Directory, then it should retrieve that metadata and initialize other parts of the application.

The application should then establish a pool of connections to serve user requests.

Application Runtime Logic

For every end-user request that needs an LDAP operation, the application should:

Application Shutdown Logic

Abandon any outstanding LDAP operations and close all LDAP connections.

Application Deinstallation Logic

Remove the application identity and the associated LDAP authorizations granted to the application identity.

Entities Modeled in LDAP

Oracle enhancements to the LDAP API help applications get or set LDAP information for these entities:


Enterprise users represented in Oracle Internet Directory who have access to one or more applications.


Aggregations of enterprise users that typically signify an authorization. Directory-enabled applications that store these aggregations in the directory must be able to locate groups and query group membership.


Entities modeled in the hosted environment. A subscriber is typically a company that subscribes to one or more Oracle hosting-enabled products.

The rest of this section describes what applications need from Oracle Internet Directory for these entities. It contains these topics:


Directory-enabled applications need to access Oracle Internet Directory for the following user-related operations:

A user is typically identified by the applications by one of the following techniques:


Groups are modeled in Oracle Internet Directory as a collection of distinguished names. Directory-enabled applications need to access Oracle Internet Directory for the following group related operations to get the properties of a group, and verify that a given user is a member of that group.

A group is typically identified by one of the following:


Subscribers are entities or organizations that subscribe to the hosting-enabled services offered in the Oracle product stack. Directory-enabled applications need to access Oracle Internet Directory to get subscriber properties--for example, user search base or password policy--and to create a new subscriber.

A subscriber is typically identified by one of the following:

API Enhancements: Overview & Usage Model

As described in the preceding section, there are several conventions that all applications integrating with the directory need to follow. The primary goal of the API enhancements described in this chapter help you conform your applications to these conventions.

API Enhancements: Assumptions

The API enhancements described in this chapter rest on the following assumptions:

System Placement

Figure 5-2 shows the placement of the API enhancements in relation to existing APIs:

Figure 5-2 Oracle API Enhancements and Existing APIs

Text description of oiddg008.gif follows
Text description of the illustration oiddg008.gif

As Figure 5-2 shows, in the languages--PL/SQL and Java--the API enhancements described in this chapter are layered on top of existing APIs:

Applications need to access the underlying APIs for such common things as connection establishment and connection closing. They can also use the existing APIs to look up other LDAP entries not covered by the API enhancements.

API Enhancements Functional Categorization

Based on the entities on which they operate, these API enhancements can be categorized as follows:

API Enhancements Usage Model

The primary users of the enhancements described in this chapter are middle-tier or back-end applications that must perform LDAP lookups for users, groups, applications, or subscribers. This section describes how these applications integrate these API enhancements into their logic--that is, the usage of the API enhancements only.

See Also:

"The LDAP Access Model" for a conceptual description of the usage model

Figure 5-3 shows the programmatic flow of control for using the API enhancements described in this chapter:

Figure 5-3 Programmatic Flow of API Enhancements

Text description of oiddg009.gif follows
Text description of the illustration oiddg009.gif

As Figure 5-3 shows, the applications first establish a connection to Oracle Internet Directory. They can then use existing API functions and the API enhancements interchangeably.

Programming Abstractions for the PL/SQL Language

Most of the enhancements described in this chapter provide helper functions to access data in relation to such specific LDAP entities as users, groups, subscribers and applications. In many cases, you have to pass a reference to one of these entities to the API functions. These API enhancements use opaque data structures, called handles. For example, an application that needs to authenticate a user would follow these steps:

  1. Establish an LDAP connection, or get it from a pool of connections

  2. Create a user handle based on user input. This could be a DN, or a GUID, or a simple Oracle9iAS Single Sign-On ID.

  3. Authenticate the user with the LDAP connection handle, user handle, and credentials.

  4. Free the user handle.

  5. Close the LDAP connection, or return the connection back to the pool of connections.

Figure 5-4 illustrates this usage model.

Figure 5-4 Programming Abstractions for the PL/SQL Language

Text description of orclapi2.gif follows
Text description of the illustration orclapi2.gif

Programming Abstractions for the Java Language

Instead of handles, LDAP entities--that is, users, groups, subscribers, and applications--are modeled as Java objects in the package. All other utility functionality is modeled either as individual objects--as, for example, GUID--or as static member functions of a utility class.

For example, an application that needs to authenticate a user would have to follow these steps:

  1. Create oracle.ldap.util.user object, given the user DN.

  2. Create a DirContext JNDI object with all of the required properties, or get one from a pool of DirContext objects.

  3. Invoke the User.authenticate function, passing in a reference to the DirContext object and the user credentials.

  4. If DirContext object was retrieved from a pool of existing DirContext objects, return it to that pool.

Unlike C and PL/SQL, Java language usage does not need to explicitly free objects because the Java garbage collection mechanism can do it.

User Management Functionality

This section describes user management functionality for Java, C, and PL/SQL LDAP APIs.


As described in the example in the previous section, all user related functionality is abstracted in a Java class called oracle.ldap.util.User. Following is the high level usage model for this functionality:

  1. Construct oracle.ldap.util.User object based on DN, GUID or simple name.

  2. Invoke User.authenticate(DirContext, Credentials) to authenticate the user if necessary.

  3. Invoke User.getProperties(DirContext) to get the attributes of the user entry itself.

  4. Invoke User.getExtendedProperties(DirContext, PropCategory, PropType) to get the extended properties of the user. PropCategory here is either shared or application-specific. PropType is the object representing the type of property desired. If PropType is NULL, then all properties in a given category are retrieved.

  5. Invoke PropertyType.getDefinition(DirContext) to get the metadata required to parse the properties returned in step 4.

  6. Parse the extended properties and continue with application-specific logic. This parsing is also done by the application specific logic.

Installation and First Use

The Java API is installed as part of the LDAP client installation.

The PL/SQL API are installed as part of the Oracle9i Database installation. To use the PL/SQL API, you must load it by using a script, called catldap.sql, located in $ORACLE_HOME/rdbms/admin.

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index