If enabled, it maintains the following information about each recorded attempt:

  • A Boolean value indicating whether the attempt was successful
  • A timestamp, formatted in the ISO 8601 format described in RFC 3339, indicating when the attempt occurred
  • The name of the authentication method that was attempted (for example, “simple” or “SASL PLAIN”)
  • The IP address of the client that made the attempt, if available
  • A general reason that the authentication attempt failed for failed attempts
  • An optional additional attempt count that can be used to indicate how many other attempts with the same properties (successful, authentication method, client IP address, and failure reason) occurred on the same date

Enabling recent login history

The following password policy configuration properties are used to manage recent login history tracking:

maximum-recent-login-history-successful-authentication-count
The maximum number of successful attempts to maintain in the recent login history.
maximum-recent-login-history-successful-authentication-duration
The maximum length of time to retain successful login attempts in the recent login history.
maximum-recent-login-history-failed-authentication-count
The maximum number of failed attempts to maintain in the recent login history.
maximum-recent-login-history-failed-authentication-duration
The maximum length of time to retain failed attempts in the recent login history.
recent-login-history-similar-attempt-behavior
The behavior to exhibit for clients with multiple similar attempts (with the same values for the successful, authentication method, client IP address, and failure reason fields) on the same date (within the UTC time zone). Allowed values include:
  • collapse-similar-attempts-on-the-same-date — Indicates that multiple similar attempts should be collapsed into a single record. The timestamp of that record reflects the most recent attempt on that date, and the additional attempt count reflects the number of additional similar attempts that were collapsed. This is the default behavior.
  • maintain-every-attempt — Indicates that the server should not collapse multiple similar attempts and that each attempt is maintained as a separate record in the recent login history. Clients that authenticate multiple times per day can have multiple records per day.
  • update-at-most-once-per-day — Indicates that the server should not collapse multiple similar attempts and that only the first such attempt on any given day is recorded. This can reduce the number of writes required to maintain the recent login history.

If either the maximum-recent-login-history-successful-authentication-count or the maximum-recent-login-history-successful-authentication-duration properties has a value, then the server maintains a history of recent successful attempts. If both properties are configured, then the server can purge information about successful attempts that match the criteria for either. This is useful, for example, if you usually want to keep records based on a duration, but want to add protection against the history growing too large from an excessive number of records created within that duration.

Similarly, the server maintains a record of recent failed authentication attempts if either or both the maximum-recent-login-history-failed-authentication-count and maximum-recent-login-history-failed-authentication-duration properties are configured. It is possible to maintain a record of successful attempts without a record of failed attempts, to maintain a record of failed attempts without successful attempts, or to maintain a record of both successful and failed attempts. By default, no recent login history is maintained.

Note:

If the maximum-recent-login-history-successful-authentication-duration and maximum-recent-login-history-failed-authentication-duration properties are used to maintain records of successful and failed attempts based on their duration, then it is possible for the server to retain records older than that duration if they are the most recent record of that type in the user’s entry. That is, if the server is configured to maintain a history of successful logins, then the record of the most recent successful attempt will be retained even if it is older than the maximum duration for successful login attempts. The same is true if failed authentication attempts are to be maintained and a duration is configured.

See the config/sample-dsconfig-batch-files/enable-recent-login-history.dsconfig batch file for more information about configuring a recent login history.

Retrieving a user’s recent login history

If the server is configured to maintain a recent login history for a user, then there are several ways that this history can be retrieved. They include:

  • The client can include the get recent login history request control in the bind request. If the bind succeeds, then the server includes a corresponding response control in the bind result. The UnboundID LDAP SDK for Java provides support for these controls, and the ldapsearch and ldapmodify command-line tools both offer the --getRecentLoginHistory argument that can be used to retrieve the history from the command line.
  • If the ds-pwp-state-json virtual attribute is enabled, then it might include a recent-login-history field whose value is a JSON object with information about recent successful and failed attempts for that user.
  • The password policy state extended operation (or the manage-account command-line tool) can be used to retrieve the user’s recent login history.