The PUT /environments/{environmentId}/users/{userId}/password endpoint is also called to set a user’s password. This operation uses the application/vnd.pingidentity.password.set+json custom media type as the content type in the request header.

The PUT /environments/{environmentId}/users/{userId}/password operation sets a password for the user identified by the user ID and environment ID.

The request body shows how to specify the optional password.external.gateway object to reference an external gateway for the set password operation, if the user information is stored in an external directory. See the Users Data Model for descriptions of the password.external.gateway properties.

In the request body, the forceChange value specifies whether the user must change the current password on the next login. If forceChange is set to true, the status attribute value is changed to MUST_CHANGE_PASSWORD. If forceChange is omitted from the request, its value is set to false by default, and the status attribute value is set to OK. The bypassPolicy value specifies whether the user’s password policy should be ignored. If this property is omitted from the request, its value is set to false.

The value attribute specifies the value of the new password assigned to this user. The password can be either cleartext or pre-encoded. Cleartext passwords are evaluated against the current password policy. Pre-encoded passwords are not evaluated against the password policy, and they are specified by the name of the encoding scheme followed by an encoded representation of the password (for example, {SSHA512}df6b9fb15cfdbb7527be5a8a6e39f39e572c8ddb943fbc79a943438e9d3d85ebfc2ccf9e0eccd9346026c0b6876e0e01556fe56f135582c05fbdbb505d46755a). PingOne supports the following encoding schemes:

Scheme Scheme identifier
bcrypt {BCRYPT}
PBKDF2 {PBKDF2}
MSCrypto library {MSKCC_PBKDF2}
scrypt {SCRYPT}
salted SHA1 {SSHA}
salted SHA256 {SSHA256}
salted SHA384 {SSHA384}
salted SHA512 {SSHA512}

The hash for SHA schemes

The algorithm to compute the hash for SHA schemes looks like this:

prefix       = "{" scheme "}"
scheme = %x30-39 / %x41-5A / %x61-7a / %x2D-2F / %x5F / ;0-9, A-Z, a-z, "-", ".", "/", or "_"
b64-hashandsalt = <base64 of hashandsalt>
hashandsalt = password-hash salt 
password-hash = <digest of cleartext-password salt>

(Note: SHA1 and SHA256 also support hashandsalt = salt password-hash.)

Iterative hashing for password imports into PingOne

For organizations that want to import encoded customer passwords into PingOne that use hash iterations, the algorithm for encoded passwords with iterative hashing in PingOne is:

"{PBKDF2}" + base-64-encode( 2 byte version | 2 byte for salt length | salt | 2/4 bytes for number of iterations | encoded password)

A sample of a final encoded password looks like this:

{PBKDF2}ARDCg7vxrqqSDV/UzQ5N9j+XJxDv0E64J9X5aHSZk4108X3esUoaKqGJePteFKJxT6qPkQ==

The attributes used to encode passwords with PBKDF2 iterative hashing are described in the following table:

Attribute Number of Bytes Description
Version 2 Version options are:
  • 00 if PBKDF2WithHmacSHA1
  • 01 if PBKDF2WithHmacSHA256
  • 02 if PBKDF2WithHmacSHA384
  • 03 if PBKDF2WithHmacSHA512
Salt length 2 Salt length is between 8 and 127.
Salt Salt length Cryptographic salt used in hash computation.
Iteration 2 or 4 Number of iterations is between zero and 2147483647. If the number of iterations is less than or equal to 32767, use two bytes to represent number of iterations. Otherwise, use 4 bytes to represent the number of iterations. The leading digit is based on the number of bytes used. The leading digit is zero if two bytes are used. Otherwise, the leading digit is one.
Encoded password Variable length The password that was hashed using the configuration in the encoding.

Password import errors

If a cleartext password is provided and it does not meet the password quality requirements, the following error is returned.

400 BAD REQUEST
{  
   "id":"6c796712-0f16-4062-815a-e0a92f4a2143",
   "code":"INVALID_DATA",
   "message":"The data provided was invalid.",
   "details":[  
      {  
         "code":"INVALID_VALUE",
         "target":"value",
         "message":"The password did not satisfy password policy requirements",
         "innerError":{
           "unsatisfiedRequirements":["excludesProfileData", "length"]
         }
      }
   ]
}

The password policy attribute names returned in the unsatisfiedRequirements array identify the specific password policy requirements that the submitted password does not meet.