TN0013: Jazz Server Authentication Explained

Ritchie Schacher, John Vasta
Last Updated: April 30, 2015
Build Basis: Rational Collaborative Lifecycle Management 6.0

Summary

Jazz applications that are included with Collaborative Lifecycle Management (CLM) or Systems and Software Engineering (SSE) are deployed as Java Enterprise Edition (Java EE) Web Applications, and as such run within a supported Java EE application server (IBM WebSphere Application Server or Apache Tomcat). By default, the “core” applications (Jazz Team Server, Rational Team Concert, and Rational Quality Manager) use Java EE authentication per the Java Servlet specification, and the other applications (for example, Rational Doors Next Generation) delegate authentication to a Jazz Team Server. The 6.0 software release adds two new authentication options, Jazz Security Architecture based on OpenID Connect, and Kerberos.

This note explains the authentication mechanisms used by Jazz applications, and reasons for choosing one over the other. It also describes how to change the configuration to use alternate authentication methods and how to unsecure feed URLs for a custom deployment, along with the tradeoffs associated with each configuration.

More Information

Authentication Mechanisms

There are three options available for configuring user authentication in Jazz products.

Jazz EE container authentication

The “web container”, or application server (WebSphere or Tomcat), handles authentication for the Jazz Team Server, Rational Team Concert, and Rational Quality Manager servers. All other applications delegate authentication to the Jazz Team Server (by redirecting clients to the Jazz Team Server to authenticate with it). This is the default configuration, and is the only configuration supported in releases prior to 6.0. Of the four types of login allowed by the Java EE servlet specification, Jazz supports three of them: form (the default), Basic, and client certificates. When applications are deployed in separate application servers, by default users must login to each of them, though WebSphere servers can be configured to implement single sign-on across a collection of servers.

Figure 1: Container Managed Authentication

Jazz Security Architecture Single Sign-On (SSO) based on OpenID Connect

The OpenID Connect (OIDC) authentication protocol was established in early 2015 as an extension of the OAuth 2.0 protocol, designed to be easier to adopt across a wide range of clients (native applications, browsers, browser-based applications, and mobile devices). It is extensible and configurable (with optional features). Jazz Security Architecture is a particular profile of OIDC, specifying which optional features are included, and a few extensions. Authentication is handled by a separate OpenID provider (OP, also known as an authorization server); Jazz applications delegate to that provider instead of relying on the application server to handle authentication. Single sign-on is supported across all applications that are configured to use the same OP. This option became available in the 6.0 software release, which includes the Jazz Authorization Server, an OP that supports the Jazz Security Architecture profile.

When Jazz Security Architecture SSO is enabled in an application that would normally delegate authentication to a Jazz Team Server, then the application will instead delegate to the Jazz Authorization Server using OIDC, unless the incoming request uses the OAuth 1.0a protocol. In that case, the application still delegates OAuth 1.0a authentication to a Jazz Team Server (more on that below).

Figure 2: Jazz Security Architecture Single Sign-On

Kerberos

Kerberos is another industry-standard authentication protocol that has been in use for some time. It is the default authentication mechanism used by Microsoft Windows servers and clients. As of the 6.0 software release, the Rational Team Concert server and its clients support Kerberos, when the servers are deployed in a WebSphere Application Server which is configured to use a Windows Active Directory server for authentication. Users can experience single sign-on between their Windows clients and one or more Rational Team Concert servers. (Note that Kerberos authentication is actually another form of container authentication, since it is implemented by WebSphere, but it is distinct from standard Java EE container authentication.)

Figure 3: Kerberos Single Sign-On

Security Roles

The above mechanisms handle authentication, which determines the identity of the user. Jazz applications also define access levels, known as security roles, which determine whether a user is allowed to read, write, or administer various resources. When using Java EE container authentication (or Kerberos), the web container is responsible for mapping a user’s group memberships to security roles. When using Jazz Security Architecture SSO, the applications themselves are responsible for performing the group-to-role mapping. During the processing of a request that has been authenticated with some user identity and security roles, the Jazz application servicing the request enforces any security role requirements.

Jazz applications use the following pre-defined security roles:

Role Name	Description
JazzAdmins	Administrators of a Jazz application with full read-write access
JazzProjectAdmins	Administrators of a Jazz application with specific permissions to control the creation and maintenance of Jazz Projects
JazzUsers	Users with regular read-write access to the Jazz application
JazzGuests	Users with read-only access to the Jazz application.
JazzDebug	Users who are allowed to access the Jazz Repository Debug service.

The roles are declared in application deployment descriptors for applications that can be configured for container authentication (described later). These roles map to group membership within the authentication realm configured in the container.

Container Authentication

Of the four authentication methods defined by the Java EE Servlet specification, Jazz supports three of them: FORM, BASIC, and CLIENT-CERT. The table below describes the differences, advantages and disadvantages of each:

METHOD	FORM	BASIC	CLIENT-CERT
Behavior and Implementation	Jazz 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	A user’s credentials consist of a secure certificate (possibly provided by a “smart card”)
Advantages	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	No username/password login is required by the user.
Disadvantages	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 a secure connection (TLS) to prevent identity theft Because authentication is required on every request, results in severe performance penalty in containers that don’t cache credentials	Requires management and distribution of client certificates or smart cards Distinct protocol requires special knowledge and code for programmatic HTTP client access Most third party feed clients will not understand this protocol

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 Jazz applications. However, the application has been tested using BASIC and CLIENT-CERT 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, or if your organization uses client certificates or smart cards.

Deployment Descriptor

Java EE applications are packaged with a deployment descriptor, which is a configuration file that defines how the application server is to load, execute, and secure the application. The deployment descriptor is packaged as a file at the path WEB-INF/web.xml in the application’s Web ARchive (WAR) file.

There are two kinds of deployment descriptors used by Jazz applications: those that support container authentication (Jazz Team Server, Rational Team Concert, Rational Quality Manager) have deployment descriptors that define a secure URL (one that will trigger authentication when accessed by a client), define the Jazz security roles described above, and specify what form of container authentication to use (FORM, BASIC, or CLIENT-CERT). All other applications delegate authentication to a Jazz Team Server by redirecting a client to the Jazz Team Server, so their deployment descriptors do not define any secure URLs, security roles, or login method.

The security roles are defined in the following segment of the container-authenticating deployment descriptor:

      <security-role>          <role-name>JazzAdmins</role-name>      </security-role>            <security-role>          <role-name>JazzProjectAdmins</role-name>      </security-role>            <security-role>          <role-name>JazzUsers</role-name>      </security-role>          <security-role>          <role-name>JazzGuests</role-name>      </security-role>        <security-role>          <role-name>JazzDebug</role-name>      </security-role>  

These roles are used to configure access to web resources. For example, the following segment by default secures the /secure/authenticated/identity URL in the application, requiring authentication by users with one of the security roles:

      <security-constraint>          <web-resource-collection>              <web-resource-name>secure</web-resource-name>              <url-pattern>/secure/authenticated/identity</url-pattern>          </web-resource-collection>  	          <auth-constraint>              <role-name>JazzUsers</role-name>              <role-name>JazzAdmins</role-name>              <role-name>JazzGuests</role-name>              <role-name>JazzProjectAdmins</role-name>              <role-name>JazzDebug</role-name>          </auth-constraint>                    <user-data-constraint>              <transport-guarantee>CONFIDENTIAL</transport-guarantee>          </user-data-constraint>      </security-constraint>  

If a request is received at some other URL that should require authentication, and the user has not been authenticated yet, and the application is configured for container authentication, then the application will redirect the client to the /secure/authenticated/identity URL to trigger authentication. This “indirect authentication” technique is used to allow switching from Java EE container authentication to some externally-provided authentication service (i.e. OIDC, as provided by Jazz Security Architecture SSO) without having to provide alternate deployment descriptors.

In applications that delegate authentication to a Jazz Team Server, no <security-constraint> element appears in their deployment descriptors. When such an application receives a request for a service that requires authentication, and the user has not been authenticated yet, the client is redirected to authenticate with the Jazz Team Server, which then issues an access token representing the user’s identity to the delegating application. That application will then return a session cookie to the client that represents the user’s authenticated session with the application. Subsequent requests from the client to the same application will include the session cookie, and from that the application can determine that the user has already been authenticated, avoiding the redirection to the Jazz Team Server on every request.

Configuring the container 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, uncomment the <login-config> element that is used for BASIC:

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

You can change the realm name if you like; it will be displayed to the user when they log in to the application.

If you are using Tomcat, you must also modify the “server/tomcat/webapps/<app>/META-INFO/context.xml” file and change the className attribute on the “Valve” element from:

org.apache.catalina.authenticator.FormAuthenticator

to

org.apache.catalina.authenticator.BasicAuthenticator

You must also remove the characterEncoding attribute.

Figure 4: Example of a BASIC login dialog, using a realm name of “XYZ Enterprise Directory”

Configuring client certificate or smart card authentication also involves changing the deployment descriptor, as well as configuring WebSphere Application Server to accept the certificates. Detailed instructions can be found in the Configuring certificate authentication in Rational Team Concert 3.0 using WebSphere Application Server 7.0 article.

Jazz Security Architecture Single Sign-On

Starting with the 6.0 software release, Jazz Security Architecture SSO is available as an authentication option. Based on OpenID Connect, authentication is not performed by the container hosting Jazz applications, but instead is delegated to a separate Jazz Authorization Server, which performs the role of an OpenID Connect provider (OP). When a user logs into a Jazz application, the OP generates a token for the user (known as a bearer token) that can then be used to authenticate with any application that is configured with the same OP. Therefore, Jazz Security Architecture provides a single sign-on experience that is independent of the type of application container, unlike Kerberos, WebSphere, and Tomcat single sign-on mechanisms. Also, since only a single server (the Jazz Authorization Server) must be configured for authentication, it is simpler to set up, compared with configuring multiple Jazz Team Server, Rational Team Concert, and Rational Quality Manager servers that are running in separate containers.

