TN0030: User Management in Tomcat

Last Updated: October 29, 2008
Author: Balaji Krish

Summary

The Jazz Team Server application runs in a secure application server and requires authentication. The authentication is managed by the application server. User information maintained in an external user directory is used by the application server for authentication and by the Jazz application for displaying group membership information in the UI and synchronizing the user information between the user directory and Jazz database. This note describes how to set up the Tomcat user database, the LDAP user directory, and the custom user directory in Tomcat application server.

More Information

The application server manages authentication. Therefore, you can use any authentication realm supported by Tomcat application server for authentication. Jazz application uses the user directory information to display the group membership information, to authorize user operation, and to synchronize user data between the Jazz database and the user directory. In 1.0, Jazz application provides first class integration with 2 user directories: the Tomcat user database and the LDAP user directory. If you are using any other custom user directory, you need to manually manage users in the external user database and the Jazz database. The Tech Tip “User Management in Jazz” provides a good introduction on the different user directories supported by Jazz.

Tomcat User Database

The Tomcat user database is the default authentication realm shipped with Jazz Team Server. The Tomcat user database is a simple file tomcat-users.xml present in {Jazz-Installation-Dir}/jazz/server/tomcat/conf directory. The deployment descriptor describes the authentication realm to be used. The deployment descriptor in Tomcat (server.xml) is present in {Jazz-Install-path}/Jazz/server/tomcat/conf directory.

Tomcat User Database Realm defined in server.xml:

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"       resourceName="UserDatabase"       digest="SHA-1"       digestEncoding="UTF-8"/>  

We have now configured Tomcat application server to use Tomcat user database for authentication. Now, we need to configure Jazz application to use the same Tomcat user database for authorization and synchronizing user records with the Jazz repository. The following describes the steps to configure the user directory in Jazz application.

• Start the server
  
• Go to https://serverName:9443/jazz/setup.  Tomcat application server is now using the Tomcat user database for authentication. You need to login using your user database credentials. The user must have administrator privileges to configure Jazz server
• Choose “Custom setup”
  
• Configure database and E-mail settings.
• Choose “Tomcat User Database” as the user registry

Fig 2: User Registry page in setup wizard:

• Optionally create a new user and disable Admin access
• Click finish to complete the configuration.
  

LDAP User Directory

LDAP (Lightweight Directory Access protocol) user directory is a user registry that stores the user data in a logical and hierarchical manner. The information present in LDAP user directory can be retrieved in a variety of ways. LDAP user directory index all the data, and “filters” may be used to select just the person or group you want.

First, we need to configure Tomcat application server to use LDAP realm for authentication. The deployment descriptor describes the authentication realm to be used. The deployment descriptor (server.xml) is present in {Jazz-Install-path}/Jazz/server/tomcat/conf directory.

To configure the LDAP realm in tomcat, you need the following information:

LDAP Realm parameters

LDAP Properties	Definition
connectionURL	URL to connect to LDAP. For example: ldap://example.com:389
userBase	The user base indicates where in the hierarchy to begin to search the users.
userSearch	Search query to search users
userSubtree	Boolean to indicate whether subtree under the userBase must be searched to find the user.
roleBase	The role base indicates where in the hierarchy to begin the search for groups
roleSubtree	Boolean to indicate whether subtree under the roleBase must be searched to find the groups.
roleSearch	Search query to search the members of a group
roleName	Property to describe the name of the group in LDAP directory.

A sample LDAP realm is shown below

<Realm className="org.apache.catalina.realm.JNDIRealm"
   debug="9"
   connectionURL="ldap://ldapserver:389"
   userBase="ou=Jazz,o=ibm.com"
   userSearch="(mail={0})"
   userSubtree="true"
   roleBase="ou=people,o=ibm.com"
   roleSubtree="false"
   roleSearch="(members={0})"
   roleName="cn"
/>

Jazz supports four groups. The four groups are JazzAdmins, JazzDWAdmins, JazzUsers and JazzGuests. If the group names in LDAP user directory are different from the Jazz group names, you need to make changes to the web.xml file to map the LDAP group names to Jazz group names. Note that the web.xml  ({Jazz-Installation-Dir}jazzservertomcatwebappsjazzWEB-INFweb.xml)is accessible only if jazz.war has been deployed. (Web.xml file is created when you start the jazz.server the first time. You need to at least start the server once for the Web.xml file to be created.)

Changes in web.xml to support Jazz-LDAP group mapping:

• Add security role references to map Jazz to LDAP group names 
• Security role references are used to map one role name to another. The security role definition must be between <servlet> tags in web.xml.

  <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>  	<!-- Add the following section if the LDAP group names are different from Jazz group names -->  		<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 Data Warehouse Admin]</role-link>  		</security-role-ref>  		<security-role-ref>  			<role-name>JazzGuests</role-name>  			<role-link>[LDAP Group for Jazz guest]</role-link>  		</security-role-ref>  		<security-role-ref>  			<role-name>JazzUsers</role-name>  			<role-link>[LDAP Group for Jazz users]</role-link>  		</security-role-ref>  		<!-- End Addition -->  	</servlet>  	....  </web-app>

