Enabling LDAP Nested Search

Nested search enables the Cloud Pak users to onboard the users or groups that belong to Nested hierarchy in the LDAP tree.

You can enable the nested search for the following:

  • Microsoft Active Directory (MSAD) server
  • Tivoli Directory Server (TDS) and Security Directory Server (SDS)

IMPORTANT: Nested Search can be an expensive operation. If the Nested search is enabled, it can affect the response time.

Nested search for MSAD

You can enable Nested search for Microsoft Active Directory by using the console in the following scenarios:

  • Creating the MSAD connection
  • Editing connection for existing MSAD

Enabling Nested search for MSAD while creating the connection

  1. Log on to the console by using the URL and enter the username and password.

    Note: The console can be Platform UI or Common UI. For more information, see Accessing your cluster by using the console.

  2. From the navigation menu, click Identity and access > Identity providers.

  3. Click Create Connection. The LDAP connection page is displayed.

  4. Select the Server type as Microsoft Active Directory. The Nested group search option is enabled.

  5. Select the Nested group search to enable the nested search for the Microsoft Active Directory.

    Nested Search

Enabling Nested search for existing MSAD connection

  1. Log on to the console by using the URL and enter the username and password.

    Note: The console can be Platform UI or Common UI. For more information, see Accessing your cluster by using the console.

  2. From the navigation menu, click Identity and access > Identity providers.

  3. In the Identity providers page, the name of the MSAD connection is displayed. Select the MSAD connection name to edit and click Edit connection. The Edit your LDAP connection page is displayed.

  4. Select the Nested group search option to enable the nested search for an existing Microsoft Active Directory server.

  5. Click Save.

Nested search support for Tivoli Directory Server (TDS) and Security Directory Server (SDS)

For now, TDS and SDS nested search can only be configured using APIs, not from the product UI. You can enable nested search for Tivoli Directory Server (TDS) and Security Directory Server (SDS) by two ways:

  • TDS or SDS recommended way: From IBM Cloud Pak foundational services version 3.19.9, 3.22, and later, you can enable nested search for TDS/SDS by creating nested group data as per TDS or SDS recommendations.

  • Recursive method: From IBM Cloud Pak foundational services version 3.19.9 and 3.23, IM supports recursive method to enable nested search for TDS/SDS if LDAP nested group data set up is not created as per TDS or SDS recommendations.

IMPORTANT: It is mandatory to use the TDS or SDS recommended way method to enable nested search for TDS/SDS when you have created the LDAP nested group data set up as per TDS or SDS recommendations. In this case, if you use the recursive method, nested group functionality might not work properly.

IMPORTANT: It is mandatory to use the recursive method to enable nested search for TDS/SDS when you have not created the LDAP nested group data set up as per TDS or SDS recommendations. In this case, if you use the TDS or SDS recommended way method, nested group functionality might not work properly.

Tivoli Directory Server (TDS) and Security Directory Server (SDS) recommended way to create Nested group

IMPORTANT: The IBM Cloud Pak foundational services IM will be retrieving the Nested Group members only if data has been created with the TDS or SDS recommended format.

In IBM TDS/SDS LDAP server, a nested group is created by adding the ibm-nestedGroup object class in the group schema. And, the nested child groups must be added using ibm-memberGroup attributes.

The ibm-nestedGroup and ibm-memberGroup attributes must be present in the nested group schema as following:

dn: cn=TeamStaff,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com
cn: TeamStaff
objectClass: groupOfUniqueNames
objectClass: top
objectclass: ibm-nestedGroup
ibm-memberGroup: cn=TeamDoctors,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com
ibm-memberGroup: cn=Coaches,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com

IM uses operational attribute that is provided by TDS/SDS LDAP to query aggregate group membership as following. Ensure that LDAP data is created as per the TDS or SDS recommended format.

  • ibm-allMembers: For a given group entry, the ibm-allMembers operational attribute returns all nested members.
  • ibm-allGroups: For a given user entry, the ibm-allGroups returns all nested groups.

Note:

  • If your data for nested groups is set up as per the TDS recommended way, IBM Cloud Pak foundational services IM will be able to use the ibm-allMembers attribute, and the ibm-allMembers attribute will return all nested members for a group, and ibm-allGroups attribute will return all nested groups for a user.

  • If your data for nested group is not set up as per the TDS recommended way, Nested search feature will not work as expected, means, when IBM Cloud Pak foundational services IM uses the ibm-allMembers attribute, the ibm-allMembers attribute will only return all first-level members for a group, and ibm-allGroups attribute will return only the parent groups for a user.

Enabling Nested search feature in TDS/SDS recommended way by using SCIM API

