Library > Articles >

Configuring certificate authentication for CLM deployed with Jazz Authorization Server

Shubjit Naik, IBM
Last updated: 02 November 2017 
Build basis: Rational solution for Collaborative Lifecycle Management, Jazz Authorization Server versions 6.0.2 and higher

 

Rational solution for Collaborative Lifecycle Management (CLM) applications configured to authenticate through Jazz Authorization Server can be configured to log in by 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 certificate to the computer that hosts WebSphere Liberty Profile (JAS).

Configuration overview

There are two components to this configuration. The CLM application does not need to be configured because it would redirect its authentication to Jazz Authorization Server.

  1. WebSphere Liberty Profile hosting the Jazz Authorization Server (Application Server)
  2. Clients

Configuring WebSphere Liberty Profile hosting JAS 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 appConfig.xml file that is located at [JAS_HOME]\wlp\usr\servers\jazzop
  2. Add the parameter clientAuthenticationSupported=”true” within the SSL configuration as follows:
    <ssl id="defaultSSLConfig"
     keyStoreRef="defaultKeyStore"
     trustStoreRef="defaultTrustStore"
     serverKeyAlias="<Server_CA_Cert_Label>"
     clientAuthenticationSupported="true"
     />

    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.

Modify OIDC configuration to support client certificate authentication

Edit the appConfig.xml file that is located at [JAS_HOME]\wlp\usr\servers\jazzop, Go to the <oauthProvider> element in the file. Under the line that starts with autoAuthorize=, add certAuthentication="true"


<oauthProvider id="JazzOP"
 httpsRequired="true"
 autoAuthorize="true"
 certAuthentication="true"
 customLoginURL="/jazzop/form/login"
 accessTokenLifetime="7201" 
 authorizationGrantLifetime="604801">
 <autoAuthorizeClient>client01</autoAuthorizeClient>
 <databaseStore dataSourceRef="OAuthFvtDataSource" /> 
 </oauthProvider>

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 [JAS_HOME]\wlp\usr\servers\jazzop. 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 appConfig.xml file, located at [JAS_HOME]\wlp\usr\servers\jazzop
    <ssl id="defaultSSLConfig"
     keyStoreRef="defaultKeyStore"
     trustStoreRef="defaultTrustStore"
     serverKeyAlias="<Server_CA_Cert_Label>"
     clientAuthenticationSupported="true"
     />

  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 by 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 [JAS_HOME]\wlp\usr\servers\jazzop
    <ssl id="defaultSSLConfig"
     keyStoreRef="defaultKeyStore"
     trustStoreRef="defaultTrustStore"
     serverKeyAlias="<Server_CA_Cert_Label>"
     clientAuthenticationSupported="true"
     />
  3. Add the new TrustStore details below the defaultKeyStore configuration in the appConfig.xml file.
    <keyStore 
     id="defaultTrustStore"
     location="ibm-team-Trust.keystore"
     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"
     trustStoreRef="defaultKeyStore"
     serverKeyAlias="<Server_CA_Cert_Label>"
     clientAuthenticationSupported="true"
     />

    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 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, when accessing any of the CLM applications, you are redirected to the Jazz Authorization Server and then the imported certificates are listed. Select the appropriate user certificate to authenticate.
  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

The 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.
Feedback
Was this information helpful? Yes No 1 person rated this as helpful.