As noted elsewhere, password history has been added to all existing Identity Cloud entity types (and will be included in any new entity types you create). This change largely involves adding a history property to the password attribute, and by creating a new API endpoint (/entityType.setPasswordSettings) that specifies the number of “old” passwords maintained in the history property.
The /entityType.setPasswordSettings endpoint uses the settings parameter and the historySize property to configure the maximum number of passwords that can be stored in a user’s password history. For example, if historySize is set to 5 that means that the entity type stores your last 5 passwords (including your current password). If historySize is set to 9, that means that the entity type stores your last 9 passwords, again including your current password. And if historySize is set to 0, that means that the entity type only stores your current password, which also means that password history is disabled.
Note. Before you ask, historySize can be set to any integer value between 0 and 10, inclusive, You can also set the value to null (the default value), although there's no appreciable difference between a history size of 0 and a history size of null.
Here are a few other things to keep in mind when it comes to password history:
- Password history only works if you store user passwords in the password attribute. Most likely you do store passwords in the password attribute. But if you have a custom setup that uses a different attribute (e.g., user-password) for storing passwords then password history won’t work. That’s because the password attribute, and only the password attribute, has been modified to work with this feature. (Plus, the /entityType.setPasswordSettings endpoint has been hardwired to modify the password attribute: it's impossible to use that endpoint to add password history to any other Identity Cloud attribute.)
- Suppose you use the /entity API to return information about a user profile and the password attribute; however, the historySize property doesn’t appear in the API response. If you don't see the history property tthat indicates that you’ve never changed the history size: by default the pass history is set to null. A 0 means that you explicitly set the history size to 0. Regardless of whether the history size is null or 0, password history is disabled. To be a little more specific, is password history has been enabled (even if it's now currently enabled), the password attribute will look similar to this:
"historySize": 7, "name": "password", "type": "password-bcrypt"If you've never changed the historySize property then the password attribute will look like the following (with no historySize value):
"name": "password", "type": "password-bcrypt"But if the historySize property isn’t part of your password attribute the how can you possibly change the history size? How can you enable password history if you can't set the history size to 2 or 6 or 9 or whatever? That's something you don't need to worry about: if you set the password history by calling the /entityType.setPasswordSettings endpoint and the history size property is missing, that property will automatically be added to the password attribute.
- Password history is available only for passwords that use the password-bcrypt password type. Most likely your passwords already use this encryption type. However, it's also true that, prior to the release of password history, both the /entityType.create and the /entityType.addAttribute endpoints allowed you to specify a different password type (for example, SHA256) when creating or modifying the password attribute. That’s no longer the case: now, if you create or modify the password attribute the password type is automatically set to password-bcrypt. If you try to set the password type to something else (say, SHA256), the Identity Cloud will ignore that portion of your API call and automatically set the encryption type to password-bcrypt.
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 might not 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.