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
-
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.
-
From the navigation menu, click Identity and access > Identity providers.
-
Click Create Connection. The LDAP connection page is displayed.
-
Select the Server type as
Microsoft Active Directory
. The Nested group search option is enabled. -
Select the Nested group search to enable the nested search for the Microsoft Active Directory.
Enabling Nested search for existing MSAD connection
-
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.
-
From the navigation menu, click Identity and access > Identity providers.
-
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.
-
Select the Nested group search option to enable the nested search for an existing Microsoft Active Directory server.
-
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, theibm-allMembers
operational attribute returns all nested members.ibm-allGroups
: For a given user entry, theibm-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 theibm-allMembers
attribute will return all nested members for a group, andibm-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, theibm-allMembers
attribute will only return all first-level members for a group, andibm-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 theLDAP_NESTEDSEARCH
parameter totrue
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:
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.
- 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.
The 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": "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 huge 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
: TheLDAP_NESTEDSEARCH
parameter in the Directory management API is used to support the nested search feature in SCIM APIs. Set theLDAP_NESTEDSEARCH
parameter totrue
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"
}'