Package com.unboundid.directory.sdk.ds.api

Class PasswordValidator

java.lang.Object

com.unboundid.directory.sdk.ds.api.PasswordValidator

All Implemented Interfaces:

Configurable, ExampleUsageProvider, Reconfigurable<PasswordValidatorConfig>, UnboundIDExtension

@Extensible
@DirectoryServerExtension
@DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=false)
@SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class PasswordValidator
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<PasswordValidatorConfig>, ExampleUsageProvider

This class defines an API that must be implemented by extensions which attempt to determine whether a proposed user password is acceptable. Each server password policy may be configured with zero or more password validators, and whenever a user changes his or her password (and optionally whenever an administrator resets the password for another user), then each of the password validators configured in the password policy for the target user will be given access to the clear-text password in order to determine whether that password will be allowed. Password validators will also have access to the rest of the user entry, and may also have access to a clear-text version of the user's current password(s) if they were provided in the request.

Configuring Password Validators

In order to configure a password validator created using this API, use a command like:

      dsconfig create-password-validator \
           --validator-name "{validator-name}" \
           --type third-party \
           --set enabled:true \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{validator-name}" is the name to use for the password validator instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.ds.api.PasswordValidator, and "{name=value}" represents name-value pairs for any arguments to provide to the password validator. If multiple arguments should be provided to the password validator, then the "--set extension-argument:{name=value}" option should be provided multiple times.

See Also:

ScriptedPasswordValidator

Constructor Summary

Constructors

Constructor	Description
PasswordValidator()	Creates a new instance of this password validator.

Method Summary

Modifier and Type	Method	Description
ResultCode	applyConfiguration(PasswordValidatorConfig config, ArgumentParser parser, java.util.List<java.lang.String> adminActionsRequired, java.util.List<java.lang.String> messages)	Attempts to apply the configuration from the provided argument parser to this extension.
void	defineConfigArguments(ArgumentParser parser)	Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizePasswordValidator()	Performs any cleanup which may be necessary when this password validator is to be taken out of service.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets()	Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription()	Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName()	Retrieves a human-readable name for this extension.
PasswordQualityRequirement	getPasswordQualityRequirement()	Retrieves the password quality requirement for this password validator, if available.
void	initializePasswordValidator(DirectoryServerContext serverContext, PasswordValidatorConfig config, ArgumentParser parser)	Initializes this password validator.
boolean	invokeForAdd()	Indicates whether this password validator should be invoked for add operations that attempt to create an entry containing one or more password values.
boolean	invokeForAdministrativeReset()	Indicates whether this password validator should be invoked for modify or password modify operations that represent one user's attempt to change the password for another user.
boolean	invokeForSelfChange()	Indicates whether this password validator should be invoked for modify or password modify operations that represent a user's attempt to change his/her own password.
boolean	isConfigurationAcceptable(PasswordValidatorConfig config, ArgumentParser parser, java.util.List<java.lang.String> unacceptableReasons)	Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension.
abstract boolean	isPasswordAcceptable(OperationContext operationContext, ByteString newPassword, java.util.Set<ByteString> currentPasswords, Entry userEntry, java.lang.StringBuilder invalidReason)	Indicates whether the proposed password is acceptable for the specified user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PasswordValidator

public PasswordValidator()

Creates a new instance of this password validator. All password validator implementations must include a default constructor, but any initialization should generally be done in the initializePasswordValidator method.

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

defineConfigArguments

public void defineConfigArguments(ArgumentParser parser)
                           throws ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

ArgumentException - If a problem is encountered while updating the provided argument parser.

initializePasswordValidator

public void initializePasswordValidator(DirectoryServerContext serverContext,
                                        PasswordValidatorConfig config,
                                        ArgumentParser parser)
                                 throws LDAPException

Initializes this password validator.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

config - The general configuration for this password validator.

parser - The argument parser which has been initialized from the configuration for this password validator.

Throws:

LDAPException - If a problem occurs while initializing this password validator.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(PasswordValidatorConfig config,
                                         ArgumentParser parser,
                                         java.util.List<java.lang.String> unacceptableReasons)

Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension. The parser will have been used to parse any configuration available for this extension, and any automatic validation will have been performed. This method may be used to perform any more complex validation which cannot be performed automatically by the argument parser.

Specified by:

isConfigurationAcceptable in interface Reconfigurable<PasswordValidatorConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the proposed configuration for this extension.

unacceptableReasons - A list to which messages may be added to provide additional information about why the provided configuration is not acceptable.

Returns:

true if the configuration in the provided argument parser appears to be acceptable, or false if not.

applyConfiguration

public ResultCode applyConfiguration(PasswordValidatorConfig config,
                                     ArgumentParser parser,
                                     java.util.List<java.lang.String> adminActionsRequired,
                                     java.util.List<java.lang.String> messages)

Attempts to apply the configuration from the provided argument parser to this extension.

Specified by:

applyConfiguration in interface Reconfigurable<PasswordValidatorConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the new configuration for this extension.

adminActionsRequired - A list to which messages may be added to provide additional information about any additional administrative actions that may be required to apply some of the configuration changes.

messages - A list to which messages may be added to provide additional information about the processing performed by this method.

Returns:

A result code providing information about the result of applying the configuration change. A result of SUCCESS should be used to indicate that all processing completed successfully. Any other result will indicate that a problem occurred during processing.

finalizePasswordValidator

public void finalizePasswordValidator()

Performs any cleanup which may be necessary when this password validator is to be taken out of service.

invokeForAdd

public boolean invokeForAdd()

Indicates whether this password validator should be invoked for add operations that attempt to create an entry containing one or more password values.

Returns:

true if this password validator should be invoked for add operations that include one or more passwords, or false if not.

invokeForSelfChange

public boolean invokeForSelfChange()

Indicates whether this password validator should be invoked for modify or password modify operations that represent a user's attempt to change his/her own password.

Returns:

true if this password validator should be invoked for self password change operations, or false if not.

invokeForAdministrativeReset

public boolean invokeForAdministrativeReset()

Indicates whether this password validator should be invoked for modify or password modify operations that represent one user's attempt to change the password for another user.

Returns:

true if this password validator should be invoked for administrative password reset operations, or false if not.

getPasswordQualityRequirement

public PasswordQualityRequirement getPasswordQualityRequirement()

Retrieves the password quality requirement for this password validator, if available.

Returns:

The password quality requirement for this password validator, or null if no requirement information is available.

isPasswordAcceptable

public abstract boolean isPasswordAcceptable(OperationContext operationContext,
                                             ByteString newPassword,
                                             java.util.Set<ByteString> currentPasswords,
                                             Entry userEntry,
                                             java.lang.StringBuilder invalidReason)

Indicates whether the proposed password is acceptable for the specified user.

Parameters:

operationContext - The operation context for the associated request. It may be associated with an add, modify, or password modify operation.

newPassword - The proposed new password for the user that should be validated. It will not be encoded or obscured in any way.

currentPasswords - The current set of passwords for the user, if available. It may be null if this is not available. Note that even if one or more current passwords are available, it may not constitute the complete set of passwords for the user.

userEntry - The entry for the user whose password is being changed.

invalidReason - A buffer to which a message may be appended to indicate why the proposed password is not acceptable.

Returns:

true if the proposed new password is acceptable, or false if not.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.