Directory Services 7.2.5

Actions

Examples in this documentation depend on features activated in the ds-evaluation setup profile.

For details, see Learn about the evaluation setup profile.

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:

$ 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:

$ 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:

$ 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:

$ 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":"<new-password>"}

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.

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:

  • 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:

    "supportedActions": [ "accountUsability","modifyPassword", "resetPassword" ],

  2. Enable the password administrator to use the LDAP account usability control.

    The following example sets a global ACI for Kirsten Vaughan:

    $ 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:

    $ 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:

    $ 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:

    $ 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":<seconds>}

The JSON response can contain these fields. Only the "status" property is always present in the response. Other fields are optional:

{
  "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
}