5
Overview of Oracle Extensions

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

• The LDAP Access Model
• Entities Modeled in LDAP
• API Enhancements: Overview & Usage Model
• API Enhancements: Overview & Usage Model
• API Enhancements: Assumptions
• Installation and First Use

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 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
• Application Startup and Bootstrap Logic
• Application Runtime Logic
• Application Shutdown Logic
• Application Deinstallation Logic

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:

• Pick a connection from the pool of LDAP connections
• If Oracle9iAS Single Sign-On is not used, then authenticate the end-user if required
• If the LDAP operation needs to be performed with the effective rights of the end-user, then switch the user to the end-user identity
• Perform the LDAP operation by using regular API or the enhancements to it described in this chapter
• Once the operation is complete, if the application performed a proxy operation, then ensure that the effective user is now the application identity itself
• Return the LDAP connection back to the pool of connections

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:

Entity	Description
Users	Enterprise users represented in Oracle Internet Directory who have access to one or more applications.
Groups	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.
Subscribers	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:

• Users
• Groups
• Subscribers

Users

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

• User entry properties, which are stored as attributes of the user entry itself--in the same way, for example, as surname or home address
• Extended user preferences, which pertain to a user but are stored in a different location in the DIT. These properties can be further classified as:
  • Extended user properties common to all applications. These are stored in a common location in the Oracle Context.
  • Extended user properties specific to an application. These are stored in the application-specific DIT.
• Querying the group membership of a user
• Authenticating a user given a simple name and credential

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

• A fully qualified LDAP distinguished name (DN)
• A global unique identifier (GUID)
• A simple user name along with the subscriber name

Groups

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:

• A fully qualified LDAP distinguished name
• A global unique identifier
• A simple group name along with the subscriber name

Subscribers

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:

• A fully qualified LDAP distinguished name
• A global unique identifier
• A simple subscriber name

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:

• All of these API functions that require an LDAP connection assume that the application has already established it by using the appropriate mechanisms in the respective programming language
• The LDAP connection being passed into these API functions is associated with an identity that has the necessary permissions to perform the given operation. In other words, the new API functions do not have their own authorization model. Rather, they rely on the LDAP authorization model. If a certain operation fails because of insufficient authorization, the error is simply transmitted back to the invoking application.
• All Java-based applications use Sun's JNDI as the interface for LDAP connectivity
• All PL/SQL based applications use Oracle's DBMS_LDAP package for LDAP connectivity

System Placement

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

Figure 5-2 Placement of Oracle API Enhancements

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:

• Oracle's DBMS_LDAP PL/SQL API, for PL/SQL programs
• Sun's LDAP JNDI Service Provider, for Java programs

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:

• User Management--This functionality allows applications to get or set various user related properties
• Group Management--This functionality allows applications to query group properties
• Subscriber Management--This functionality allows applications to get or set such subscriber-related properties as user search base
• Application Management--This functionality allows applications to manage certain application metadata in Oracle Internet Directory
• Miscellaneous--This functionality--generate GUID--is universally applicable

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.

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 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 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 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:

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.

Java

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.