Copyright © Cloud Software Group, Inc. All Rights Reserved

Creating a Domain that Integrates with an LDAP Directory Server

Certain configuration information such as LDAP directory server connection search parameters and synchronization parameters must be specified when using Domain Utility to create an administration domain. These can be set at installation when creating the initial domain, or later when creating or modifying an administration domain.

After creating an administration domain that is integrated with an LDAP directory server, you cannot change the same administration domain to be a non-LDAP domain. You must create a new administration domain that does not integrate with an LDAP directory server.

You can integrate an existing domain with an LDAP directory server or modify an administration domain that uses an LDAP directory server by invoking Domain Utility and selecting the Server Setting category, then selecting the LDAP Configuration task. See Changing a Domain’s Integration With an LDAP Directory Server for details.

 

Working With User and Group Filters

When defining search criteria for retrieving users, groups or both from the LDAP server, you can create multiple search filters and test the search parameters before creating the domain.

The valid LDAP users that will appear in the TIBCO Administrator GUI and that can log into any TIBCO application are determined by the user filter. The valid LDAP groups that will appear as group synchronized roles in the TIBCO Administrator GUI are determined by the group filter. Group membership is limited by the user filter. This means that if a valid LDAP group contains users in its membership that are not valid based on a user filter, those users will not display in the corresponding group-synchronized role in the TIBCO Administrator GUI.

An LDAP user is a valid user if it meets any of the user filter conditions. Similarly an LDAP group is a valid group if it meets any of the group filter conditions. There is no correlation between group filter and a user filter within a set. The filters are separate, one for groups and one for users. This allows you to omit a filter in any filter set as long as there is at least one set where a user filter is specified.

If you are using Microsoft Active Directory server, there is a limit on the number of entries that can be retrieved. For information about how to manage the limit, see Searching and Active Directory Server in the TIBCO Administrator User’s Guide.

Viewing Calls Made to the LDAP Server

Information about the calls made to the LDAP server is logged in the LDAP server’s log files and can be logged in the TIBCO_TRA_DOMAIN_HOME\domain-name\logs\administrator.log file.

To log the calls in the administrator.log file, you must first edit the TIBCO_TRA_DOMAIN_HOME\domain-name\AuthorizationDomain.properties file) by setting LogDebug=true. Debug statements such as "... searchLDAP ..." will then appear in the administrator.log file.

To Create an LDAP Based Domain Using the GUI

To create an administration domain that uses LDAP users and groups:

1.	Start Domain Utility and click the Next button on the main screen.

2.	Under Category, click Domain Configuration, then click Create a new Administration Domain.

3.	Click Next and in the screen that appears, provide a name for the administration domain in Administration Domain. See Domain Details for information about the fields that display.

4.

To use TIBCO Enterprise Message Service as the transport for the domain, click Show Advanced and select TIBCO EMS. Provide values for connecting to the Enterprise Message Service server in the TIBCO EMS parameters for TIBCO Administrator panel. To use TIBCO Rendezvous as the transport, no action is necessary as Rendezvous is the default transport choice.

5.	As shown next, Select User and Group information retrieved from a corporate LDAP.

Figure 3 Administrator Configuration

6.	Click Next and, if necessary, change the values for the web server ports. In most cases, its best to accept the default settings. See Web Server Ports.

7.	Click Next and provide the administrator credentials for the administration domain. Note that these credentials are for TIBCO Administrator, not for the LDAP directory server.

8.	Click Next and in the screen that appears provide the LDAP connection information, search parameters and synchronization information. See LDAP Configuration Fields for a description of these values.

Figure 4 Corporate LDAP for Users and Groups

9.	Click Next to display a summary page where you can verify the parameters.

10.	Click Next to create the domain. After creating the domain, start the required services that are listed in the dialog.

11.	Click Finish to end the session.

To Create an LDAP Based Domain Using the Command Line Utility

1.	Create a working directory that will hold the XML file that defines configuration options.