• Define security roles for LDAP group names

    <web-app id="WebApp">  	<servlet id="bridge">  	...  	</servlet>  	<!-- ... -->  	<security-role>  		<role-name>JazzAdmins</role-name>  	</security-role>  	<security-role>  		<role-name>JazzDWAdmins</role-name>  	</security-role>  	<security-role>  		<role-name>JazzUsers</role-name>  	</security-role>  	<security-role>  		<role-name>JazzGuests</role-name>  	</security-role>  	<!-- Add the following section if the LDAP group names are different from Jazz group names -->  	<security-role>  		<role-name>[LDAP Group for Jazz admins]</role-name>  	</security-role>            	<security-role>           		<role-name>[LDAP Group for Jazz Data Warehouse Admin]</role-name>        	</security-role>            	<security-role>           		<role-name>[LDAP Group for Jazz users]</role-name>        	</security-role>          	<security-role>           		<role-name>[LDAP Group for Jazz guest]</role-name>        	</security-role>      	<!-- End Additions -->  </web-app>  

• Update authentication constraints

  <web-app id="WebApp">      	<servlet id="bridge">          	...      	</servlet>  	<!-- ... -->  	  	<!-- secures everything under the web root -->  	<security-constraint>  		<web-resource-collection>  		...  		</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>  	  		<!-- Add the following section if the LDAP group names are different from Jazz group names -->         		<role-name>[LDAP Group for Jazz admins]</role-name>        		<role-name>[LDAP Group for Jazz users]</role-name>        		<role-name>[LDAP Group for Jazz Data Warehouse Admin]</role-name>        		<role-name>[LDAP Group for Jazz guest]</role-name>        		<!-- End Addition -->          	</auth-constraint>  	<user-data-constraint>   	.....  	</user-data-constraint>  	</security-constraint>  	  	<!-- Repeat the same addendum on each security-constraint referencing a Jazz group: -->  	  	<!-- opens up just /jazz/web, /jazz/repo, /jazz/admin and /jazz/setup leaving everything else secured -->  	<security-constraint>  		<web-resource-collection>  		...  		</web-resource-collection>  	         		<!-- Leaving out the <auth-constraint> section means these resources don't require authentication -->  	       		<user-data-constraint>  			<transport-guarantee>CONFIDENTIAL</transport-guarantee>  		</user-data-constraint>  	</security-constraint>  	      	<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>  		</auth-constraint>  	  		<!-- Add the following section if the LDAP group names are different from Jazz group names -->        		<role-name>[LDAP Group for Jazz admins]</role-name>      		<!-- End Addition -->  	     		<user-data-constraint>  			<transport-guarantee>CONFIDENTIAL</transport-guarantee>  		</user-data-constraint>  	</security-constraint>  </web-app>  

After you have configured Tomcat application server to use LDAP user directory for authentication, you need to configure Jazz application to use LDAP user directory for authorization and  synchronizing user records with the Jazz repository. The following describes the steps to configure user directory in Jazz application.

1. Start the server
2. Go to https://example.com:9443/jazz/setup. Tomcat application server is now using LDAP for authentication. You need to login using your LDAP credentials. The user must have administrator privileges to configure Jazz server
3. Choose “Custom Setup”.
4. Configure database and e-mail settings.
5. Choose “LDAP” as the user registry

   

6. Specify the configuration properties to access LDAP user directory

   Parameter	Value
   LDAP Registry Location	The URL referencing your LDAP server. It should be a URL like ldap://ldap.example.com:389
   User Name	The user name to login to this LDAP server. Some LDAP servers support anonymous access and don’t require a login and password.
   Password	The password associated to access the LDAP directory
   Base User DN	The search base indicates where in the hierarchy to begin to search the users. For example, “o=[company],c=[your country]” is a base user dn to search users under the company’s main directory.
   User Property Names Mapping	Indicates how to map Jazz user property names to your LDAP directory entry attribute names. You must define the mapping for user id, name and emailAddress properties. userId =[User Id property in LDAP], name =[User Name property in LDAP], emailAddress =[Email address property in LDAP]
   Base Group DN	This search base indicates where in the hierarchy to begin the search the group names.
   Jazz to LDAP Group Mapping	Mapping between Jazz groups and LDAP groups. One Jazz group can be mapped to multiple LDAP groups. The LDAP groups mapped to a single Jazz group must be separated by a semicolon. For example, JazzAdmins=LDAPAdmins1;LDAPAdmins2 maps JazzAdmins group to LDAPAdmins1 and LDAPAdmins2. You must define mapping for JazzAdmins, JazzUsers, JazzDWAdmins and JazzGuests JazzAdmins =[LDAP Group for Jazz admins], JazzUsers =[LDAP Group for Jazz users], JazzDWAdmins =[LDAP Group for Jazz Data Warehouse Admins], JazzGuests =[LDAP Group for Jazz guests]
   Group Name Property	LDAP Property to represent the name of the Jazz groups in the LDAP registry.
   Group Member Property	LDAP Property to represent the members of a group in the LDAP registry.

   Sample LDAP configuration properties:

   

7. Enable the check box to compute additional LDAP properties. Jazz application computes other LDAP configuration properties based on the values specified above.

Custom User Directory

Tomcat supports administrators to hook in custom authentication modules. The following section describes the steps involved in using a custom user directory for authentication and authorization in Jazz.

1. Configure Tomcat application server to use custom user directory for authentication. Edit the server.xml present under {Jazz-Install-path}/Jazz/server/tomcat/conf directory to modify the realm used for authentication
2. Start the Jazz server
3. Go to https://example.com:9443/jazz/setup. Tomcat application server is now using custom user directory for authentication.
4. Choose “Custom Setup”.
5. Configure database and e-mail settings.
6. Choose “Non LDAP External directory” as the user registry

   

7. Click finish to complete the configuration.

Note that by using custom user directory, you need to manage the list of users in the user directory and the Jazz database. The Web UI and Eclipse Jazz UI will not display the groups membership information.