Managing users with Lightweight Directory Access Protocol (LDAP)

This information helps you configure your LDAP registry to manage users.

If you plan to use an LDAP registry with your Jazz™ Team Server, you must configure your Apache Tomcat or WebSphere® Application Server to use an LDAP registry to authenticate users.

To configure LDAP to work with Jazz Team Server, follow these tasks:
  1. Understanding the LDAP configuration parameters.
  2. LDAP configuration setup process.
  3. Configure the Web container for LDAP in Apache Tomcat.
    Note: The Jazz Team Server user identity is case sensitive. When using LDAP for user management, turn off the case-insensitive option. Work with your server administrator or consult your product documentation to ensure that the settings are case-sensitive.
  4. Configure the WebSphere Application Server with LDAP realm.
  5. Create an initial user. This user is the initial Jazz Team Server administrator.
  6. Using the LDAP sync task.
  7. Use the setup wizard to configure the Jazz Team Server to use LDAP.
  8. Import the users.

Understanding the LDAP configuration parameters

Table 1. LDAP Parameters and descriptions
Parameter Value description
LDAP Registry Location The URL that references your LDAP server. ldap://ldap.example.com:389
User Name The user name to log in to this LDAP server. Some LDAP servers allow anonymous login and password. In this case, this parameter is blank.
Password The password associated with the user name.
Base User DN The search base indicates where in the hierarchy to begin the search for the users. For example, "o=company,l=your city,c=your country"
User Property Names Mapping The mapping of Jazz user property names to LDAP registry entry attribute names. You must define the following mappings:
  • userId =[LDAP user ID]
  • name =[LDAP user name]
  • emailAddress =[LDAP user e-mail]

The userid property identifies the user ID that is used when a user logs into the system. The name property is used to render the name in the user interface.

For example, userId=mail,name=cn,emailAddress=mail

Base Group DN This search base indicates where in the hierarchy to begin the search of group names, for example, ou=memberlist,ou=yourgroups,o=example.com
Jazz to LDAP Group Mapping The mapping between Jazz groups and LDAP groups. One Jazz group can be mapped to multiple LDAP groups. The LDAP groups must be separated by a semicolon. For example, JazzAdmins=LDAPAdmins1;LDAPAdmins2 maps JazzAdmins group to LDAPAdmins1 and LDAPAdmins2. Jazz Team Server defines five groups to map with:
  • JazzAdmins =[LDAP Group for Jazz admins]
  • JazzUsers =[LDAP Group for Jazz users]
  • JazzDWAdmins =[LDAP Group for Jazz Data Warehouse Admin]
  • JazzGuests =[LDAP Group for Jazz guest]
  • JazzProjectAdmins =[LDAP Group for Jazz project admins]
For example, JazzAdmins= YourGroupA, JazzUsers= YourGroupB, JazzDWAdmins= YourGroupC, JazzGuests= YourGroupD, JazzProjectAdmins= YourGroupE.
Group Name Property The LDAP Property that represents the name of the Jazz groups in the LDAP registry. For example, cn. This is used in the query to retrieve an LDAP group. To retrieve an LDAP group, a query uses a combination of the Base group DN and the Group Name Property.
Group Member Property The LDAP Property that represent the members of a group in the LDAP registry. For example, uniquemember.

LDAP configuration setup process

To configure LDAP connection and import users follow these steps:
  1. Stop the server.
  2. If you have previously tried to install your LDAP server, backup the JazzInstallDir/jazz/server/tomcat/conf/server.xml file.
  3. Open the JazzInstallDir/jazz/server/tomcat/conf/server.xml file for editing and uncomment the following realm tag:
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
                 resourceName="UserDatabase" 
                 digest="SHA-1"
                 digestEncoding="UTF-8"/>
  4. Save the file and restart the server.
  5. Open a Web browser window and go to https://localhost:9443/jazz/setup.
  6. Login with ADMIN/ADMIN (both username and password are case sensitive).
  7. Click the Custom Setup button.
  8. click Next until you reach page 5, Setup User Registry.
  9. In the Step 1 section under Type, select the Tomcat User Database radio button.
  10. Under Step 3, select the checkbox for Disable default ADMIN access.
  11. Under Step 4, Select the checkbox for Rational Team Concert - Developer license.
  12. Click Next to create this first user.
  13. Click Previous to go back to page 5, Setup User Registry.
  14. Under Step 1, select the LDAP radio button.
  15. Fill out the fields in Section 2. For more information, see Understanding the LDAP configuration parameters.
  16. Shut down the server.
  17. Configure the Web container for LDAP in Apache Tomcat.
  18. Restart the server.
  19. Open a Web browser window and go to https://localhost:9443/jazz/admin.
  20. Login with the user ID that you created to test your connection.

Configure the Web container for LDAP in Apache Tomcat

