1 of 7 Abstract MKS Integrity Server LDAP (Lightweight Directory Access Protocol) implementations vary depending on the environment they are being placed into. The configuration of the corporate LDAP implementation at each customer site determines the needs for this authentication schema. However, the best practice for configuring LDAP authentication with the MKS Integrity Server is to pull in the least number of users and groups possible. This allows for quicker startups and easier administration. This document provides information on how to configure LDAP authentication effectively to best fit your current network environment and to meet your needs within the MKS Integrity Suite. It also provides information on some additional configuration techniques and troubleshooting. This document is not intended to be a one size fits all set of practices. Rather it is intended to help customers investigate their options before implementing LDAP authentication. It is also intended to help existing LDAP users tune their configuration to better suit their needs. This document assumes you are familiar with LDAP, its terminology, and various configurations. 2001 2005 MKS Software Inc.; in Canada copyright owned by MKS Inc. All rights reserved. MKS Source Integrity, MKS Integrity Manager, Implementer, MKS Toolkit, Sandbox, N u TCRACKER, MKS Integrity Suite, AlertCentre, MKS Federated Server, and Build Better Software are trademarks or registered trademarks of MKS Inc. All other trademarks or registered trademarks are the property of their respective holders.
2 of 7 1.0 INTRODUCTION Corporate LDAP configurations can be as varied as the companies themselves. Some have an open configuration in which users are separated into job groups, such as developers and human resources. Others have highly granular Organizational Unit (OU) configurations in which users are separated into much more specific groupings. Some have something in between (or completely different from) these two extremes. Even with these differing configurations, the MKS Integrity Server s LDAP capabilities should be able to accommodate the environment. Regardless of your corporate LDAP implementation, you should be able to use one or more strategies listed in this document to limit the number of users and groups pulled by the MKS Integrity Server, thus improving performance within the MKS Integrity environment. Several methods are available that will allow you to achieve optimum performance, including: using multiple.dn lines to pull users/groups from multiple locations in your LDAP tree using the member.scope property to limit the number of subtrees searched using filters to pull users and groups based on Common Name (CN) attributes pulling users from certain groups with the UserEnumeration property This document references the following example LDAP implementation. Note that it is merely an example and does not necessarily recommend the best way to implement an LDAP network environment. com mks waterloo london strategic tactical strategic tactical chicago strategic tactical NOTE All examples in this document make use of Active Directory property lines; however, all strategies and examples in the document should work with other flavors of LDAP authentication. 1.1 Configuring group.dn and user.dn properties The best practice for setting up user and group Distinguished Names (DNs) to pull entities into the MKS Integrity Server s realm is to be as granular as possible while still maintaining a reasonable number of DNs to work with.
3 of 7 Using granular OUs allows the MKS Integrity Server to parse the least number of CNs (specifically users and groups) when starting up and populating user lists. This results in decreased startup times for the MKS Integrity Server, along with better responses for end users in certain views. The best strategy for configuring the DN lines depends on your environment. If you have users and groups in a single, discreet subtree (all MKS users are in the tactical and strategic OUs within the waterloo location), setting up the DN lines is relatively simple: ads.user.dn=ou=waterloo,dc=mks,dc=com ads.group.dn=ou=waterloo,dc=mks,dc=com However, if you have users/groups spread out in several discreet subtrees, you can specify multiple DN lines. You do this by adding.# to the end of the DN property. For example, if you want to pull users and groups from the tactical OUs in the three locations, you would set: ads.user.dn=ou=tactical,ou=waterloo,dc=mks,dc=com ads.user.dn.1=ou=tactical,ou=chicago,dc=mks,dc=com ads.user.dn.2=ou=tactical,ou=london,dc=mks,dc=com ads.group.dn=ou=tactical,ou=waterloo,dc=mks,dc=com ads.group.dn.1=ou=tactical,ou=chicago,dc=mks,dc=com ads.group.dn.2=ou=tactical,ou=london,dc=mks,dc=com The alternative to this setup could be to set the user and group DN lines to point to dc=mks,dc=com,. Such a setup, however, would also pull in users from multiple other OUs that are not needed. This situation could be addressed by filtering (covered later in this document). Regardless, it is always considered best practice to first parse through only the needed DNs, then apply the filters to the users/groups found. This results in quicker response times due to a reduced number of LDAP entities to parse. 1.2 Using member.scope You can set the member.scope property to three values: subtree, one-level, or base. Setting the correct value can further reduce the number of CNs that is parsed. subtree tells the MKS Integrity Server to pull users or groups from the OUs specified in the DN lines, as well as any OUs below. This is useful when users are spread throughout the subtree specified at various levels in the tree, but it provides the least amount of filtering. one-level pulls CNs from the location specified and one level below it. For example, if you specify ads.user.dn=ou=waterloo,dc=mks,dc=com and one-level in the member.scope property, all CNs from the waterloo OU are pulled, but nothing from any OUs below this point. base pulls the DN you specify, but not anything in this level or below it. NOTE Because of its extremely limited scope, base is likely something you should not use in any LDAP implementation. 1.3 Using keywords in LDAP CNs for query filters CNs in LDAP have multiple attributes you can set within the network environment. You can use these attributes (keywords) to filter users pulled into the MKS Integrity Server s realm. This strategy best suits LDAP implementations where users of the MKS Integrity Suite are spread out among many OUs or for further filtering users within OUs specified in your user.dn line(s).
4 of 7 One potential strategy is to set the ads.user.dn line in ldaprealm.properties to a high level OU, then filter the users within the subtree based on an attribute (for example, pull all users with MKS in their description fields). For example, if you have users spread out in various teams at Waterloo and Chicago locations, you may want to make use of this strategy. The network administrator could add MKS to the description of all MKS Integrity Suite users within the corporate LDAP domain and use this to filter users being pulled into the MKS Integrity Server s realm. For example: ads.user.dn=dc=mks,dc=com ads.user.filter=(&(cn=%u)(objectclass=user)(objectcategory=person) (description=*mks*)) NOTE This strategy involves a certain degree of administration overhead. Whenever new users are added to the corporate LDAP environment, the network administrator needs to remember to add the appropriate attribute to the users in question. Otherwise, the MKS Integrity Server s filters will not picked them up. 1.4 Using mksis.usersenumeration property to filter users based on groups You can use the mksis.usersenumeration property (found in the security.properties file) to pull users into the MKS Integrity Server s realm based on a group or multiple groups. This property is best used if you locate users in a small number of groups, but spread out among multiple OUs within your corporate LDAP environment. This property is different from the ones found in the ldaprealm.properties file as it mainly affects users that appear in dropdowns, such as in ACL administration. It does not remove users from the MKS Integrity Suite, which is handled by filters in the ldaprealm.properties file. Users not enumerated by the usersenumeration property can still log in to the MKS Integrity Server. For example, if you have set up ldaprealm.properties to pull users from the Chicago OU, but would like to further filter users in certain views to only users that are in the Seniors group, you would set: mksis.usersenumeration=seniors 2.0 SUMMARY It is a best practice for any MKS Integrity Suite LDAP implementation to limit the number of users/groups that are pulled from the LDAP server. You can accomplish this within your MKS Integrity Server properties by: using multiple.dn lines to pull users/groups from multiple locations in your LDAP tree using the member.scope property to limit the number of subtrees searched making use of filters to pull users and groups based on CN attributes pulling users from certain groups with the UserEnumeration property You can use these techniques individually or in combination to help limit the entities pulled into the MKS Integrity Server s realm to increase performance within your implementation.
5 of 7 APPENDIX A: ADDITIONAL CONFIGURATION TECHNIQUES This appendix provides additional LDAP configuration techniques that do not fall into the category of best practices; however, they are techniques that administrators may be interested in implementing in their environments. Using fields other than CN for authentication Some organizations use fields other than the CN, such as samaccountname in Active Directory, for authenticating users to the corporate network. You can configure the MKS Integrity Server to do the same. To set this up, simply change the.user.filter and.user.name fields to incorporate the field that you would like to use. For example, if you want to have users authenticate using their samaccountname, you would set: ads.user.filter=(&( samaccountname =%u)(objectclass=user)(objectcategory=person)) ads.user.name=samaccountname To use a field called EmployeeID, you would set: ads.user.filter=(&( EmployeeID=%u)(objectclass=user)(objectcategory=person)) ads.user.name=employeeid NOTE Make sure your.filter line contains the same field as your.name line (as indicated in the examples above). Additionally, you can have users authenticate using one user name (for example, EmployeeID) and have the MKS Integrity Suite display them as another user name (for example, full name). To do this, you simply change ads.user.displayname=displayname to the CN attribute field you would like users to be displayed as. Connecting to multiple LDAP servers If you have multiple LDAP servers that are the children of a common domain (for example, x.mks.com and y.mks.com), you can pull users and groups from both locations. You do this by adding.1 after the three server connection lines (you can add more by incrementing the number that is appended), for example: ads.server.host=x.mks.com ads.server.principal=cn=mksuserx,ou=serviceaccts,dc=x,dc=mks,dc=com ads.server.credential=*secret* ads.server.host.1=y.mks.com ads.server.principal.1=cn=mksusery,ou=serviceaccts,dc=y,dc=mks,dc=com ads.server.credential.1=*secret*
6 of 7 APPENDIX B: TROUBLESHOOTING Several methods are available for troubleshooting LDAP configurations: The weblogic.log file, with logging turned up, allows you to see users as they are pulled into the realm. The weblogicerr.log file logs information if an MKS Integrity Server fails to start because of LDAP issues. The AdminRealm page allows you to see users and groups the same as the Integrity Server sees them. Weblogic.log The weblogic.log file is a valuable tool for troubleshooting LDAP issues. With default logging levels enabled, the log file does not capture much LDAP information; however, you can increase the level of LDAP logging by adding the following lines to the weblogic.properties file: java.system.property.weblogic.security.ldaprealm.verbose=true weblogic.security.realm.debug=true With these two lines in place, your weblogic.log shows the calls the MKS Integrity Server makes to your LDAP environment. This is useful during server startup because it shows every user pulled from the LDAP environment into the MKS Integrity Server s realm. NOTE You should remove these settings after troubleshooting because the increased logging may impact the performance of the MKS Integrity Server. For more information about logging with the MKS Integrity Server, see the MKS Integrity Server 2005 Administration Guide. Weblogicerr.log/stderr If the MKS Integrity Server fails to start up due to an LDAP problem, the weblogic.log file will not likely tell you what the issue is. Quite often the weblogic.log file stops at the lines: <Date> Users will be taken from Scheme ldap_clear by default <Date> Groups will be taken from Scheme ldap_clear by default and the MKS Integrity Server process stops. However, quite often the weblogicerr.log file (located in the root of the MKS Integrity Server installation directory) or stderr (on UNIX) captures the cause of the failure. AdminRealm Page The AdminRealm page displays the users and groups pulled into the MKS Integrity Server s realm, along with ACL information. The user and group information is located at the bottom of the page. If you are using LDAP authentication, it also includes the DN information for all users being pulled into the MKS Integrity Server s realm. This information is extremely useful when initially setting up LDAP authentication to ensure the appropriate users and groups are being parsed by the server. It is also useful when troubleshooting user authentication issues because it allows you to make sure the MKS Integrity Server is seeing the user in question. You can view the AdminRealm page at the following URL: http://yourservernamehere:port/adminrealm (for example, http://mksserver:7001/adminrealm)
7 of 7 You are prompted for your system user name and password. NOTE You can save the AdminRealm page in HTML format by clicking File>Save As in your Web browser. Note also that depending on the size of your realm the page may take some time to display.