The attribute value password validator

The attribute value password validator can be used to help ensure that users are not allowed to choose passwords that match other information in their entry. For example, a user might want to make their password the same as their username or email address. If an attacker gains access to information in a user’s entry, then they can use that information to customize attacks gained at cracking that user’s password.

The attribute value password validator offers the following configuration options:

match-attribute
The names of the other attributes to check when validating the password. If this is not provided, then all attributes are used by default.
test-password-substring-of-attribute-value
Indicates whether to reject passwords that are a substring of the value of another attribute in the user’s entry. By default, only exact matches are rejected.
test-attribute-value-substring-of-password
Indicates whether to reject passwords that contain the value of another attribute in the user’s entry as a substring. By default, only exact matches are rejected.
minimum-attribute-value-length-for-substring-matches
An integer value that specifies the minimum attribute value length that will be checked if test-attribute-value-substring-of-password is set to true. This can help prevent inappropriately rejecting passwords that happen to contain short attribute values. For example, if you have an attribute whose values can be just a single character, you probably don’t want to prevent passwords that happen to contain that character. By default, only attributes values that contain at least four characters are checked.
test-reversed-password
Indicates whether to check attribute values in reverse order in addition to the order in which the values are stored. For example, if an attribute has value of “jdoe”, then this could cause the server to also check for a value of “eodj”. This is true by default.

See the config/sample-dsconfig-batch-files/use-the-attribute-value-password-validator.dsconfig batch file for more information about using the attribute value password validator.

The character set password validator

The character set password validator can be used to ensure that passwords contain an appropriate combination of characters. For example, you might want to require that a password contain at least one lowercase letter, one uppercase letter, one digit, and one symbol. Or you might want to ensure that a password contains characters from at least three of those four sets.

The character set password validator offers the following configuration properties:

character-set
Defines the sets of characters that are validated. Each of these sets should be defined as an integer followed by a colon and the characters contained in that set. The integer defines the minimum number of characters from that set that must be present in passwords. For example, a character-set value of “1:abcdefghijklmnopqrstuvwxyz” indicates that passwords will be required to have at least one lowercase letter. The integer value can be zero to indicate that characters from that set are permitted to be included in passwords but are not required. By default, the validator is configured with sets containing all lowercase letters, all uppercase letters, all numeric digits, and a range of ASCII symbols, and to require passwords to contain at least one character from each of those sets.
allow-unclassified-characters
Indicates whether to allow passwords to contain characters that are not contained in any of the defined character sets. This is true by default.
minimum-required-character-sets
Specifies the minimum number of character sets that are required to be included in passwords. This is useful, for example, if you want to require passwords to contain characters from at least three of the four predefined sets of lowercase letters, uppercase letters, digits, and symbols. In this case, all of the character sets should be updated to have a minimum required count (the value before the colon) of zero to indicate that they are all optional. If any character set has a nonzero minimum required count, then at least that many characters from that set are required in passwords, even if they would otherwise have contained characters from enough of the other sets.
Note:

While this has been and still is a common practice, it is discouraged by modern password guidelines, such as those in NIST Special Publication 800-63B section 5.1.1.2. Studies have shown that these types of constraints annoy users without significantly improving password security, or even giving the false impression of security.

See the config/sample-dsconfig-batch-files/use-the-character-set-password-validator.dsconfig batch file for more information about using the character set password validator.

The dictionary password validator

The dictionary password validator can be used to prevent passwords that are known to be weak. The server comes predefined with two instances of the dictionary password validator:

  • One that contains a dictionary of common words from a variety of languages
  • One that contains a dictionary of strings that are known to be the most commonly used passwords

We also recommend that you provide your own dictionary that includes additional words not included in either of the included word lists. In particular, we recommend prohibiting words that are related to your company’s name or products or services that you provide.

The dictionary password validator offers the following configuration properties:

