Rate this page

Password

SCIM resources capable of performing logins (i.e., users) may expose two password-related sub-resources:

  • A password sub-resource, used to change the password of the parent resource.
  • A passwordQualityRequirements resource, which lists rules that must be satisfied in order to change the password of the parent resource.

Password quality requirements

Password quality requirements are sets of rules enforced by the user store when changing a user’s password. These correspond to password validators in a Ping Identity Directory Server’s configuration.

Password quality requirement objects will always contain the type and description fields. Other fields may be present, depending on the type.

Field Type Provided? Description
type string always The type of password requirement. See the table below.
description string always A human-readable description of the password requirement.
requirementSatisfied boolean Whether or not a proposed password satisfied this password requirement. This field only appears in password update error responses.

Possible password requirement types are:

Password requirement type Description
notCurrentPassword The current password may not be reused.
history A new password cannot match a password in the user’s password history.
attributeValue The password value must not be present in another attribute of the user.
characterSet The password must contain at least a specified number of characters from one or more character sets defined by the password requirement.
haystack The password must satisfy a configurable requirement based upon the password haystacks concept.
length The password must meet a minimum/maximum length requirement.
regularExpression The password must match a configured regular expression.
repeatedCharacters The password may not contain a configured number of consecutive characters.
similarity The password must be sufficiently dissimilar to the current password.
uniqueCharacters The password must contain a minimum number of unique characters.

The user store may also be configured with custom password requirements with other type values.

Retrieve a user’s password quality requirements

GET /scim/v2/Users/{id}/passwordQualityRequirements

GET /scim/v2/Me/passwordQualityRequirements

A client may retrieve a user’s password quality requirements sub-resource to obtain the rules that determine whether a new password value will be accepted by the user store. The client may use these password quality requirements to present guidance to an end user.

The following table describes the fields of a password quality requirements response.

Field Type Provided? Description
schemas array always The SCIM schema of the password quality response resource. Should have the value urn:pingidentity:schemas:2.0:PasswordQualityRequirement.
meta complex always Will always contain a resourceType sub-attribute with the value Password Quality Requirements. Will always contain a location attribute with the session resource’s canonical URI.
currentPasswordRequired boolean always Indicates whether the client must provide the current password value when performing a password change.
passwordRequirements array always An array of password quality requirements. Password quality requirements are described above.

Example request:

GET /scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/passwordQualityRequirement HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 818
Content-Type: application/scim+json
Date: Tue, 19 Jul 2016 01:04:31 GMT

{
    "currentPasswordRequired": false, 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/passwordQualityRequirement", 
        "resourceType": "Password Quality Requirements"
    }, 
    "passwordRequirements": [
        {
            "caseSensitiveValidation": "false", 
            "description": "Passwords must not be included in a list of commonly-used passwords, as they are also commonly used by attackers trying to break into accounts", 
            "dictionaryFile": "commonly-used-passwords.txt", 
            "testReversedPassword": "false", 
            "type": "dictionary"
        }, 
        {
            "description": "The password must contain at least 6 characters.", 
            "minPasswordLength": "6", 
            "type": "length"
        }, 
        {
            "description": "The new password must not be the same as the current password.", 
            "type": "notCurrentPassword"
        }
    ], 
    "schemas": [
        "urn:pingidentity:schemas:2.0:PasswordQualityRequirement"
    ]
}

Update a user’s password

PUT /scim/v2/Users/{id}/password

PUT /scim/v2/Me/password

A client may update a user’s password using the user’s password sub-resource. The password sub-resource supports providing the user’s current password, if required by the user’s password quality requirements, and also supports password generation.

The following table describes the fields of a password update request.

Field Type Required? Description
schemas array yes The SCIM schema of the password update request. Always has the value urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest.
newPassword string no The proposed new password. If this field is omitted, then a password will be generated and returned in the response.
currentPassword string no The user’s current password. A client may determine if this is needed by checking the currentPasswordRequired value of the user’s passwordQualityRequirements sub-resource.

The following table describes the fields of a password update response.

Field Type Provided? Description
schemas array always The SCIM schema of the password resource. Always has the value urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest.
meta complex always Will always contain a resourceType sub-attribute with the value Password Update. Will always contain a location attribute with the password sub-resource’s canonical URI.
generatedPassword string A generated password value. Only present if newPassword was not provided in the request.

The following example illustrates a basic password change.

In the request, the client provides the new password:

PUT /scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/password HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Length: 125
Content-Type: application/scim+json
Host: example.com:443

{
    "newPassword": "s00perS3cret!#@#$", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest"
    ]
}

And the server responds with a 200 status code:

HTTP/1.1 200 OK
Content-Length: 225
Content-Type: application/scim+json
Date: Tue, 19 Jul 2016 03:35:06 GMT

{
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/password", 
        "resourceType": "Password Update"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest"
    ]
}

This example demonstrates omitting the newPassword field so that the user store will generate a new password:

PUT /scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/password HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Length: 87
Content-Type: application/scim+json
Host: example.com:443

{
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest"
    ]
}

In the response, the server provides the automatically generated new password in the generatedPassword field.

HTTP/1.1 200 OK
Content-Length: 296
Content-Type: application/scim+json
Date: Tue, 19 Jul 2016 03:35:26 GMT

{
    "generatedPassword": "AncestryDecontaminationTransplantationHemorrhage", 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/password", 
        "resourceType": "Password Update"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest"
    ]
}

Finally, the following example shows a failed password update attempt and an error response containing the user’s password quality requirements.

PUT /scim/v2/Users/bc525544-5f1c-437e-9fe8-3ffbba8d98a8/password HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Length: 145
Content-Type: application/scim+json
Host: example.com:443

{
    "currentPassword": "s00perS3cret!#@#$", 
    "newPassword": "cats", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateRequest"
    ]
}

Note that the response indicates that one password quality requirement is satisfied, while the other is not.

HTTP/1.1 400 Bad Request
Content-Length: 913
Content-Type: application/scim+json
Date: Tue, 19 Jul 2016 03:34:10 GMT

{
    "detail": "The provided new password failed the validation checks defined in the server:  The provided password is shorter than the minimum required length of 6 characters", 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ], 
    "scimType": "invalidValue", 
    "status": 400, 
    "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateError": {
        "passwordRequirements": [
            {
                "caseSensitiveValidation": "false", 
                "description": "Passwords must not be included in a list of commonly-used passwords, as they are also commonly used by attackers trying to break into accounts", 
                "dictionaryFile": "commonly-used-passwords.txt", 
                "requirementSatisfied": true, 
                "testReversedPassword": "false", 
                "type": "dictionary"
            }, 
            {
                "additionalInfo": "The provided password is shorter than the minimum required length of 6 characters", 
                "description": "The password must contain at least 6 characters.", 
                "minPasswordLength": "6", 
                "requirementSatisfied": false, 
                "type": "length"
            }
        ]
    }
}