Using paged SCIM searches

When searching large data sets, the results can be numerous and produce errors about a request matching too many results relative to the lookthrough limit. Paged searches avoid these errors and reduce memory usage.

Before you begin

The paged System for Cross-domain Identity Management (SCIM) searches feature is not available for entry-balanced data sets. To use paged SCIM searches, your SCIM service’s backend servers must be LDAP directory servers.

Complete the following one-time operation. You only need to run the command once per PingDirectoryProxy.

If you’re not sure if you have run the command, you can run it again safely.

$ dsconfig set-request-processor-prop \
--processor-name  <proxying-request-processor>  \
--set supported-control-oid:2.16.840.1.113730.3.4.9 \
--set supported-control-oid:1.2.840.113556.1.4.473

<proxying-request-processor> is the request processor handling the entries targeted by the search.

About this task

The PingDirectoryProxy server does SCIM searches using LDAP requests. After you complete the following steps, the PingDirectoryProxy server creates LDAP requests that include request controls that ask the backend servers to sort and page the search results before returning the results.

These request controls are marked noncritical, meaning that if the backend server can’t page the results, the backend server still returns the results. In this case, the PingDirectoryProxy server handles the sorting and paging itself.

If your SCIM searches result in an error because the request matched too many results, you can avoid the error by using paged searches. For more information, see SCIM 2.0 searches.

For each search:

Steps

Decide your SCIM search.

To get paged results, your search must include at least one of these parameters: startIndex, count, or sortBy.

Example:

Your search might look like the following.
```
https://<proxy-hostname>:<proxy-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending
```
This is the corresponding encoded version.
```
https://<proxy-hostname>:<proxy-port>/scim/v2/Users/?filter=st%20eq%20%22TX%22&sortBy=sn&sortOrder=ascending
```
On your PingDirectoryProxy server, collect some information to use later. To find the SCIM resource type, structural-ldap-objectclass, include-base-dn, and include-filter values, run the following command.
```
$ dsconfig get-scim-resource-type-prop --type-name  <SCIM-resource-type-name>  \
--property structural-ldap-objectclass \
--property include-base-dn \
--property include-filter
```

For each backend server:

Create a Virtual List View (VLV) index for your search using dsconfig create-local-db-vlv-index with the following options.

Option Description

Option	Description
`--index-name`	Names the index.
`--backend-name`	Specifies the name of the local database backend in which to place the index. The default database backend for PingDirectory is userRoot.
`--set base-dn`	Specifies the desired base distinguished name (DN). This value must match the value of the `include-base-dn` property that you found in the previous step.
`--set scope`	Is always `whole-subtree`.
`--set filter`	Specifies the filter. Specify `(objectclass=<name-of-SCIM-resource-type-objectclass>)` where `<name-of-SCIM-resource-type-objectclass>` is the name of the objectclass used by the SCIM resource type property, which you found in the previous step. If the SCIM resource type has the `include-filter` property set, also specify that property value in the filter. For example, if the filter for the objectclass is `(objectclass=inetorgperson)` and the `include-filter` value is `(st=CA)`, specify the `--set filter` argument as `(&(objectclass=inetorgperson)(st=CA))`. Specify the LDAP attributes for all the components of your SCIM search filter. For example, if a mapping SCIM resource type maps the LDAP attribute `st` to the SCIM attribute `address.region` and the SCIM search filter requires that `address.region eq TX`, then this filter must include `(st = TX)` instead of `(address.region = TX)`.
`--set sort-order`	Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by. If the SCIM search doesn’t specify the `sortBy` parameter, specify the sort order as `+entryUUID`.

--index-name

Names the index.

--backend-name

Specifies the name of the local database backend in which to place the index.

The default database backend for PingDirectory is userRoot.

--set base-dn

Specifies the desired base distinguished name (DN). This value must match the value of the include-base-dn property that you found in the previous step.

--set scope

Is always whole-subtree.

--set filter

Specifies the filter.

Specify (objectclass=<name-of-SCIM-resource-type-objectclass>)

where <name-of-SCIM-resource-type-objectclass> is the name of the objectclass used by the SCIM resource type property, which you found in the previous step.

If the SCIM resource type has the include-filter property set, also specify that property value in the filter. For example, if the filter for the objectclass is (objectclass=inetorgperson) and the include-filter value is (st=CA), specify the --set filter argument as (&(objectclass=inetorgperson)(st=CA)).

Specify the LDAP attributes for all the components of your SCIM search filter.

For example, if a mapping SCIM resource type maps the LDAP attribute st to the SCIM attribute address.region and the SCIM search filter requires that address.region eq TX, then this filter must include (st = TX) instead of (address.region = TX).

--set sort-order

Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by.

If the SCIM search doesn’t specify the sortBy parameter, specify the sort order as +entryUUID.

Example:

Each SCIM search that you want to produce paged results must have its own VLV index.

Recall the original, decoded SCIM search, shown here.

https://<proxy-hostname>:<proxy-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending

To create a VLV index for that search, run the following command:

$ dsconfig create-local-db-vlv-index --index-name sn \
--backend-name userRoot --set base-dn:ou=people,dc=example,dc=com \
--set scope:whole-subtree \
--set filter:"(&(objectclass=inetorgperson)(st=TX))" --set sort-order:+sn

Using the command line, stop the server, rebuild the index, start the server, and run the rebuild-index command specifying the base DN and the name of the index.
$ rebuild-index --baseDN <baseDN-value> --index <name-of-index>
Example:
$ stop-server $ rebuild-index --baseDN dc=example,dc=com --index vlv.sn $ start-server

Run your SCIM search filter.

The search can include only the filter you specified with --set filter in the earlier step without the "(objectclass=<name-of-SCIM-resource-type-objectclass>)" portion.

In addition to the Virtual List View request control, PingDirectoryProxy server adds a Server Side request control to the LDAP request. These request controls require certain parameters be set. To satisfy this requirement, PingDirectoryProxy server uses the following parameters.

Parameter Default

Parameter	Default
`startIndex`	1
`count`	The value of the `lookthrough-limit` property of the SCIM resource type being searched. That default is 500.
`sortBy`	entryUUID With this default, the results appear unsorted.
`sortOrder`	ascending

startIndex

count

The value of the lookthrough-limit property of the SCIM resource type being searched. That default is 500.

sortBy

entryUUID

With this default, the results appear unsorted.

sortOrder

ascending

If the client does not provide values for one of the parameters, the search uses the corresponding default value shown in the table.