Manage password policies

IDM provides password management features that help you enforce password policies, limit the number of passwords users must remember, and allow users to reset and change their passwords.

Password policy

A password policy is a set of rules defining what sequence of characters constitutes an acceptable password. Acceptable passwords generally are too complex for users or automated programs to generate or guess.

Password policies set requirements for password length, character sets that passwords must contain, dictionary words and other values that passwords must not contain. Password policies also require that users not reuse old passwords, and that users change their passwords on a regular basis.

IDM enforces password policy rules as part of the general policy service. The default password policy applies the following rules to passwords as they are created and updated:

A password property is required for any user object.
The value of a password cannot be empty.
The password must include at least one capital letter.
The password must include at least one number.
The minimum length of a password is 8 characters.
The password cannot contain the user name, given name, or family name.

You can change these validation requirements, or include additional requirements, by configuring the policy for passwords.

Passwords are validated in several situations:

Password change and password reset: Password change refers to users changing their own passwords. Password reset refers to an administrator setting a user or account password on behalf of a user.

By default, IDM validates password values as they are provisioned.
Password recovery: Password recovery involves recovering a password or setting a new password when the password has been forgotten.
Password history: You can add validation to prevent reuse of previous password values. For more information, refer to Password history policy.
Password expiration: You can use workflows to ensure that users are able to change expiring passwords or to reset expired passwords.

Password history policy

The sample described in Store multiple passwords for managed users shows how to set up a password history policy in a scenario where users have multiple different passwords across resources. You can use the scripts provided in that sample to set up a simple password history policy that prevents managed users from setting the same password that they used previously. The default scripts do not evaluate the current password.

To create a password history policy based on the scripts in the multiple passwords sample, make the following changes to your project:

Copy the pwpolicy.js script from the multiple passwords sample to your project’s script directory:
```
cp /path/to/openidm/samples/multiple-passwords/script/pwpolicy.js /path/to/openidm/my-project-dir/script/
```
The pwpolicy.js script contains an is-new policy definition that compares a new field value with the list of historical values for that field.

The is-new policy takes a historyLength parameter that specifies the number of historical values on which the policy should be enforced. This number must not exceed the historySize that you set in conf/managed.json to be passed to the onCreate and onUpdate scripts.
Copy the onCreate-user-custom.js and onUpdate-user-custom.js scripts to your project’s script directory:
```
cp samples/multiple-passwords/script/onCreate-user-custom.js /my-project-dir/script/
cp samples/multiple-passwords/script/onUpdate-user-custom.js /my-project-dir/script/
```
These scripts validate the password history policy when a managed user is created or updated.
Update your policy configuration (conf/policy.json ) to reference the new policy definition by adding the policy script to the additionalFiles array:
```
{
    "type" : "text/javascript",
    "file" : "policy.js",
    "additionalFiles": [ "script/pwpolicy.js" ],
    ...
}
```

Update your project’s conf/managed.json file as follows:

Add a fieldHistory property to the managed user object:
```
"fieldHistory" : {
    "title" : "Field History",
    "type" : "object",
    "viewable" : false,
    "searchable" : false,
    "userEditable" : false,
    "scope" : "private"
}
```
The value of this field is a map of field names to a list of historical values for that field. These lists of values are used by the is-new policy to determine if a new value has already been used.

Update the managed user object to call the scripts when a user is created or updated:

"name" : "user",
"onCreate" : {
    "type" : "text/javascript",
    "file" : "script/onCreate-user-custom.js",
    "historyFields" : [
        "password"
    ],
    "historySize" : 4
},
"onUpdate" : {
    "type" : "text/javascript",
    "file" : "script/onUpdate-user-custom.js",
    "historyFields" : [
        "password"
    ],
    "historySize" : 4
},
...

If you have any other script logic that is executed on these events, you must update the scripts to include that logic, or add the password history logic to your current scripts.

Add the is-new policy to the list of policies enforced on the password property of a managed user. Specify the number of historical values that the policy should check in historyLength property:

"password" : {
   ...
   "policies" : [
       {
           "policyId" : "at-least-X-capitals",
           "params" : {
               "numCaps" : 1
           }
       },
       ...
       {
           "policyId" : "is-new",
           "params" : {
               "historyLength" : 4
           }
       },
       ...
   ]
}

You should now be able to test the password history policy by creating a new managed user, and having that user update their password. If the user specifies the same password used within the previous four passwords, the update request is denied with a policy error.

Multiple passwords per linked resource

You can store multiple passwords in a single managed user entry to enable synchronization of different passwords on different external resources.

To store multiple passwords, extend the managed user schema to include additional properties for each target resource. You can set separate policies on each of these new properties, to ensure that the stored passwords adhere to the password policies of the specific external resources.

To use this custom managed object property and its policies to update passwords on an external resource, you must make the corresponding configuration and script changes in your deployment. For a detailed sample that implements multiple passwords, refer to Store multiple passwords for managed users. That sample can also help you set up password history policies.

Random passwords

In certain situations, you might want to generate a random password when users are created.

You can customize your user creation logic to include a randomly generated password that complies with the default password policy. This functionality is included in the default crypto script, bin/defaults/script/crypto.js, but is not invoked by default. For an example of how this functionality might be used, refer to the openidm/bin/defaults/script/onCreateUser.js script. The following section of that file (commented out by default) means that users created through the admin UI, or directly over the REST interface, will have a randomly generated password added to their entry:

if (!object.password) {

    // generate random password that aligns with policy requirements
    object.password = require("crypto").generateRandomString([
        { "rule": "UPPERCASE", "minimum": 1 },
        { "rule": "LOWERCASE", "minimum": 1 },
        { "rule": "INTEGERS", "minimum": 1 },
        { "rule": "SPECIAL", "minimum": 1 }
    ], 16);

}

The changes made to scripts take effect after the time set in the recompile.minimumInterval, described in Script configuration.

The generated password can be encrypted or hashed, in accordance with the managed user schema, defined in conf/managed.json . For more information, refer to Encoding Attribute Values. Synchronizing hashed passwords is not supported.

You can use this random string generation in a number of situations. Any script handler that is implemented in JavaScript can call the generateRandomString function.

`password` property

To use a property other than the default password property to store passwords, you must change the following files:

policy.json

If you want to enforce password validation rules on a different property, change the password property in this file.

managed.json

Modify the password object in this file, which also includes password complexity policies.

sync.json

If you change the password property, make sure that you limit the change to the appropriate system, designated as source or target.

selfservice-reset.json

If you are setting up self-service password reset, as described in Password reset, change the value of identityPasswordField from password to the desired new property.

Every UI file that includes password as a property name

Whenever there’s a way for a user to enter a password, the associated HTML page will include a password entry. For example, the LoginTemplate.html file includes the password property. A full list of default files with the password property include:

_passwordFields.html
_resetPassword.html
ConfirmPasswordDialogTemplate.html
EditPasswordPageView.html
LoginTemplate.html
MandatoryPasswordChangeDialogTemplate.html
resetStage-initial.html
UserPasswordTab.html

This list does not include any created custom UI files.

Email rate limiting

No rate limiting is applied to password reset emails, or any emails sent by the IDM server. This means that an attacker can potentially spam a known user account with an infinite number of emails, filling that user’s inbox. In the case of password reset, the spam attack can obscure an actual password reset attempt.

In a production environment, you must configure email rate limiting through the network infrastructure in which IDM runs. Configure the network infrastructure to detect and prevent frequent repeated requests to publicly accessible web pages, such as the password reset page. You can also handle rate limiting within your email server.

PingIDM 7.5.0