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 also reduce memory utilization.
The paged 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 and you must use the LDAP store adapter.
Complete the following one-time operations. For either command, you only need to run the command one time per backend server. If you are not sure whether you have run the command, you can run it again safely.
- Set the service account’s permissions by running the
prepare-external-storecommand on the PingAuthorize server for each backend server.Note:For example:
If you have run this command with PingDataGovernance 22.214.171.124 or earlier, run it again using the command from a PingDataGovernance 126.96.36.199 or a PingAuthorize 188.8.131.52 or later release.
$ prepare-external-store --hostname server.example.com --port 1389 \ --bindDN "cn=Directory Manager" --bindPassword <password1> \ --governanceBindDN "cn=Authorize User,cn=Root DNs,cn=config" \ --governanceBindPassword <password2> \ --userStoreBaseDN ou=people,dc=example,dc=com
- If your LDAP store adapter points to a PingDirectoryProxy server, run the following command on
$ dsconfig set-request-processor-prop \ --processor-name <proxying-request-processor> \ --set supported-control-oid:2.16.840.1.1137184.108.40.206 \ --set supported-control-oid:1.2.840.1135220.127.116.113
<proxying-request-processor>is the request processor handling the entries targeted by the search.
PingAuthorize performs SCIM searches using LDAP requests. After you complete the steps below, PingAuthorize creates LDAP requests that include request controls asking 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 cannot page the results, the backend server still returns the results. In this case, PingAuthorize handles the sorting and paging itself.
If your SCIM searches result in an error because the request matched too many results, as discussed in Lookthrough limit for SCIM searches, you can avoid the error by using paged searches.
Complete the following steps for each search:
Decide your SCIM search.
Note: To get paged results, your search must include at least one of these parameters: startIndex, count, or sortBy.For example, your search might look like the following:
https://<pingauthorize-hostname>:<pingauthorize-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascendingHere is the corresponding encoded version:
On your PingAuthorize Server, collect some information to use later.
Given a SCIM resource type that you want to search for, find the
primary LDAP store adapter that the SCIM resource type uses by looking
Find the corresponding adapter by running the following command:
$ dsconfig list-store-adapters
include-filtervalues for the adapter by running the following command:
$ dsconfig get-store-adapter-prop --adapter-name <name-of-store-adapter> \ --property structural-ldap-objectclass \ --property include-base-dn \ --property include-filter
- Given a SCIM resource type that you want to search for, find the primary LDAP store adapter that the SCIM resource type uses by looking at its
On each backend server, complete the following steps:
Create a Virtual List View (VLV) index for your search.
Each SCIM search that you want to produce paged results must have its own VLV index.
Create this index using
dsconfig create-local-db-vlv-indexwith the following options.
Names the index.
Specifies the name of the local database backend in which to place the index.
The default database backend for PingDirectory is userRoot.
Specifies the desired base dn. This value must match the value of the
include-base-dnproperty that you found in the previous step.
Specifies the filter.
<name-of-store-adapter-objectclass>is the name of the objectclass used by the adapter, which you found in the previous step.
If the primary LDAP store adapter has the
include-filterproperty set, also specify that property value in the filter. For example, if the filter for the adapter objectclass is
(st=CA), specify the
--set filterargument as
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
stto the SCIM attribute
address.regionand the SCIM search filter requires that
address.region eq TX, then this filter must include
(st = TX)instead of
(address.region = TX).
Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by.If the SCIM search does not specify the
sortByparameter, specify the sort order as
+entryUUID.Recall the original, decoded SCIM search, shown here:
https://<pingauthorize-hostname>:<pingauthorize-port>/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascendingFor example, 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
Stop the server. Rebuild the index. Start the server. Run the
rebuild-indexcommand specifying the baseDN and the name of the index.
$ rebuild-index --baseDN <baseDN-value> --index <name-of-index>For example, run these commands:
$ stop-server $ rebuild-index --baseDN dc=example,dc=com --index vlv.sn $ start-server
- Create a Virtual List View (VLV) index for your search.
Run your SCIM search filter.
The search can include only the filter you specified with
--set filterin the earlier step without the
In addition to the Virtual List View request control, PingAuthorize adds a Server Side request control to the LDAP request. These request controls require certain parameters be set. To satisfy this requirement, PingAuthorize uses the following parameters. If the client does not provide values for one of the parameters, the search uses the corresponding default value shown in the following table.
The value of the
lookthrough-limitproperty of the SCIM resource type being searched. That default is 500.
With this default, the results appear unsorted.