PingDirectory API Reference

Search Using POST with Controls

POST {{apiPath}}/directory/v1/{{dn}}/subtree/search

This POST /directory/v1/{{dn}}/subtree/search adds a _controls property to the requests and responses for the search action. The property is an array of JSON formatted controls that are used to include additional content in LDAP requests and responses. For more information about supported controls, refer to Controls.

The sample shows a search request that includes two controls, a join request control and permit unindexed search request control.

The response body includes an additional _controls property that shows the join result control JSON.

The _controls property is only supported for PingDirectory 9.1 or later.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.9",
            "control-name": "Join Request Control",
            "criticality": false,
            "value-json": {
                "join-rule": {
                    "type": "dn",
                    "source-attribute": "manager"
                },
                "base-dn-type": "use-search-base-dn",
                "require-match": false
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.55",
            "control-name": "Permit Unindexed Search Request Control",
            "criticality": true
        }
    ]
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/directory/v1/{{dn}}/subtree/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.9",
            "control-name": "Join Request Control",
            "criticality": false,
            "value-json": {
                "join-rule": {
                    "type": "dn",
                    "source-attribute": "manager"
                },
                "base-dn-type": "use-search-base-dn",
                "require-match": false
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.55",
            "control-name": "Permit Unindexed Search Request Control",
            "criticality": true
        }
    ]
}'
var options = new RestClientOptions("{{apiPath}}/directory/v1/{{dn}}/subtree/search")
{
  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" +
@"    ""filter"": ""uid eq \""user.68\""""," + "\n" +
@"    ""searchScope"": ""wholeSubtree""," + "\n" +
@"    ""_controls"": [" + "\n" +
@"        {" + "\n" +
@"            ""oid"": ""1.3.6.1.4.1.30221.2.5.9""," + "\n" +
@"            ""control-name"": ""Join Request Control""," + "\n" +
@"            ""criticality"": false," + "\n" +
@"            ""value-json"": {" + "\n" +
@"                ""join-rule"": {" + "\n" +
@"                    ""type"": ""dn""," + "\n" +
@"                    ""source-attribute"": ""manager""" + "\n" +
@"                }," + "\n" +
@"                ""base-dn-type"": ""use-search-base-dn""," + "\n" +
@"                ""require-match"": false" + "\n" +
@"            }" + "\n" +
@"        }," + "\n" +
@"        {" + "\n" +
@"            ""oid"": ""1.3.6.1.4.1.30221.2.5.55""," + "\n" +
@"            ""control-name"": ""Permit Unindexed Search Request Control""," + "\n" +
@"            ""criticality"": true" + "\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}}/subtree/search"
  method := "POST"

  payload := strings.NewReader(`{
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.9",
            "control-name": "Join Request Control",
            "criticality": false,
            "value-json": {
                "join-rule": {
                    "type": "dn",
                    "source-attribute": "manager"
                },
                "base-dn-type": "use-search-base-dn",
                "require-match": false
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.55",
            "control-name": "Permit Unindexed Search Request Control",
            "criticality": 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/{{dn}}/subtree/search HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
        {
            "oid": "1.3.6.1.4.1.30221.2.5.9",
            "control-name": "Join Request Control",
            "criticality": false,
            "value-json": {
                "join-rule": {
                    "type": "dn",
                    "source-attribute": "manager"
                },
                "base-dn-type": "use-search-base-dn",
                "require-match": false
            }
        },
        {
            "oid": "1.3.6.1.4.1.30221.2.5.55",
            "control-name": "Permit Unindexed Search Request Control",
            "criticality": true
        }
    ]
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"filter\": \"uid eq \\\"user.68\\\"\",\n    \"searchScope\": \"wholeSubtree\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.9\",\n            \"control-name\": \"Join Request Control\",\n            \"criticality\": false,\n            \"value-json\": {\n                \"join-rule\": {\n                    \"type\": \"dn\",\n                    \"source-attribute\": \"manager\"\n                },\n                \"base-dn-type\": \"use-search-base-dn\",\n                \"require-match\": false\n            }\n        },\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.55\",\n            \"control-name\": \"Permit Unindexed Search Request Control\",\n            \"criticality\": true\n        }\n    ]\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/directory/v1/{{dn}}/subtree/search")
  .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}}/subtree/search",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.9",
        "control-name": "Join Request Control",
        "criticality": false,
        "value-json": {
          "join-rule": {
            "type": "dn",
            "source-attribute": "manager"
          },
          "base-dn-type": "use-search-base-dn",
          "require-match": false
        }
      },
      {
        "oid": "1.3.6.1.4.1.30221.2.5.55",
        "control-name": "Permit Unindexed Search Request Control",
        "criticality": true
      }
    ]
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/directory/v1/{{dn}}/subtree/search',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "filter": "uid eq \"user.68\"",
    "searchScope": "wholeSubtree",
    "_controls": [
      {
        "oid": "1.3.6.1.4.1.30221.2.5.9",
        "control-name": "Join Request Control",
        "criticality": false,
        "value-json": {
          "join-rule": {
            "type": "dn",
            "source-attribute": "manager"
          },
          "base-dn-type": "use-search-base-dn",
          "require-match": false
        }
      },
      {
        "oid": "1.3.6.1.4.1.30221.2.5.55",
        "control-name": "Permit Unindexed Search Request Control",
        "criticality": true
      }
    ]
  })

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

url = "{{apiPath}}/directory/v1/{{dn}}/subtree/search"

payload = json.dumps({
  "filter": "uid eq \"user.68\"",
  "searchScope": "wholeSubtree",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.9",
      "control-name": "Join Request Control",
      "criticality": False,
      "value-json": {
        "join-rule": {
          "type": "dn",
          "source-attribute": "manager"
        },
        "base-dn-type": "use-search-base-dn",
        "require-match": False
      }
    },
    {
      "oid": "1.3.6.1.4.1.30221.2.5.55",
      "control-name": "Permit Unindexed Search Request Control",
      "criticality": 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/{{dn}}/subtree/search');
$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    "filter": "uid eq \\"user.68\\"",\n    "searchScope": "wholeSubtree",\n    "_controls": [\n        {\n            "oid": "1.3.6.1.4.1.30221.2.5.9",\n            "control-name": "Join Request Control",\n            "criticality": false,\n            "value-json": {\n                "join-rule": {\n                    "type": "dn",\n                    "source-attribute": "manager"\n                },\n                "base-dn-type": "use-search-base-dn",\n                "require-match": false\n            }\n        },\n        {\n            "oid": "1.3.6.1.4.1.30221.2.5.55",\n            "control-name": "Permit Unindexed Search Request Control",\n            "criticality": true\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}}/subtree/search")

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({
  "filter": "uid eq \"user.68\"",
  "searchScope": "wholeSubtree",
  "_controls": [
    {
      "oid": "1.3.6.1.4.1.30221.2.5.9",
      "control-name": "Join Request Control",
      "criticality": false,
      "value-json": {
        "join-rule": {
          "type": "dn",
          "source-attribute": "manager"
        },
        "base-dn-type": "use-search-base-dn",
        "require-match": false
      }
    },
    {
      "oid": "1.3.6.1.4.1.30221.2.5.55",
      "control-name": "Permit Unindexed Search Request Control",
      "criticality": true
    }
  ]
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"filter\": \"uid eq \\\"user.68\\\"\",\n    \"searchScope\": \"wholeSubtree\",\n    \"_controls\": [\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.9\",\n            \"control-name\": \"Join Request Control\",\n            \"criticality\": false,\n            \"value-json\": {\n                \"join-rule\": {\n                    \"type\": \"dn\",\n                    \"source-attribute\": \"manager\"\n                },\n                \"base-dn-type\": \"use-search-base-dn\",\n                \"require-match\": false\n            }\n        },\n        {\n            \"oid\": \"1.3.6.1.4.1.30221.2.5.55\",\n            \"control-name\": \"Permit Unindexed Search Request Control\",\n            \"criticality\": true\n        }\n    ]\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/directory/v1/{{dn}}/subtree/search")!,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": {
        "self": {
            "href": "https://ds.example.com/directory/v1/ou=People,dc=example,dc=com/subtree/search",
            "data": {
                "limit": 100,
                "searchScope": "wholeSubtree",
                "filter": "uid eq \"user.68\""
            }
        }
    },
    "_embedded": {
        "entries": [
            {
                "mail": [
                    "test@test.com",
                    "abc@defg.com"
                ],
                "sn": [
                    "Karwowski"
                ],
                "cn": [
                    "Austin Karwowski"
                ],
                "description": [
                    "8b383262-eb69-43aa-9720-6e8e34796481",
                    "973cf4d6-f871-4ea3-a64e-e26acc93e30d",
                    "847c8ace-4ebc-4f0f-a408-4649e6f51d5b"
                ],
                "uid": [
                    "user.68"
                ],
                "isDirectMemberOf": [
                    "cn=Org-1,ou=Admins,dc=example,dc=com"
                ],
                "isMemberOf": [
                    "cn=Org-1,ou=Admins,dc=example,dc=com"
                ],
                "objectClass": [
                    "top",
                    "person",
                    "organizationalPerson",
                    "inetOrgPerson"
                ],
                "_dn": "uid=user.68,ou=People,dc=example,dc=com",
                "_links": {
                    "schemas": [
                        {
                            "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
                        }
                    ],
                    "self": {
                        "href": "https://ds.example.com/directory/v1/uid=user.68,ou=People,dc=example,dc=com"
                    },
                    "isMemberOf": [
                        {
                            "href": "https://ds.example.com/directory/v1/cn=Org-1,ou=Admins,dc=example,dc=com"
                        }
                    ],
                    "isDirectMemberOf": [
                        {
                            "href": "https://ds.example.com/directory/v1/cn=Org-1,ou=Admins,dc=example,dc=com"
                        }
                    ]
                },
                "_controls": [
                    {
                        "oid": "1.3.6.1.4.1.30221.2.5.9",
                        "control-name": "Join Result Control",
                        "criticality": false,
                        "value-json": {
                            "result-code": 0,
                            "joined-entries": [
                                {
                                    "_dn": "uid=user.67,ou=People,dc=example,dc=com",
                                    "objectClass": [
                                        "top",
                                        "person",
                                        "organizationalPerson",
                                        "inetOrgPerson"
                                    ],
                                    "mail": [
                                        "user.67@example.com"
                                    ],
                                    "initials": [
                                        "KHM"
                                    ],
                                    "homePhone": [
                                        "+1 675 225 0395"
                                    ],
                                    "pager": [
                                        "+1 041 404 4168"
                                    ],
                                    "givenName": [
                                        "Kathlin"
                                    ],
                                    "employeeNumber": [
                                        "67"
                                    ],
                                    "telephoneNumber": [
                                        "+1 170 960 0090"
                                    ],
                                    "mobile": [
                                        "+1 502 609 9004"
                                    ],
                                    "sn": [
                                        "Mymryk"
                                    ],
                                    "cn": [
                                        "Kathlin Mymryk"
                                    ],
                                    "description": [
                                        "This is the description for Kathlin Mymryk."
                                    ],
                                    "street": [
                                        "43172 Lee Street"
                                    ],
                                    "st": [
                                        "SC"
                                    ],
                                    "postalAddress": [
                                        "Kathlin Mymryk$43172 Lee Street$Baton Rouge, SC  73430"
                                    ],
                                    "uid": [
                                        "user.67"
                                    ],
                                    "l": [
                                        "Baton Rouge"
                                    ],
                                    "postalCode": [
                                        "73430"
                                    ],
                                    "title": [
                                        "TheDescriptionForKathlin"
                                    ],
                                    "manager": [
                                        "uid=user.66,ou=People,dc=example,dc=com"
                                    ]
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    },
    "size": 1
}