--- title: Authentication-related extended operations description: The PingDirectory server provides support for several extended operations that can be used when authenticating or interacting with password policy-related operations. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdirectory_security_guide:pd_sec_authn_ext_ops canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdirectory_security_guide/pd_sec_authn_ext_ops.html page_aliases: ["pd_sec_who_am_i_ext_request.adoc", "pd_sec_get_pw_quality_reqs.adoc", "pd_sec_generate_password_ext_op.adoc", "pd_ds_verify_password_extended_op.adoc", "pd_ds_enable_verify_password_ext_op.adoc"] section_ids: the-who-am-i-extended-request: "The \"Who am I?\" extended request" the-get-password-quality-requirements-extended-operation: The get password quality requirements extended operation the-generate-password-extended-operation: The generate password extended operation the-verify-password-extended-operation: The verify password extended operation aci_verify_pw: Restrictions and privileges enabling-the-verify-password-extended-operation: Enabling the verify password extended operation before-you-begin: Before you begin about-this-task: About this task steps: Steps example: Example: --- # Authentication-related extended operations The PingDirectory server provides support for several extended operations that can be used when authenticating or interacting with password policy-related operations. ## The "Who am I?" extended request The "Who am I?" extended request is defined in [RFC 4532](https://www.ietf.org/rfc/rfc4532.txt). It behaves much like the authorization identity request control in that it returns the authorization identity associated with the connection and it should always be in `dn:` form in the PingDirectory server, but this request can be issued at any time on a connection to retrieve the current authorization identity for that connection. ## The get password quality requirements extended operation Use the proprietary [get password quality requirements extended operation](https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/ldap/sdk/unboundidds/extensions/GetPasswordQualityRequirementsExtendedRequest.html) to request that the PingDirectory server provide a list of the requirements that the server enforces when setting a password. The request control allows you to indicate the context in which the password is provided (for example, whether it's an add request, a self password change, or an administrative password reset) because the requirements can vary in different circumstances. The extended result includes a list of the requirements the server will impose, including a human readable description for each and an optional name and set of properties that can allow for some client-side validation. The result might also indicate whether the user is required to provide their current password, whether they are required to choose a new password after the add or administrative reset, and how long a new password is valid before it expires. ## The generate password extended operation The proprietary [generate password extended operation](https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/ldap/sdk/unboundidds/extensions/GeneratePasswordExtendedRequest.html) is used to request that PingDirectory server generate one or more suggested passwords and return them to the client. This is intended for use by applications that allow a user to change their password or allow an administrator to reset user passwords and want to allow the server to suggest several strong options that the user can choose from or use as examples when choosing their own password. As with the generate password request control, this extended operation relies on a password generator to create the passwords. While it might optionally try multiple times to generate passwords that pass validation, it can ultimately return passwords that do not satisfy all of the configured password validators. For each generated password included in the extended response, the server indicates whether that password passed validation, and if not, it might include a list of errors that explain the reasons it was not considered acceptable. ## The verify password extended operation There is an extended operation to verify a user's password. Read carefully before enabling this operation. For security reasons, PingDirectory provides vague responses to bind requests. If an authentication attempt is unsuccessful, the server doesn't communicate the reason for the failure. Additionally, for both security and performance reasons, the server doesn't attempt to verify the provided credentials if it can determine that the target account is not in a usable state (for example, if it has been administratively disabled, or if it has been locked as a result of too many previous authentication failures). The `verify-password` extended operation enables you to differentiate the authentication response to the client with respect to certain kinds of failures. For example, if you can determine that a user's account has been locked as a result of too many failed authentication attempts, you can present the user with a means of resetting the password if and only if you can verify that the provided password was correct. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Enabling the `verify-password` extended operation circumvents server security functionality.An attacker could use this extended operation to get unlimited attempts to guess a user's password, circumventing the security benefit of an account lockout. We strongly discourage designing applications in a way that could provide a malicious client with information that might help them better craft an attack against user accounts.This extended operation is not a standalone alternative to authenticating clients. Only use it to augment the existing authentication process, if at all. | The `verify-password` extended operation determines if a provided password is correct for a specified user without performing any other password policy processing for that user. This verification is available even if the target account isn't currently allowed to authenticate, and it won't cause any updates to the user's entry as a result of the determination. ### Restrictions and privileges Because of the security risks associated with using `verify-password`, there are a number of restrictions in place to ensure that it can only be used by authorized clients, including: * The extended operation handler isn't defined or enabled by default. * The server's access control configuration doesn't permit the use of the extended operation by default. If a client without the `bypass-acl` privilege has a legitimate need to use this extended operation, you must to create a global ACI that grants the client permission to use the extended request with OID 1.3.6.1.4.1.30221.2.6.72. * Requesters must also have the `permit-verify-password-request` privilege, which isn't granted to users (even root users) by default. * Clients must issue `verify-password` requests over a secure connection so that anyone able to view network messages can't access the content of that communication. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can disable this safeguard if necessary, but the server still requires secure communication protocol if either the target user's password policy or operational attributes in the user's entry require secure authentication. | * The extended operation supports clients submitting password verification requests directly to PingDirectory or forwarded through a PingDirectoryProxy server (in both simple-proxy and entry-balanced configurations). When requests are forwarded from PingDirectoryProxy to PingDirectory, you must configure both server instances to enable the extended operation. ### Enabling the verify password extended operation #### Before you begin You must enable the required access privileges described in [Restrictions and privileges](#aci_verify_pw). #### About this task To verify a password using the `verify-password` extended operation, enable the extended operation and then send a client request with the required information. The client request must be a JavaScript Object Notation (JSON) *(tooltip: \
\

An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\

\
)* object containing the following required fields: * `dn` The distinguished name (DN) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)* of the user account whose password the server should verify. * `password` The password to verify for that user. The server response contains a result code that explains the outcome of the `verify-password` operation. The following table describes the result codes that the server can return: | Server response code | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `PROTOCOL_ERROR (2)` | The extended request is malformed. | | `COMPARE_FALSE (5)` | The provided password isn't correct for the target user. | | `COMPARE_TRUE (6)` | The provided password is correct for the target user. | | `CONFIDENTIALITY_REQUIRED (13)` | The server is required to only permit the extended operation over a secure connection, or the server is configured to require secure authentication for the target user, but the client is using an insecure connection. | | `NO_SUCH_OBJECT (32)` | The target user account does not exist. | | `INVALID_DN_SYNTAX (34)` | The provided DN is malformed. | | `INAPPROPRIATE_AUTHENTICATION (48)` | The target user account doesn't have a password. | | `INSUFFICIENT_ACCESS_RIGHTS (50)` | The client doesn't have sufficient permission to use the extended operation. | | `OTHER (80)` | The server encountered an internal error while attempting to verify the password. | #### Steps 1. Enable the `verify-password` extended operation. ##### Example: ```shell $ bin/dsconfig create-extended-operation-handler \ --handler-name "Verify Password" \ --type verify-password \ --set enabled:true ``` 2. Send a properly formed client request. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Learn more about [formulating a request using the extended operation](https://docs.ldap.com/ldap-sdk/docs/javadoc/index.html?com/unboundid/ldap/sdk/unboundidds/extensions/VerifyPasswordExtendedRequest.html). | 3. Use the result code in the response to determine how the client responds to the user.