Skip to main content
Mitratech Success Center

LDAP Authentication Plug-in

By default, TeamConnect authenticates each user by comparing a username and password entered in the login screen with information stored in the TeamConnect database.

This is a safe and secure method of authentication, but your organization might choose to integrate the TeamConnect authentication process with a network-wide authentication mechanism, such as an LDAP (Lightweight Directory Access Protocol) server.

You can integrate any version of TeamConnect 3.0 and higher with LDAP by uploading a configuration file to TeamConnect's Documents area. Once this is done correctly, the LDAP authentication plug-in is available on the Authentication Plug-In block of the Admin Settings/ Security page.

TeamConnect also provides the ability for you to enable LDAP authentication per user through a setting on the user's account.

Note: TeamConnect's integration with LDAP for authentication does not provide single-sign-on (SSO) functionality to TeamConnect. Each user must sign on to TeamConnect, and then sign on to other applications.

For additional assistance, such as customization for your LDAP directory structure or authentication using password comparison, contact Mitratech Client Services. In addition, if your server is using password encryption or an SSL connection, certain changes might be required in the plug-in. These modifications can be made by Mitratech.

This guide does not cover managing access rights in TeamConnect. You must define group rights to TeamConnect objects and tools directly in TeamConnect. TeamConnect is not compatible with LDAP Access Control Lists (ACL).

As with other applications to which users gain access through your LDAP server, users can log in to TeamConnect only when the LDAP server is available.

LDAP Authentication Prerequisites

The process of configuring TeamConnect for LDAP integration includes the following basic steps:

  1. Creating Custom LDAP Authentication Error Pages—(optional) Create custom HTML pages for use with LDAP authentication.
  2. Defining LDAP Parameters—Enter information in TeamConnect's LDAP properties file.
  3. Installing LDAP Plug-in Files—Upload a TeamConnect LDAP properties file to the TeamConnect Documents area. You can also upload customized authentication error messages.
  4. Enabling a Default Authentication Method—Enable the LDAP plug-in from TeamConnect Admin Settings.
  5. Overriding Authentication for Individual Users—Allows you to enable LDAP authentication for individual user accounts. This step is only required if you do not select LDAP as the default authentication mechanism in the previous step.

Creating Custom LDAP Authentication Error Pages

You have the option to create customized screens for logging into TeamConnect using LDAP authentication and related error messages. To enable custom error pages, you must do the following:

  1. Create custom error pages.
  2. Update the LDAP authenticationDescriptor.properties file properties for the new pages.
  3. Upload the custom pages to the TeamConnect Documents area folder:

\Top Level\System\Authentication\LDAP\pages

See Installing LDAP Plug-in Files for more information.

Note: If you choose not to create customized error and login pages then you should comment out related lines from the LDAP authenticationConfiguration.properties file

Requirements

The custom pages should be in HTML format. The custom page file extensions should be .html, If any custom pages require images, those images should be uploaded to the TeamConnect Documents area

Custom Error Pages List

A list of pages that can be customized follows. Each page has a corresponding property in the LDAP authenticationDescriptor.properties file whose value should match the file name you create per page. The corresponding properties are described in Defining LDAP Parameters.

  • Authentication Failed page
  • Normal Logout page
  • Session Timeout page
  • Restore Session page
  • Bad Credentials page
  • Account Locked page

Defining LDAP Parameters

To enable TeamConnect to use your LDAP plug-in, you must provide certain parameters which represent your environment and save them in a properties file. You must modify the authenticationDescriptor.properties file for LDAP authentication and enter the appropriate information in these parameters according to the descriptions in the table below.

Note: To comment out a property, type # at the beginning of the line to comment it out

LDAP Parameters and Definitions

Parameter

Description

Example

tc.displayName

Required field. Do not change this value.

 

tc.uniqueId

Required field. Do not change this value.

 

tc.isSSO

Required field. Do not change this value.

 

ldap.host

LDAP server host name.

This value is combined with ldap.port and ldap.root to form the ldap-server URL.

10.0.0.1

Note: When combined with ldap.port and ldap.root values, an ldap-server URL like ldap://10.0.0.1:389

/dc=myserver,dc=org

would result

ldap.port

LDAP server port.

This value is combined with ldap.host and ldap.root to form the ldap-server URL.

389

Note: When combined with ldap.host and ldap.root values, an ldap-server URL like ldap://10.0.0.1:389

/dc=myserver,dc=org

would result

ldap.root

Enter the top-level DN (distinguished name) under which the TeamConnect users can be found in the LDAP directory structure.

This value is combined with ldap.host and ldap.port to form the ldap-server URL.

dc=springframework,dc=org

Note: When combined with ldap.host and ldap.port values, an ldap-server URL like ldap://10.0.0.1:389

/dc=myserver,dc=org

would result

ldap.userDn

Enter the name of the attribute that stores the username on the LDAP server.

TeamConnect will log into the LDAP server with this username.

Note: Do not confuse the attribute name with the actual value of the username that it stores.

directory.username=uid

ldap.password

Enter the name of the attribute that stores the password on the LDAP server.

TeamConnect will log into the LDAP server with this password.

Note: Do not confuse the attribute name with the actual value of the password that it stores.

directory.password=userPassword

ldap.userDnPatterns

The elements of the user's Distinguished Name that, when assembled, will form the complete DN to authenticate the user's identity to the LDAP Directory Service (if authentication is required).

uid={0},ou=people

Note: This example would obtain the DN for the user by substituting the user login name in the supplied pattern and attempting to bind as that user with the login password. This would work if all your users are stored under a single node in the directory.

ldap.groupDnPattern

The group's Distinguished Name. For authentication, users will need to belong to this group.

You must create and configure this group on the LDAP server. Then add users to this group.

teamconnect

ldap.groupRoleAttribute

The attribute which contains the name of the authority defined by the group entry. This parameter is used to load authorities from groups in the LDAP directory.

The default value is cn

page.badCredentials

Page to display if the password does not match the password stored for the TeamConnect user account.

Note: If you do not create a custom file, then comment out this line.

/login.html?error=bc

page.lockedAccount

Page to display if the TeamConnect user account is locked and User Locking is enabled in TeamConnect settings.

Note: If you do not create a custom file, then comment out this line.

/login.html?error=1

page.maximumLogins

Page to display if the LDAP account has already exceeded their maximum allowed sessions.

Note: If you do not create a custom file, then comment out this line.

/login.html?error=1

page.logout

This page is shown when a user logs out normally.

Note: If you do not create a custom file, then comment out this line.

/login.html

page.sessionTimeout

This page is shown when a user's session times out.

Note: If you do not create a custom file, then comment out this line.

login.html?error=2

To define LDAP parameters in the properties file

  1. Copy the LDAP authenticationDescriptor.properties file from the TeamConnect Installer installation path (subfolder utilities\config\ldap) to your local hard disk.

    Tip: When editing a properties file, use a text-only editor to ensure no formatting codes get inserted by the application.
     
  2. Edit the authenticationDescriptor.properties file according to your environment. For details about each parameter, see the LDAP Parameters and Definitions table.
  3. Save and close this file.
  4. Make note of the location of this modified file so that you can use it in the next procedure.

Now that you have configured your LDAP plug-in, you must upload a file into TeamConnect, as described in Installing LDAP Plug-in Files.

Installing LDAP Plug-in Files

This section describes:

  1. Creation of TeamConnect Documents area folders for LDAP files
  2. Uploading LDAP configuration files for TeamConnect
  3. Uploading custom LDAP screens

LDAP authentication plug-in installation consists of a configuration file, authenticationDescriptor.properties, that must be uploaded to a specific directory within the Documents area of TeamConnect:

You must edit the authenticationDescriptor.properties file, as described in Defining LDAP Parameters.

To install the LDAP Authentication configuration file

  1. In the TeamConnect tab bar, select Documents.
  2. Navigate to Top Level, then System.
  3. Create a folder named Authentication.
  4. In the Authentication folder that you just created, create a sub-folder named LDAP.
  5. In the LDAP folder that you just created, create the following sub-folders:

    Caution: The folder names must be entered exactly as they appear below.
    • classes
    • pages
  6. In the classes folder that you just created, upload this file: authenticationDescriptor.properties
  7. The pages folder does not require any file uploads, unless you choose to override the default error message pages. using the page.xxx properties in the configuration file. If so, you would upload your matching custom error message pages to this folder.

The LDAP Authentication plug-in is now installed.

To complete the implementation of LDAP, make sure that you are using the correct default authentication method, as described in Enabling a Default Authentication Method. If LDAP is not your default authentication method, override individual users who need LDAP, as described in Overriding Authentication for Individual Users. If LDAP is your default authentication method, you need to perform overrides only:

  • For users who may have previously been overridden with a different authentication method and are now using LDAP. In this case you can set their method to (System Default).
  • For users who are not using LDAP.

Also, user TeamConnectAdmin should always use the Standard Authentication method. You can force this behavior by appending /standardLogin to the end of the URL that launches TeamConnect for that user.

LDAP Authentication Sample Files

This section provides sample files described in this guide.

Sample Custom Log-in Page

Note: You do not need to customize the TeamConnect login page for LDAP Authentication. If you customize the login page, however, you must reference the j_spring_security_check servlet, the user field input value should correspond to the j_username variable, the password field input value should correspond to the j_password variable as shown in the example below.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http:// www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Log In - TeamConnect 3.0</title>
</head>
<body scroll="no">
    <div id="horizon" style="margin-top:150px">
        <div id="content">
            <div id="contentText">
                <center>
                <table class="logincontent" border="0" width="600" cellpadding="0" cellspacing="0">
                <tr>
                <td style="background-image: url(images/bg_login.jpg); background- repeat: no-repeat;">
                <!-- LOGIN TABLE [BEGIN] -->
                    <table border="0" width="600" cellpadding="0" cellspacing="0">
                    <tr>
                        <td colspan="2" style="line-height: 1.5em;" align="center"></td>
                    </tr>
                    <tr>
                        <td height="150" align="center">
                            <form method="post" id="loginForm" name="loginForm" action="j_spring_security_check">
                            <table border="0" cellpadding="5" cellspacing="0" style="margin: 10px;">
                            <tr valign="middle">
                                <td width="90" align="right" nowrap><b>User Name:</b></td>
                                <td align="left"><input type="text" name="j_username" id="j_username" size="18" maxLength=50                                  tabindex="1"/></td>
                            </tr>
                            <tr valign="middle">
                                <td align="right" nowrap><b>Password:</b></td>
                                <td align="left"><input autocomplete="off" type="password" name="j_password" id="j_password"                                  size="18" maxLength=50 tabindex="2"/></td>
                            </tr>
                            <tr valign="middle">
                                <td align="right" nowrap>&nbsp;</td>
                                    <td colspan="2" align="left" class="texthdr" nowrap><input type="submit" name="submit"                                      value="Log In" class="mainSearchBtn"></td>
                            </tr>
                            </table>
                            </form>
                        </td>
                    </tr>
                </table>
                </td>
                </tr>
                </table>
                </center>
            </div>
        </div>
    </div>
</body>
<script>
$("j_username").focus();
</script>
</html>

Sample Custom Error Page

Note: You do not have to customize error pages. If you create custom error pages, they must be in HTML format (with file extension .HTML). You can use existing TeamConnect error message JSP files but cannot upload custom JSP files.

<html>
    <head>
    </head>
    <body>
    Authentication error.
    </body>
</html>

Sample Restore Session Page

Note: The following is a sample HTML page content you may choose to redirect to for the LDAP parameter, ldap.restoreSessionUr

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http:// www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>You have another session open</title>
</head>
<body>
    <div id="horizon" style="margin-top:150px">
        <div id="content">
            <div id="contentText">
                <center>
                    <table border="0" width="500" cellpadding="0" cellspacing="0" style="margin: 20px;">
                        <tr valign="top">
                            <td class="bgcolor16" align="left" style="padding: 20px; border-bottom: 1px solid #CCCCCC;
                                line-height: 1.7em;">
                            <table border="0" cellpadding="3" cellspacing="0">
                            <tr valign="top">
                                <td style="padding: 8px 0px 0px 15px;">
                                    <span class="titlehdr5">You have another session open</span>
                                </td>
                        </tr>
                        <tr>
                            <td style="padding: 8px 0px 8px 15px;"><span style="padding:200px 0px 20px 0px;">You are either                             logged in at another location or did not log out of your previous session.<p>Do you want to recover                             the previous session and return to what you were working on, or start a new session (losing all                             previous work)?
                            </span></td>
                         </tr>
                         <tr>
                            <td align="center" class="texthdr">
                            <form name="mainForm" action="restoreSession.htm" method="post">
                            <input type="button" name="recover" value="Recover Session" class="mainSearchBtn"                             onclick="document.getElementById('restoreSession').value=true;document.mainForm.submit();"/>&nbsp;
                            <input type="button" name="new" value="New Session" class="mainSearchBtn"                              onclick="document.getElementById('restoreSession').value=false;document.mainForm.submit();"/>&nbsp;
                            <input type="hidden" id="restoreSession" name="restoreSession" value="true" />
                            </form>
                            </td>
                         </tr>
                         </table>
                         </td>
                        </tr>
                    </table>
                </center>
            </div>
        </div>
    </div>
</body>
</html>

Sample LDAP Configuration File

## This is a sample properties file for LDAP authentication. You can tailor it to your specific

## situation to work with the LDAP authentication mechanism included within TeamConnect. All

## un-commented properties in this file are required, though their values can be changed.

# Identification properties for this authentication component tc.displayName=LDAP Team Connect Authenticator

tc.uniqueId=LDAP

tc.isSSO=false

# Custom page mappings (omit any that do not apply)

#page.badCredentials=tryagain.html

#page.lockedAccount=giveup.html

#page.maximumLogins=sorry.html

#page.logout=goodbye.html

#page.sessionTimeout=missedyou.html

# LDAP configuration properties

#

# The URL of the LDAP server to be used ldap.host=10.1.2.48

ldap.port=389 ldap.root=dc=domain,dc=com

# DN of the user/administrator allowed to connect to the LDAP server ldap.userDn=cn=Manager,dc=domain,dc=com

# Password of the user/administrator ldap.password=secret

#

ldap.userDnPatterns=uid={0},ou=Department

#

ldap.groupDnPattern=ou=Department

#

ldap.groupRoleAttribute=cn

  • Was this article helpful?