SCIM pagination support for LDAP server

From the foundational services version 3.21 and newer, the server-side pagination is supported for the LDAP. The pagination feature in the LDAP server allows you to access the large results sets when there is a server-side administrative limit to the number of entries returned from a query.

The supported LDAP types in your product cluster enforce the page size limits upon the results that are returned from the LDAP in the SCIM user/group API call. The supported LDAP types in your product cluster with their corresponding default page size limit:

For example, in Microsoft Active Directory, the default page size limit is 1000. It means, the default number of entries that are returned in a single request is, 1000. If you send the request to retrieve more than 1000 entries, the LDAP server returns the LDAP_SIZELIMIT_EXCEEDED error. To avoid the LDAP_SIZELIMIT_EXCEEDED error in the foundational services version 3.20 and earlier, the entry request in your query should be less than or equal to 1000.

Similarly, for other LDAPs server, if the number of entries in your request exceeds the default page size limit of the LDAP server, the server displays the LDAP_SIZELIMIT_EXCEEDED error. To overcome this page size limit of LDAP server, the SCIM pagination option is introduced with the foundational services version 3.21 and later. The pagination option for LDAP server is applicable for the SCIM APIs. This option enables you to retrieve the result of your query even if your LDAP entry request is beyond the default page size limit of the LDAP server.

Enabling pagination option for LDAP server

By default, the SCIM pagination option for the LDAP server is disabled. You can enable the pagination option by using the Directory management API. For now, you can enable pagination option through the APIs only.

The Directory management API is enhanced with the following parameters to support the server-side pagination option for LDAP:

• LDAP_PAGINGSEARCH: If the LDAP_PAGINGSEARCH parameter is set as "false", it indicates that the pagination option is disabled. Set this parameter to "true" to enable the pagination option.

• LDAP_PAGING_SIZE: It is a numeric field that defines the page size of the LDAP type. You can set the number as per your requirement. It is an optional field. If you do not provide the value to the LDAP_PAGING_SIZE parameter, the default page size of the LDAP server will be considered as a request in the API query. For example, when the LDAP type is Microsoft Active Directory (MSAD) and you do not provide the LDAP_PAGING_SIZE value in the API, then 1000 (default page size) value will be considered as a request in the API. Also, the LDAP_PAGING_SIZE value should not exceed the default server side page limit or the maximum configured value for the respective LDAP type.

Note:

• The IAM supports LDAP user and group search through SCIM APIs and LDAP APIs. However, the pagination option for the LDAP server is applicable for the SCIM APIs only.

• You can configure the server-side pagination option for each LDAP type.

• LDAP_PAGINGSEARCH and LDAP_PAGING_SIZE parameters are optional in the Directory management API. Include these parameters in the API as per your requirement.

Procedure

The following example to enable the pagination and set the page size while creating an LDAP connection through the directory management API:

Before you begin: Ensure that you are informed about the other LDAP configuration parameters that are used in the Directory management APIs. For more information, see LDAP authentication, LDAP filters and Default LDAP filters by LDAP type.

Prerequisites: The LDAP server must have bind dn and bind password, otherwise you might get InsufficientAccessRightsError while performing the SCIM APIs query. You must use the admin bind dn and bind password while configuring the LDAP connection. If you use the non-admin bind dn and bind password, enable the non-admin page search option in the underlying LDAP server. For example, in IBM Tivoli Directory Server, the conf file attribute, ibm-slapdPagedResAllowNonAdmin(boolean) should be enabled. This file attribute decides that whether the non-admin binds are allowed to perform page search.

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/directory/ldap/onboardDirectory

Command

POST

Command output format

application/json

  curl -k -X POST 'https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/onboardDirectory' 
  --header "Authorization: bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json'
  -d 
  '{
   "LDAP_ID": "msad",
   "LDAP_URL": "ldap://corp.abc.com:389", 
   "LDAP_BASEDN": "DC=ibmtest,DC=com", 
   "LDAP_BINDDN": "CN=Administrator,cn=Users,DC=ibmtest,DC=com", 
   "LDAP_BINDPASSWORD": "password in base64 encoded", 
   "LDAP_TYPE": "Microsoft Active Directory", 
   "LDAP_USERFILTER": "(&(sAMAccountName=%v)(objectclass=person))", 
   "LDAP_GROUPFILTER": "(&(cn=%v)(objectcategory=group))", 
   "LDAP_USERIDMAP": "user:sAMAccountName",
   "LDAP_GROUPIDMAP":"*:cn", 
   "LDAP_GROUPMEMBERIDMAP": "memberOf:member"
   "LDAP_PAGINGSEARCH": "true",
   "LDAP_PAGING_SIZE":"1000"
  }'

To use the LDAP directory management APIs, you need to get the host details, and the base64-encoded password for the "LDAP_BINDPASSWORD" parameter. For more information, see Creating an LDAP connection.

By using Directory management API, you can also enable pagination option and set the page size while updating the existing LDAP directory. For more information, see Update an LDAP directory.