Password Modify

POST {{apiPath}}/directory/v1/{{dn}}/changePassword

The POST {{apiPath}}/directory/v1/{{dn}}/changePassword+ request performs the LDAP modify password extended operation through HTTP. An example of a valid {{dn}} value is uid=jdoe,ou=People,dc=example,dc=com.

It is possible (but not recommended) to update these attributes via a PUT REST API operation by superseding the deny write global ACI with the bypass-acl privilege or to remove the default deny write ACI entirely.

The request may include the following fields:

oldPassword

The current password for the user. If provided, the request is a self password change, regardless of its authorization state. If not provided, the request is either a self change or an administrative reset, based on whether the target user identity matches the authorized user identity.
newPassword

The new password for the user. If provided, the value will be used as the new password. If not provided, the server will generate the new password for the user and include it in the response.
_controls

An optional array of JSON-formatted request controls to be used when processing the password modify request. These controls are narrowed down based on which conversions from JSON to LDAP are currently implemented by the Directory REST API. The following request controls are supported and relevant to the password modify request:

This application can return several HTTP status codes. The 200 (OK) status code will return a HAL+JSON-formatted response body containing relevant password modification data. The JSON response will include any of the following fields populated by the underlying LDAP password modify extended operation. The fields that might be included are:

resultCode

A mandatory JSON object that contains the following fields:
- value
  
  The integer value for the LDAP result code. This is required.
- name
  
  A name for the LDAP result code. This is optional but recommended.
matchedDN

A string that holds the matched DN for the operation. You can omit this if no matched DN value is necessary or appropriate.
diagnosticMessage

A string that holds a human-readable message with additional information about the operation. You can omit this if no diagnostic message is necessary.
generatedPassword

A string that holds the new password that was generated for the user by the server. This should only be present if the request did not specify a new password and the server was able to generate and set a new password for the user.
_controls

An optional array of JSON-formatted response controls.

In the case of non-successful, non-no-op LDAP results, the explicit LDAP diagnostic message is included in the HTTP failure response.

Headers

Authorization Bearer {{accessToken}}

Content-Type application/json

Body

raw ( application/json )

{
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.40",
            "control-name": "Password Validation Details Request Control",
            "criticality": false
        }
    ]
}

Example Request

curl --location --globoff '{{apiPath}}/directory/v1/{{dn}}/changePassword' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.40",
            "control-name": "Password Validation Details Request Control",
            "criticality": false
        }
    ]
}'

var options = new RestClientOptions("{{apiPath}}/directory/v1/{{dn}}/changePassword")
{
  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" +
@"    ""oldPassword"": ""oldPasswordExample""," + "\n" +
@"    ""newPassword"": ""newPasswordExample""," + "\n" +
@"    ""_controls"": [" + "\n" +
@"        {" + "\n" +
@"            ""oid"": ""1.3.6.1.4.1.30221.2.5.40""," + "\n" +
@"            ""control-name"": ""Password Validation Details Request Control""," + "\n" +
@"            ""criticality"": false" + "\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/{{dn}}/changePassword"
  method := "POST"

  payload := strings.NewReader(`{
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.40",
            "control-name": "Password Validation Details Request Control",
            "criticality": false
        }
    ]
}`)

  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/{{dn}}/changePassword HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.40",
            "control-name": "Password Validation Details Request Control",
            "criticality": false
        }
    ]
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"oldPassword\": \"oldPasswordExample\",\n    \"newPassword\": \"newPasswordExample\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.40\",\n            \"control-name\": \"Password Validation Details Request Control\",\n            \"criticality\": false\n        }\n    ]\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/directory/v1/{{dn}}/changePassword")
  .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/{{dn}}/changePassword",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.40",
        "control-name": "Password Validation Details Request Control",
        "criticality": false
      }
    ]
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/directory/v1/{{dn}}/changePassword',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "oldPassword": "oldPasswordExample",
    "newPassword": "newPasswordExample",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.40",
        "control-name": "Password Validation Details Request Control",
        "criticality": false
      }
    ]
  })

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

import requests
import json

url = "{{apiPath}}/directory/v1/{{dn}}/changePassword"

payload = json.dumps({
  "oldPassword": "oldPasswordExample",
  "newPassword": "newPasswordExample",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.40",
      "control-name": "Password Validation Details Request Control",
      "criticality": False
    }
  ]
})
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/{{dn}}/changePassword');
$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    "oldPassword": "oldPasswordExample",\n    "newPassword": "newPasswordExample",\n    "_controls": [\n        {\n            "oid": "1.3.6.1.4.1.30221.2.5.40",\n            "control-name": "Password Validation Details Request Control",\n            "criticality": false\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/{{dn}}/changePassword")

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({
  "oldPassword": "oldPasswordExample",
  "newPassword": "newPasswordExample",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.40",
      "control-name": "Password Validation Details Request Control",
      "criticality": false
    }
  ]
})

response = http.request(request)
puts response.read_body

let parameters = "{\n    \"oldPassword\": \"oldPasswordExample\",\n    \"newPassword\": \"newPasswordExample\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.40\",\n            \"control-name\": \"Password Validation Details Request Control\",\n            \"criticality\": false\n        }\n    ]\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/directory/v1/{{dn}}/changePassword")!,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

{
    "_links": {
        "entry": {
            "href": "https://localhost:1443/directory/v1/uid=jimbob,ou=People,dc=example,dc=com"
        }
    },
    "resultCode": {
        "value": 0,
        "name": "success"
    },
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.41",
            "control-name": "Password Validation Details Response Control",
            "criticality": false,
            "value-json": {
                "response-type": "validation-performed",
                "validation-details": [
                    {
                        "password-quality-requirement": {
                            "description": "The new password must not be the same as the current password.",
                            "client-side-validation-type": "not-current-password"
                        },
                        "requirement-satisfied": true
                    }
                ],
                "missing-current-password": false,
                "must-change-password": false
            }
        }
    ]
}

PingDirectory API Reference

Password Modify

Headers

Body

Example Request

Example Response