Managing Password History

Important. Password history requires that your passwords be stored using bcrypt password hashing. If you enable password history then your passwords will automatically be converted to bcrypt, For organizations already using bcrypt that won't be a problem. However, if your organization doesn't use bcrypt that won't necessarily be true: problems could potentially arise if your passwords are automatically converted from, say, SHA256 to bcrypt. See your Identity Cloud representative for more information.


Password history is managed by using the /entityType.setPasswordSettings endpoint (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 defaut), use the POST method and the /entityType.setPasswordSettings endpoint 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'

Password history properties must be included in the body parameter of the API call as x-www-form-urlencoded parameters. The allowed parameters, all of which are required, are:

Parameter

Description

Example

application_id

Unique identifier of your Identity Cloud application. You can find your application ID on Console’s Manage Application page.

4s37vggj5zfmupafdgu9hctsbc

type_name

Name of the entity type where password history is being enabled (or disabled).

user

settings

JSON array containing the historySize property followed by an integer value indicating the number of passwords to maintain in the password history; for example, the value 5 indicates that a user’s last 5 passwords (including the current password) should be retained. 

The historySize property must be set to a value from 0 to 10 inclusive, with indicating that you want to disable password history. If you set historySize to any other value (e.g., 12) your API call will fail.

Note that the settings parameter must be formatted using JavaScript Object Notation (JSON). Note, too that historySize is currently the only property that can be used with the settings parameter.

{"historySize": 7}

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

 The following Curl command enables password history on the user entity type; in this case, setting historySize to 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 bmtmcW5iZDN0NGU1NW55YnIzbW5uaHB6czg3NTY0bng6c2VtdTJoc3A0NmQ0ajhzNWZ4eHJ
6Y25jY2EybnI1dGU=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'settings={"historySize": 3}' \
  --data-urlencode 'type_name=user' \
  --data-urlencode 'application_id=3vadba3vhqpkdgtsrqd4st76m3'
Note. This is a good time to clarify that password history must be set on an entity type-by-entity type basis: the /entityType.setPasswordSettings endpoint 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.

To disable password history on an entity type, set historySize to 0. For example:

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 password history, the password history for all the users in that entity type will be deleted as well; in other words, all a user’s previously-used passwords are deleted from the user profile (and only the current password will remain). In addition, those previous passwords won't be restored if you later re-enable password history. 

Note. Minor clarification: technically, that's what the user's password attribute looks like after the user has successfully logged on for the first time since password history was disabled. When you disable password history, the password attribute remains as-is until the user logs on the first time; at that point, the previous passwords are deleted. If a user never logs on again then his or her password attribute continues to maintain their 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; 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.

Important. 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.