5 Using the API Extensions in PL/SQL

This chapter explains how to use PL/SQL extensions to the standard directory APIs to manage and authenticate users. Note that the Oracle extensions do not include PL/SQL APIs that create users. The Oracle extensions to the standard APIs are documented in full in Chapter 14.

This chapter contains these topics:

Sample Code
Installing the PL/SQL Extensions
Using Handles to Access Directory Data
Managing Users
Authenticating Users
Dependencies and Limitations of the PL/SQL LDAP API

5.1 Sample Code

Sample code is available at this URL:

http://www.oracle.com/technology/sample_code/

Look for the Oracle Identity Management link under Sample Applications–Oracle Application Server.

5.2 Installing the PL/SQL Extensions

The PL/SQL extensions are installed with the DBMS_LDAP package when the Oracle database is installed. You must run the script $ORACLE_HOME/rdbms/admin/catldap.sql.

5.3 Using Handles to Access Directory Data

Most of the extensions described in this chapter are helper functions. They access data about specific LDAP entities such as users, groups, realms, and applications. In many cases, these functions must pass a reference to one of these entities to the standard API functions. To do this, the API extensions use opaque data structures called handles. The steps that follow show an extension creating a user handle:

Establish an LDAP connection or get one from a pool of connections.
Create a user handle from user input. This could be a DN, a GUID, or a single sign-on user ID.
Authenticate the user with the LDAP connection handle, user handle, or credentials.
Free the user handle.
Close the LDAP connection, or return the connection back to the connection pool.

5.4 Managing Users

The steps that follow show how the DBMS_LDAP_UTL package is used to create and use a handle that retrieves user properties from the directory.

Invoke DBMS_LDAP_UTL.create_user_handle(user_hd, user_type, user_id) to create a user handle from user input. The input can be a DN, a GUID, or a single sign-on user ID.
Invoke DBMS_LDAP_UTL.set_user_handle_properties(user_hd, property_type, property) to associate a realm with the user handle.
Invoke DBMS_LDAP_UTL.get_user_properties(ld, user_handle, attrs, ptype, ret_pset_coll) to place the attributes of a user entry into a result handle.
Invoke DBMS_LDAP_UTL.get_property_names(pset, property_names) and DBMS_LDAP_UTL.get_property_values(pset, property_name, property_values) to extract user attributes from the result handle that you obtained in step 3.

5.5 Authenticating Users

Use DBMS_LDAP_UTL.authenticate_user(session, user_handle, auth_type, cred, binary_cred) to authenticate a user to the directory. This function compares the password provided by the user with the password attribute in the user's directory entry.

5.6 Dependencies and Limitations of the PL/SQL LDAP API

The PL/SQL LDAP API for this release has the following limitations:

The LDAP session handles obtained from the API are valid only for the duration of the database session. The LDAP session handles cannot be written to a table and reused in other database sessions.
Only synchronous versions of LDAP API functions are supported in this release.

The PL/SQL LDAP API requires a database connection to work. It cannot be used in client-side PL/SQL engines (like Oracle Forms) without a valid database connection.