TN0013: Jazz Team Server Authentication Explained


The Jazz Team Server that ships with Rational Team Concert 4.0 is packaged as a Java Enterprise Edition (Java EE) Web Application, and as such runs within a supported Java EE application server (IBM WebSphere Application Server or Apache Tomcat). The application uses Java EE authentication per the Java Servlet specification. This note explains the authentication mechanism used by Jazz Team Server, and the rationale for the design. It also describes how to change the configuration to use alternate authentication methods and to unsecure feed URLs for a custom deployment, along with the tradeoffs associated with each configuration.

More Information


The Jazz Team Server application runs in a secure container and requires authentication. The application also uses a set of predefined roles that can be assigned to users, for authorization to access specific URLs or to perform specific low-level operations (e.g. read, write, administer). The "container" is another term for "application server", e.g. WebSphere or Tomcat. The authentication itself is managed by the container; if a user fails to authenticate by providing a valid user id and password, then the container rejects the request without the request ever reaching the application. When the user successfully authenticates, the container subsequently forwards the request to the application (Jazz Team Server in this case) for processing. Within the operation that processes the request, the application checks that the user is assigned a role with the requisite authority to perform the operation.

Figure 1: Container Managed Authentication for the Jazz Team Server

Why Use Java EE Container Managed Authentication?

Jazz Team Server uses Java EE container managed authentication in order to leverage existing capabilities provided by the application servers for handling user credentials, and for integrating with enterprise user directories. In fact, the Jazz Team Server application never handles nor even sees the user password as part of processing a request. Additionally, by associating application roles with external user-group membership at the Java EE web application-level (as opposed to within the Jazz Repository), authorized users can administer and configure the server even when the Jazz Repository's backing database is unavailable or not yet configured.

Repository Roles

The Jazz Team Server application uses the following pre-defined roles:

Role Name Description
JazzAdmins Administrators of a Jazz Repository with full read-write access
JazzProjectAdmins Administrators of a Jazz Repository with specific permissions to control the creation and maintenance of Jazz Projects
JazzDWAdmins Administrators of a Jazz Repository with specific permissions to control the data warehouse on a Jazz Server
JazzUsers Users with regular read-write access to the Jazz Repository
JazzGuests Users with read-only access to the Jazz Repository.

The roles are declared in the application deployment descriptor (described later). These roles map to group membership within the authentication Realm configured in the container.

Authentication Methods

Of the four authentication methods defined by the Servlet specification, Jazz supports the following two: FORM and BASIC. The table below describes the differences, advantages and disadvantages of each:

Behavior and Implementation
  • Jazz Team Server Web UI presents HTML form to collect user credentials first time user attempts to access a secured resource
  • Redirects to custom page for failed login
  • Login "session" is established between the browser and the server; once authenticated, server only needs to validate session but does not need to re-authenticate credentials
  • The web browser itself presents a dialog to collect user credentials first time user attempts to access a secured resource
  • Credentials passed on every request from client to the server; on each request server (WebSphere) validates credentials or (Tomcat) reauthenticates credentials
  • Embedded form in login page improves Web UI experience
  • Easy to provide logout functionality in Web UI
  • Because authentication is not required on every request, provides significant performance advantages in containers that don't cache credentials
  • Well-known standard protocol makes it easy to write programmatic http client access
  • Many third party feed clients can authenticate with this method
  • Distinct protocol requires special knowledge and code for programmatic http client access
  • Most third party feed clients will not understand this protocol
  • Browser login dialog is out of place with the look and feel of the Web UI
  • No way to logout, other than restarting browser or using advanced browser functions
  • Because user ID and password are sent with each request in a weakly encoded format, server must always run over https to prevent identity theft
  • Because authentication is required on every request, results in severe performance penalty in containers that don't cache credentials

Because of the performance benefits and the ability to have a better user experience in the Web UI, FORM based authentication is the default method pre-configured in the Jazz Team Sever. However, the application has been tested using BASIC authentication and this can be modified in the deployed application. Generally you would only want to change the default if you would like to provide secure access to feeds by feed readers that can handle BASIC authentication.

Deployment Descriptor

