Password Validation Policy¶

Before you start¶

Goal

Define an appropriate password validation policy for internal Altair SLC Hub users

By default, Altair SLC Hub validates passwords for internal Altair SLC Hub users (that is, ones that are not imported from LDAP) using a library that evaluates the "guessability" of a password. However, to comply with any corporate password standards that may exist, Altair SLC Hub allows the password validation policy to be configured.

Configuration¶

The password validation policy is configured using the auth.passwordValidityPolicy configuration section.

The configuration consists of a set of optional validators that can be enabled if desired. For example there are validators for the policy of "must contain an upper case character", "must be at least 12 characters" and so on. These validators can be combined to create an overall validation policy.

To create a custom password validation policy, create a new configuration file in the etc/config.d directory with a name such as passwordpolicy.yaml, with contents such as:

auth:
    passwordValidityPolicy:
     minLength: 12
     uppercase: 1
     lowercase: 1
     specialchars: 1
     digits: 1

An example configuration, along with comments on the available validators can be found in the etc/config.d/auth.yaml configuration file.

Note that the configuration files in the etc/config.d directory are read in alphabetical order. However, there are no explicit settings in any installation supplied configuration files relating to the password validation policy, so the name of the file containing any custom password validation policy does not have to be alphabetically later than auth.yaml for it to have an effect.

Validators¶

The list of supported validators is as follows:

Minimum length¶

Validates that the length of a password is more than the specified minimum length.

Example configuration:

passwordValidityPolicy:
  minLength: 12

Maximum length¶

Validates that the length of a password is less than the specified maximum length.

Example configuration:

passwordValidityPolicy:
  maxLength: 64

Must contain one or more numerical digits¶

Validates that a password has a given number of numerical digits.

Example configuration:

passwordValidityPolicy:
  digits: 2

Must contain one or more lower case letters¶

Validates that a password contains a given number of lower case letters.

Example configuration:

passwordValidityPolicy:
  lowercase: 2

Must contain one or more upper case letters¶

Validates that a password contains a given number of upper case letters.

Example configuration:

passwordValidityPolicy:
  uppercase: 2

Must contain one or more special characters¶

Validates that a password contains a given number of special characters. Special characters are defined as being anything other than letters and digits, so would typically include spaces and punctuation characters.

Example configuration:

passwordValidityPolicy:
  specialchars: 2

Must not be equal to the username¶

Validates that the password is not equal to the username (case insensitively)

Example configuration:

passwordValidityPolicy:
  notEqualUsername: true

Must not contain the username¶

Validates that the password does not contain the username (case insensitively)

Example configuration:

passwordValidityPolicy:
  notContainsUsername: true

Must not be equal to the email address¶

Validates that the password does not equal the users email address (case insensitively)

Example configuration:

passwordValidityPolicy:
  notEqualEmail: true

Must not contain any part of the email address¶

Validates that the password does not contain any part of the email address. The email address is split into parts around the delimiters ".", "-", "+", "_" and "@", and the password must not contain any of the parts.

Example configuration:

passwordValidityPolicy:
  notContainsEmailParts: true

Must not contain any part of the users display name¶

Validates that the password does not contain any part of the user's display name. The display name is split into parts around spaces, and the password must not contain any of the parts three or more characters long. This would typically validate that the password does not contain the user's first name or surname

Example configuration:

passwordValidityPolicy:
  notContainsDisplayNameParts: true

Must not be equal to one of a provided blacklist of passwords¶

Validates that the password does not exist on a given blacklist of passwords.

Matching a password against the blacklist is done using a Bloom filter. This means that false positives are possible, but unlikely. That is, it is possible that a password will be rejected for being on the blacklist when it is in fact not. However, the reverse cannot happen; passwords on the blacklist are always rejected.

The false positive rate can be configured if desired. The lower the false positive rate the more memory is consumed. The rate is configured as a float, for example 0.01 for 1%. The default is 0.01%.

More than one blacklist file can be specified. Each blacklist file should consist of one password per line.

Example configuration:

passwordValidityPolicy:
  blacklist:
    filepaths: 
      - /opt/altair/slchub/var/blacklist.txt
    falsePositiveRate: 0.0001

Must not appear on leaked password database¶

Validates that the password does not exist on the database of leaked passwords, using the "haveibeenpwned" service at https://haveibeenpwned.com

Note that the password is not sent directly to the service. The way that the haveibeenpwned service works is that the first 5 characters of the SHA-1 hash of the password is sent to the service. The service then sends back the list of hashes (plus some padding entries) starting with that prefix. Altair SLC Hub can then perform a check of the password hash against that small part of the haveibeenpwned database.

The password checking service at https://haveibeenpwned.com is free and does not require an account. However, it does require that Altair SLC Hub has direct visibility of that URL.

It is possible to access the HiBP service through a proxy using the haveibeenpwnedService configuration parameter if necessary. As an alternative it is possible to use a locally hosted version of HiBP by configuring the haveibeenpwnedService configuration parameter. Setting up such a local service is beyond the scope of this documentation, but an example of a minimal self-hosted, k-anonymity enabled HiBP API can be found in this repository.

Example configuration:

passwordValidityPolicy:
  haveibeenpwnedCheck: true

Must not be too "guessable"¶

Validates that the password reaches a certain level of complexity according to the commonly used zxcvbn library.

The zxcvbn library scores the complexity of passwords to estimate their guessability and the difficulty of cracking the password.

The score ranges from 0 to 4:

Score	Meaning
0	too guessable: risky password. (guesses < 10^3)
1	very guessable: protection from throttled online attacks. (guesses < 10^6)
2	somewhat guessable: protection from unthrottled online attacks. (guesses < 10^8)
3	safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10^10)
4	very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10^10)

Validating passwords using a score threshold of at least 3 is recommended.

Example configuration:

passwordValidityPolicy:
  minimumZxcvbnScore: 3

Must not equal any of the given number of previous passwords¶

Validates that the password is not equal to any previous password up to a given limit.

Example configuration:

passwordValidityPolicy:
  history: 12

Restart Altair SLC Hub¶

Having changed the password validation configuration, first verify that the configuration is read from the files correctly using the hubctl config print command:

hubctl config print auth.passwordValidityPolicy

It is then necessary to restart the authentication service in order for the change in configuration to have an effect. Restart the service using the following command:

hubctl service restart auth

Verify¶

To verify the password validation policy, attempt to change the password of a user in the Altair SLC Hub portal and verify that the validation policy is being applied correctly.

To do this, ensure that you are logged on the Altair SLC Hub portal as an internal Altair SLC Hub user (that is, not one that has been imported from LDAP). Click on the user name in the top right hand corner of the Altair SLC Hub portal and select "Account Settings", and press the "Change Your Password" button.