Managing LDAP Directories

About this task

You can manage the LDAP directories in the LDAP directories section. You can view all the LDAP directories configured listed in a table here with their directory URL details. You can create, update, delete and prioritize the LDAP directories here.

To add an LDAP directory

Procedure

Expand the menu options icon , in the title bar, and select User management.
Click LDAP configuration.
In the LDAP directories section, click Add LDAP directory.

Provide the following information to add an LDAP directory.

Field	Description
Directory URL	Specifies the complete URL of the LDAP server. The URL has the format `protocol ://hostname :portnumber`where The `protocol` is LDAP for standard connections or LDAPS for secure connections The `host` is the host name or IP address of the LDAP server. The `port` is the port on which the server is running. The port is optional. If omitted, the port defaults to 389 for LDAP, or 636 for LDAPS For example, specifying the URL `ldaps:// ldapserv1:700` would create a secure connection to the LDAP server running on the non-standard port 700 on the host called ldapserv1. If you specify ldaps, webMethods API Gateway attempts to make a secure connection to the directory server using an SSL socket. If the directory server is configured to use SSL, it has a server certificate in place to identify itself to clients. This certificate must be signed by an authority to prove its validity that is, the server certificate is signed by a CA). By default, webMethods API Gateway only trusts certificates signed by a signing authority whose CA certificate is in the webMethods API Gateway's trusted CAs directory.
Principal	Specifies the user ID webMethods API Gateway should supply to connect to the LDAP server. For example, `o=webm.com` or `dc=webm,dc=com`. This user should not be the Administrator account, but a user that has permission to query groups and group membership. If your LDAP server allows anonymous access, leave this field blank.
Credentials	Specifies the password webMethods API Gateway should supply to connect to the LDAP server, that is, the Principal's password.
Connection timeout (seconds)	Specifies the number of seconds webMethods API Gateway waits while trying to connect to the LDAP server. After this time has passed, webMethods API Gateway tries for the next configured LDAP server on the list. The default is 5 seconds.
Minimum connection pool size	Specifies the minimum number of connections allowed in the pool that webMethods API Gateway maintains for connecting to the LDAP server. When webMethods API Gateway starts, the connection pool initially contains this minimum number of connections. webMethods API Gateway adds connections to the pool as needed until it reaches the maximum allowed, which is specified in the Maximum Connection Pool field. The default value is 0.
Maximum connection pool size	Specifies the maximum number of connections allowed in the pool that webMethods API Gateway maintains for connecting to the LDAP server. When webMethods API Gateway starts, the connection pool initially contains the minimum number of connections as specified in the Minimum Connection Pool field. webMethods API Gateway adds connections to the pool as needed until it reaches the maximum allowed. The default value is 10.
Distinguished Name (DN) method. Specifies the directory name to be built on selecting any of the following criteria.
Synthesize DN	Builds a distinguished name by adding a prefix and suffix to the user name. The Synthesize DN method can be faster than the Query DN method because it does not perform a query against the LDAP directory. However, if your LDAP system does not contain all users in a single flat structure, use the Query DN method instead. DN prefix A string that specifies the beginning of a DN you want to pass to the LDAP server. DN suffix A string that specifies the end of a DN you want to pass to the LDAP server. For example, if the prefix is `cn=` and the suffix is `,ou=Users` and a user logs in specifying `bob`, then webMethods API Gateway builds the DN `cn=bob,ou=Users` and sends it to the LDAP server for authentication. Note: Be sure to specify all the characters required to form a proper DN. For instance, if you omit the comma from the suffix above, that is, you specify `ou=Users` instead of `,ou=Users`, webMethods API Gateway builds an invalid DN `cn=bobou=Users`.
Query DN	Builds a query that searches a specified root directory for the user. Use this method instead of the Synthesize DN method if your LDAP directory has a complex structure. UID property A property that identifies an LDAP userid, such as `"cn"` or `"uid"`. User root DN Provide the full distinguished name. For example, if you specify `ou=users,dc=webMethods,dc=com,` webMethods API Gateway issues a query that starts searching in the root directory `ou=users` for a common name that matches the name the user has logged in with.
User email attribute	Specifies the name of the email attribute in the LDAP directory. The email ID of the webMethods API Gateway's user object is mapped to the value specified in this field . This value depends on the schema of the LDAP directory.
Default group	Specifies the webMethods API Gateway group with which the user is associated. The user is allowed to access APIs that members of this webMethods API Gateway group can access. This access is controlled by the ACLs with which the group is associated. If you also specify a value in the Group member attribute field, the user has the same access as members of the webMethods API Gateway group and members of LDAP groups that have been mapped to an ACL. Note: If you do not want to select a default group, you can select <None> from the options provided.
Group member attribute	Specifies the name of the attribute in a group's directory entry that identifies each member of the group. This value is usually `member` or `uniqueMember`, but can vary depending on the schema of the LDAP directory. webMethods API Gateway uses this information during ACL checking to see if the user attempting to log in belongs to an LDAP group that has been mapped to an ACL. If no value is specified here, webMethods API Gateway does not check for membership in an LDAP group. As a result, the user's ability to access webMethods API Gateway services is controlled by the webMethods API Gateway group specified in the Default group field.
Group ID property	Specifies a property that identifies an LDAP group, such as CN.
Group root DN	Specifies the full distinguished name. For example, if you specify `ou=groups,webMethods,dc=com,` webMethods API Gateway issues a query that displays all the LDAP groups. Note: You must specify values in the Group ID property field and Group root DN fields.

Click Save.

Results

The LDAP directory is added and listed in a table under the LDAP directories section.

Note:

If you define multiple LDAP servers, API Gateway searches the LDAP directories in the order in which they are displayed in the User Management > LDAP directories section. If API Gateway does not find the user in in the first LDAP directory, it searches in order through the list.
If the connection between API Gateway and the LDAP server drops intermittently, and you notice the following exception in the Trace logs, connect to the Global Catalog port (3268/3269) on the LDAP server, instead of using the standard LDAP port (389). For example, ldap://hostname:3268
```
PartialResultException in the trace logs : [ISS.0002.0000T]
[LDAPv2] javax.naming.PartialResultException [Root exception is
javax.naming.CommunicationException:
[Root exception is java.net.SocketTimeoutException: connect timed out]]
```
If the connection issues continue despite using the Global Catalog port (3268/3269), it may be due to the following errors:
- Connection timeout error
- Communication error
- Resource shortage error
- An orphaned domain acts as the Global Catalog

Set appropriate values for the watt.server.ldap.retryCount and watt.server.ldap.retryWait parameters to restore the connection in case of transient errors.

Next Steps:

You can perform the following operations in the LDAP directories section where the configured LDAP directories are listed.

You can update an LDAP directory by clicking on the LDAP directory URL field in the table, modify the details as required and save the changes.
You can prioritize the LDAP directory as required by clicking in the Prioritize column for the corresponding LDAP directory.
You can delete an LDAP directory by clicking the icon in the Delete column for the corresponding LDAP directory.