PingDirectory API Reference

Get Password Quality Requirements

POST {{apiPath}}/directory/v1/passwordRequirements

The POST /directory/v1/passwordRequirements request performs the LDAP get password quality requirements extended operation through HTTP.

Request body

The request may include the following fields:

  • operationType

    A required parameter that specifies the type of operation in which the new password will be used. The value for this parameter must be one of the following:

    • add

      The new password will be used to create a new user.

    • selfChange

      The new password will be used for a self password change.

    • administrativeReset

      The new password will be used for an administrative password reset.

  • userDN

    The DN of the target user who will be using the password.

    • This is required if the operationType is administrativeReset.

    • The must be absent if the operationType is add.

    • If the request has an authorization header and the new password is for the user associated with that authorization identity, it can be absent for an operationType of selfChange.

  • passwordPolicyDN

    An optional parameter that specifies the DN of the password policy to determine the requirements for a new user.

    • This must be absent for an operationType of selfChange or administrativeReset.

    • It can be present for an operationType of add.

      If it is absent, then the server’s default password policy is used.

  • _controls

    An optional array of JSON-formatted request controls to be used when processing the get password quality requirements request. These controls are narrowed down based on which conversions from JSON to LDAP are currently implemented by the Directory REST API. Documentation for all controls supported by the Directory REST API are listed here.

The No operation request control is read-only and not supported for this operation.

Response body

