Authentication-related controls

The authorization identity request control is described in RFC 3829 and can be included in a bind request to indicate that the server should include the resulting authorization identity in the successful bind response.

In the PingDirectory server, this authorization identity is always in the form of a distinguished name (DN), prefixed by dn: (for example, dn:uid=jdoe,ou=People,dc=example,dc=com).

This control is useful to determine the DN of the authenticated user entry, especially when the bind request does not identify the user by a DN, such as if the client was identified by a username, a Kerberos principal, a client certificate, or an OAuth access token.

While the authorization identity request control can be helpful, it only provides the distinguished name (DN) of the authenticated user and the specification does not even require that.

The PingDirectory server offers a more useful alternative in the form of the proprietary get authorization entry request control.

This control can also be included in a bind request, and if the bind is successful, then the server can return a corresponding response control with the DN and a requested set of attributes from the authenticated user’s entry. If the bind request also used an alternate authorization identity, then the response control can also include information about that user.

Include the account usable request control in a search request to indicate that matching entries should include a corresponding response control with a minimal set of information about whether the server considers the associated account to be usable.

This includes:

This control is maintained for compatibility with a legacy system. While it is still useful, it is not updated to support new features.

PingDirectory server supports the password policy request control, as described in draft-behera-ldap-password-policy-10.

This control can be included in add, bind, compare, modify, and password modify extended requests to obtain information about the associated user’s password policy state. This includes:

Because this control is based on a public specification, its format is fixed and it is not updated to support additional features.

PingDirectory server supports the password expiring and password expired controls, as described in draft-vchu-ldap-pwd-policy-00.

The password expiring control can be included in the response to a successful bind attempt to indicate that the user’s password is about to expire. Its value indicates the length of time until the password actually expires.

The password expired control can be included in the response to a successful or failed bind attempt to indicate that the user’s password has expired and must be changed. If the bind operation was successful, then it means that the user must change their password before they are allowed to request any other operations. If the bind operation failed, then it means that the password must be reset before the user can access their account.

By default, PingDirectory server returns a minimal amount of information in the response to a failed bind attempt. This is intentional because revealing too much can give an attacker useful information that could allow them to improve their tactics.

Yet, it’s useful in some circumstances to provide an application with a way to obtain information about the reason for a failed authentication attempt. As such, PingDirectory server offers a get password policy state issues request control that can be included in a bind request to indicate that the server should include a control in the bind response with information about any error, warning, or notice conditions in the user’s password policy state that might currently or soon interfere with their ability to authenticate. If the bind attempt fails, then it might also include specific information about the reason for that failure.

To prevent this control from being misused, PingDirectory server only allows it to be requested under a limited set of circumstances:

The bind request must also include the retain identity request control in the bind request.

PingDirectory server provides support for a password validation details request control that can be included in an add request, modify request, or password modify extended request.

It indicates that the server should return a corresponding response control with a list of each of the requirements that the password must satisfy and an indication as to whether the proposed password satisfied.

You can include the proprietary generate password request control in an add request to indicate that the server should automatically generate a password for the user.

The add response includes a corresponding response control that contains the generated password, along with an indication as to whether the user is required to choose a new password and how long the generated password is valid.

The password is generated using the password generator defined in the password policy that governs the new entry. Although the server might attempt to re-generate the password multiple times if previous attempts do not satisfy the configured set of password validators for the user, it might end up setting a password that does not pass validation. We recommend configuring the password generator to ensure that it is capable of generating passwords of acceptable strength.