--- title: Actions description: Examples in this documentation depend on features activated in the ds-evaluation setup profile. component: pingds version: 7.2 page_id: pingds:rest-guide:action-rest canonical_url: https://docs.pingidentity.com/pingds/8.1/rest-guide/action-rest.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-03-28T11:11:16Z superseded_by: https://docs.pingidentity.com/pingds/8.1/rest-guide/action-rest.html section_ids: rest-action-modify-password: Change your password rest-action-password-quality-check: Check password quality rest-action-reset-password: Reset a password rest-action-account-usability: Account usability action --- # Actions | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Examples in this documentation depend on features activated in the `ds-evaluation` setup profile.For details, see [Learn about the evaluation setup profile](../install-guide/setup-ds.html#about-ds-evaluation). | ## Change your password | | | | - | --------------------------------------------------------------------------------------- | | | This action *requires HTTPS* to avoid sending the password over an insecure connection. | Perform an HTTPS POST with the header `Content-Type: application/json`, `_action=modifyPassword` in the query string, and the old and new passwords in JSON format as the POST data. The JSON POST DATA must include the following fields: * `oldPassword` The value of this field is the current password as a UTF-8 string. * `newPassword` The value of this field is the new password as a UTF-8 string. On success, the HTTP status code is 200 OK, and the response body is an empty JSON resource: ```bash $ curl \ --request POST \ --cacert ca-cert.pem \ --user bjensen:hifalutin \ --header "Content-Type: application/json" \ --data '{"oldPassword": "hifalutin", "newPassword": "chngthspwd"}' \ --silent \ https://localhost:8443/api/users/bjensen?_action=modifyPassword {} ``` ## Check password quality The `passwordQualityAdvice` and `dryRun` query string parameters let you get additional information for a password update that might fail. The `passwordQualityAdvice` parameter relies on the LDAP password quality advice control, OID `1.3.6.1.4.1.36733.2.1.5.5`, which users must have access to request. The `dryRun` parameter relies on the LDAP no-op control, OID `1.3.6.1.4.1.4203.1.10.2`. You can use this as a means to test a password, and to evaluate the effectiveness of a new password policy. | | | | - | ------------------------------------------------------------------------------------------------------------------- | | | The password quality advice control and the `passwordQualityAdvice` parameter have interface stability: *Evolving*. | The following commands demonstrate how the parameters cause the server to return information. On failure, the status code is HTTP 400 Bad Request, and the response is a JSON object listing what passed validation and what failed: ```bash $ ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=admin \ --bindPassword password << EOF dn: cn=Minimum length policy,dc=example,dc=com objectClass: top objectClass: subentry objectClass: ds-pwp-password-policy objectClass: ds-pwp-validator objectClass: ds-pwp-length-based-validator cn: Minimum length policy ds-pwp-password-attribute: userPassword ds-pwp-default-password-storage-scheme: PBKDF2-HMAC-SHA512 ds-pwp-length-based-min-password-length: 8 subtreeSpecification: {base "ou=people", specificationFilter "(uid=bjensen)" } dn: dc=example,dc=com changetype: modify add: aci aci: (targetcontrol="PasswordQualityAdvice") (version 3.0; acl "Authenticated users can check password quality"; allow(read) userdn="ldap:///all";) EOF $ curl \ --request POST \ --cacert ca-cert.pem \ --user bjensen:chngthspwd \ --header "Content-Type: application/json" \ --data '{"oldPassword": "chngthspwd", "newPassword": "passwd"}' \ --silent \ "https://localhost:8443/api/users/bjensen?_action=modifyPassword&dryRun=true&passwordQualityAdvice=true" { "code" : 400, "reason" : "Bad Request", "message" : "Constraint Violation: The provided new password failed the validation checks defined in the server: The provided password is shorter than the minimum required length of 8 characters", "detail" : { "passwordQualityAdvice" : { "passingCriteria" : [ ], "failingCriteria" : [ { "type" : "length-based", "parameters" : { "max-password-length" : 0, "min-password-length" : 8 } } ], "attributeType" : "userPassword" } } } ``` You can use `passwordQualityAdvice` without the `dryRun` parameter: ```bash $ curl \ --request POST \ --cacert ca-cert.pem \ --user bjensen:password \ --header "Content-Type: application/json" \ --data '{"oldPassword": "chngthspwd", "newPassword": "hifalutin"}' \ --silent \ "https://localhost:8443/api/users/bjensen?_action=modifyPassword&passwordQualityAdvice=true" ``` On success, the HTTP status code is 200 OK, and the response body is an empty JSON resource. ## Reset a password Whenever one user changes another user's password, DS servers consider it a password reset. Often, password policies specify that users must change their passwords again after a password reset. | | | | - | --------------------------------------------------------------------------------------- | | | This action *requires HTTPS* to avoid sending the password over an insecure connection. | Perform an HTTPS POST with the header `Content-Type: application/json`, `_action=resetPassword` in the query string, and an empty JSON document (`{}`) as the POST data. The following example demonstrates an administrator changing a user's password. Before trying this example, make sure the password administrator has been given the `password-reset` privilege. Otherwise, the password administrator has insufficient access. On success, the HTTP status code is 200 OK, and the response body is a JSON resource with a `generatedPassword` containing the new password: ```bash $ curl \ --request POST \ --cacert ca-cert.pem \ --user kvaughan:bribery \ --header "Content-Type: application/json" \ --data '{}' \ --silent \ https://localhost:8443/api/users/bjensen?_action=resetPassword {"generatedPassword":""} ``` As password administrator, provide the new, generated password to the user. Use this feature in combination with a password policy that forces the user to change their password after a reset. For an example, see [Require password change on add or reset](../security-guide/passwords.html#example-require-password-change-on-add-or-reset). ## Account usability action The `accountUsability` action lets a password administrator read information about whether the user can authenticate to the directory. This mirrors the LDAP [Account usability control](../ldap-reference/controls.html#account-usability-control): * The `"supportedActions"` list in the REST to LDAP mapping for the user must include the `"accountUsability"` action. This action is not in the `"supportedActions"` list by default. * The remote LDAP directory service must support the LDAP control, which has OID `1.3.6.1.4.1.42.2.27.9.5.8`. * The password administrator must be able to use the LDAP control. Try the `accountUsability` action: 1. Edit the mapping configuration to include the `"accountUsability"` action in the list for the user resource: ```json [${json.dir}/example-v1.json:// account-usability] ``` 2. Enable the password administrator to use the LDAP account usability control. The following example sets a global ACI for Kirsten Vaughan: ```bash $ dsconfig \ set-access-control-handler-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --add global-aci:"(targetcontrol=\"AccountUsability\")\ (version 3.0; acl \"Account usability access\"; allow(read) \ userdn=\"ldap:///uid=kvaughan,ou=People,dc=example,dc=com\";)" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt ``` 3. Use a password policy that produces results for account usability, as in the following example: ```bash $ ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=admin \ --bindPassword password << EOF dn: cn=Lockout with max age and grace logins,dc=example,dc=com objectClass: top objectClass: subentry objectClass: ds-pwp-password-policy cn: Lockout with max age and grace logins ds-pwp-password-attribute: userPassword ds-pwp-default-password-storage-scheme: PBKDF2-HMAC-SHA256 ds-pwp-lockout-failure-expiration-interval: 10 m ds-pwp-grace-login-count: 3 ds-pwp-lockout-duration: 5 m ds-pwp-lockout-failure-count: 3 ds-pwp-max-password-age: 30 d subtreeSpecification: { base "ou=people", specificationFilter "(uid=bjensen)" } EOF ``` 4. Produce some account usability information on a user account: ```bash $ curl \ --user bjensen:wrong-password \ --cacert ca-cert.pem \ --silent \ https://localhost:8443/api/users/bjensen?_fields=userName $ curl \ --user bjensen:wrong-password \ --cacert ca-cert.pem \ --silent \ https://localhost:8443/api/users/bjensen?_fields=userName $ curl \ --user bjensen:wrong-password \ --cacert ca-cert.pem \ --silent \ https://localhost:8443/api/users/bjensen?_fields=userName ``` 5. Use the action to get account usability information: ```bash $ curl \ --request POST \ --user kvaughan:bribery \ --header "Content-Type: application/json" \ --data '{}' \ --cacert ca-cert.pem \ --silent \ https://localhost:8443/api/users/bjensen?_action=accountUsability {"status":"locked","unlockIn":} ``` The JSON response can contain these fields. Only the `"status"` property is always present in the response. Other fields are optional: ```none { "status": "string", // One of "disabled", "locked", "passwordExpired", // "mustChangePassword", or "valid" "unlockIn": integer, // Seconds until locked account is unlocked "graceLoginsRemaining": integer, // Number of remaining authentications allowed with // an expired password "passwordExpiresIn": integer, // Seconds until password expires } ```