The response must include a body that is formatted as a JSON object. Upon a successful operation where the LDAP resultCode value is 0 and HTTP status code is 200, the following fields will be included in the JSON object:

  • resultCode

    A required JSON object that contains the following fields:

    • value

      The required integer value for the LDAP result code.

    • name

      A name for the LDAP result code. This is optional but recommended.

  • matchedDN

    An optional string field that holds the matched DN for the operation. You can omit this if no matched DN value is needed or appropriate.

  • diagnosticMessage

    An optional string field that holds a human-readable message with additional information about the operation. You can omit this if no diagnostic message is needed or appropriate.

  • passwordQualityRequirements

    A required array of JSON objects that represent the set of password quality requirements that the server will impose. This field will be returned even if the array of JSON objects is empty. Each of these objects should include the following fields:

    • description

      A required string field that provides a user-friendly description for the environment.

    • client-side-validation-type

      An optional string field that contains the name of the client-side validation type for the requirement.

    • client-side-validation-properties

      An optional array of JSON objects with the client-side validation properties for the requirement. Each of these objects should include the following fields:

      • name

        A required string field with the name for the client-side validation property.

      • value

        A required string field with the value for the client-side validation property.

  • currentPasswordRequired

    An optional Boolean field that indicates whether the target user is required to provide their current password when choosing a new password. This field is present in a successful response to a request for a self password change, and is absent otherwise.

  • mustChangePassword

    An optional Boolean field that indicates whether the target user will be required to choose a new password after an administrative reset. This field is present in a successful response to a request for an add or an administrative password reset, and is absent otherwise.

  • secondsUntilExpiration

    An optional integer field that specifies the length of time that a new password is considered valid for the requested type of operation. This field is absent if the request was not processed successfully or if the new password may be used indefinitely.

  • _controls

    An optional array of JSON-formatted response controls.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.19",
            "criticality": true,
            "value-json": {
                "application-name": "22, A Million",
                "application-version": "22.1000000.0",
                "code-location": "authenticateUser",
                "request-purpose": "It might be over soon"
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.2",
            "criticality": true,
            "value-json": {
                "downstream-client-address": "6.6.6",
                "downstream-client-secure": true
            }
        }
    ]
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/directory/v1/passwordRequirements' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.19",
            "criticality": true,
            "value-json": {
                "application-name": "22, A Million",
                "application-version": "22.1000000.0",
                "code-location": "authenticateUser",
                "request-purpose": "It might be over soon"
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.2",
            "criticality": true,
            "value-json": {
                "downstream-client-address": "6.6.6",
                "downstream-client-secure": true
            }
        }
    ]
}'
var options = new RestClientOptions("{{apiPath}}/directory/v1/passwordRequirements")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"    ""operationType"": ""administrativeReset""," + "\n" +
@"    ""userDN"": ""uid=jimbob,ou=people,dc=example,dc=com""," + "\n" +
@"    ""_controls"": [" + "\n" +
@"        {" + "\n" +
@"            ""oid"": ""1.3.6.1.4.1.30221.2.5.19""," + "\n" +
@"            ""criticality"": true," + "\n" +
@"            ""value-json"": {" + "\n" +
@"                ""application-name"": ""22, A Million""," + "\n" +
@"                ""application-version"": ""22.1000000.0""," + "\n" +
@"                ""code-location"": ""authenticateUser""," + "\n" +
@"                ""request-purpose"": ""It might be over soon""" + "\n" +
@"            }" + "\n" +
@"        }," + "\n" +
@"        {" + "\n" +
@"            ""oid"": ""1.3.6.1.4.1.30221.2.5.2""," + "\n" +
@"            ""criticality"": true," + "\n" +
@"            ""value-json"": {" + "\n" +
@"                ""downstream-client-address"": ""6.6.6""," + "\n" +
@"                ""downstream-client-secure"": true" + "\n" +
@"            }" + "\n" +
@"        }" + "\n" +
@"    ]" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/directory/v1/passwordRequirements"
  method := "POST"

  payload := strings.NewReader(`{
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.19",
            "criticality": true,
            "value-json": {
                "application-name": "22, A Million",
                "application-version": "22.1000000.0",
                "code-location": "authenticateUser",
                "request-purpose": "It might be over soon"
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.2",
            "criticality": true,
            "value-json": {
                "downstream-client-address": "6.6.6",
                "downstream-client-secure": true
            }
        }
    ]
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /directory/v1/passwordRequirements HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.19",
            "criticality": true,
            "value-json": {
                "application-name": "22, A Million",
                "application-version": "22.1000000.0",
                "code-location": "authenticateUser",
                "request-purpose": "It might be over soon"
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.2",
            "criticality": true,
            "value-json": {
                "downstream-client-address": "6.6.6",
                "downstream-client-secure": true
            }
        }
    ]
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"operationType\": \"administrativeReset\",\n    \"userDN\": \"uid=jimbob,ou=people,dc=example,dc=com\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.19\",\n            \"criticality\": true,\n            \"value-json\": {\n                \"application-name\": \"22, A Million\",\n                \"application-version\": \"22.1000000.0\",\n                \"code-location\": \"authenticateUser\",\n                \"request-purpose\": \"It might be over soon\"\n            }\n        },\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.2\",\n            \"criticality\": true,\n            \"value-json\": {\n                \"downstream-client-address\": \"6.6.6\",\n                \"downstream-client-secure\": true\n            }\n        }\n    ]\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/directory/v1/passwordRequirements")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/directory/v1/passwordRequirements",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.19",
        "criticality": true,
        "value-json": {
          "application-name": "22, A Million",
          "application-version": "22.1000000.0",
          "code-location": "authenticateUser",
          "request-purpose": "It might be over soon"
        }
      },
      {
        "oid": "1.3.6.1.4.1.30221.2.5.2",
        "criticality": true,
        "value-json": {
          "downstream-client-address": "6.6.6",
          "downstream-client-secure": true
        }
      }
    ]
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/directory/v1/passwordRequirements',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "operationType": "administrativeReset",
    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.19",
        "criticality": true,
        "value-json": {
          "application-name": "22, A Million",
          "application-version": "22.1000000.0",
          "code-location": "authenticateUser",
          "request-purpose": "It might be over soon"
        }
      },
      {
        "oid": "1.3.6.1.4.1.30221.2.5.2",
        "criticality": true,
        "value-json": {
          "downstream-client-address": "6.6.6",
          "downstream-client-secure": true
        }
      }
    ]
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/directory/v1/passwordRequirements"

payload = json.dumps({
  "operationType": "administrativeReset",
  "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.19",
      "criticality": True,
      "value-json": {
        "application-name": "22, A Million",
        "application-version": "22.1000000.0",
        "code-location": "authenticateUser",
        "request-purpose": "It might be over soon"
      }
    },
    {
      "oid": "1.3.6.1.4.1.30221.2.5.2",
      "criticality": True,
      "value-json": {
        "downstream-client-address": "6.6.6",
        "downstream-client-secure": True
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/directory/v1/passwordRequirements');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n    "operationType": "administrativeReset",\n    "userDN": "uid=jimbob,ou=people,dc=example,dc=com",\n    "_controls": [\n        {\n            "oid": "1.3.6.1.4.1.30221.2.5.19",\n            "criticality": true,\n            "value-json": {\n                "application-name": "22, A Million",\n                "application-version": "22.1000000.0",\n                "code-location": "authenticateUser",\n                "request-purpose": "It might be over soon"\n            }\n        },\n        {\n            "oid": "1.3.6.1.4.1.30221.2.5.2",\n            "criticality": true,\n            "value-json": {\n                "downstream-client-address": "6.6.6",\n                "downstream-client-secure": true\n            }\n        }\n    ]\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/directory/v1/passwordRequirements")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "operationType": "administrativeReset",
  "userDN": "uid=jimbob,ou=people,dc=example,dc=com",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.19",
      "criticality": true,
      "value-json": {
        "application-name": "22, A Million",
        "application-version": "22.1000000.0",
        "code-location": "authenticateUser",
        "request-purpose": "It might be over soon"
      }
    },
    {
      "oid": "1.3.6.1.4.1.30221.2.5.2",
      "criticality": true,
      "value-json": {
        "downstream-client-address": "6.6.6",
        "downstream-client-secure": true
      }
    }
  ]
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"operationType\": \"administrativeReset\",\n    \"userDN\": \"uid=jimbob,ou=people,dc=example,dc=com\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.19\",\n            \"criticality\": true,\n            \"value-json\": {\n                \"application-name\": \"22, A Million\",\n                \"application-version\": \"22.1000000.0\",\n                \"code-location\": \"authenticateUser\",\n                \"request-purpose\": \"It might be over soon\"\n            }\n        },\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.2\",\n            \"criticality\": true,\n            \"value-json\": {\n                \"downstream-client-address\": \"6.6.6\",\n                \"downstream-client-secure\": true\n            }\n        }\n    ]\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/directory/v1/passwordRequirements")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

200 OK

{
    "resultCode": {
        "value": 0,
        "name": "success"
    },
    "passwordQualityRequirements": [],
    "mustChangePassword": "false",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.2",
            "control-name": "Intermediate Client Response Control",
            "criticality": false,
            "value-json": {
                "server-name": "PingDirectory",
                "server-session-id": "conn=-1403",
                "server-response-id": "op=61007"
            }
        }
    ]
}