dictionary-file
The path to a file containing the list of prohibited passwords. Each line of the file represents a prohibited password.
case-sensitive-validation
Indicates whether differences in capitalization should not be ignored when checking passwords against the dictionary file. By default, the validator uses case-insensitive validation.
test-reversed-password
Indicates whether to test passwords in reversed order when checking them against the dictionary file. For example, to prohibit a password of “terces” if the dictionary contains the word “secret”. Reversed passwords are not checked by default.
ignore-leading-non-alphabetic-characters
Indicates whether to ignore any non-alphabetic characters that might appear at the start of the password when checking passwords against the dictionary file. For example, “123secret” could be rejected if the dictionary contains the word “secret”. By default, all leading characters are considered significant.
ignore-trailing-non-alphabetic-characters
Indicates whether to ignore any non-alphabetic characters that might appear at the end of the password when checking passwords against the dictionary file. For example “secret123” could be rejected if the dictionary contains the word “secret”. By default, all trailing characters are considered significant.
strip-diacritical-marks
Indicates whether to strip diacritical marks, such as accents, cedillas, circumflexes, diaereses, tildes, and umlauts, off of characters before checking passwords against the dictionary. For example, “sèçréť” could be rejected if the dictionary contains the word “secret”. By default, diacritical marks are preserved.
alternative-password-character-mapping
Specifies a set of alternative characters that might be substituted in when checking passwords against a dictionary. For example, if a dollar sign is a substitute for the letter s, the number 3 is a substitute for the letter e, and the number 7 is a substitute for the letter t, then “$3cr37” could be rejected if the dictionary contains the word “secret”. By default, no character substitutions are defined.
maximum-allowed-percent-of-password
Indicates that the proposed password should be rejected if it makes up at least a given percentage of a dictionary word . For example, if this threshold is set to 70%, then “mysecret” could be rejected if the dictionary contains the word “secret” because the word “secret” makes up 75% of “mysecret”. By default, this is set to 100%, so values are ony rejected if they match complete dictionary words (after performing any other configured processing, like stripping of leading or trailing non-alphabetic characters).

See the config/sample-dsconfig-batch-files/use-the-dictionary-password-validator.dsconfig batch file for more information about using the dictionary password validator.

The haystack password validator

The haystack password validator is based on the concept of password haystacks as described at https://www.grc.com/haystack.htm. It is based on the premise that a password’s resistance to brute-force attacks comes from a combination of two factors:

  • The number of characters contained in the password. Longer passwords require more effort to crack than shorter passwords.
  • The types of characters contained in the password. Passwords containing a wider range of characters might require more effort to crack than shorter passwords. For example, a password containing a mix of lowercase and uppercase letters might take longer to crack than a password containing just lowercase letters (at least, if an attacker crafts their attack to prioritize passwords that contain characters from only one set over those that contain passwords from multiple sets)

Because this cost is a combination of two factors, an increase in one of them can make up for a deficiency in another. For example, a password containing only lowercase letters can be very strong if it is long enough, while a shorter password might be acceptable if it contains a wider mix of characters.

This is a useful metric to offer because it can reject passwords that are legitimately easy to crack while not flatly rejecting passwords purely based on the types of characters that they contain. Unfortunately, it can be a difficult concept to succinctly convey to users when describing the requirements that their password will have to satisfy, which might ultimately make it undesirable for use.

The haystack password validator offers the following configuration properties:

assumed-password-guesses-per-second
The assumed rate at which an attacker can make password guessing attempts. By default, the validator assumes a rate of one hundred billion guesses per second.
minimum-acceptable-time-to-exhaust-search-space
The minimum acceptable length of time required to try all possible combinations of characters in the sets that make up the proposed password at the configured maximum rate. By default, the minimum acceptable time is one week.

See the config/sample-dsconfig-batch-files/use-the-haystack-password-validator.dsconfig batch file for more information about using the haystack password validator.

The length-based password validator

The length-based password validator can be used to impose restrictions on the allowed number of characters that a password may contain. Available configuration properties include:

min-password-length
The minimum number of characters that passwords are allowed to contain. Passwords that contain fewer characters than this limit are rejected.
max-password-length
The maximum number of characters that passwords are allowed to contain. Passwords that contain more characters than this limit are rejected. A value of zero indicates that no limit is enforced.

In some cases, it might be useful to impose a maximum length to prevent the server from spending too much processing power on extremely long passwords, but we strongly discourage setting a maximum length that is too short and unnecessarily limits the strength that a password can have. NIST Special Publication 800-63B section 5.1.1.2 recommends allowing passwords to be at least 64 characters long.

The PingDirectory server includes two length-based dictionary validator definitions by default: one with a minimum length of six characters and another with a minimum length of twelve characters. The NIST guidelines referenced above recommend requiring that passwords contain at least 8 characters.

See the config/sample-dsconfig-batch-files/use-the-length-based-password-validator.dsconfig batch file for more information about using the length-based password validator.

The Pwned Passwords password validator

The Pwned Passwords validator can be used to prevent users from choosing passwords that are known to have been compromised. By default, it checks with the free Pwned Passwords service, which includes a database of hundreds of millions of compromised passwords although it can be used with any other service that uses a compatible API.

The Pwned Passwords service uses the k-Anonymity algorithm to allow a client to securely determine whether a password has been compromised without revealing what the proposed password actually is. It does this by first computing an unsalted SHA-1 digest of the proposed password, and then only sending the first five characters of the hexadecimal representation of that digest to the service. The service then identifies all compromised passwords whose hex-encoded SHA-1 digest starts with those five characters and return the remaining 35 characters for all of those digests back to the client. If that returned set includes the last 35 characters in the digest for the proposed password, then it is one that has been known to be compromised.

