Skip Headers
Oracle® Identity Management Application Developer's Guide
10g (

Part Number B15997-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

3 Extensions to the LDAP Protocol

This chapter describes extensions to the LDAP protocol that are available in Oracle Internet Directory 10g (

This chapter contains these topics:

3.1 SASL Authentication

Oracle Internet Directory supports two mechanisms for SASL-based authentication. This section describes the two methods. It contains these topics:

3.1.1 SASL Authentication by Using DIGEST-MD5

SASL Digest-MD5 authentication is the required authentication mechanism for LDAP Version 3 servers (RFC 2829). LDAP Version 2 does not support Digest-MD5.

To use the Digest-MD5 authentication mechanism, you can use either the Java API or the C API to set up the authentication. The C API supports only auth mode.

The SASL Digest-MD5 mechanism includes three modes, each representing a different security level or "Quality of Protection." They are:

  • auth—Authentication only. Authentication is required only for the initial bind. After that, information is passed in clear text.

  • auth-int—Authentication plus integrity. Authentication is required for the initial bind. After that, check sums are used to guarantee the integrity of the data.

  • auth-conf—Authentication plus confidentiality. Authentication is required for the initial bind. After that, encryption is used to protect the data. Five cipher choices are available:

    • DES

    • 3DES

    • RC4

    • RC4-56

    • RC4-40

These are all symmetric encryption algorithms.

Prior to 10g (, Oracle Internet Directory supported only the auth mode of the Digest-MD5 mechanism. As of 10g (, Oracle Internet Directory supports all three modes with the Java Naming and Directory Interface (JNDI) of jdk1.4 API or with the OpenLDAP Java API. The Oracle LDAP SDK supports only auth mode.

Out of the box, Oracle Internet Directory SASL Digest-MD5 authentication supports generation of static SASL Digest-MD5 verifiers based on user or password, but not based on realm. If you want to use SASL Digest-MD5 with realms, you must enable reversible password generation by changing the value of the orclpasswordencryptionenable attribute to 1 in the related password policy before provisioning new users. The LDIF file for modifying the value should look like this:

dn: cn=default,cn=pwdPolicies,cn=Common,cn=Products,cn=OracleContext
changetype: modify
replace: orclpwdencryptionenable
orclpwdencryptionenable: 1

The Digest-MD5 mechanism is described in RFC 2831 of the Internet Engineering Task Force. It is based on the HTTP Digest Authentication (RFC 2617).

See Also: Steps Involved in SASL Authentication by Using DIGEST-MD5

SASL Digest-MD5 authenticates a user as follows:

  1. The directory server sends data that includes various authentication options that it supports and a special token to the LDAP client.

  2. The client responds by sending an encrypted response that indicates the authentication options that it has selected. The response is encrypted in such a way that proves that the client knows its password.

  3. The directory server then decrypts and verifies the client's response.

3.1.2 SASL Authentication by Using External Mechanism

The following is from section 7.4 of RFC 2222 of the Internet Engineering Task Force.

The mechanism name associated with external authentication is "EXTERNAL". The client sends an initial response with the authorization identity. The server uses information, external to SASL, to determine whether the client is authorized to authenticate as the authorization identity. If the client is so authorized, the server indicates successful completion of the authentication exchange; otherwise the server indicates failure.

The system providing this external information may be, for example, IPsec or SSL/TLS.

If the client sends the empty string as the authorization identity (thus requesting the authorization identity be derived from the client's authentication credentials), the authorization identity is to be derived from authentication credentials that exist in the system which is providing the external authentication.

Oracle Internet Directory provides the SASL external mechanism over an SSL mutual connection. The authorization identity (DN) is derived from the client certificate during the SSL network negotiation.

3.2 Using Controls

The LDAPv3 Protocol, as defined by RFC 2251, allows extensions by means of controls. Oracle Internet Directory supports several controls. Some are standard and described by RFCs. Other controls, such as the CONNECT_BY control for hierarchical searches are Oracle-specific. You can use controls with either Java or C.

Controls can be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls. The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server.

For information about using LDAP controls in C, see "Working With Controls".

For information about using LDAP controls in Java, see the documentation for the JNDI package javax.naming.ldap at

The following controls are supported by Oracle Internet Directory 10g (

Table 3-1 Controls Supported by Oracle Internet Directory

Object Identifier Name Description



Used to manage referrals, dynamic groups, and alias objects in Oracle Internet Directory. For more information, please see RFC 3296, "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories," at



Used to perform a proxy switch of an identity on an established LDAP connection. For example, suppose that Application A connects to the directory server and then wishes to switch to Application B. It can simply do a rebind by supplying the credentials of Application B. However, there are times when the proxy mechanism for the application to switch identities could be used even when the credentials are not available. With this control, Application A can switch to Application B provided Application A has the privilege in Oracle Internet Directory to proxy as Application B.



Sent by applications that require Oracle Internet Directory to check for account lockout before sending the verifiers of the user to the application. If Oracle Internet Directory detects this control in the verifier search request and the user account is locked, then Oracle Internet Directory will not send the verifiers to the application. It will send an appropriate password policy error.



See "Performing Hierarchical Searches"



Intended for a client to send the end user IP address if IP lockout is to be enforced by Oracle Internet Directory.



Used with dynamic groups. Directs the directory server to read the specific attributes of the members rather than the membership lists.



Password policy control. Request control that the client sends to get a response from the server.



Password policy control. Response control that the server sends when the pwdExpireWarning attribute is enabled and the client sends the request control. The response control value contains the time in seconds to password expiration.



Password policy control. The response control that the server sends when grace logins are configured and the client sends a request control. The response control value contains the remaining number of grace logins.



Password policy control. The response control that the server sends when forced password reset is enabled and the client sends the request control. The client must force the user to change the password upon receipt of this control.



The request control that the client sends when it wants the server to create a dynamic password verifier. The server uses the parameters in the request control to construct the verifier.



The response control that the server sends to the client when an error occurs. The response control contains the error code.



If this control is included in a verifier search request, all password policies that are applicable to the user are applied to the verifier search.



Certificate search control. The request control that the client sends to specify how to search for a user certificate.



See "Sorted LDAP Search Results".



See "Paged LDAP Search Results".

To find out what controls are available in your Oracle Internet Directory installation, type:

ldapsearch -p port -b "" -s base "objectclass=*"

Look for entries that begin with supportedcontrol=.

3.3 Proxying on Behalf of End Users

Often applications must perform operations that require impersonating an end user. An application may, for example, want to retrieve resource access descriptors for an end user. (Resource access descriptors are discussed in the concepts chapter of Oracle Internet Directory Administrator's Guide.)

A proxy switch occurs at run time on the JNDI context. An LDAP v3 feature, proxying can only be performed using InitialLdapContext, a subclass of InitialDirContext. If you use the Oracle extension oracle.ldap.util.jndi.ConnectionUtil to establish a connection (the example following), InitialLdapContext is always returned. If you use JNDI to establish the connection, make sure that it returns InitialLdapContext.

To perform the proxy switch to an end user, the user DN must be available. To learn how to obtain the DN, see the sample implementation of the oracle.ldap.util.User class at this URL:

Look for the Oracle Identity Management link under Sample Applications—Fusion Middleware, then look for "Sample Application Demonstrating Proxy Switching using Oracle Internet Directory Java API."

This code shows how the proxy switch occurs:

import oracle.ldap.util.jndi.*;
import javax.naming.ldap.*;
import javax.naming.*;

public static void main(String args[])
       InitialLdapContext appCtx=ConnectionUtil.getDefaultDirCtx(args[0], // host
                                                                 args[1], // port
                                                                 args[2], // DN
                                                                 args[3]; // pass)
         // Do work as application
         // . . .
         String userDN=null;
         // assuming userDN has the end user DN value
         // Now switch to end user
         ctx.addToEnvironment(Context.SECURITY_PRINCIPAL, userDN);
         ctx.addToEnvironment("", "");
         Control ctls[] = {
           new ProxyControl()
         // Do work on behalf of end user
         // . . .
    catch(NamingException ne)
       // javax.naming.NamingException is thrown when an error occurs 

The ProxyControl class in the code immediately preceding implements a javax.naming.ldap.Control. To learn more about LDAP controls, see the LDAP control section of Oracle Identity Management User Reference. Here is an example of what the ProxyControl class might look like:

import javax.naming.*;
import javax.naming.ldap.Control;
import java.lang.*;
public class ProxyControl implements Control {
   public byte[] getEncodedValue() {
      return null;
   public String getID() {
      return "2.16.840.1.113894.1.8.1";
   public boolean isCritical() {
      return false;

3.4 Creating Dynamic Password Verifiers

You can modify the LDAP authentication APIs to generate application passwords dynamically—that is, when users log in to an application. This feature has been designed to meet the needs of applications that provide parameters for password verifiers only at runtime.

This section contains the following topics:

3.4.1 Request Control for Dynamic Password Verifiers

Creating a password verifier dynamically involves modifying the LDAP authentication APIs ldap_search or ldap_modify to include parameters for password verifiers. An LDAP control called DynamicVerifierRequestControl is the mechanism for transmitting these parameters. It takes the place of the password verifier profile used to create password verifiers statically. Nevertheless, dynamic verifiers, like static verifiers, require that the directory attributes orclrevpwd (synchronized case) and orclunsyncrevpwd (unsynchronized case) be present and that these attributes be populated.

Note that the orclpwdencryptionenable attribute of the password policy entry in the user's realm must be set to 1 if orclrevpwd is to be generated. If you fail to set this attribute, an exception is thrown when the user tries to authenticate. To generate orclunsyncrevpwd, you must add the crypto type 3DES to the entry cn=defaultSharedPINProfileEntry,cn=common,cn=products,cn=oraclecontext.

3.4.2 Syntax for DynamicVerifierRequestControl

The request control looks like this:

controlOid:  2.16.840.1.113894.1.8.14  
criticality:  FALSE
controlValue: an OCTET STRING whose value is the BER encoding of the following type:

ControlValue ::= SEQUENCE {

                  version [0]
                  crypto  [1] CHOICE OPTIONAL {
                     SASL/MD5  [0] LDAPString,
                     SyncML1.0 [1] LDAPString,
                     SyncML1.1 [2] LDAPString, 
                     CRAM-MD5  [3] LDAPString },
                  username [1] OPTIONAL LDAPString,
                  realm    [2] OPTIONAL LDAPString,
                  nonce    [3] OPTIONAL LDAPString,

Note that the parameters in the control structure must be passed in the order in which they appear. Table 3-2 defines these parameters.

Table 3-2 Parameters in DynamicVerifierRequestControl

Parameter Description

The string that uniquely identifies the control structure.


The hashing algorithm. Choose one of the four identified in the control structure.


The distinguished name (DN) of the user. This value must always be included.


A randomly chosen realm. It may be the identity management realm that the user belongs to. It may even be an application realm. Required only by the SASL/MD5 algorithm.


An arbitrary, randomly chosen value. Required by SYNCML1.0 and SYNCML1.1.

3.4.3 Parameters Required by the Hashing Algorithms

Table 3-3 lists the four hashing algorithms that are used to create dynamic password verifiers. The table also lists the parameters that each algorithm uses as building blocks. Note that, although all algorithms use the user name and password parameters, they differ in their use of the realm and nonce parameters.

Table 3-3 Parameters Required by the Hashing Algorithms

Algorithm Parameters Required


username, realm, password


username, password, nonce


username, password, nonce


username, password

3.4.4 Configuring the Authentication APIs

Applications that require password verifiers to be generated dynamically must include DynamicVerifierRequestControl in their authentication APIs. Either ldap_search or ldap_compare must incorporate the controlOID and the control values as parameters. They must BER-encode the control values as shown in "Syntax for DynamicVerifierRequestControl"; then they must send both controlOID and the control values to the directory server. Parameters Passed If ldap_search Is Used

If you want the application to authenticate the user, use ldap_search to pass the control structure. If ldap_search is used, the directory passes the password verifier that it creates to the client.

ldap_search must include the DN of the user, the controlOID, and the control values. If the user's password is a single sign-on password, the attribute passed is authpassword. If the password is a numeric pin or another type of unsynchronized password, the attribute passed is orclpasswordverifier;orclcommonpin. Parameters Passed If ldap_compare Is Used

If you want Oracle Internet Directory to authenticate the user, use ldap_compare to pass the control structure. In this case, the directory retains the verifier and authenticates the user itself.

Like ldap_search, ldap_compare must include the DN of the user, the controlOID, the control values, and the user's password attribute. For ldap_compare, the password attribute is orclpasswordverifier;orclcommonpin (unsynchronized case).

3.4.5 Response Control for Dynamic Password Verifiers

When it encounters an error, the directory sends the LDAP control DynamicVerifierResponseControl to the client. This response control contains the error code. To learn about the error codes that the response control sends, see the troubleshooting chapter in Oracle Internet Directory Administrator's Guide.

3.4.6 Obtaining Privileges for the Dynamic Verifier Framework

If you want the directory to create password verifiers dynamically, you must add your application identity to the VerifierServices group of directory administrators. If you fail to perform this task, the directory returns an LDAP_INSUFFICIENT_ACCESS error.

3.5 Performing Hierarchical Searches

One of the server controls you can pass to an LDAP search function is CONNECT_BY. This is an Oracle-specific control that causes the search to traverse a hierarchy. For example, if you search for all the users in group1, without the CONNECT_BY control, the search function will return only users who are direct members of group1. If you pass the CONNECT_BY control, however, the search function will traverse the hierarchy. If group2 is a member of group1, the search will also return users in group2. If group3 is a member of group2, the search will also return users in group3, and so forth.

3.5.1 New Features of the CONNECT_BY Control

In 10g (, the CONNECT_BY control has been enhanced in two ways:

  • You can now traverse the hierarchy in either direction. That is, you can search through all containers in which an entry is contained, as well as through all containers contained within an entry.

  • You can now specify the number of levels of the hierarchy to search.

3.5.2 Value Fields in the CONNECT_BY Control

In previous releases, the CONNECT_BY control required no values. Because of the new functionality, you can now pass one or both of the following values to CONNECT_BY:

  • Hierarchy-establishing attribute–A string representing the attribute to be searched. This value is necessary only when searching through all containers in which an entry is contained. When searching through containers contained within an entry, you need not provide this value because the search filter provides that information.

  • Number of levels–An integer representing the number of levels to traverse. If the value is 0, the search will traverse all levels. The default value is 0, so you need not pass this value if you want the search to traverse all leve.s

Example 1: Find All the Groups to Which a User Belongs

Using a filter such as (member=cn=jsmith), you do not need to provide the hierarchy-establishing attribute member because it is in the search filter. You do not need to pass a value for the number of levels because 0 is the default.

Example 2: Find Only the Groups to Which a User Directly Belongs

Using the same filter as in Example 1, you would pass the integer control value 1. The result would be the same as if you did not use the CONNECT_BY control at all.

Example 3: Find All Members of a Group

In this case, your search filter would specify (objectclass=*), but if you want to find all members of group1, the attribute for traversing the hierarchy is member. For this search, you must pass the string "member" as the hierarchy-establishing attribute. You do not need to pass a value for the number of levels because 0 is the default.

Example 4: Finding all Managers of a User

This is similar to Example 3, except that you want to find all managers of the user jsmith, so manager is the attribute for traversing the hierarchy. For this search, you would pass the string "manager". You do not need to pass a value for the number of levels because 0 is the default.

3.6 Sorted LDAP Search Results

As of Oracle Internet Directory 10g (, you can obtain sorted results from an LDAP search, as described by IETF RFC 2891. You request sorted results by passing a control of type 1.2.840.113556.1.4.473 to the search function. The server returns a response control is of type 1.2.840.113556.1.4.474. Error processing and other details are described in RFC 2891.

See Also:

IETF RFC 2891, "LDAP Control Extension for Server Side Sorting of Search Results," at

Sorting and paging may be used together.

The Oracle Internet Directory implementation of RFC 2891 has the following limitations:

3.7 Paged LDAP Search Results

As of Oracle Internet Directory 10g (, you can obtain paged results from an LDAP search, as described by IETF RFC 2696. You request sorted results by passing a control of type 1.2.840.113556.1.4.319 to the search function. Details are described in RFC 2696.

See Also:

IETF RFC 2696, "LDAP Control Extension for Simple Paged Results Manipulation," at

Sorting and paging may be used together.

The Oracle Internet Directory implementation of RFC 2696 has the following limitations: