Password History and Individual User Accounts

Before going any further, we should point out that password history isn't reflected in a user profiles. For example, if a user looks at the Account Security screen in their Hosted Login user profile, they won’t see any of their previous passwords, or even any indication that password history is enabled:

In fact, for end users password history only comes into play when they try to change their password to a previous password and they see the This password is not acceptable. Select a different password. error message.

However, if you’re an administrator you can see the password history for an individual user by calling the /entity endpoint and returning the password attribute. For example, if you haven’t enabled password history and you use an API call to view the password attribute for a user, you’ll see something similar to this your API response:

{
    "result": {
        "password": {
            "value": "$2a$10$gjW1gnLwF7uuOqeqXn0cjednn8w6Rm2VwLHtJoaRU8xIq2e0.j79i",
            "type": "password-bcrypt"
        }
    },
    "stat": "ok"
}

The only thing listed is the hashed value of the user’s current password and the password type. No previous passwords are listed because, with password history disabled, no previous passwords are saved.

Now, let’s look at the password attribute for user in an entity type where password history has been enabled; more specifically, we’ll look at the password attribute for a user who’s made several password changes since password history was enabled:

 {
    "result": {
        "history": [
            {
                "created": "2021-06-04 22:18:23.461414108 +0000",
                "value": "$2b$10$Ns7uvN5pTfw5m7L90vsIvOuJoevehWa0n/Sq.JkAtaRVIigjx7FRG",
                "type": "password-bcrypt"
            },
            {
                "created": "2021-06-04 22:17:06.51735915 +0000",
                "value": "$2b$10$ZzQmFTbp193iqPSpTjdqh.EWyfOTuaMoaun.bNPvZgtwmxP3SGAiy",
                "type": "password-bcrypt"
            }
        ],
        "created": "2021-06-04 22:19:20.854025955 +0000",
        "value": "$2b$10$Ptqzl8nB2kNfxSQn1Rv3m.9nBK1gRbJnILsWgESMluV9x7Ry50dgW",
        "type": "password-bcrypt"
    },
    "stat": "ok"
}

Here’s a quick guide to what we see in this user account:

  • The type value is the password encryption type. This will always be password-bcrypt, because that’s the only type that can be used with password history.

  • The value setting is the hashed value of the user’s password. (In other words, it is the user’s password, but in encrypted format.)

  • The created value is the date and time that the password was created (i.e., the date and time that the user changed their password). You can use this value to determine such things as how long it’s been since users have changed their passwords, and how frequently users change their passwords. 

The user’s current password is listed as the value of the password attribute, with the user’s previous passwords stored in the history property. In the history property, passwords are maintained in reverse chronological order, with the current password shown first. Schematically, that might look similar to the following diagram, a diagram showing a user who’s had 5 different passwords (and an entity type where the history_size is also set to 5):

So what happens the next time this user changes their password (which will be their sixth password)? Well, in that case, Password 6 will become the current password, and Password 5 will become the top entry in the history property. Passwords 4, 3, and 2 will correspondingly move down one spot in that history:

And what about Password 1? Well, because the password history has been set to 5, and because this user has had six passwords, something has to give. In this case, that means that Password 1, the oldest password in the history, is deleted (first in, first out). That also means that the user can now reuse Password 1: because it’s not included in the password history there’s nothing to stop them from resetting their password to that previous password (Password 1).

As you can see, password histories are dynamic:  new passwords can be added and old passwords can be dropped. This also occurs if you change your password history settings. For example, suppose password history is enabled and a user has a password attribute that looks like this:

Suppose you disable password history. In that case, the user’s password attribute will look like this:

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.

If you disable password history, the only item maintained in the user profile is the current password; all the previous passwords are erased. If you then re-enable password history, the password attribute will look like this:

No previous passwords are listed, because, again, those passwords were erased when password history was disabled.

Similarly, your previous passwords (or at least some of them) might be erased if you change the value of the historySize property. For example, suppose you set the historySize to 5 and a user has 5 passwords stored:

If you change the history size to 3, the two oldest passwords are deleted (because there’s no longer a spot for them):

That means that the user can now reuse passwords 1 and 2; after all. neither password is in the password history.