2.	Copy the following file to your working directory: TRA_HOME\template\domainutility\cmdline\CreateDomain.xml

3.	Open CreateDomain.xml in a text editor.

The CreateDomain.xml file contains sections for creating a domain that uses a repository, LDAP server, and database. Change only the LDAP server section and make sure that the LDAP server section is not commented out. The parameters for a domain that integrates with an LDAP server are explained in the following section. After changing the parameters, save the file and exit the text editor.

4.	Execute the following command to apply your changes to the domain:

   domainutilitycmd -cmdFile working-dir-path\CreateDomain.xml

LDAP Configuration Fields

Certain LDAP settings can cause your administration server to crash at runtime. See LDAP Settings Cause the Administration Server to Crash for more information.

 

Table 17 LDAP Configuration Fields

LDAP Connection
LDAP URL	Provide the hostname and port used to connect to your corporate LDAP. The hostname can be a name or an IP address. For example, ldap://directory.acme.com:389
Bind DN and Bind Password	Enter the full distinguished name of the entry with which you want to log into the LDAP directory server. For example, cn=directory manager. TIBCO Administrator and other services in the administration domain will connect to the LDAP server with these administrator credentials. The administrator should have read access to all user and group entries within the LDAP directory. If no value is given in the Bind Password fields, an anonymous login into the LDAP directory server is assumed. The behavior for an anonymous login varies depending on the LDAP directory server vendor. For example, in case of Novell, an anonymous user does not have read access to much of the LDAP tree and, while the test connection may succeed, the search parameters test will fail. On the other hand, in case of the Sun ONE Directory server, anonymous login is provided with read access to the complete tree by default. Again, the defaults for an anonymous login may have been changed in your installation, and therefore it is not advisable to use anonymous login. The Bind DN provided can be an LDAP user that has only read access to LDAP. The user needs permission to: • Read LDAP user objects • Read LDAP group objects • Authenticate other users to LDAP (that is, call the LDAP authenticate API or have read access to password/credentials of LDAP user objects).
LDAP Authentication	Set the authentication type that is accepted by your LDAP directory server. The values are Simple and SSL. If using simple authentication, the Bind DN and Bind password (in clear text) is sent to the LDAP directory server. If using SSL, see Configuring LDAP Integration With SSL Connections for more information and additional configuration steps.
Maximum Pool Size	Set the maximum pool size for a Directory Server (LDAP) connection pool. The default maximum pool size uses a maximum of 20 connections.
Dereference Aliases	Select the check box to dereference aliases, or clear it to not dereference aliases. By default, references are not dereferenced. Aliases point to another object in a namespace. The alias contains the DN of the object to which it is pointing. When you look up an object by using the alias, the alias is dereferenced so that what is returned is the object pointed to by the alias's DN. Note that Sun ONE Directory Server does not support alias dereferencing.
Use NetBIOS Domain-based Names	If using Microsoft Active Directory with multiple domains and if users exist with the same name across the different domains, select this option. With this option selected, users will be displayed in the TIBCO Administrator GUI with names in NetBIOS format (for example, acme_la\jsmith). Group synchronized roles will also be created and displayed in NetBIOS format (for example, acme_la\Human Resources). Note that if you change this field after the administration domain has been created, all existing user profiles will be deleted. This occurs if the flag was originally selected and then cleared, or originally cleared and then selected.
Add Referral LDAP Bind Information	An LDAP server might not store the entire Directory Information Tree (DIT). Servers can be linked together to form a distributed directory that contains the entire DIT. This is accomplished with help of server-side chaining or client-side referrals. The referral acts like a pointer that can be followed to where the desired information is stored. In case where your LDAP directory server is distributed using client-side referrals, you must specify the bind information for each of the referred LDAP directories. Note: You cannot use LDAP referral if you are using CA Directory Server as your LDAP server. When selected, the Referral LDAP form appears. Click the Add button to configure the referral LDAP bind information with an LDAP URL, Bind DN and Bind Password. The connection to each referral LDAP directory server can be tested. One or more bind information referrals to LDAP directories can be added. Note that you need not specify the bind information for referral LDAP directories that have the same bind information as the primary LDAP directory. You can limit the maximum number of referral hops that TIBCO applications and services should follow by setting the number in the Maximum Referral Hops field. This helps to avoid indefinite queries when cyclic referrals are present in LDAP directories. The referrals in LDAP (in case of Sun Java System Directory Server) must be specified correctly, that is, the attribute name and value of the referral entry be specified the same as that of the target DN. Otherwise, the group synchronized role for the groups from referral LDAP will provide correct membership information.
	On Active Directory 2003, the following message may appear after adding a referral: LDAPConnection.checkSearchMsg: ignoring bad referral message If this message appears, you must set the following entries in your DNS server to point to the domain controller running the Active Directory server for the respective domains. This allows TIBCO applications and services, such as TIBCO Administrator when run on a machine of its own, to resolve the entire listed domain names through its designated DNS server. (In most cases the IT department in your organization that manages the Active Directory domains have already set it up correctly.) • DomainDnsZones.domain • ForestDnsZones.domain • domain Where domain is the domain of the domain controller, such as acme.com or la.acme.com. Refer to this article on MSDN: KCC Error Event 1567 Occurs When You Install DNS on a Windows Server 2003-Based Domain Controller (http://support.microsoft.com/default.aspx?scid=kb;en-us;813484). Note that if you connect to Global Catalog Server (port 3268) instead of Active Directory server (port 389), there are no referrals and there is no need to provided referral configuration in your administration domain.
Test Connection	Connects to the LDAP server using the connection parameters you supplied. A dialog displays, indicating success or failure.
Search Parameters and Attributes
Vendor (provides defaults)	Click the arrow to display a popup window where you can select your LDAP vendor. This will reset the search parameters and search attributes with selected vendor defaults. Note that any search parameters added earlier will disappear, and all custom search attributes specified earlier will disappear. Note: If you select CA Directory Server, note that it does not support LDAP referral. Note also that TIBCO PortalBuilder™ does not support CA Directory Server.
Add Remove Edit	This allows you to add, edit or remove the search criteria for retrieving users, groups or both from the LDAP server. Click Add to display the search parameters dialog where you can define search criteria for users and groups. You can select the vendor for your LDAP directory server from the drop-down list to populate the fields with common values. This will reset the search parameters and search attributes with selected vendor defaults. Note that any search parameters added earlier will disappear, and all custom search attributes specified earlier will disappear. When you write a search filter, you must provide a Base DN value as shown next. Using the defaults for the user and group search filters, all users and groups are returned. Base DN: dc=na,dc=tibco,dc=com User Search Filter: objectclass=person Group Search Filter: objectclass=groupofuniquenames You can specify a user search filter and only users that have the specified attribute are returned. For example, the following returns only users that have the ProductManager attribute assigned. Base DN: dc=na,dc=tibco,dc=com User Search Filter: (&(objectclass=person)(manager=ProductManager)) Group Search Filter: objectclass=groupofuniquenames You can specify a user and group filter and only users that have that attribute and groups that match the filter will be returned: Base DN: dc=na,dc=tibco,dc=com User Search Filter: (&(objectclass=person)(manager=ProductManager)) Group Search Filter: (&(objectclass=groupofuniquenames)(cn=TEAK*))
User Name Attribute	Provide the LDAP attribute name that represents the user name in the LDAP directory server. For example, uid for the Sun ONE Directory server.
Group Name Attribute	Provide the LDAP attribute name that represents the group name in the LDAP directory server. For example, cn for the Sun ONE Directory server.
Group Membership Attribute	Provide the LDAP attribute that represents the group membership attribute in the LDAP directory server. The value for this attribute lists the DN for all the static group members. For example, uniquemember for the Sun ONE Directory server.
Group Member URL Attribute	Provide the LDAP attribute name that identifies the dynamic group URL in the LDAP directory server. The value for attribute lists the URL to compute all the dynamic group members. For example, memberurl for the Sun ONE Directory server.
Use Optimistic User Membership	For both dynamic and periodic synchronization, this option is available to improve performance. This parameter is valid for LDAP directory servers with or without referrals. The parameter is only relevant when Microsoft Active Directory is used as the LDAP directory server. The membership list of an LDAP group contains users, other groups (called sub groups) and potentially other LDAP entry types such as computers or networks. The group membership list does not distinguish members and only stores the DN for each of these entries. While computing the entire group membership, TIBCO applications and services must distinguish among the entries in the membership list. The sub group entries in the list are identified by their DNs, but for other entries the application must individually retrieve the LDAP entry for each DN. This is potentially a performance issue. If the optimistic option is used, TIBCO applications and services assume that all entries that are not sub groups are valid users, and does not query the LDAP directory server. Using the optimistic option reduces the number of queries, and thus improves performance. If LDAP entries for users do not contain their user name as part of the DN, the optimistic option is useless, since individual entries must still be retrieved to obtain user names. Before using this option, you must ensure that the following are true (otherwise unpredictable results may occur): • The static membership list of any group in the LDAP directory server contains only sub-groups and valid (existent) users. If it contains other types of items such as computers or networks, the algorithm will work only if there are no users in the LDAP directory server that have the same name as any of these other items. • The static membership lists contain only users that are integrated based on user search filters specified in the LDAP setting for the administration domain. The static membership lists do not contain users that are unreachable because of LDAP referrals for which credentials are either not provided or are provided incorrectly. • The static membership lists do not contain members that are aliases of unreachable users or sub groups.
Compute Group Hierarchy by Loading Membership	Use this option to improve performance when synchronizing with an LDAP server that contains a large number of static groups. When this checkbox is cleared, the administration server computes the group hierarchy by making a separate LDAP query to find the parent group of each group. When it is selected, the administration server loads the entire group hierarchy from the LDAP server and uses it to compute each group’s parent group.
Test Search	Click to validate the search parameters you have supplied.
Synchronization Parameters	TIBCO Administrator synchronizes LDAP groups into group-synchronized roles in the domain. In addition, TIBCO applications and services authenticate users through the LDAP directory and query the LDAP directory server for group membership, users and user corporate properties.
Automatically create Roles for each Corporate Group	Select this check box to allow TIBCO Administrator to automatically synchronize LDAP groups and create roles for these in TIBCO Administration domain. Group-synchronized roles are created only for only those groups that match the search filter specified. This synchronization is repeated at intervals specified in the Synchronization Interval. Note that the groups that are synchronized can be further limited. This can be performed by manually selecting them via the Select LDAP Groups screen in the TIBCO Administrator GUI after creating this domain. If you do not set this option, you can still perform synchronization manually in the TIBCO Administrator GUI or by using the CorpRoleSynchronizer command line utility. See the TIBCO Administrator User’s Guide for more information.
Synchronization Interval	This interval determines when the administration server queries the LDAP directory to discover changes in the directory’s group list or group hierarchy. If groups have been added to or removed from the LDAP directory, or sub groups added to or removed from groups, the administration server makes corresponding changes to the role list and role hierarchies it maintains. The interval specified in this field sets the amount of time to expire before the administration server queries the LDAP directory server to discover changes. For example, if the time is set to 12 hours, synchronization occurs in 12 hour cycles. Changes are written to the administration domain repository. Note: To ensure that LDAP synchronizations happen at the same time(s) each day, specify an interval that is divisible by 24 hours.
Synchronization Time of Day	Use this field to dictate a specific time that LDAP synchronization happens. The time you specify will be the time that the administration server synchronizes with the LDAP server after it starts up the first time. After the first LDAP synchronization, the time interval you specify in Synchronization Interval determines the time of the next LDAP synchronization.
Corporate User Expiration Interval	When a TIBCO application or service needs to • search for valid users, • get user properties, or • get membership of a group synchronized role, it makes a request to the LDAP directory server. These queries are made on demand and the results are cached in the application’s or service’s memory. It remains in memory for some time and then this cache is cleared in order to avoid caching stale information. This interval specifies the time until this information is expired or cleared. For example, if the interval is set for 10 minutes, the TIBCO application or service’s cache is cleared in 10-minute cycles. The amount of time query results persist in memory depends on when it was launched in respect to the cycle. Q1 stays in memory longer than Q2 because Q1 was launched earlier than Q2. When the 10 minute cycle repeats, the cache is cleared and Q1 and Q2 are removed from the application or service’s memory. The interval is normally (much) shorter than the Synchronization Interval. Note: To ensure that cached corporate users expire at the same time (s) each day, specify an interval that is divisible by 24 hours.
Corporate User Expiration Time of Day	Use this field to dictate a specific time that the cached corporate users in memory expire (see above). The time you specify will be the time that the administration server expires cached corporate users in memory after it starts up the first time. After the first expiration, the time interval you specify in Corporate User Expiration Interval determines the time of the next expiration of cached corporate users. See also Time of Day for Expiry Parameter as described next.

Time of Day for Expiry Parameter

For Administration Domains integrated with Corporate LDAP, group memberships and user LDAP properties are retrieved from LDAP and cached in memory when required by a TIBCO Runtime Agent based application. This information expires at the schedule specified in the Corporate User Expiration Interval field in TIBCO Domain Utility. The schedule is reset automatically at midnight GMT and then proceeds using the interval given in the field. However, performance can be affected if a reset occurs during high traffic times.

You can now control when the schedule is reset with the use of the TimeOfDayForExpiry parameter. Instead of the schedule reset always occurring at midnight GMT, the reset can occur at the time given for the TimeOfDayForExpiry parameter.

The parameter must be specified in the AuthorizationDomain.properties file on each machine where TIBCO Runtime Agent is installed. Applications that use TIBCO Runtime Agent (including TIBCO Administrator) must be restarted after adding the parameter to the file. For example:

TimeOfDayForExpiry=2:00:00 AM EST

The time can be specified in any of these formats:

2:00:00 AM time-zone

2:00:00 AM

2:00 AM

In the case where the time zone is not specified in the parameter, it uses the default time zone of the server where the TIBCO Runtime Agent based application is running. For example:

•	If TimeofDayForExpiry is not set and the Corporate User Expiration Interval is 24 hours, a TIBCO Runtime Agent application cache is cleared at midnight GMT (even if the application server is in some other time zone such as EST).

•	If TimeofDayForExpiry is set to 2:00 AM EST and the Corporate User Expiration Interval is 24 hours, a TIBCO Runtime Agent application cache is cleared at 2:00 AM EST.

•	If TimeofDayForExpiry is not set and the Corporate User Expiration Interval is 4 hours, a TIBCO Runtime Agent application cache is cleared every 4 hours counting from midnight GMT.

(Again it is counted from Midnight GMT, even if the application server is in some other time zone such as EST).

•	If TimeofDayForExpiry is set to 2:00 AM EST and the Corporate User Expiration Interval is 4 hours, a TIBCO Runtime Agent application cache is cleared every 4 hours counting from 2:00 AM EST.

Note that:

•

TimeOfDayForExpiry works with the Corporate User Expiration Interval setting. Even though you can set TimeOfDayForExpiry to a certain time of the day, it can expire at another time of the day too, based on a Corporate User Expiration interval that is shorter than 24 hours as described in examples above.

•	Avoid setting a Corporate User Expiration Interval that is not a factor of 24 hours (for example 5 hours), because that changes the expiry times on each day.

•	TimeOfDayForExpiry does not affect the time of the synchronization process that (only) occurs in the TIBCO Administrator server and that is based on the synchronization interval that automatically creates roles for each LDAP Corporate Group.

•	This feature may require further steps if the products are dependent on TIBCO Runtime Agent such as TIBCO PortalBuilder. Please refer to the specific product documentation for more information.

Copyright © Cloud Software Group, Inc. All Rights Reserved