Password policies


Password policies

The password policies endpoints implement functions to list password policies associated with an environment, get information about a specific password policy, and modify a password policy’s properties. PingOne provides the following three pre-defined password policies:

Basic

A relaxed standard policy to allow for maximum customer flexibility. Requirements include:

  • The password will be checked against a list of most commonly-used passwords.

  • The password must be between 8 and 255 characters.

  • The password must have at least 1 of the following characters: 1234567890

  • The password must have at least 1 of the following characters: abcdefghijklmnopqrstuvwxyz

  • The password must have at least 1 of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ

  • The password must have at least 1 of the following characters: ~!@#$%^&*()-_=+[]{}|;:,.<>/?

  • The user’s account will lockout after 5 failed attempts for 15 minutes. Repeated attempts of the same password will not be counted as failed attempts.

Note: The basic password policy does not have an expiration rule. When this password policy is in effect, user passwords do not expire.

Standard

A standard password policy that incorporates industry best practices. Requirements include:

  • The password will be checked to make sure it doesn’t match strings that appear in the user’s identity data.

  • The password will be checked to make sure it is not too similar to the user’s current password.

  • The password will be checked against a list of most commonly-used passwords.

  • The password cannot have more than 2 repeated characters.

  • The password must have a minimum of 5 unique characters.

  • The password must be between 8 and 255 characters.

  • The password must have at least 1 of the following characters: 1234567890

  • The password must have at least 1 of the following characters: abcdefghijklmnopqrstuvwxyz

  • The password must have at least 1 of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ* The password must have at least 1 of the following characters: ~!@#$%^&*()-_=+[]{}|;:,.<>/?

  • The password will expire every 182 days.

  • Passwords can be changed after 1 day.

  • 6 prior passwords will be maintained in the password history count for a maximum of 365 days.

  • The user’s account will lockout after 5 failed attempts for 15 minutes. Repeated attempts of the same password will not be counted as failed attempts.

Passphrase

A password policy that accepts the use of passphrases. Requirements include:

  • The password will be checked to make sure it doesn’t match strings that appear in the user’s identity data.

  • The password will be checked to make sure it is not too similar to the user’s current password.

  • The password will be checked against a list of most commonly-used passwords.

  • The password must have a complexity of at least 7 days, based on the Gibson Research Corporation Password Haystacks concept.

  • The password will expire every 182 days.

  • Passwords can be changed after 1 day.

  • 6 prior passwords will be maintained in the password history count for a maximum of 365 days.

To perform password policy management operations, you need to know the environment ID for the associated password policy.

Password policies API operations

The passwords endpoints support the following 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.

Password policies 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. The value must be a positive, non-zero integer.
history.retentionDays An integer that specifies the length of time to keep recent passwords for prevention of password re-use. The value must be a positive, non-zero integer.
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. This property is not enforced when not present.
length.min An integer that specifies the minimum number of characters required for the password. This property is not enforced when not present.
lockout.durationSeconds An integer that specifies the length of time before a password is automatically moved out of the lock out state. The value must be a positive, non-zero integer.
lockout.failureCount An integer that specifies the number of tries before a password is placed in the lock out state. The value must be a positive, non-zero integer.
maxAgeDays An integer that specifies the maximum number of days the same password may be used before it must be changed. The value must be a positive, non-zero integer.
- The value must be greater than or equal to minAgeDays, if provided.
maxRepeatedCharacters An integer that specifies the maximum number of repeated characters allowed. This property is not enforced when not present.
minAgeDays An integer that specifies the minimum number of days a password must be used before changing. The value must be a positive, non-zero integer. 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. The only allowed keys are ABCDEFGHIJKLMNOPQRSTUVWXYZ, abcdefghijklmnopqrstuvwxyz, 0123456789, and ~!@#$%^&*()-_=+[]{}\|;:,.<>/?. 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 to exhaust 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. This value must be unique within the environment.
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 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.

Endpoint examples

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 "Authorization: Bearer jwtToken"

