Passwords service


Passwords

The password management service implements functions that enable the following operations on a specified user:

  • Get a user’s password state
  • Validate a user’s password
  • Set a user’s password
  • Update a user’s password
  • Unlock a user’s password
  • Recover a forgotten password

The password policies service implements functions to list password policies associated with an environment, get information about a specific password policy, and modify a password policy’s attributes. To perform password policy management operations, you need to know the environment ID for the associated password policy.

Password API operations

The Applications service supports the following endpoint operations:

For hands-on experience with the Applications API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Passwords data model

Property Description
currentPassword A string that specifies the current password that must be verified before the new password is set. Required for self change (when the user whose password being changed is the same as the actor in the access token) when the user already has a password.
default Boolean that specifies whether this password policy is enforced within the environment. When set to true, all other password policies are set to false.
description A string that specifies the brief description of the password policy.
environment.id A string that specifies the ID of the environment resource referenced by this relationship.
excludesCommonlyUsed Boolean that ensures the password is not one of the commonly used passwords.
excludesProfileData Boolean that ensure the password does not match (exact and substring) the value of any attribute in the user’s profile, such as name, phone number, or address.
history.count An integer that specifies the number of prior passwords to keep for prevention of password re-use.
history.retentionDays An integer that specifies the length of time to keep recent passwords for prevention of password re-use.
id A string that specifies the password resource’s unique identifier.
lastChangedAt The time the password was last changed. This property is not returned if the user does not have a password.
length.max An integer that specifies the maximum number of characters allowed for the password.
length.min An integer that specifies the minimum number of characters required for the password.
lockout.durationSeconds An integer that specifies the length of time before a password is automatically moved out of the lock out state.
lockout.failureCount An integer that specifies the number of tries before a password is placed in the lock out state.
maxAgeDays An integer that specifies the maximum number of days the same password may be used before it must be changed.
maxRepeatedCharacters An integer that specifies the maximum number of repeated characters allowed. This property is not enforced when not present.
minCharacters A set of key-value pairs where the key is a string containing all the characters that may be included and the value is the minimum number of times one of the characters must appear in the password. This property is not enforced when not present.
minComplexity An integer that specifies the minimum complexity of the password based on the concept of password haystacks. Value is number of days required toexhaust the entire search space during a brute force attack. This property is not enforced when not present.
minUniqueCharacters An integer that specifies the minimum number of unique characters required. This property is not enforced when not present.
name A string that specifies the name of the password policy.
newPassword A string that specifies the new password.
notSimilarToCurrent Boolean that ensures that the proposed password is not too similar to the user’s current password based on the Levenshtein distance algorithm.
passwordPolicy.id A string that specifies the ID of the password policy resource referenced by this relationship.
secondsUntilUnlock An integer that specifies the number of seconds before the password may be used again after a lock out. If absent, the password must be reset by an administrator before it may be used again after a lockout.
status A string that specifies the current status of the password. Options are OK, NO_PASSWORD, PASSWORD_EXPIRED, PASSWORD_LOCKED_OUT, and MUST_CHANGE_PASSWORD.
user.id A string that specifies the ID of the user resource referenced by this relationship.
warnings.expires The password will expire on the specified date and time.
warnings.failuresRemaining There has been recent attempts to check the password unsuccessfully and will be locked out after the indicated number of further unsuccessful attempts.
warnings.noChangeUntil The password was recently self-changed and cannot be self-changed again until the specified date and time.

Response codes

Code Message
200 Successful operation.
400 Bad Request (e.g., invalid username or password)
401 Unauthorized (e.g., invalid token or missing permissions)
404 Not Found (e.g., user or environment)

Note: The Identity Data Admin role is required to perform password management operations. The Environment Admin role is required to perform password policy management operations.

Endpoint examples

Get a user’s password state

You can check the current status of a user’s password to determine whether the password is active or expired. You can also check the number of password-attempt failures remaining before the account is locked.

The following sample shows the GET /environments/{environmentId}/users/{userId}/password returns information about the user’s password state.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/passwordPolicies/02d37832-476a-431b-86d3-01018f6ef0ad"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password/"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        }
    },
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "user": {
        "id": "9a774ad6-b6b6-4179-af87-226cd68955f0"
    },
    "passwordPolicy": {
        "id": "02d37832-476a-431b-86d3-01018f6ef0ad"
    },
    "status": "NO_PASSWORD",
    "lastChanged": "2018-05-15T19:23:25.089Z"
}

Check a user’s password

You can check a user’s password to verify its current state. The result of a password validation check returns one of the following values for the status property:

  • NO_PASSWORD

    No password has been set for the account.

  • OK

    The password is set and can be used to log in.

  • PASSWORD_EXPIRED

    The current password has expired and cannot be used to log in.

  • PASSWORD_LOCKED_OUT

    The password is locked because of too many failed password attempts. It cannot be used to log in.

  • MUST_CHANGE_PASSWORD

    The password was changed by an administrator. It must be reset (changed) by the user before it can be used to log in.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to check the password attribute value provided in the request body against the current password. This operation uses the application/vnd.pingidentity.password.check+json custom content type in the request header.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H "Content-type: application/vnd.pingidentity.password.check+json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "password": "<password>"
}"

The password value in the request body is checked against the user’s current password. If the password is checked successfully, and the password status is OK, MUST_CHANGE_PASSWORD, or PASSWORD_EXPIRED, the response returns a 200 OK message. If the password status is NO_PASSWORD or PASSWORD_LOCKED_OUT, the response returns a 400 BAD REQUEST message.

Update a user’s password

Password update requests are structured differently based on whether the password update is a self change or an administrative change. The PUT /environments/{environmentId}/users/{userId}/password endpoint is called in both cases, but the request body for the self-change operation requires a value for the currentPassword attribute while the administrative-change operation does not. Both operations use application/vnd.pingidentity.password.reset+json as the content type in the request header.

Self-change password update

The following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to execute a self-change reset of the password identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.reset+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "currentPassword": "changeme",
  "newPassword": "difPassword123!"
}'

In the request body, the currentPassword value specifies the existing password, and newPassword specifies the value of the new password assigned to this user. Note that the new password is validated against the current password policy. For a successful self-change update, the status attribute value is changed to OK.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        },
        "environment": {
            "href": "http://directory-api:8080/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/passwordPolicies/ec814a6f-4e7e-45aa-86d3-01018f6ef0ad"
        },
        "passwordValidation": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password/validation"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        }
    },
    "environment": {
        "id": "ec814a6f-4e7e-45aa-92ea-c670f7190352"
    },
    "user": {
        "id": "8b015deb-073d-4c25-a51d-99768b01567d"
    },
    "passwordPolicy": {
        "id": "ec814a6f-4e7e-45aa-86d3-01018f6ef0ad"
    },
    "status": "OK",
    "lastChanged": "2018-06-15T17:14:03.296Z"
}

Administrative-change password update

The following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to execute an administrative-change reset of the password identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.reset+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "newPassword": "Changeme123!"
}'

In the request body, the newPassword attribute specifies the new password assigned to this user by the administrator. For a successful administrator-change update, the status attribute value is changed to MUST_CHANGE_PASSWORD. Note that this assigned temporary password is not validated against the current password policy.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/passwordPolicies/ec814a6f-4e7e-45aa-86d3-01018f6ef0ad"
        },
        "passwordValidation": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password/validation"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/ec814a6f-4e7e-45aa-92ea-c670f7190352/users/8b015deb-073d-4c25-a51d-99768b01567d/password"
        }
    },
    "environment": {
        "id": "ec814a6f-4e7e-45aa-92ea-c670f7190352"
    },
    "user": {
        "id": "8b015deb-073d-4c25-a51d-99768b01567d"
    },
    "passwordPolicy": {
        "id": "ec814a6f-4e7e-45aa-86d3-01018f6ef0ad"
    },
    "status": "MUST_CHANGE_PASSWORD",
    "lastChanged": "2018-06-15T17:12:30.087Z"
}

Set password

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 following sample shows the PUT /environments/{environmentId}/users/{userId}/password operation to set a password for the user identified by the user ID and environment ID.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.set+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "forceChange": "true",
  "value": "Changeme123!"
}'

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 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}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX). PingOne supports the following encoding schemes:

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

Note: Pre-encoded passwords must use the LDAP userPassword syntax supported by PingDirectory and other directory servers. For more information about the LDAP userPassword attribute, see Hashed attribute values for userPassword. For import operations, if a pre-encoded password is not accepted by PingOne, then it does not conform to the supported encoding schemes described above.

Unlock password