The following parameters are used in directory management API to enable nested search in TDS/SDS recommended way:

  • The LDAP_NESTEDSEARCH parameter in the directory management API is used to support the nested search feature in SCIM APIs. Set the LDAP_NESTEDSEARCH parameter to true to enable nested search option for TDS/SDS.

  • From IBM Cloud Pak foundational services version 3.19.9 and 3.23,LDAP_TDS_NESTEDCONFIG parameter is introduced in directory management API. The value of this parameter is used to determine that which method (TDS/SDS recommended way or recursive method) is used to enable nested search for TDS/SDS.

    • If this parameter is set as true, the TDS/SDS recommended method will be used for nested search. However, make sure that to use TDS/SDS recommended method, you must create the LDAP nested group data set up as per TDS or SDS recommendations.

    • If this parameter is set as false, the recursive method logic will be used for nested search. Note that if you have not created the LDAP nested group data set up as per TDS or SDS recommendations, you need to use recursive method to enable nested search for TDS/SDS.

    • If the parameter is not provided, its default value will be considered as false, that means by default, recursive method is used to enable nested search.

Note: To use the directory management APIs, you need to get the host details. To get the host details, see Getting host details. And, use the base64-encoded password for the "LDAP_BINDPASSWORD" parameter. To encode the password, use the following command:

echo -n <password> | base64

Following is an example output:
```cmd {: pre}

UGFzc3cwcmQ=

#### Enabling nested search in TDS/SDS recommended way while creating LDAP connection by using the Directory management API

The following API shows how to enable the nested search option in TDS/SDS recommended way while creating an LDAP connection by using the Directory management API. 

<dl>
<dt><b>API version</b></dt>
<dd>1.0.0</dd>
<dt><b>API URI components</b></dt>
<dd>
<dl>
<dt><b>Scheme</b></dt>
<dd><pre>HTTPS</pre></dd>
<dt><b>Host IP</b></dt>
<dd><pre>Cluster Master Host</pre></dd>
<dt><b>Port number</b></dt>
<dd><pre>Cluster Master API Port</pre></dd>
<dt><b>Path</b></dt>
<dd><pre>idmgmt/identity/api/v1/directory/</pre></dd>
<dt><b>Command</b></dt>
<dd><pre>POST</pre></dd>
</dl>
</dd>
<dt><b>Command output format</b></dt>
<dd><pre>application/json</pre></dd>
</dl>

**Note:** For more information about the LDAP parameters, see [Configuring LDAP authentication](configure_ldap.html).

The curl command resembles the following code:

```cmd {: codeblock}
curl -k -X POST \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "content-type: application/json" \
"https://${CP_CONSOLE_URL}/idmgmt/identity/api/v1/directory/" \
-d
'{
  "TYPE": "LDAP",
  "LDAP_ID":"SDS",
  "LDAP_REALM":"SDSRealm",
  "LDAP_HOST":"ip",
  "LDAP_PORT":"389",
  "LDAP_IGNORECASE":"true",
  "LDAP_BASEDN":"dc=ibm,dc=com",
  "LDAP_BINDDN":"cn=admin",
  "LDAP_BINDPASSWORD":"password in base64 encoded",
  "LDAP_TYPE":"IBM SecureWay Directory Server",
  "LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))",
  "LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))",
  "LDAP_USERIDMAP":"*:uid",
  "LDAP_GROUPIDMAP":"*:cn",
  "LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember",
  "LDAP_NESTEDSEARCH": "true"
  "LDAP_TDS_NESTEDCONFIG": "true"
}'

Enabling nested search in TDS/SDS recommended way while updating existing LDAP connection by using the Directory management API

The following API shows how to enable nested search in TDS/SDS recommended way while updating existing LDAP connection.

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/{id}
Command
PUT
Command output format
application/json

Note: Use id to update the LDAP directory. To get the id, see Getting information about all LDAP connections.

The curl command resembles the following code:

curl -k -X PUT \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "content-type: application/json" \
"https://${CP_CONSOLE_URL}/idmgmt/identity/api/v1/directory/ldap/<id>" \

-d
 '{
    "TYPE": "LDAP",
    "LDAP_ID":"SDS",
    "LDAP_REALM":"SDSRealm",
    "LDAP_HOST":"ip",
    "LDAP_PORT":"389",
    "LDAP_IGNORECASE":"true",
    "LDAP_BASEDN":"dc=ibm,dc=com",
    "LDAP_BINDDN":"cn=admin",
    "LDAP_BINDPASSWORD":"password in base64 encoded",
    "LDAP_TYPE":"IBM SecureWay Directory Server",
    "LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))",
    "LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))",
    "LDAP_USERIDMAP":"*:uid",
    "LDAP_GROUPIDMAP":"*:cn",
    "LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember",
    "LDAP_NESTEDSEARCH": "true",
    "LDAP_TDS_NESTEDCONFIG": "true"
  }'

Recursive approach to enable nested search for TDS/SDS