Jazz Team Server is packaged as a Web ARchive (WAR) file that can be deployed to an application server. When installed, this archive is located in [JazzServerInstallDir]/server/tomcat/webapps/jazz.war. Within this archive the deployment descriptor is located at WEB-INF/web.xml.

The application roles are defined in the following segment of the deployment descriptor:



These roles are used to configure access to web resources. For example, the following segment by default secures all resources within the WAR, requiring secure authentication by users with one of the application roles:

    <!-- secures everything under the web root -->

Configuring the authentication method

As mentioned above, for performance reasons and improving the user experience, we recommend using the pre-packaged default FORM-based login configuration. However, if you have reasons to change to BASIC, this can be configured by modifying the deployment descriptor. First comment out the following section:


Next, add in a section like the following and provide a realm name for your server:


The realm name will be displayed the user when they log in to the application:

Figure 2: Example of a BASIC auth browser login dialog, using a realm name of "XYZ Enterprise Directory"

If you are using Tomcat, you must also modify "jazz\server\tomcat\conf\Catalina\localhost\jazz.xml" and change the className attribute on the "Valve" element from:




Jazz Feeds and Security Considerations

Jazz Team Server provides a variety of feeds that can be subscribed to by the Rational Team Concert client or a web browser. Examples of feed events include changes to work items, source code delivery, and completion of builds. Most well-known web browsers can handle either the form-based or basic authentication configurations; the Rational Team Concert client also supports both. Thus the feeds can be viewed seamlessly using either a web browser or Rational Team Concert. As noted in an earlier section, however, the authentication mechanisms can prevent usage of some 3rd party feed readers for viewing server feeds. Server administrators should consider how important this is for their deployment. Some feed readers support basic authentication, while it's unlikely for a reader other than a web browser or Rational Team Concert to support form-based authentication. You should consult the documentation for any feed readers you'd like to support for further information on what authentication methods are supported.

If you want to make feeds available to any feed reader, it is possible to unsecure the URLs for feeds only. This should be done only after deliberate consideration of the security implications. If you unsecure the feeds, you are allowing unsecure, unauthenticated access to any info in the feed itself, but not to the repository artifacts. For example, a feed entry about a work item change may contain the description or the comment from the work item, but it still would not be possible to fetch the entire work item or related artifacts unsecurely.

You can use the following guidelines to help with your decision on what auth. method to use and whether to unsecure the feeds:

No one in your project needs to access feeds outside of Rational Team Concert or a web browser.
You should use the default auth. method of FORM and keep everything secure.

You are using Tomcat, and are not interested in writing a custom module to cache credentials.
You should use the default authentication method of FORM in order to see adequate performance.

You would like feeds to be accessible to other feed readers, but they must be secured to authorized users only.
You can configure for BASIC auth., and deploy to WebSphere, which has built-in caching support for authentication. Because of the security constraints there will still be some feed readers that will not be able to view the feeds. We also do not recommend using BASIC auth on Tomcat due to the performance penalty.

You would like feeds to be accessible to other feed readers, and it is okay for them to be visible without security.
Use this option only if you are sure no sensitive data will be leaked by exposing events from your server.

Unsecuring the Feeds

With all of the disclaimers out of the way, this section describes how you can unsecure the feeds.

  • Open up the Admin web UI of your server by going to https://<yourserver>:9443/jazz/admin
  • Click the 'Advanced Properties' link on the left of the page
  • Find the entry for "Allowed Anonymous URL Prefixes" and set the value to "events"
  • Click 'save' at the top of the page.

Accessing Unsecure Feeds

Following is an example feed URL copied from the Team Artifacts view in Rational Team Concert:

Figure 3: Example Feed in Rational Team Concert


In this example, the client was connected to the server running on localhost, and connected to the JUnit Project example project area. And below is a modified version of this URL with the following changes:

  • Changed protocol to http instead of https
  • Change to the unsecure port 9080 instead of 9443
  • Replaced jazz/service/ with the alias jazz/events
  • Replaced substitution variable {$user} with an actual user name

The above feed URL can be used in any third party feed reader without security while all other server operations will still require authentication.


The following documents provide information related to this topic.

Was this information helpful? Yes No 18 people rated this as helpful.