Configure unique password enforcement

Password history is managed by using the /entityType.setPasswordSettings operation (password history can only be managed by using API calls). By default, password history is available for use with all your entity types. To enable password history on an entity type (as a reminder, password history is disabled by default), use the POST method and the /entityType.setPasswordSettings operation to set the historySize to an integer value between 1 and 10, inclusive. For example, the following Curl command enables password history on the user entity type and, by setting historySize to 7, tells the Identity Cloud to save the last 7 passwords employed by users:

curl -L -X POST \
  'https://https://se-demos-gstemp.us-dev.janraincapture.com.com/entityType.setPasswordSettings' \
  -H 'Authorization: Basic bmtmcW5iZDN0NGU1NW55YnIzbW5uaHB6czg3NTY0bng6c2VtdTJoc3A0NmQ0ajhzNWZ4eHJ6Y25jY2EybnI1dGU=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'settings={"historySize": 7}' 
  --data-urlencode 'type_name=user' \
  --data-urlencode 'application_id=3vadba3vhqpkdgtsrqd4st76m3'

Note that password history properties must be included in the request body of the API call as x-www-form-urlencoded members. The allowed members, all of which are required, are:

The settings member must be formatted using JavaScript Object Notation (JSON) even though historySize is currently the only property that can be used with the settings member.

For example, if you're using Postman, your request body will look similar to this:

The following Curl command enables password history on the user entity type; in this case, setting historySize to 3 means that the Identity Cloud
will save a user’s last 3 passwords:

curl -L -X POST \
  'https://https://se-demos-gstemp.us-dev.janraincapture.com.com/entityType.setPasswordSettings' \
  -H 'Authorization: Basic bmtmcW5iZDN0NGU1NW55YnIzbW5uaHB6czg3NTY0bng6c2VtdTJoc3A0NmQ0ajhzNWZ4eHJ6Y25jY2EybnI1dGU=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'settings={"historySize": 3}' \
  --data-urlencode 'type_name=user' \
  --data-urlencode 'application_id=3vadba3vhqpkdgtsrqd4st76m3'

📘

This is a good time to clarify that password history must be set on an entity type-by-entity type basis: the /entityType.setPasswordSettings operation doesn’t include a “set this same value on all my entity types” option. If you have 8 different entity types you’ll need to make 8 different API calls in order to enable password history on each entity type.

curl -L -X POST \
  'https://https://se-demos-gstemp.us-dev.janraincapture.com.com/entityType.setPasswordSettings' \
  -H 'Authorization: Basic bmtmcW5iZDN0NGU1NW55YnIzbW5uaHB6czg3NTY0bng6c2VtdTJoc3A0NmQ0ajhzNWZ4eHJ
6Y25jY2EybnI1dGU=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'settings={"historySize": 0}' \
  --data-urlencode 'type_name=user' \
  --data-urlencode 'application_id=3vadba3vhqpkdgtsrqd4st76m3'

If you disable this feature the password history for all the users in that entity type is deleted as well. In other words, all the user’s previously-used passwords are deleted from the user profile and only the current password remains. On top of that, those previous passwords won't be restored if you later re-enable password history. 

For example, suppose Maria Fuentes has an account in an entity type where password history has been enabled; Maria has changed her password on several occasions, which means she has several previous passwords in her password history. If you disable password history on the entity type, all of Maria’s previous passwords are deleted and only her current password is retained. If you re-enable password history, only her current password will appear. Those previous passwords are gone for good.

📘

If you set the password history to 1, only the user's current password is retained. However, because password history is enabled, Maria won't be able to reuse her current password. Setting password history to 1 prevents users from reusing their current password, but allows them to reuse any other password they might have had in the past.