|Oracle Internet Directory Application Developer's Guide
Part Number A96577-01
This chapter explains how to directory-enable your applications. It contains these topics:
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.
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:
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.
For every end-user request that needs an LDAP operation, the application should:
Abandon any outstanding LDAP operations and close all LDAP connections.
Remove the application identity and the associated LDAP authorizations granted to the application identity.
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:
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.
The API enhancements described in this chapter rest on the following assumptions:
DBMS_LDAPpackage for LDAP connectivity
Figure 5-2 shows the placement of the API enhancements in relation to existing APIs:
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.
Based on the entities on which they operate, these API enhancements can be categorized as follows:
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.
"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:
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.
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:
Figure 5-4 illustrates this usage model.
Instead of handles, LDAP entities--that is, users, groups, subscribers, and applications--are modeled as Java objects in the
oracle.java.util 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:
oracle.ldap.util.userobject, given the user DN.
DirContextJNDI object with all of the required properties, or get one from a pool of DirContext objects.
User.authenticatefunction, passing in a reference to the
DirContextobject and the user credentials.
DirContextobject 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.
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:
oracle.ldap.util.Userobject based on DN, GUID or simple name.
User.authenticate(DirContext, Credentials)to authenticate the user if necessary.
User.getProperties(DirContext)to get the attributes of the user entry itself.
User.getExtendedProperties(DirContext, PropCategory, PropType)to get the extended properties of the user.
PropCategoryhere is either shared or application-specific.
PropTypeis the object representing the type of property desired. If
PropTypeis NULL, then all properties in a given category are retrieved.
PropertyType.getDefinition(DirContext)to get the metadata required to parse the properties returned in step 4.
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