Enforcing 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, see "Creating a Password History Policy".

Password expiration

You can use workflows to ensure that users are able to change expiring passwords or to reset expired passwords.

Creating a 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.

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, 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
},
...

Important

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.