4.1 Implementing User-defined Password Storage Scheme

The user-defined password storage scheme framework in Oracle Unified Directory (OUD) follows an approach similar to the one of the plugin API described earlier. The User-defined password storage scheme related interfaces and classes are defined in the package, oracle.oud.pwdstoragescheme. For more information on how to set up the IDE environment, see Oracle® Fusion Middleware Java API Reference for Oracle Unified Directory and see Before You Begin Deploying OUD Plug-in.

The custom user-defined password storage scheme must implement the oracle.oud.pwdstoragescheme.ManagedPasswordStorageScheme interface with the generic T as oracle.oud.pwdstoragescheme.UserPassword or oracle.oud.pwdstoragescheme.AuthPassword.

For ease of development, OUD API provides an abstract class oracle.oud.pwdstoragescheme.AbstractPasswordStorageScheme that implements the oracle.oud.pwdstoragescheme.ManagedPasswordStorageScheme interface.

The custom implementation class can extend from oracle.oud.pwdstoragescheme.AbstractPasswordStorageScheme. The implementation class must provide a default constructor implementation and override the methods that implement the underlying logic for encoding and validating password.

Example:

public class CustomUserPasswordHash extends AbstractPasswordStorageScheme<UserPassword>

4.1.1 Important Methods to be Implemented

You need to implement the following important methods:

encodePassword - This method gets invoked when the server needs to encrypt and store the cleartext password. This method must contain the custom implementation code that performs the hashing. While persisting this value, Oracle Unified Directory (OUD) prefixes this encoded value by the name of the custom scheme that is configured in the server.

For example, {custom1}encoded_value, where custom1 is the name of the user-defined password storage scheme in OUD configuration and encoded_value is the value returned by this method.

passwordMatches - This method gets invoked when the server needs to validate the provided cleartext password.

For example, during a ldapbind or ldapcompare operation to validate the credential. This method must contain the custom implementation code that performs this validation and must return true only if the password matches. OUD takes the authentication success or failure decision based on the result of this method invocation.

initializePasswordStorageScheme and handleConfigurationChange - These methods need to be overridden for retrieving user-defined password storage scheme configurations from the server.

A PasswordStorageSchemeConfiguration containing the configurations are provided during invocation of these methods.

The following example shows how to read configurations using oracle.oud.pwdstoragescheme.PasswordStorageSchemeConfiguration. Consider there are two configuration parameters named rounds and saltlength that can be defined in the custom scheme. The custom configuration interface appears as follows:

Example:

publicinterfaceCustomPasswordConfig extendsPasswordStorageSchemeConfiguration {  
   publicintgetRounds() throwsNullPointerException;  
   publicintgetSaltlength() throwsNullPointerException;
}

Inside the user-defined scheme implementation, the above two configuration related overridden methods would read these two parameters as follows:

@Override
public void initializePasswordStorageScheme(
final PasswordStorageSchemeConfiguration configuration)
throws PasswordStorageSchemeException {
try {
  super.initializePasswordStorageScheme(configuration);
  CustomPasswordConfig conf = this.getConfiguration(CustomPasswordConfig.class);
  readConfigParams(conf);
} catch (Exception e) {
    getLogger().logError("Error during CustomUserPasswordHash.initializePasswordStorageScheme "
    + e.getMessage());
    throw new PasswordStorageSchemeException(ResultCode.OPERATIONS_ERROR, e);
  }
}
 
@Override
public void handleConfigurationChange(
final PasswordStorageSchemeConfiguration configuration)
throws PasswordStorageSchemeException {
try {
  super.handleConfigurationChange(configuration);
  CustomPasswordConfig conf = this.getConfiguration(CustomPasswordConfig.class);
  readConfigParams(conf);
} catch (Exception e) {
    getLogger().logError("Error during CustomUserPasswordHash.handleConfigurationChange " + e.getMessage());
    throw new PasswordStorageSchemeException(ResultCode.OPERATIONS_ERROR, e);
  }
}
 
private void readConfigParams(CustomPasswordConfig conf) {
  try {
    this.numSaltBytes = conf.getSaltlength();
  } catch (Exception e) {
    getLogger().logDebug(LEVEL.INFO, "Config parameter saltlength not set");
  }
  try {
    this.numRounds = conf.getRounds();
  } catch (Exception e) {
    getLogger().logDebug(LEVEL.INFO, "Config parameter rounds not set");
  }
}

4.1.2 Writing into OUD Server Logs

The getLogger() method provides a handle to Oracle Unified Directory (OUD) server's logger which can be used to write log messages into error or debug logs at different log levels of the OUD instance.