Configuring certificate authentication in Engineering Lifecycle Management

You can configure the Engineering Lifecycle Management applications and IBM® WebSphere® Liberty to log in using a certificate (.p12) file or a smart card, which are more secure than logging in with 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, you must complete the following tasks:

Configure WebSphere Liberty server 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 root certificate authority's public certificate to the computer that hosts WebSphere Liberty server.
Smart card authentication is available for Windows operating systems only.

There are three components involved in this configuration:

WebSphere Liberty server Profile hosting Engineering Lifecycle Management applications.
Jazz applications
- Configure Jazz applications to require certificate-based authentication
Clients

Configure WebSphere Liberty server to accept certificates

About this task

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

Edit the server.xml file that is located at [JAZZ_INSTALL_DIR]\server\liberty\servers\clm.
Add the clientAuthenticationSupported=”true” parameter within the SSL configuration as follows:
```
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" 
sslProtocol="SSL" 
trustStoreRef="defaultTrustStore" 
clientAuthenticationSupported="true" 
serverKeyAlias="<Server_CA_Cert>" /> 
```
If you specify the clientAuthentication="true" parameter, the server requests a certificate from the client. 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 the clientAuthenticationSupported="true" parameter, the server requests a certificate from the client. 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 parameter, or you specify clientAuthentication=”false” or clientAuthenticationSupported=”false”, the server does not request a certificate from the client during the handshake.

Configure the default KeyStore

About this task

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 Engineering Lifecycle Management Server public URI.

Procedure

Use ikeyman or keytool to import the CA certificate to the default keyStore that is located at [JAZZ_INSTALL_DIR]\server\liberty\servers\clm\resources\security.
The default keyStore file used in Liberty is ibm-team-ssl.keystore and password is ibm-team.
Copy the KeyAlias/Label of the imported certificates and include it in the <ssl> configuration serverKeyAlias.

Edit the server.xml file located at <JAZZ_INSTALL_DIR>\server\liberty\servers\clm.

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

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="/>

Configure the default TrustStore

About this task

Configure the default TrustStore with the certificate authority’s root certificate, so that the server trusts the client certificates.

Procedure

Create a New TrustStore using ikeyman or keytool (IBM JRE) and import the root/public certificate from the CA authority.

Include the new TrustStore name under <ssl> configuration in the server.xml file that is located at [JAZZ_INSTALL_DIR]\server\liberty\servers\clm.

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

Add the new TrustStore details below the default KeyStore configuration.
```
<keyStore 
id="defaultTrustStore"
location="trust.jks"
type="JKS"
password="<TrustStore_Password>" />
```
Alternatively, you can 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.

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

About this task

WebSphere Liberty server 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: CertificateMapMode and CertificateFilter. 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="(&(uid=%v)(objectclass=ePerson))" 
groupFilter="(&(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" />

Configure Jazz applications to require certificate-based authentication

About this task

WebSphere Liberty server 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 Jazz® Team Server for authentication.

Complete the following steps on all of your Liberty servers, hosting any jts, Engineering Workflow Management and Engineering Test Management war files, to configure the applications:

Procedure

Navigate to the directory where you installed CLM. The default path for the application .war files is: [JAZZ_INSTALL_DIR]/server/liberty/servers/clm/apps.
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_INSTALL_DIR]/server/liberty/clmServerTemplate/apps.
Navigate to the <app>.war/WEB-INF directory and open the web.xml file for editing.
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.
Save and close the web.xml file.

Configure web browsers to authenticate applications via user certificates

Procedure

Import the user certificate into the browser as personal certificates.
On Microsoft Windows, double-click on the user certificate and follow the steps in the wizard to import the certificate to your web browser.
After the import completes, on accessing any of the Engineering Lifecycle Management applications, the imported certificates are listed.
Select the appropriate user certificate to log in to Engineering Lifecycle Management.
check the user name that is displayed at the top-right corner and confirm the certificate if it matches your user ID.

Configure Eclipse and Visual Studio clients to authenticate applications via user certificates

Procedure

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

Repotools Utility

Repotools supports the use of certificate authentication using the certificateFile parameter. The adminPassword parameter is the password for the certificate provided. Below is an example of using a User Certificate and password to execute repotools commands

Example

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