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 attributes. 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.
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 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.
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 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/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 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. The following sample changes the Basic password policy to the default by setting the default property value to true.

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": 5,
    "durationSeconds": 900
  },
  "length": {
    "min": 8,
    "max": 255
  },
  "minCharacters": {
    "abcdefghijklmnopqrstuvwxyz": 1,
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
    "1234567890": 1,
    "~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
  },
  "default": true
}'