LDAP Authentication

By default the Code Collaborator server authenticates users against the users in its database. For large organizations with hundreds or thousands of users in multiple product groups, it is simply impractical to add each would-be Code Collaborator user to the database. For this reason, Code Collaborator can integrate with an existing LDAP directory (or ActiveDirectory) to perform user authentication.

When LDAP authentication is configured, Code Collaborator authenticates users attempting to login against their entry in the directory. When a user logs in for the first time, a user account is created for them automatically in Code Collaborator to store their user preferences.

Warning: Only users with accounts can be assigned to roles within reviews, so it is not possible to add a user to a review who has not previously logged in to Code Collaborator.

Internally, Code Collaborator uses the Tomcat Servlet Container's JNDI Realm for LDAP authentication. For a detailed description of how it works and for complete configuration information, consult the JNDI Realm Documentation.

The installation wizard provides a screen to perform basic configuration of LDAP authentication. This wizard minimally configures Code Collaborator to use LDAP authentication. For advanced configuration, see Advanced Configuration or contact Customer Support.

•	LDAP Connection URL This is a URL where Code Collaborator can connect to the LDAP server. The format of the url is: ldap://servername:port The standard default port for LDAP is 389.

•	User Pattern This string instructs Code Collaborator how to locate a user within LDAP. The format of the string is the same as the LDAP distinguished name of a user with the username replaced with the string {0}.

•	System Administrator The username of the system administrator. The system administrator will always be able to log in and administer license codes and user accounts. This account takes the place of the admin account when using internal authentication.

Microsoft Active Directory is an LDAP compliant directory and can be used to authenticate users to Code Collaborator. However, in typical Active Directory environments, more configuration is needed than can be provided by the installation wizard. Specifically, the username that users log in with typically corresponds to the sAMAccountName attribute of their record. Because this is not part of their LDAP distinguished name (DN), Code Collaborator cannot create a DN directly from the user-entered username to bind to the directory. Instead, Code Collaborator must query the directory to get the user's distinguished name and then attempt the bind. To configure this, you will need to first install Code Collaborator, specifying LDAP authentication and then manually edit the configuration file. The configuration file in question is installation-directory/tomcat/conf/Catalina/localhost/ROOT.xml. Locate the Realm element in the context file and replace it with the following:

You will need to update the attributes which have xxxx'ed out fields. The fields connectionName and connectionPassword define a user account the Code Collaborator will use to connect to Active Directory to find the user records. If anonymous connections are allowed to your directory (not typical), then these attributes are not required.

Warning: Modifying the ROOT.xml file will cause Tomcat to dynamically reload the Code Collaborator application, terminating any active sessions. Changes to ROOT.xml should be done in the context of stopping and restarting the Code Collaborator service (i.e., in a production environment coordinating the restart with user activity), regardless of whether the service itself is actually stopped and restarted, or just reloaded by Tomcat.

To use security groups or other user attributes to restrict access to Code Collaborator, you can refine the userSearch query to return only users that meet your requirements.

The configuration examples above are a starting place for configuring Active Directory authentication. Additional configuration may be required because of specific configuration details of the directory. The JNDI Realm Documentation describes the different operational modes and explains each of the configuration attributes, and may be helpful in debugging the issue. The directory administrator that manages the directory will be a valuable resource in resolving the issue, either directly, or in conjunction with Smart Bear's Customer Support team.

If the directory administrator is unavailable, Smart Bear's Customer Support team can help you resolve configuration issues, but often do not have enough information about the directory schema, permissions, etc., to efficiently resolve issues. We will walk you through several basic configurations that we have seen work with other directories. Having an LDAP browser tool available (there are many good free and commercial browsers available) when you call will help answer some of the questions required to properly configure your server. In some cases, we will still need to discuss details with your directory administrator.

Configuring Code Collaborator to communicate securely with an LDAP server using LDAPS (LDAP over SSL) can be done, but requires manual configuration outside of the installer wizard. To configure LDAPS, first install Code Collaborator configured for normal LDAP access. The service will start automatically upon completion of the install, so you will need to shut it down to continue configuration. Open the context configuration file (installation-directory/tomcat/conf/Catalina/localhost/ROOT.xml) in a text editor and find the Realm configuration element. It will look something like the following:

If you are configuring Code Collaborator for use with Microsoft Active Directory using LDAPS, follow the Active Directory instructions to make a best effort to configure the realm for your Active Directory server. Do not worry if you do not get it exactly right or cannot test the connection because the server refuses insecure connections. That issue can be resolved once connectivity is established.

To the realm configuration above (or your Active Directory realm configuration), you will need to add an attribute 'protocol' with the value 'ssl' and you will probably need to change the 'connectionURL' attribute to an LDAPS url. The updated configuration below highlights the changes:

Depending on the LDAP server's SSL certificates, this configuration may be enough to establish the connection. However, often companies generate their own SSL certificates signed by their own Certificate Authority (CA) certificate. Unless additional measures are taken, these certificates may not be trusted so Code Collaborator will still not connect to the LDAP server. To establish trust, you will need to create a "key store" and import the public key of either the Certificate Authority or the public key of the LDAP server as a trusted certificate. Obtain from your LDAP or network administrator the appropriate certificate file. Then using Java's keytool (located in $JAVA_HOME/bin), import the certificate into a key store for Code Collaborator using the following command:

keytool -import -alias ldapserver -keystore <collab install dir>/tomcat/conf/collab.ks -trustcacerts \

Important: You will likely be prompted to confirm the validity of the certificate. It is imperative for the security of the overall system that you verify the key matches the trusted material. Before accepting the certificate, you should contact the administrator that sent you the certificates and verify that the certificate fingerprints that you see match the certificate fingerprints that they intended to send you. For more information on why this step is important, see the note in the keytool documentation.

The final step is to configure Code Collaborator to use the newly created keystore. Open installation-directory/ccollab-server.vmoptions in a text editor and add the following lines:

Upon restart, the Code Collaborator service should be connecting to the LDAP server via SSL. If you are still getting errors, check that the other LDAP configuration options have been configured correctly. If you are using Active Directory, it is now worth revisiting the Active Directory configuration above.

Finally, a note on troubleshooting SSL connections: adding the following line to the ccollab-server.vmoptions file will enable Java's network debug logging.

Upon restarting Code Collaborator, this information will be written to <installation-directory>/output.log. If you need assistance interpreting this log, contact Smart Bear Customer Support.

Note: Do not run in a production environment with network debug logging enabled. This will severely impact the performance of the system and will also consume vast quantities of disk space.

The basic configuration provided by the installer sets up the simplest possible LDAP configuration. Many more sophisticated configurations are possible, but require manually editing the context configuration file (installation-directory/tomcat/conf/Catalina/localhost/ROOT.xml).

Sometimes it is necessary for users from different organizational units to have access to Code Collaborator. If you are using direct-bind configuration using the userPattern attribute, you can change the configuration to use userPatternArray instead where the value is a colon-separated list of user patterns. For example, if there are users in ou=foo,dc=mycompany,dc=com and ou=bar,dc=mycompany,dc=com identified by their uid attribute, you can set the userPatternArray attribute as follows:

userPatternArray="(uid={0},ou=foo,dc=mycompany,dc=com):(uid={0},ou=bar,dc=mycompany,dc=com)"

Likewise, if you are using search to locate users (as in Active Directory Configuration) you can use the LDAP filter operators | and & (SGML encoded as &) to form compound filters. Taking the same example:

userSearch=(|(uid={0},ou=foo,dc=mycompany,dc=com)(uid={0},ou=bar,dc=mycompany,dc=com)

If you need to restrict access to Code Collaborator, we recommend that you configure your Realm definition to use userSearch for searching for user accounts rather than userPattern for direct bind (see Active Directory Configuration for examples). With userSearch, you can expand your search criteria to include only members of the specified group or groups. For example, the following userSearch would restrict access to only members of the ccusers security group:

userSearch="(&(memberOf=CN=ccusers,OU=Security Groups,OU=Accounts and Groups,DC=xxxx,DC=xxxx,DC=com)(sAMAccountName={0}))"

Please note that the ampersand (&), needs to be SGML encoded to "&" because the configuration file is an XML document.

Previous versions of Code Collaborator advised administrators to manually edit the deployment descriptor (web.xml file) to include an role-name in the auth-constraint. While this method will work to restrict access to Code Collaborator, it is not preserved after a server upgrade, so administrators were required to edit the deployment descriptor at each upgrade. The userSearch method described above is preserved on upgrade, so upgrades are much simpler.

When users first log in to Code Collaborator, their user account is created automatically, as a standard user account. It is possible to have users in certain roles (see Restricting Access above) to automatically receive administrator privileges. This configuration is done in the installation-directory/tomcat/conf/Catalina/localhost/ROOT.xml file.

Near the bottom of the ROOT.xml file, there is a section of server parameters (Parameter XML elements). These are name-value pairs of configuration options. To configure certain LDAP groups to be assigned administrator rights, create an admin-roles parameter and for its value specify a comma-separated list of LDAP group names. New users that are members of the specified LDAP groups will be given administrator privileges when their accounts are created. Users that already have accounts in Code Collaborator will not automatically be promoted to administrator. Those privileges will need to be assigned manually from the Admin screen.

Warning: After making changes to the ROOT.xml file, you will need to restart the Code Collaborator service for the changes to take effect.