The POST /environments/{environmentId}/users/{userId}/password endpoint is called by an administrator or an application to unlock a user’s password. This operation uses the application/vnd.pingidentity.password.unlock custom media type as the content type in the request header.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to unlock a password for the user identified by the user ID and environment ID.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.unlock' \
-H 'Authorization: Bearer jwtToken'

This POST request does not require any attribute values in the request body. It returns a 200 OK message when successful and generates a PASSWORD.UNLOCKED event.

Recover password

The POST /environments/{environmentId}/users/{userId}/password endpoint is called to recover a forgotten password. It sends a one-time-password (OTP) that is used to reset the password. The OTP is a randomly generated eight-character alphanumeric string sent to the user’s email address, and the code is valid for five minutes. This operation uses the application/vnd.pingidentity.password.sendRecoveryCode+json custom media type as the content type in the request header.

Note: This operation cannot be used if the user is disabled or if the password status is NO_PASSWORD or PASSWORD_LOCKED_OUT.

The following sample shows the POST /environments/{environmentId}/users/{userId}/password operation to recover a password for the user identified by the environment ID and user ID.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.sendRecoveryCode+json' \
-H 'Authorization: Bearer jwtToken'

If the user exceeds the maximum number of invalid attempts to recover the password while using the recovery OTP, the password status is changed to the PASSWORD_LOCKED_OUT. The POST /environments/{environmentId}/users/{userId}/password endpoint is also used to reset the locked-out password using a recovery code. This operation uses the application/vnd.pingidentity.password.recover+json custom media type as the content type in the request header, and it requires the recoveryCode and the newPassword attributes in the request body.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Content-type: application/vnd.pingidentity.password.recover+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "recoveryCode": "<code>",
  "newPassword": "VerySecure123!"
}'

Password policies

The Password Policies API implements functions to list password policies associated with an environment, get information about a specific password policy, and modify a password policy’s attributes.

To perform password policy management operations, you need to know the environment ID for the associated password policy. The examples below show common actions to manage password policies.

Note: The Environment Admin role is required to perform password policy management operations.

Get password policies

You can get all password policies for an environment or a specific password policy.

The GET /environments/{environmentId}/passwordPolicies operation returns all password policies for the selected environment.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/passwordPolicies" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

In this sample, the environment has two defined password policies, a Standard policy and a Passphrase policy. The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies"
    }
  },
  "_embedded" : {
    "passwordPolicies" : [ {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies/0bda42bc-d54f-449f-86d3-01018f6ef0ad"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
      },
      "id" : "0bda42bc-d54f-449f-86d3-01018f6ef0ad",
      "environment" : {
        "id" : "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
      },
      "name" : "Standard",
      "description" : "A standard policy that incorporates industry best practices",
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "maxAgeDays" : 90,
      "maxRepeatedCharacters" : 2,
      "minUniqueCharacters" : 5,
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      },
      "lockout" : {
        "failureCount" : 5,
        "durationSeconds" : 900
      },
      "length" : {
        "min" : 8,
        "max" : 255
      },
      "minCharacters" : {
        "abcdefghijklmnopqrstuvwxyz" : 1,
        "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : 1,
        "123456890" : 1,
        "~!@#$%^&*()-_=+[]{}|;:,.<>/?" : 1
      },
      "default" : true
    }, {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/passwordPolicies/0bda42bc-d54f-449f-b22d-3c605c617410"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
      },
      "id" : "0bda42bc-d54f-449f-b22d-3c605c617410",
      "environment" : {
        "id" : "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
      },
      "name" : "Passphrase",
      "description" : "A policy that encourage the use of passphrases",
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "minComplexity" : 7,
      "maxAgeDays" : 90,
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      },
      "lockout" : {
        "failureCount" : 5,
        "durationSeconds" : 900
      },
      "default" : false
    } ]
  },
  "count" : 2,
  "size" : 2
}

The GET /environments/{environmentId}/passwordPolicies/{policyId} operation returns information for a single password policy specified by the policyId attribute in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/passwordPolicies/{policyId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data shows information for the password policy identified by its id.

Update a password policy

You can update a specified password policy by changing the value of its default property. The PUT /environments/{environmentId}/passwordPolicies/{policyId} operation updates the password policy specified by the policy ID in the request URL.

curl -X PUT "https://api.pingone.com/v1/environments/{environmentId}/passwordPolicies/{policyId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d $'{
  "default": "true"
}'