Summary

The Jazz Team Server that ships with Rational Team Concert 1.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

Background

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 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:

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:

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:

    <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>

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 -->
    <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>
        </auth-constraint>
        
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

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:

    <login-config>
        <auth-method>FORM</auth-method>
        <form-login-config>
            <form-login-page>/auth/authrequired</form-login-page>
            <form-error-page>/auth/authfailed</form-error-page>
          </form-login-config>
    </login-config>    

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

    <login-config>
        <realm-name>RealmName</realm-name>
        <auth-method>BASIC</auth-method>
    </login-config>

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:

org.apache.catalina.authenticator.FormAuthenticator

to

org.apache.catalina.authenticator.BasicAuthenticator

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.

Edit the web.xml deployment descriptor, and add the following section with the other security-constraint elements:

    <!-- opens up /jazz/events -->
    <security-constraint>
       <web-resource-collection>
           <web-resource-name>unsecure_feeds</web-resource-name>
           <url-pattern>/events/*</url-pattern>
       </web-resource-collection>        
    </security-constraint>

The /events namespace is an alias for all feeds. Opening up this pattern allows the feeds to be accessed unsecurely.

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

https://localhost:9443/jazz/service/com.ibm.team.repository.common.internal.IFeedService?
provider=team&project_area=JUnit+Project&user={$user}

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/com.ibm.team.repository.common.internal.IFeedService with the alias jazz/events
• Replaced substitution variable {$user} with an actual user name

http://localhost:9080/jazz/events?provider=team&project_area=JUnit+Project&user=schacher

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

References

The following documents provide information related to this topic.

• Form Based Auth (Jazz development wiki)- a technical deep dive into programmatic form based authentication with the Jazz Team Server
• Java Servlet Specification