Recently the question how to authenticate to a ELM/CLM (aka Jazz) application came up in several occasions. I did not know the whole story either, so I had a look. Here is what I found.
Update history
2019/05/14 Added Basic Authentication
2021/01/22 Added Links
Important Links
- The ELM API Landing Page note the entries for the OSLC Workshop and OSLC in general.
- Especially the explanation about client authentication to ELM
- The Interesting Links for examples
- The Learning To Fly: Getting Started with the RTC Java API’s page with an API overview for RTC.
- OSLC Frameworks and examples can be found in the Eclipse Lyo project.
Scenarios
There are several scenarios that could be of interest. Some of the scenarios will be provided below. A general documentation about how the authentication of a client to a Jazz application works is provided here in the development wiki.
Common scenarios are as follows:
- Using a REST client to explore the REST/OSLC APIs
- Creating custom automation using REST/OSLC APIs
Scenario 1 is also used in the OSLC Workshop. However, as explained below, things have changed since the workshop was initially written and the latest changes are not addressed in the workshop.
REST clients
The main changes that could be recognized are in the browsers and the integration of REST clients. These changes heavily impact how easy or hard it is to login. The first REST client used in the OSLC workshop was the Firefox browser addon REST Client . Using this addon It is easy to login to the Jazz application. All that needs to be done is
- Open a browser window
- Provide the URL to the CLM application and open the URL
- The application prompts for a login
- Provide user name and password and perform the login
- Open the REST Client Addon
The REST client addon uses the login performed in the steps above for subsequent calls to the server. This makes it easy, because it is transparent and there is no reason to worry about the details. The browser basically handled them.
Similar addons are available for the Chrome Browser. Examples are
- The Advanced REST Client as shown in this post.
- Postman as a Chrome App as explained at the end of the post above, which is no longer available.
- Tabbed Postman as Chrome App.
The browser integrations above all allowed to use the browser to login and use the login information in subsequent calls. These browser addons or extensions used to be very popular, but security threats and changes in integration philosophies seem to make them more and more unavailable. Some of the addons mentioned above are discontinued and might not be available much longer.
The Postman as packaged app as explained at the end of this post is currently still available and allows to configure a Postman Interceptor, that intercepts the login information from the browser and uses it in later calls. So it works like the solutions 1-3 above and the REST clients available as Firefox addons or extensions.
Alternatives are standalone solutions like Postman as standalone App which seems to be the path forward for Postman. There are many other stand alone REST clients. The caveat is, that the simple option to just login to the Jazz application is no longer available as an option. So it is important to know the details,
When trying to write custom tooling that needs to access data on a CLM/ELM server, it is also necessary to understand the details.
Testing and special considerations
It is a good idea to have a test system. Ideally local on your own machine. You can follow Lab 1 of the Rational Team Concert Extensions Workshop to set up a small system with JTS and RTC. It is not necessary to install the plain Java client libraries, any of the SDKs or to run the WorkshopSetup application. It is possible to install the other applications as well sing the Web Installer or one of the many Installation Manager repositories.
Create the sample project in the lifecycle project administration section to have data to play with.
Postman Settings
This blog shows the examples using Postman as standalone App which is very useful and allows to save and organize calls as a benefit. Like any application there are usually settings that can be beneficial or get into the way. Here the settings of interest in the context of this blog.
Disable SSL Certificate Verification
Please be aware that the SSL certificates of a test system as described above will typically be considered invalid. It is very common that test systems have invalid SSL certificates. A common issue is that the certificate is self signed and often for a different or generic host name. In such cases SSL certificate validation throws an error. Browsers, REST clients and APIs often reject working with servers presenting invalid SSL certificates. It is usually necessary to create exceptions or to configure the systems to ignore the SSL validation error.
Make sure the REST client or API works with sites that have invalid SSL certificates, or provide valid SSL certificates.
Postman rejects communicating with servers using invalid SSL certificates and displays an error message. This can be changed by changing the settings, turning the setting ‘SSL certificate verification’ to off. Postman now allows communicating to servers using invalid SSL certificates.
As an alternative, it is possible to provide valid certificates. It is also possible to use any other test system that might be available, especially when dedicated test systems with valid certificates are available. The screen shots in this blog refer to a test system that has been set up similar to the Extensions workshop, but with all applications installed and the sample lifecycle project being deployed.
Automatically Follow Redirects
By default Postman automatically follows redirects. This can be nice but it hides a lot of details. To better understand the details explained in the wiki page Authentication of a native client with a Jazz-based application, switch the setting automatically follow redirects to off.
With the redirects disabled it is possible to see the 302 response as explained in Authentication of a native client with a Jazz-based application.
Minimal Header settings
When following redirects automatically, postman also collects several cookies. To focus on the really important details, and understand which headers and cookies are really needed, the setting below is very helpful.
Form based authentication
As explained in the wiki page Authentication of a native client with a Jazz-based application, there are multiple scenarios, how a client login would be performed. Unfortunately the number of scenarios are getting more over time as new standards are becoming available.
The easiest to use method that has worked for me so far has been the Form Based authentication. This works in a simple set up of CLM with any application server in a standard configuration without Jazz Authorization Server (OIDC) installed.
Perform a Form based authentication login to an application
To perform the Form based authentication to the application use the context root of the JTS or the application and append /j_security_check to the context root to create the login URI.
With a given context root of e.g. https://clm.example.com:9443/jts for JTS, the URI to login is https://clm.example.com:9443/jts/j_security_check.
As explained in Authentication of a native client with a Jazz-based application, the authentication is performed with a POST to the URI https://clm.example.com:9443/jts/j_security_check with a request body that contains the x-www-form-urlencoded encoded username and password.
The image below shows the simplest way of performing the authentication using Postman.
The POST to the secure resource URI provides the username and password using the form encoded key and value pairs for the j_username and j_password. password and username are both identical myadmin.
The code for this request is shown below.
POST /jts/j_security_check HTTP/1.1 Host: clm.example.com:9443 cache-control: no-cache j_username=myadmin&j_password=myadmin
Please note that there are no additional headers necessary. The request does not specify anything in the request for Parameters, Authorization, Headers, Pre-request Script or Tests.
The response shows status 302. There is no header X-com-ibm-team-repository-web-auth-msg. There is no header Location with any value, let alone
/auth/authfailed. This indicates the authentication was successful.
The Cookies keeps the LtpaToken to authenticate.
If the setting for Automatically follows redirects is on, and other header options are also set to on, the request would be redirected and likely show a status 200. There would be a lot more headers and Cookies collected as well.
Once successfully authenticated, it is possible to send other requests passing the Cookies. For this OSLC request it is also necessary to pass an accept header and the OCLS-Core-version header.
Please note that the Jazz Product APIs might need other special handling. In the above example the communication returns an additional Cookie JSESSIONID. In subsequent calls provide a header JSESSIONID with the value of the returned Cookie.
The easiest way to ‘log out’ is to delete the Cookies for the server.
The request above can also be created by using a special content header Content-Type:application/x-www-form-urlencoded and a raw post body with a special encoding.
j_username=myadmin&j_password=myadmin
The images below show how this looks like in Postman.
This code shows the whole POST information.
POST /jts/j_security_check HTTP/1.1 Host: clm.example.com:9443 Accept: / X-Requested-With: XMLHttpRequest Content-Type: application/x-www-form-urlencoded cache-control: no-cache j_username=myadmin&j_password=myadmin
Authentication Failure
The Following image shows an unsuccessful authentication due to a typo in the password. This is only one of the possible flows, but the other scenarios are handled the same way.
The response shows status 302. There is however a header Location with value /auth/authfailed. This indicates the authentication was not successful.
If the setting for Automatically follows redirects is on, the request would be redirected and likely show a status 200. The response body contains a page that the client could show to allow the user to enter the user ID and the password to authenticate. This web page uses JavaScript. Because the REST client Postman does not support JavaScript execution the page shows an error.
Where to Authenticate
My understanding so far has been that the CCM and the QM server have their own authentication. The RM server delegates authentication to the JTS. The Lyo implementation uses the public URI of the applications to create the authentication request. For the RM application it uses JTS instead.
The document Authentication of a native client with a Jazz-based application, seems to imply that authenticating to the JTS should do the trick for all applications. Using this has, so far, not caused any problems, so my suggestion would be to use the JTS URI to authenticate.
If you experience any issues, fall back trying to use the application specific URI.
Basic Authentication
Although Form based authentication has been the preference, Jazz also supports Basic authentication. However, when using Jazz Authorization Server/OIDC, Basic authentication is not supported. See this section (since 6.0.6).
See this information to understand the details.
As a summary, for Basic authentication, a special header Autorization that contains username and password encrypted in Base64 is sent with each request. The request below shows the header
Authorization: Basic c29tZXVzZXI6c29tZXBhc3N3b3Jk
Testing and special considerations
When using Basic Authentication in Postman it is useful to have the Automatically follow redirects setting to be on.
To configure Basic authentication in Postman, select the Authorization type Basic Auth and enter the username and the password. Postman generates the authentication header. When using the API or other tools that do not create the authentication header, it has to be created and added.
The call below gets the workitems catalog for a RTC server on Jazz.net. This requires sending a valid Accept header and the OCLS-Core-version header.
The code below is the important information.
GET /jazz/oslc/workitems/catalog HTTP/1.1 Host: jazzdev.rtp.raleigh.ibm.com:9443 Accept: application/xml OSLC-Core-version: 2.0 Authorization: Basic c29tZXVzZXI6c29tZXBhc3N3b3Jk cache-control: no-cache
When sending the request, the final response should have a status 200.
Please be aware that basic auth does not have a session handling and you have to always send the authentication header.
Malicious website
I am currently working with a customer trying to authenticate to one of their CLM systems. This seems to work except with the CCM server. When they try to authenticate they get the following message.
You have followed a direct link to log in to a Jazz server. This page has been presented to ensure that a malicious website cannot use cleverly crafted content to circumvent security. Please log in if you would like to access the server.
We are looking into what could cause this issue. The web does not provide any good explanation. I found some questions in the Forum and other places and think I noticed a pattern. Several requests I have seen used a wrong URI to authenticate.
When using URIs like https://clm.example.com:9443/ccm/authenticated/j_security_check or
https://clm.example.com:9443/ccm/j_security_check and GET them in a browser, I get the same error.
It is currently unclear what is happening and how to resolve the issue the customer is seeing. I will update the post, if we can figure out what is going wrong.
Summary
This blog post tries to shed some light on how to log into a CLM System to be able to use the REST and OSLC APIs. This should work for manual work as well as for automation tools. This blog uses Postman, but any REST client should work. The details, especially covering redirects and different authentication methods can be found inn this document Authentication of a native client with a Jazz-based application.
As always, I hope that this post helps users out there with using their Jazz tools.
rsjazz 
Hi Ralph,
Did you have a chance to determine the solution for Malicious website issues? I have already another client having that issue.
What is the ‘Malicious website issue’ Chris? I can not answer a question without any context.
Chris, I explained the situations I was able to create the situation that the Jazz Server or the CCM responded with that error.
I usually tried to access pages directly, which would usually only be accessible through a redirect within the server. I can imagine that inconsistent names could be a problem e.g. in certificates.
I have created a situation on my laptop where I maintain two host names with the same IP using the hosts file. One is an older e.g. clm.example.com instead of elm.example.com. If I have a server using elm.example.com and try to access it as clm.example.com I reach it, but some APIs fail.
This is very useful! Thank you!
Do you know how to find out the LTPAtoken2 code expiry time? what is the default time? and is it possible to change it? knowing that our RTC is deployed on IBM WAS 9.0.5
Thank you again RTC godfather!
Mohammad
Sorry, I do not know that. This would be WAS specific.
Google: https://www.ibm.com/docs/en/jfsm/1.1.3.0?topic=hub-configuring-ltpa-token-timeout-value