You might have LDAP directories for years and your data set up for nested search might not be as per Tivoli Directory Server (TDS) and Security Directory Server (SDS) recommendations. In such case, from IBM Cloud Pak foundational services version 3.19.9, 3.23, and later, IM supports recursive approach to enable nested search. It is mandatory to use the recursive method for nested search when you have not created the LDAP nested group data set up as per TDS or SDS recommendations. Otherwise, nested group functionality might not work properly.

Enabling recursive method to support nested search for TDS/SDS by using SCIM API

The following parameters are used in directory management API to enable recursive method/logic to support nested search for TDS/SDS:

  • LDAP_NESTEDSEARCH : The LDAP_NESTEDSEARCH parameter in the Directory management API is used to support the nested search feature in SCIM APIs. Set the LDAP_NESTEDSEARCH parameter to true to enable recursive logic for nested search in TDS/SDS.

  • LDAP_TDS_NESTEDCONFIG: From IBM Cloud Pak foundational services version 3.19.9 and 3.23,LDAP_TDS_NESTEDCONFIG parameter is introduced in directory management API. The value of this parameter is used to determine that which method (TDS/SDS recommended way or recursive method) is used to enable nested search for TDS/SDS.

    • If this parameter is set as true, the TDS/SDS recommended method will be used for nested search. However, make sure that to use TDS/SDS recommended method, you must create the LDAP nested group data set up as per TDS or SDS recommendations.

    • If this parameter is set as false, the recursive method logic will be used for nested search. Note that if you have not created the LDAP nested group data set up as per TDS or SDS recommendations, you need to use recursive method to enable nested search for TDS/SDS.

    • If the parameter is not provided, its default value will be considered as false,that means by default, recursive method is used to enable nested search.

Note:

  • For SCIM group API, IM returns only first level members (users and groups) for any groups.

  • For SCIM users API, IM returns all nested groups of any users.

  • To use the directory management APIs, you need to get the host details. To get the host details, see Getting host details. And, use the base64-encoded password for the "LDAP_BINDPASSWORD" parameter. To encode the password, use the following command:

    echo -n <password> | base64

    Following is an example output:

    UGFzc3cwcmQ=

Enabling recursive logic to support nested search for TDS/SDS while creating an LDAP connection

The following API shows how to enable recursive logic for nested search while creating an LDAP connection by using the Directory management API.

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/
Command
POST
Command output format
application/json

Note: For more information about the LDAP parameters, see Configuring LDAP authentication.

Curl command resembles the following code:

curl -k -X POST \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "content-type: application/json" \
"https://${CP_CONSOLE_URL}/idmgmt/identity/api/v1/directory/" \
-d
 '{
    "TYPE": "LDAP",
    "LDAP_ID":"SDS",
    "LDAP_REALM":"SDSRealm",
    "LDAP_HOST":"ip",
    "LDAP_PORT":"389",
    "LDAP_IGNORECASE":"true",
    "LDAP_BASEDN":"dc=ibm,dc=com",
    "LDAP_BINDDN":"cn=admin",
    "LDAP_BINDPASSWORD":"password in base64 encoded",
    "LDAP_TYPE":"IBM SecureWay Directory Server",
    "LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))",
    "LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))",
    "LDAP_USERIDMAP":"*:uid",
    "LDAP_GROUPIDMAP":"*:cn",
    "LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember",
    "LDAP_NESTEDSEARCH": "true",
    "LDAP_TDS_NESTEDCONFIG": "false"
  }'

Enabling recursive logic to support nested search for TDS/SDS while updating the existing LDAP directory

By using Directory management API, you can also enable the Nested search using recursive method while updating the existing LDAP directory.

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/{id}
Command
PUT
Command output format
application/json

Note: Use id to update the LDAP directory. To get the id, see Getting information about all LDAP connections.

Curl command resembles the following code:

 curl -k -X PUT \
 -H "Authorization: Bearer ${ACCESS_TOKEN}" \
 -H "content-type: application/json" \
 "https://${CP_CONSOLE_URL}/idmgmt/identity/api/v1/directory/ldap/<id>" \

 -d
  '{
     "TYPE": "LDAP",
     "LDAP_ID":"SDS",
     "LDAP_REALM":"SDSRealm",
     "LDAP_HOST":"ip",
     "LDAP_PORT":"389",
     "LDAP_IGNORECASE":"true",
     "LDAP_BASEDN":"dc=ibm,dc=com",
     "LDAP_BINDDN":"cn=admin",
     "LDAP_BINDPASSWORD":"password in base64 encoded",
     "LDAP_TYPE":"IBM SecureWay Directory Server",
     "LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))",
     "LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))",
     "LDAP_USERIDMAP":"*:uid",
     "LDAP_GROUPIDMAP":"*:cn",
     "LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember",
     "LDAP_NESTEDSEARCH": "true",
     "LDAP_TDS_NESTEDCONFIG": "false"
   }'