3 Extensions to the LDAP Protocol

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 (10.1.4.0.1), Oracle Internet Directory supported only the auth mode of the Digest-MD5 mechanism. As of 10g (10.1.4.0.1), 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).

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

DynamicVerifierRequestControl
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-3 defines these parameters.

controlOID

crypto

username

realm

nonce

3.4.3 Parameters Required by the Hashing Algorithms

Table 3-4 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.

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 Section 3.4.2, "Syntax for DynamicVerifierRequestControl." Then they must send both controlOID and the control values to the directory server.

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 Fusion Middleware Administrator's Guide for Oracle Internet Directory.

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.1 New Features of the CONNECT_BY Control

In 10g (10.1.4.0.1), the CONNECT_BY control was 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, and 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 traverses 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.8.1 User Provisioning

If your application provisions its own users in the directory, you should test passwords for acceptability by the server before committing the new user entry into the directory. You can test a password by using the following custom control:

EffectivePolicyControl
::= SEQUENCE {
                        controlType     2.16.840.1.113894.1.8.29,
                        criticality     BOOLEAN DEFAULT FALSE,
                        controlValue    testPassword
                       }
testPassword ::= OCTET STRING (optional)

Package this control as part of an LDAP base search, where the base DN is that of the user entry being tested. The entry does not need to exist in the directory at the time. The server returns the LDAP entry describing the applicable password policy, assuming the entity performing the search has the access rights to view the password policy entry. Providing the desired password as the optional testPassword parameter results in the directory server returning the following response control:

PasswordValidationControl
::= SEQUENCE {
                        controlType     2.16.840.1.113894.1.8.32,
                        criticality     BOOLEAN DEFAULT FALSE,
                        controlValue    validationResult
                       }
validationResult ::= OCTET STRING

Your client application can parse the validationResult to determine whether the password is accepted by the server ("Success") or the reason it has been rejected. The error message is the same as that generated during a failed LDAP modify operation on userpassword.

3.8.2 User Authentication

User authentication use-cases broadly fall into two main categories:

1. LDAP Bind/Compare Operation-Based Authentication

2. LDAP Search Operation-Based Authentication

The former refers to authentication performed on the standard userpassword attribute. The entire authentication process is performed within the directory server, and appropriate internal events are generated to update various account states as necessary.

The latter refers to authentication performed against other authentication tokens, such as password verifiers, maintained as part of a user entry. The token may be retrieved by the application. The authentication process occurs within the application and outside the scope of the directory server. Therefore in LDAP search-based authentications, the directory does not implicitly know the result of the authentication attempt.

The following two subsections describe the best practices for application integration when dealing with these two types of authentication scenarios.

PasswordStatusRequestControl
::= SEQUENCE {
                        controlType     2.16.840.1.113894.1.8.6,
                        criticality     BOOLEAN DEFAULT FALSE,
                       }

AccountStatusRequestControl
::= SEQUENCE {
                        controlType     2.16.840.1.113894.1.8.16,
                        criticality     BOOLEAN DEFAULT FALSE,
                       }

dn: UserDN
changetype: modify
replace: orclAccountStatusEvent
orclAccountStatusEvent: UserAccountEvent

UserAccountEvent = 1 (Authentication Success)
UserAccountEvent = 2 (Authentication Failure)

3.8.3 User Account Maintenance

User account maintenance and its interaction with password policies occur mostly around periodic password modifications. We recommend that applications utilize the EffectivePolicyControl described above to retrieve the effective policy and parse it to generate a message guiding the end user to the password construction requirements. Furthermore, we encourage the usage of the "test" capabilities encapsulated in this control to direct the end user towards the cause behind a modification failure. Handling these situations within the application reduces administrative overhead.

Secondly, there are a multitude of use-cases requiring a user to change his or her password upon next logon. The Oracle Internet Directory natively triggers this requirement when the pwdmustchange password policy element is enabled and a userpassword undergoes a non-self modification. However, in the event that an explicit trigger of this requirement is needed, the Oracle Internet Directory supports it also via the orclAccountStatusEvent attribute described above. The relevant events are:

UserAccountEvent = 3 (Require Password Reset on next Logon)
UserAccountEvent = 4 (Clear Password Reset Requirement)

If the application has an administrative interface, this functionality may be desirable and can be exposed to the administrator.