In this sample, the environment includes the three PingOne pre-defined password policies, a Standard policy, a Passphrase policy, and a Basic policy. The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies"
    }
  },
  "_embedded": {
    "passwordPolicies": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies/9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          }
        },
        "id": "9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "name": "Standard",
        "description": "A standard policy that incorporates industry best practices",
        "excludesProfileData": true,
        "notSimilarToCurrent": true,
        "excludesCommonlyUsed": true,
        "maxAgeDays": 182,
        "minAgeDays": 1,
        "maxRepeatedCharacters": 2,
        "minUniqueCharacters": 5,
        "history": {
          "count": 6,
          "retentionDays": 365
        },
        "lockout": {
          "failureCount": 5,
          "durationSeconds": 900
        },
        "length": {
          "min": 8,
          "max": 255
        },
        "minCharacters": {
          "abcdefghijklmnopqrstuvwxyz": 1,
          "ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
          "1234567890": 1,
          "~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
        },
        "default": true
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies/9ad15e9e-3ac6-43f7-b22d-3c605c617410"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          }
        },
        "id": "9ad15e9e-3ac6-43f7-b22d-3c605c617410",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "name": "Passphrase",
        "description": "A policy that encourage the use of passphrases",
        "excludesProfileData": true,
        "notSimilarToCurrent": true,
        "excludesCommonlyUsed": true,
        "minComplexity": 7,
        "maxAgeDays": 182,
        "minAgeDays": 1,
        "history": {
          "count": 6,
          "retentionDays": 365
        },
        "lockout": {
          "failureCount": 5,
          "durationSeconds": 900
        },
        "default": false
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies/9ad15e9e-3ac6-43f7-adbf-7bd231c8b23d"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          }
        },
        "id": "9ad15e9e-3ac6-43f7-adbf-7bd231c8b23d",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "name": "Basic",
        "description": "A relaxed standard policy to allow for maximum customer flexibility.",
        "excludesProfileData": false,
        "notSimilarToCurrent": false,
        "excludesCommonlyUsed": true,
        "lockout": {
          "failureCount": 5,
          "durationSeconds": 900
        },
        "length": {
          "min": 8,
          "max": 255
        },
        "minCharacters": {
          "abcdefghijklmnopqrstuvwxyz": 1,
          "ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
          "1234567890": 1,
          "~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
        },
        "default": false
      }
    ]
  },
  "count": 3,
  "size": 3
}

Get one password policy

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 "Authorization: Bearer jwtToken"

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

Update a password policy

You can update the password policy for the specified environment by changing the values of its properties. The PUT /environments/{environmentId}/passwordPolicies/{policyId} operation updates the password policy specified by the policy ID in the request URL. The request body specifies values for the properties associated with the password policy.

The following password requirements property values cannot be modified at this time, but they can be excluded from the request to turn the requirement off.

Password requirement Fixed value Can be excluded
length.min 8 Yes
length.max 255 Yes
maxRepeatedCharacters 2 Yes
minUniqueCharacters 5 Yes
minCharacters abcdefghijklmnopqrstuvwxyz": 1,
“ABCDEFGHIJKLMNOPQRSTUVWXYZ”: 1,
“0123456789”: 1,
"~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
Yes

The following password requirements property values can be modified, and they can be excluded from the request to turn the requirement off.

Password requirement Default value Can be excluded
maxAgeDays 182 Yes
minAgeDays 1 Yes

The following password policy rules can be changed to any positive integer, and these properties can be excluded from the request to turn the requirement off. If history is included, both values, count and retentionDays, must be defined. Likewise, if lockout is included, both values, failureCount and durationSeconds, must be defined.

Password policy rule Default value Can be excluded
history.count 6 Yes
history.retentionDays 365 Yes
lockout.failureCount 5 Yes
lockout.durationSeconds 900 Yes

Password attributes with boolean values such as default, excludesProfileData, notSimilarToCurrent, and excludesCommonlyUsed are required. The rule can be turned on or off by changing the value.

The following sample changes the Basic password policy by setting the lockout.failureCount property value to 8.

curl -X PUT "https://api.pingone.com/v1/environments/{environmentId}/passwordPolicies/{policyId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d $'{
  "id" : "6e4b6b42-b73f-4d03-adbf-7bd231c8b23d",
  "environment" : {
    "id" : "6e4b6b42-b73f-4d03-9871-24e7b26a290e"
  },
  "name": "Basic",
  "description": "A relaxed standard policy to allow for maximum customer flexibility.",
  "excludesProfileData": false,
  "notSimilarToCurrent": false,
  "excludesCommonlyUsed": true,
  "lockout": {
    "failureCount": 8,
    "durationSeconds": 900
  },
  "length": {
    "min": 8,
    "max": 255
  },
  "minCharacters": {
    "abcdefghijklmnopqrstuvwxyz": 1,
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
    "1234567890": 1,
    "~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
  },
  "default": true
}'