Working with passwords and password policies


User 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.

To perform password management tasks, you need to know the environment ID to which the user resource is assigned and the user resource’s ID. The examples that follow show common actions to manage user passwords.

Note: The Identity Data Admin role is required to perform password management operations. For more information, see working with user roles.

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/58f92121-b753-4e7e-8d82-23b5bf80efe5/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/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"
        },
        "passwordValidation": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password/validation"
        },
        "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 login.

  • PASSWORD_EXPIRED

    The current password has expired and cannot be used to login.

  • PASSWORD_LOCKED_OUT

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

  • MUST_CHANGE_PASSWORD

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

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 provided password. This operations uses the application/vnd.pingidentity.password.check+json custom content type in the request header.

curl -X POST "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e/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/feff791f-a12f-44ec-a696-53be4ac1f9c2/users/05ad3cc6-8723-4f85-9711-05ad549717f6/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/feff791f-a12f-44ec-a696-53be4ac1f9c2/users/05ad3cc6-8723-4f85-9711-05ad549717f6/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 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/feff791f-a12f-44ec-a696-53be4ac1f9c2/users/05ad3cc6-8723-4f85-9711-05ad549717f6/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. They are specified by the name of the encoding scheme followed by an encoded representation of the password (for example, {SSHA}7z9Lzvdk3ACw9ITe/yEV5iES5ADcbdZcj3PFZQ==). Supported encoding schemes are: bcrypt, scrypt, crypt, salted SHA1, salted SHA256, salted SHA384, salted SHA512.

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. For more information, see Working with user roles.

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/58f92121-b753-4e7e-8d82-23b5bf80efe5/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/58f92121-b753-4e7e-8d82-23b5bf80efe5/passwordPolicies/58f92121-b753-4e7e-b22d-3c605c617410" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

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