Configuring Jazz applications for Jazz Security Architecture SSO is either done at install time, for new installations, or done as a migration procedure, for existing installations that are using some other form of authentication.

For information on enabling Jazz Security Architecture when installing CLM, see the “Installing the Rational solution for Collaborative Lifecycle Management by using Installation Manager” topic in the Jazz Team Server Installing book in the IBM Knowledge Center.

For information about how to migrate existing CLM applications to Jazz Security Architecture SSO after upgrading, see the “Enabling Jazz Security Architecture single sign-on after upgrading” topic in the Jazz Team Server Upgrading and migrating book in the IBM Knowledge Center.

Kerberos Single Sign-On

Starting with the 6.0 software release, Kerberos is available as an authentication option. Kerberos is a network authentication protocol that relies on a trusted, external service to authenticate users and issue tickets, which can then be used to access any application that is secured by the same Kerberos environment. In particular, since Microsoft Windows uses Kerberos by default, users that log in to the Windows operating system can access Jazz applications configured for Kerberos without any further authentication required, using Jazz clients or web browsers running on the same Windows workstation. Users can also use clients running on non-Windows operating systems, but have to do a separate “Kerberos login”.

As of the 6.0 release, Kerberos authentication is supported by the Rational Team Concert server and clients, and by the associated Jazz Team Server. Those Jazz applications must be deployed in WebSphere Application Server version 8 or later, configured to use a Windows Active Directory server for authentication.

Configuring Jazz applications and WebSphere servers for Kerberos authentication requires planning your deployment and attention to configuration details. For information on configuring Kerberos, see the “Configuring Kerberos single sign-on authentication” topic in the Jazz Team Server Installing book in the IBM Knowledge Center.

Application to Application Authentication

In addition to authenticating end users that access Jazz applications, applications also authenticate requests sent by other applications. In particular, applications that participate in Open Services Lifecycle Collaboration use linked data to share and connect resources across application development domains. When traversing those links, applications authenticate with each other, on behalf of the user navigating the links. Applications can also directly invoke services in other applications as “functional” user identities, representing the applications themselves (typically done by background tasks not directly invoked by a user). There are two forms of application-to-application authentication implemented by Jazz applications, OAuth 1.0a and OpenID Connect.

OAuth 1.0a

Up until the 6.0 software release, OAuth 1.0a was the only type of inter-application authentication supported. It requires pair-wise relationships between communicating applications – applications that are registered as “friends” of each other can send requests to each other that will be authenticated using OAuth 1.0a. For bi-directional communications, each application must be a friend of each other. The friending application is allocated a key and secret which it uses to authenticate with the friend application; they are the equivalent of a username and password for the application itself.

When applications send requests to each other on behalf of a user, the user must allow the interaction to take place by authenticating with the target application. For example, if the user is looking at a work item in Rational Team Concert which has a link to a test case in Rational Quality Manager, in order to see any details of that test case in the Rational Team Concert UI, the user must also be authenticated with Rational Quality Manager. If not, a “log in” prompt will appear in the Rational Team Concert UI where the test case details would normally be shown. Whether or not users encounter these additional login requests depends on whether the applications are deployed with some single sign-on configuration or not. For example, if all applications are deployed in a single application server (whether WebSphere or Tomcat), then single sign-on is achieved by default. Otherwise, applications could be deployed in multiple WebSphere servers with SSO configured using Lightweight Third-Party Authentication (LTPA).

OpenID Connect

When applications are configured with Jazz Security Architecture SSO enabled, they can use OpenID Connect to authenticate with each other. In that case, no pair-wise relationships are needed between applications for authentication purposes; no “keys” or “secrets” are held by applications in order to authenticate with each other. Instead, when a user authenticates with an application that has Jazz Security Architecture SSO enabled, that user is automatically authenticated with all other applications that are registered with the same Jazz Authorization Server as the first application. Therefore, applications can invoke services in other applications on behalf of the user without requiring additional logins.

Applications that have Jazz Security Architecture SSO enabled can still use OAuth 1.0a to communicate with applications that do not have Jazz Security Architecture SSO enabled, so it’s possible that a given application would use OIDC to communicate with some applications, and OAuth 1.0a to communicate with others. In that case, however, the user will most likely encounter additional login prompts when viewing linked resources.

Jazz Feeds and Security Considerations

Jazz servers provide 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 third 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 authentication 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 authentication method you prefer and keep everything secure.

You are using Tomcat, and are not interested in writing a custom module to cache credentials.
You should use an authentication method other than BASIC 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 authentication, 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 authentication 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/<app>/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 5: Example Feed in Rational Team Concert

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

  http://localhost:9080/ccm/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.

• Native Client Authentication (Jazz development wiki) – a technical deep dive into implementing programmatic authentication with a Jazz application
• Java Servlet Specification