The Pwned Passwords validator offers the following configuration properties:

pwned-passwords-base-url
The base URL to use for the service with which to communicate. By default, this is https://api.pwnedpasswords.com/range/.
invoke-for-add
Indicates whether the validator should be invoked for passwords set in add requests. Thisis true by default.
invoke-for-self-change
Indicates whether the validator should be invoked for new passwords chosen by the end user. This is true by default.
invoke-for-admin-reset
Indicates whether the validator should be invoked for new passwords set by an administrator. This is true by default.
accept-password-on-service-error
Indicates whether the validator should consider the password acceptable if it cannot communicate with the target service, or if that service returns an error response. By default, the password is considered acceptable although it might still be rejected if it fails to satisfy one or more of the other configured validators.
key-manager-provider
A key manager provider that should be used for HTTPS communication with the target service. This can be omitted, which is the case by default, if no key store is required because the client does not need to present its own client certificate chain to the server.
trust-manager-provider
A trust manager that should be used for HTTPS communication to determine whether to trust the server’s certificate chain. This can be omitted if the server should use the JVM’s default trust store.

See the config/sample-dsconfig-batch-files/use-the-pwned-passwords-validator.dsconfig batch file for more information about using the Pwned Passwords password validator.

The regular expression password validator

The regular expression password validator may be used to require passwords to match a given regular expression, or to reject passwords that do not match a given regular expression. It offers the following configuration properties:

match-pattern
The regular expression pattern to use when evaluating proposed passwords.
match-behavior
The behavior to exhibit if the given pattern matches a proposed password. Allowed values include:
  • require-match — Indicates that the validator should accept passwords that match the provided pattern and reject passwords that do not.
  • reject-match — Indicates that the validator should reject passwords that match the provided pattern and accept passwords that do not.

The repeated characters password validator

The repeated characters password validator can be used to reject passwords that have the same character more than a specified number of times in a row. This can help prevent passwords that contain stretches of the same character repeated several times, such as “aaaaaaaa”.

The repeated characters password validator offers the following configuration properties:

max-consecutive-length
The maximum number of times that the character is allowed to be present consecutively within a proposed password. The default value is 2, which means that it is acceptable for the same character to appear twice in a row, but not three times or more.
case-sensitive-validation
Indicates whether to treat uppercase and lowercase versions of the same letter as different. By default, the validator uses case-insensitive validation, which means that it would reject a password containing the string “aAa” if the validator is configured with a max-consecutive-length of 2.
character-set
An optional set of characters that should be considered equivalent for the purpose of this password validator. For example, you could use this to define a set of numeric digits, and then reject passwords that contain too many consecutive digits.

Although many organizations may use a requirement that rejects passwords with repeated characters, we do not recommend using this validator unless it is configured with a longer limit than the default (for example, four characters rather than two). A limit that is too small may unnecessarily prevent very strong long randomly generated passwords (for example, one created by a password manager) just because the same character happened to occur a few times in a row. However, the unique characters password validator can be used to achieve the same result in a better way, so its use is recommended over the repeated characters validator.

The similarity-based password validator

The similarity-based password validator can be used to prevent users from choosing new passwords that are too similar to their current password. It uses the Levenshtein distance algorithm to compute the minimum number of changes (characters added to, removed from, or replaced in) to convert the current password into the new password.

This password validator is only invoked for self-changes. It is not invoked for add operations or administrative password resets. Further, because it requires access to the user’s current password, it should only be used if the password-change-requires-current-password property is set to true in the password policy configuration.

This password validator offers the following configuration properties:

min-password-difference
The minimum number of changes (character insertions, removals, or replacements) required to convert the user’s current password into the proposed new password for that new password to be considered acceptable. The default value is 3.

See the config/sample-dsconfig-batch-files/use-the-similarity-based-password-validator.dsconfig batch file for more information about using the similarity-based password validator.

The unique characters password validator

The unique characters password validator can be used to reject passwords that contain fewer than a specified minimum number of unique characters. This can help prevent users from choosing passwords that only contain a few different characters, such as “abababab”.

This password validator supports the following configuration properties:

min-unique-characters
The minimum number of different characters that can appear in an acceptable password. Passwords that contain fewer than this number of unique characters are rejected.
case-sensitive-validation
Indicates whether to perform case-sensitive validation, in which uppercase and lowercase versions of the same letter are treated as different characters. By default, the validator uses case-insensitive validation.

See the config/sample-dsconfig-batch-files/use-the-unique-characters-password-validator.dsconfig batch file for more information about using the unique characters password validator.

Custom password validators

The UnboundID Server SDK can be used to create custom password validators using whatever logic you want.