For additional information about configuring Apache Tomcat for LDAP, see the related links below. To configure the Web container for LDAP in Apache Tomcat follow these steps:
  1. Open the JazzInstallDir/jazz/server/tomcat/conf/server.xml file for editing and comment the following tag:
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
                 resourceName="UserDatabase" 
                 digest="SHA-1"
                 digestEncoding="UTF-8"/>
  2. Add the following tag for Oracle Internet Directory (OID):
    <Realm className="org.apache.catalina.realm.JNDIRealm" 
     debug="99"
     connectionURL="ldap://ldap.company.com:389"
     roleBase="cn=Groups,dc=company,dc=com"
     roleSearch="(uniquemember={0})" 
     roleName="cn"
     userBase="cn=Users,dc=company,dc=com"
     userSearch="(uid={0})"/>
    Add the following tag for Microsoft Active Directory:
    <Realm className="org.apache.catalina.realm.JNDIRealm" 
     debug="99"
     connectionURL="ldap://ldap.company.com:3268"
     authentication="simple"
     referrals="follow"
     connectionName="cn=LDAPUser,ou=Service Accounts,dc=company,dc=com"
     connectionPassword="VerySecretPassword" 
     userSearch="(sAMAccountName={0})"
     userBase="dc=company,dc=com" 
     userSubtree="true"
     roleSearch="(member={0})" 
     roleName="cn" 
     roleSubtree="true"
     roleBase="dc=company,dc=com"/>
  3. Open the JazzInstallDir/jazz/server/tomcat/webapps/jazz/WEB-INF/web.xml file for editing and link and map the security role references to the security roles:
    <web-app id="WebApp">
    <servlet id="bridge">
    <servlet-name>equinoxbridgeservlet</servlet-name>
    <display-name>Equinox Bridge Servlet</display-name>
    <description>Equinox Bridge Servlet</description>
    <servlet-class>org.eclipse.equinox.servletbridge.BridgeServlet</servlet-class>
    <init-param><!-- ... --></init-param>
    <!-- ... -->
    <load-on-startup>1</load-on-startup>
    
    <!-- Addendum
    If the names of your LDAP Groups are the same as the default Jazz roles
    you don't need to add the following tags
    -->
    <security-role-ref>
    <role-name>JazzAdmins</role-name>
    <role-link>[LDAP Group for Jazz admins]</role-link>
    </security-role-ref>
    
    <security-role-ref>
    <role-name>JazzDWAdmins</role-name>
    <role-link>[LDAP Group for Jazz admins]</role-link>
    </security-role-ref>
    
    <security-role-ref>
    <role-name>JazzGuests</role-name>
    <role-link>[LDAP Group for Jazz admins]</role-link>
    </security-role-ref>
    
    <security-role-ref>
    <role-name>JazzUsers</role-name>
    <role-link>[LDAP Group for Jazz admins]</role-link>
    </security-role-ref>
    
    <security-role-ref>
    <role-name>JazzProjectAdmins</role-name>
    <role-link>[LDAP Group for Jazz admins]</role-link>
    </security-role-ref>
    
    </servlet>
    <!-- ... -->
    </web-app>
    Use the following tags to declare the LDAP groups as security roles:
    <web-app id="WebApp">
    <servlet id="bridge">
    <!-- ... -->
    <security-role>
    <role-name>JazzAdmins</role-name>
    <role-name>JazzDWAdmins</role-name>
    <role-name>JazzGuests</role-name>
    <role-name>JazzUsers</role-name>
    <role-name>JazzProjectAdmins</role-name>
    
    <!-- Addendum
    If the names of your LDAP Groups are the same as the default Jazz roles
    you don't need to add the following tags
    -->
    <role-name>[LDAP Group for Jazz Admins]</role-name>
    <role-name>[LDAP Group for Jazz Data Warehouse Admins]</role-name>
    <role-name>[LDAP Group for Jazz Guests]</role-name>
    <role-name>[LDAP Group for Jazz Users]</role-name>
    <role-name>[LDAP Group for Jazz Project Admins]</role-name>
    <!-- End Addendum -->
    </security-role>
    <!-- ... -->
    </web-app>
    Use the following tags to update the security-constraint section:
    <web-app id="WebApp">
    <!-- ... -->
    <security-constraint>
    <web-resource-collection>
    <web-resource-name>secure</web-resource-name>
    <url-pattern>/*</url-pattern>
    </web-resource-collection>
    
    <auth-constraint>
    <role-name>JazzUsers</role-name>
    <role-name>JazzAdmins</role-name>
    <role-name>JazzGuests</role-name>
    <role-name>JazzDWAdmins</role-name>
    <role-name>JazzProjectAdmins</role-name>
    
    <!-- Addendum
    If the names of your LDAP Groups are the same as the default Jazz roles
    you don't need to add the following tags
    -->
    
    <role-name>[LDAP Group for Jazz Admins]</role-name>
    <role-name>[LDAP Group for Jazz Data Warehouse Admins]</role-name>
    <role-name>[LDAP Group for Jazz Guests]</role-name>
    <role-name>[LDAP Group for Jazz Users]</role-name>
    <role-name>[LDAP Group for Jazz Project Admins]</role-name>
    <!-- End Addendum -->
    
    </auth-constraint>
    
    <user-data-constarint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
    </security-constraint>
    <!-- ... -->
    </web-app>
    Repeat the same addendum on each security-constraint referencing a Jazz group:
    <web-app id="WebApp">
    <!-- ... -->
    <security-constraint>
    <web-resource-collection>
    <web-resource-name>adminsecure</web-resource-name>
    <url-pattern>/admin/cmd/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
    <role-name>JazzAdmins</role-name>
    <!-- Addendum -->
    <role-name>[LDAP Group for Jazz Admins]</role-name>
    <!-- End addendum -->
    </auth-constraint>
    <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
    </security-constraint>
    <!-- ... -->
    </web-app>

Feedback

Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug