Directory management APIs

APIs to manage the LDAP directory.

Base path: https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap

Where, <cluster_address> is defined in Foundational service endpoint.

Note:

• 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 decide whether recursive method or TDS/SDS recommended way is used to enable nested search. If the parameter is not provided, its default value will be considered as false. If this parameter is set as true, the TDS/SDS recommended logic will be used for nested search. If this parameter is set as false, the recursive method logic will be used for nested search. For more information, see Enabling LDAP Nested Search.

• From the foundational services version 3.19.9, 3.22, and later, LDAP_USER_SEARCHBASE_LIST parameter is introduced in directory management API to enable custom search base for LDAP user entity through SCIM user APIs. It is an optional parameter. For more information, see Custom search base support for LDAP group and user entity in SCIM group and user APIs.

• From the foundational services versions 3.19.9, 3.21 and later, the following parameters are supported in the Directory management API:

  • LDAP_PAGINGSEARCH: It is an optional parameter. 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 an optional parameter. 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. For more information, see SCIM pagination support for LDAP server.

  • LDAP_GROUP_SEARCHBASE_LIST: It is an optional parameter. You can use LDAP_GROUP_SEARCHBASE_LIST to enable the custom search base on LDAP group entity through SCIM group APIs.

For more information, see Custom search base support for LDAP group and user entity in SCIM group and user APIs.

Creating an 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/onboardDirectory

Command

POST

Command output format

application/json

Note:

• There is a limitation on liberty, that is, the LDAP_USERFILTER and LDAP_GROUPFILTER fields must contain an attribute with =%v value. For example, (cn=%v) for Cloud Pak and Cloud Pak for data login flow to work.

• If you are setting up multiple LDAP connections, you must individually connect to each directory.

• In the curl command, you must use a base64-encoded password in the "LDAP_BINDPASSWORD" parameter. To encode the password, use the following command:

echo -n <password> | base64

Following is an example output:

UGFzc3cwcmQ=

The sample curl command for creating the LDAP connection resembles the following code:

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_GROUP_SEARCHBASE_LIST":["OU=searchbase1,DC=ibmtest,DC=com","OU=searchbase2,DC=ibmtest,DC=com","OU=searchbase3,DC=ibmtest,DC=com"]
   "LDAP_PAGINGSEARCH": "true",
   "LDAP_PAGING_SIZE":"1000"
}'

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

The response resembles the following code:

"8b019a10-daa0-11e7-8dba-bf3c83e12db5"

Get information about an 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

GET

Command output format

application/json

Note:

• There is a limitation on liberty, that is, the LDAP_USERFILTER and LDAP_GROUPFILTER fields must contain an attribute with =%v value. For example, (cn=%v) for Cloud Pak and Cloud Pak login flow to work.

• To get information about an LDAP directory, you must assign the directory as a resource to a team. Only then the team members can use this API to get information about the LDAP directory. For more information about how to assign a resource to a team, see Assign resources to a team. The format of the directory resource CRN is crn:v1:icp:private:iam::::Directory:<ID>, where <ID> is the GUID identifier that is assigned to the connection in the id field.

The sample curl command resembles the following code:

curl -k -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/{ID}"

The response resembles the following code:

{"id":"69452b20-bb3d-11e8-98b2-970b1dcdf410","LDAP_ID":"openldap","LDAP_REALM":"REALM","LDAP_HOST":"corp.abc.com","LDAP_PORT":"389","LDAP_IGNORECASE":"false","LDAP_BASEDN":"dc=ibm,dc=com","LDAP_BINDDN":"cn=admin,dc=ibm,dc=com","LDAP_TYPE":"Custom","LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))","LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))","LDAP_USERIDMAP":"*:uid","LDAP_GROUPIDMAP":"*:cn","LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember","LDAP_URL":"ldap://corp.abc.com:389","LDAP_PROTOCOL":"ldap"}

The CRN for this LDAP directory resource is crn:v1:icp:private:iam::::Directory:69452b20-bb3d-11e8-98b2-970b1dcdf410.

Update an 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 Get information about an LDAP directory.

The sample curl command resembles the following code:

curl -k -X PUT \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/{id}" \
    -d '{
      "LDAP_ID": "openldap",
      "LDAP_URL": "ldap://corp.abc.com:389",
      "LDAP_BASEDN": "dc=ibm,dc=com",
      "LDAP_BINDDN": "cn=admin,dc=ibm,dc=com",
      "LDAP_BINDPASSWORD": "UGFzc3cwcmQ=",
      "LDAP_TYPE": "Custom",
      "LDAP_USERFILTER": "(&(uid=%v)(objectclass=person))",
      "LDAP_GROUPFILTER": "(&(cn=%v)(objectclass=groupOfUniqueNames))",
      "LDAP_USERIDMAP": "*:uid",
      "LDAP_GROUPIDMAP": "*:cn",
      "LDAP_GROUPMEMBERIDMAP": "groupOfUniqueNames:uniquemember"
      "LDAP_GROUP_SEARCHBASE_LIST":["OU=searchbase1,DC=ibmtest,DC=com","OU=searchbase2,DC=ibmtest,DC=com","OU=searchbase3,DC=ibmtest,DC=com"]
      "LDAP_PAGINGSEARCH": "true",
      "LDAP_PAGING_SIZE":"1000"
    }'

The response resembles the following code:

{"id":"e02d78b0-72df-11e8-8d5e-93a06ac1d3fc","LDAP_ID":"openldap","LDAP_REALM":"REALM","LDAP_HOST":"9.37.204.115","LDAP_PORT":"389","LDAP_IGNORECASE":"false","LDAP_BASEDN":"dc=ibm,dc=com","LDAP_BINDDN":"cn=admin,dc=ibm,dc=com","LDAP_TYPE":"Custom","LDAP_USERFILTER":"(&(uid=%v)(objectclass=person))","LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))","LDAP_USERIDMAP":"*:uid","LDAP_GROUPIDMAP":"*:cn","LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniquemember","LDAP_URL":"ldap://corp.abc.com:389","LDAP_PROTOCOL":"ldap"}

List LDAP connections

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/list

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/list'

The response resembles the following code:

[{"id":"8b019a10-daa0-11e7-8dba-bf3c83e12db5","LDAP_ID":"Corp","LDAP_REALM":"REALM","LDAP_HOST":"corp.abc.com","LDAP_PORT":"389","LDAP_BASEDN":"o=ibm.com","LDAP_BINDDN":"","LDAP_BINDPASSWORD":"","LDAP_TYPE":"IBM Tivoli Directory Server","LDAP_USERFILTER":"(&(emailAddress=%v)(objectclass=ePerson))","LDAP_GROUPFILTER":"(&(cn=%v)(objectclass=groupOfUniqueNames))","LDAP_USERIDMAP":"*:emailAddress","LDAP_GROUPIDMAP":"*:cn","LDAP_GROUPMEMBERIDMAP":"groupOfUniqueNames:uniqueMember","LDAP_URL":"ldap://corp.abc.com:389","LDAP_PROTOCOL":"ldap"}]

Delete an LDAP directory

Note: Use this API to delete an LDAP directory when only one LDAP directory is configured.

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/offboardDirectory

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X POST --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/offboardDirectory'

The response resembles the following code:

"Count: 1"

Delete LDAP directory by ID

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/offboardDirectory?id={id}

Command

POST

Command output format

application/json

Note: Use id to update the LDAP directory. To get the id, see Get information about an LDAP directory.

The sample curl command resembles the following code:

curl -k -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/offboardDirectory?id={id}"

The response resembles the following code:

{"count":1}

Search for user groups in your 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}/fetchUserGroups

Command

GET

Command output format

application/json

Note: Use id to update the LDAP directory. To get the id, see Get information about an LDAP directory.

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/{id}/fetchUserGroups?searchString=*sec*"

The response resembles the following code:

[{"cn":"security","dn":"cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com"},{"cn":"cloudSecurity","dn":"cn=cloudSecurity,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com"}]

Search for users in your 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}/fetchUsers

Command

GET

Command output format

application/json

Note: Use id to update the LDAP directory. To get the id, see Get information about an LDAP directory.

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/{id}/fetchUsers?searchString=*test*"

The response resembles the following code:

[{"cn":"TestUser","dn":"uid=BDD150908,c=fr,ou=bluepages,o=ibm.com","userId":"test.user@fr.ibm.com"},{"cn":"test1","dn":"uid=TY11DN554,c=cz,ou=bluepages,o=ibm.com","userId":"test1.user@ibm.com"}]

Import user groups from your 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}/importUserGroups

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X POST --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "baseDN": "cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com" }' "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/fb01b1d0-1fa4-11e8-80d6-15882dd657a0/importUserGroups"

The response resembles the following code:

{"name":"security","directoryId":"fb01b1d0-1fa4-11e8-80d6-15882dd657a0","userGroupDN":"cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com"}

Import users from your 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}/importUser

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X POST --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "baseDN": "uid=testuser,ou=people,dc=ibm,dc=com" }' "https://<cluster_address>/idmgmt/identity/api/v1/directory/ldap/fb01b1d0-1fa4-11e8-80d6-15882dd657a0/importUser"'

The response resembles the following code:

{"userId":"testuser","directoryId":"fb01b1d0-1fa4-11e8-80d6-15882dd657a0","firstName":"TestUser","lastName":"","email":"testuser@ibm.com","lastLogin":"","userBaseDN":"uid=testuser,ou=people,dc=ibm,dc=com","type":"LDAP","_id":"testuser","loopback__model__name":"Users"}