By default, the former password is also immediately removed from the user’s entry and can no longer be used to authenticate. However, PingDirectory Server supports a feature called password retirement in which the user’s former password can continue to be valid for a limited period of time.

Password retirement is especially useful for accounts used to authenticate applications, and particularly for applications that run on multiple systems. After the account’s password is changed in the Directory Server, the application can continue trying to use the old password until it can be updated with the new one. Similarly, the application cannot be configured to use the new password before it is changed in the Directory Server because attempts to authenticate with that new password before the account has been updated will also fail. With password retirement, the password can be changed in the PingDirectory Server in a way that allows either the new password or the former password to be accepted. This provides a window of time in which the application instances can be updated with the new password.

The following password policy configuration properties can be used to configure password retirement:

password-retirement-behavior
The password retirement behavior that the server should exhibit. By default, passwords are not retired. However, any number of the following values can be used to enable retirement functionality:
  • retire-on-self-change — Indicates that self password changes should automatically cause the user’s former password to be retired unless the request includes the purge password request control.
  • retire-on-administrative-reset — Indicates that administrative password resets should cause the user’s former password to be retired unless the request includes the purge password request control.
  • retire-on-request-with-control — Indicates that the client can use the retire password request control to indicate that the user’s current password should be retired.
max-retired-password-age
The maximum length of time that the retired password should be considered valid. By default, this is set to one day.

The PingDirectory Server also provides support for two request controls that can be used to customize password retirement behavior. The retire password request control can be used to explicitly indicate that the user’s current password should be retired, even if the server would otherwise purge it. This control is only allowed if the password-retirement-behavior property includes a value of retire-on-request-with-control. The purge password request control can be used to explicitly indicate that the user’s current password should be removed from the server even if it would have otherwise retired it for example, because of the retire-on-self-change or retire-on-administrative-reset property.

See the config/sample-dsconfig-batch-files/enable-retired-passwords.dsconfig batch file for more information about configuring password retirement.