6 Using the API Extensions in PL/SQL
DBMS_LDAP_UTL.authenticate_user()
function.The following topics explain how to use PL/SQL extensions to the standard directory APIs to manage and authenticate users:
-
Process Flow to Create User Handles to Access Directory Data
-
Authenticating Users using DBMS_LDAP_UTL.authenticate_user()
Note:
The Oracle extensions do not include PL/SQL APIs that create users. The Oracle extensions to the standard APIs are documented in full in DBMS_LDAP_UTL PL/SQL Reference.
6.1 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
.
6.2 Process Flow to Create User 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.
6.3 Process Flow to Use the DBMS_LDAP_UTL Package
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)
andDBMS_LDAP_UTL.get_property_values(pset, property_name, property_values)
to extract user attributes from the result handle that you obtained in step 3.
6.4 Authenticating Users using DBMS_LDAP_UTL.authenticate_user()
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.
6.5 Dependencies and Limitations of the PL/SQL LDAP API
The PL/SQL LDAP API for this release has limitations for database session.
Some of the limitations are described below:
-
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.