Jazz Library Configuring Certificate Authentication for CLM on Liberty Profile
Author name

clm,design-management,elm,elo-engineering-insights,requirements-management-doors-next,test-management,workflow-management,continuous-engineering-solution,jazz-foundation,jazz-reporting-service,rational-doors-next-generation,rational-engineering-lifecycle-manager,rational-quality-manager,rational-team-concert,sse

Fri, 27 Oct 2017
5 min read
0

Configuring certificate authentication for Rational solution for Collaborative Lifecycle Management on Liberty Profile

Shubjit Naik, IBM
Last updated: 26 October 2017
Build basis: Rational solution for Collaborative Lifecycle Management, versions 6.0.2 and higher

 

You can configure the Rational solution for Collaborative Lifecycle Management (CLM) applications and WebSphere Liberty Profile to log in using a certificate (.p12) file or a smart card, which are more secure login methods than using a user name and password.

Although a certificate file and a smart card are different, they are both certificates that are used for authentication. Certificate authentication is more secure than BASIC and FORM-based authentication. Certificate authentication uses HTTP over SSL and authentication occurs by using a public key certificate that is issued by a trusted organization, which is known as a certificate authority.

Before you begin

Before you can configure certificate authentication, complete the following tasks:

  • Configure WebSphere Liberty Profile to use your preferred user registry, LDAP, or federated realms.
  • Ensure that a Certificate Authority and user certificates already exist and that the Certificate Authority’s public certificate is available to the administrator. For information about how to create SSL certificates, see SSL Certificates HOWTO.
  • Copy the Certificate Authority’s public (root) certificate to the computer that hosts WebSphere Liberty Profile

Configuration overview

There are 3 components involved in this configuration:

  1. WebSphere Liberty Profile hosting CLM Applications(Application Server)
  2. Jazz Applications
  3. Clients

Configuring WebSphere Liberty Profile hosting CLM applications to accept client certificates

Configure WebSphere Liberty to support or require client certification authentication at the transport layer. To configure Liberty server for client certificate authentication on the SSL configuration, add the ssl-1.0 Liberty feature to the server.xml file, along with code that communicates the keystore information for authentication to the server.

Procedure

  1. Edit the server.xml file that is located at [JAZZ_HOME]\server\liberty\servers\clm
  2. Add the parameter clientAuthenticationSupported=”true” within the SSL configuration as follows:
    < ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL" trustStoreRef="defaultTrustStore" 
    clientAuthenticationSupported="true" serverKeyAlias="<Server_CA_Cert>" />

    If you specify clientAuthentication=”true”, the server requests that a client sends a certificate. However, if the client does not have a certificate, or the certificate is not trusted by the server, the handshake does not succeed.
    If you specify clientAuthenticationSupported=”true”, the server requests that a client sends a certificate. However, if the client does not have a certificate, or the certificate is not trusted by the server, the handshake might still succeed.
    If you do not specify either clientAuthentication or clientAuthenticationSupported, or you specify clientAuthentication=”false” or clientAuthenticationSupported=”false”, the server does not request that a client send a certificate during the handshake.

Configuring certificates, the defaultKeyStore, and the defaultTrustStore

Configure the default Keystore with a server certificate from the certificate authority where the common name in the certificate matches the FQDN that is used in your CLM Server public URI. Also configure the default TrustStore with certificate authority’s root certificate, so that the server can trust the client certificates.

Procedure

Configuring defaultKeyStore

  1. Import your CA certificate into the default keyStore that is located at [JAZZ_HOME]\server\liberty\servers\clm\resources\security. The default keyStore file used in Liberty is ibm-team-ssl.keystore and password is “ibm-team”.
  2. Use ikeyman or javatool to import the CA certificate to ibm-team-ssl.keystore.
  3. Note the KeyAlias/Label of the imported certificates and include it in the <ssl> configuration “serverKeyAlias”.
  4. Edit server.xml file located at <JAZZ_HOME>\server\liberty\servers\clm.
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL" trustStoreRef="defaultTrustStore" 
    clientAuthenticationSupported="true" serverKeyAlias="<Server_CA_Cert>" />

     

  5. Edit the defaultKeyStore element if there are changes to your keystore location/password.

    <keyStore
     id="defaultKeyStore"
     location="ibm-team.keystore"
     type="JCEKS"
     password="{xor}Nj0ycis6Pjl="/>

Configuring defaultTrustStore

  1. Create a New TrustStore using ikeyman or keytool (IBM JRE) and import the root/public certificate from the CA authority.
  2. Include the new TrustStore name under <ssl> configuration in server.xml file that is located at [JAZZ_HOME]\server\liberty\servers\clm
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL" 
    trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true" serverKeyAlias="<Server_CA_Cert>"/>
  3. Add the new TrustStore details below the defaultKeyStore configuration.
    <keyStore 
     id="defaultTrustStore"
     location="trust.jks"
     type="JKS"
     password="<TrustStore_Password>" />

  4. OR import the root/public certificate from the CA authority into your defaultKeyStore and use it as your trust store “trustStoreRef”. Below the default KeyStore is used for the default TrustStore.

    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" sslProtocol="SSL" 
    trustStoreRef="defaultKeyStore" clientAuthenticationSupported="true" serverKeyAlias="<Server_CA_Cert>"/>

    For more information, see Configuring your web application and server for client certificate authentication.

Configuring Liberty Profile to map incoming certificates to users in the registry

WebSphere Liberty accepts incoming certificates as an authentication mechanism, but the server is not configured to map the incoming certificates to users. Provide a mapping strategy between certificates and users in the registry. The mapping is described through two settings: Certificate mapping mode and Certificate filter. Regardless of the user registry that you use, you must know the values for those two settings.

Certificate filter

Specifies the filter certificate mapping property for the LDAP filter. The filter is used to map attributes in the client certificate to entries in the LDAP registry. If more than one LDAP entry matches the filter specification at run time, authentication fails because the result is an ambiguous match. The syntax for this filter is: LDAP attribute=${Client certificate attribute}.

An example of a simple certificate filter is: uid=${SubjectCN}. For more information see the related Liberty Documentation.

Here is an example of an LDAP configuration with certificate filter mode enabled:


<ldapRegistry id="LDAP" realm="SampleLdapIDSRealm" 
 host="myldap.ibm.com" port="389" ignoreCase="true" 
 baseDN="o=ibm,c=us" 
 certificateMapMode="CERTIFICATE_FILTER" 
 certificateFilter="uid=${SubjectCN}" 
 userFilter="(&amp;(uid=%v)(objectclass=ePerson))" 
 groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
 (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))" 
 userIdMap="*:uid" 
 groupIdMap="*:cn" 
 groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
 groupOfNames:member;groupOfUniqueNames:uniqueMember" 
 ldapType="IBM Tivoli Directory Server" searchTimeout="8m" />

Configuring Jazz applications to require certificate-based authentication

WebSphere Liberty Profile is now configured to allow certificate authentication and map incoming certificates to known users, but you must also configure the CLM applications to accept certificate-based authentication.

By default, the applications use FORM-based authentication, declared in the deployment descriptor WEB-INF/web.xml file in the <login-config> XML element. To enable certificate authentication, edit the <login-config> XML element of the application .war files. You only need to change web.xml for applications jts.war, ccm.war, and qm.war. The rest of the applications depend on JTS for authentication.

Procedure

Complete the following steps on all of your Liberty servers, hosting any jts, ccm and qm war files, to configure the applications:

  1. Navigate to the directory where you installed CLM. The default path for the application .war files is: [JAZZ_HOME]/server/liberty/servers/clm/apps
  2. If this is a new installation and the Liberty server has not been started, the servers/clm directory has not been created. In this case, navigate to [JAZZ_HOME]/server/liberty/clmServerTemplate/apps
  3. Navigate to the <app>.war/WEB-INF directory and open the web.xml file for editing.
  4. Search for the <login-config> element and change <auth-method>FORM</auth-method> to <auth-method>CLIENT-CERT</auth-method>
    Note: Only one <login-config> XML element is allowed, so either delete or comment out any other <login-config> XML elements.
  5. Save and close the web.xml file.

Configuring clients to authenticate via user certificates

Web browser

To configure web browsers to authenticate to applications via certificates:
  1. Import the user certificate into the browser as personal certificates.
  2. On Microsoft Windows, double-click on the user certificate and follow the steps in the wizard to import the certificate to your web browser.
  3. After the import completes, on accessing any of the CLM applications, the imported certificates are listed. Select the appropriate user certificate to log in to CLM.
  4. To confirm, check the user name that is displayed at the top-right corner and confirm if it matches your user ID.


Eclipse and Visual Studio clients

To log in to the application by using the Eclipse client or the client for Microsoft Visual Studio:

  1. Create a new repository connection and configure it to use the certificate authentication.
  2. Change authentication type to SSL certificate.
  3. Browse for the user certificate and enter the password. Click Finish to log in.

Repotools Utility

Following is an example of using a User Certificate and password to execute repotools commands


> repotools-ccm.bat -backupJFSIndexes repositoryURL=https://ibmclm.vapp.com:9443/ccm 
certificateFile="C:\Certs\MyCert.p12" adminPassword="MyPassword" toFile=C:\Test\CCMIndexBackup.zip

For more information

About the author

Shubjit Naik, a member of the Global Response Team, has dedicated over a decade of his time to Client Success. He specializes in the Deployment and Security aspects of the Rational solution for Collaborative Lifecycle Management (CLM). He can be contacted at shubjit.naik@in.ibm.com

© Copyright IBM Corporation 2017

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Fri, 27 Oct 2017