Rate this page

Password and account management

User data, such as email addresses and phone numbers, are stored in the Data Governance Broker’s user store. Likewise, metadata concerning a user’s ability to log in are stored in the user store — specifically, in the user’s entry in the Ping Identity Directory Server, which ultimately governs a user’s ability to log in. The Data Governance Broker provides three SCIM sub-resource interfaces to these Directory Server services:

SCIM sub-resource Description
account Used to read and change a user’s account state.
passwordQualityRequirements Used to obtain a user’s password rules.
password Used to change a user’s password.

Account state

In the context of the Ping Identity Directory Server, an account is any entry that is subject to password policy evaluation. A password policy is a set of rules defined in the Directory Server configuration that handles features related to authentication such as password expiration, failed login attempts, and account lockout.

For our purposes, we can say that the Data Governance Broker’s account API gives us the ability to manage a user’s ability to authenticate as governed by the Directory Server’s password policies. The properties that we manage through this API are tightly coupled with password policies, and your use of them should be coordinated with the Directory Server administrator.

It’s worth noting that Directory Server password policies and account handling can affect authentication even in the absence of a password. For example, if you have a user that logs in through an external identity provider like Facebook, the user could still be prevented from authenticating if the user’s account at the Directory Server were marked as disabled.

The account API supports the HTTP GET and PUT methods. To change a user’s account state, retrieve the current account state, make the desired change, and then replace the account state.

The following example disables a user’s account so that the user cannot log in.

final String id = "2819c223-7f76-453a-919d-413861904646";
AccountState accountState =
    scimService.retrieve("Users", id + "/account", AccountState.class);
accountState.setAccountDisabled(true);
scimService.replace(accountState);

Passwords

The Data Governance Broker provides SCIM APIs for updating a user’s password and for obtaining the rules that are applied by the Directory Server when performing the password update. These rules are called password quality requirements.

Obtaining a user’s password quality requirements

A user’s password quality requirements are read-only and are obtained by performing a retrieve operation.

These rules can be customized by the Directory Server administrator, and, in fact, custom rules can be implemented. The structure of a rule is therefore quite variable. When working with this API, the best way to begin is by manually requesting a user’s password quality requirements using an HTTP tool such as curl or httpie.

Here’s an example request:

GET /scim/v2/Users/d4155857-c670-3712-ad85-ea96ee4fbe66/passwordQualityRequirements HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJraWQiOi...
Content-Type: application/scim+json
Host: example.com

And its response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 412
Content-Type: application/scim+json
Date: Thu, 15 Sep 2016 19:43:19 GMT

{
    "schemas": [
        "urn:pingidentity:schemas:2.0:PasswordQualityRequirement"
    ],
    "meta": {
        "resourceType": "Password Quality Requirements",
        "location": "https://example.com/scim/v2/Users/d4155857-c670-3712-ad85-ea96ee4fbe66/passwordQualityRequirements"
    },
    "currentPasswordRequired": false,
    "passwordRequirements": [
        {
            "type": "length",
            "description": "The password must contain at least 6 characters.",
            "minPasswordLength": "6"
        },
        {
            "type": "notCurrentPassword",
            "description": "The new password must not be the same as the current password."
        }
    ]
}

From this, we can build a SCIM 2 SDK example that parses out the minimum required length of a new password:

final String id = "2819c223-7f76-453a-919d-413861904646";

PasswordQualityRequirementResponse response =
    scimService.retrieve("Users", id + "/passwordQualityRequirements",
                         PasswordQualityRequirementResponse.class);

List<PasswordRequirementResult> passwordQualityRequirements =
    response.getPasswordRequirements();

Optional<PasswordRequirementResult> lengthRequirement =
    passwordQualityRequirements.stream()
        .filter(passwordQualityRequirement ->
          passwordQualityRequirement.getType().equals("length"))
        .findFirst();
if (lengthRequirement.isPresent()) {
  String minimumPasswordLength =
      lengthRequirement.get().getProperties().get("minPasswordLength").textValue();
  System.out.println("Minimum password length: " + minimumPasswordLength);
}

A handful of password policy-related attributes are properties of the PasswordQualityResponse itself. For example, the above example could be amended as follows to display a message if the user’s current password must be provided when performing a password change:

if (response.isCurrentPasswordRequired()) {
  System.out.println("The current password must be provided when changing this user's password");
}

Changing a user’s password

To change a user’s password, build a PasswordUpdateRequest object and replace the user’s password sub-resource.

final String id = "2819c223-7f76-453a-919d-413861904646";

PasswordUpdateRequest passwordUpdateRequest =
        new PasswordUpdateRequest.PasswordUpdateRequestBuilder()
            .setCurrentPassword("smallBeer1931520003") // Might be optional
            .setNewPassword("woodenNose072001")
            .build();

URI passwordResourceUri =
    UriBuilder.fromUri("https://example.com/scim/v2/Users/{id}/password")
        .build(id);

PasswordUpdateRequest passwordUpdateResponse =
    scimService.replaceRequest(passwordResourceUri, passwordUpdateRequest)
        .invoke();

Resetting a user’s password

To reset a user’s password, replace the user’s password sub-resource without providing a new password. This will cause the server to generate a new password, which will be included in the response.

final String id = "2819c223-7f76-453a-919d-413861904646";

PasswordUpdateRequest passwordUpdateRequest =
    new PasswordUpdateRequest.PasswordUpdateRequestBuilder()
        .build();

URI passwordResourceUri =
    UriBuilder.fromUri("https://example.com/scim/v2/Users/{id}/password")
        .build(id);

PasswordUpdateRequest passwordUpdateResponse =
    scimService.replaceRequest(passwordResourceUri, passwordUpdateRequest)
        .invoke();
String generatedPassword = passwordUpdateResponse.getGeneratedPassword();
System.out.println("New password: " + generatedPassword);