Configuring certificate authentication in Engineering Workflow Management

Edit online

You can log in to the Engineering Workflow Management client, by using a certificate (.p12) file or a smart card, which are more secure than logging in with a user name and password.

Before you begin

Before you can configure certificate authentication, you must complete the following tasks:
  • Install a supported version of WebSphere® Application Server and upgrade it to the fix packs that Engineering Workflow Management requires.
  • Configure WebSphere Application 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 Application Server.
  • Do not install the ccm.war and jts.war files on WebSphere Application Server. You must modify the contents of the .war files before you install them.

About this task

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.

Note: Smart card authentication is available on Windows only.

To configure certificate authentication for IBM® Engineering Lifecycle Management on WebSphere Liberty Profile, see Configuring certificate authentication for ELM on Liberty Profile.

Configure WebSphere Application Server to accept certificates

Edit online

About this task

You must configure WebSphere Application Server to support or require client certification authentication at the transport layer.

Procedure

  1. In WebSphere Application Server Integrated Solutions Console, click Security > SSL certificate and key management.
  2. Under Related Items, click SSL configurations.
  3. Click the node configure. The default node is NodeDefaultSSLSettings.
  4. Under Additional Properties, click Quality of protection (Qop) settings.
  5. Change Client authentication from None to Supported.
  6. Click OK and then save the changes to the master configuration.
  7. Click SSL certificate and key management and, under Related Items, click Key stores and certificates.
  8. Click NodeDefaultTrustStores and, under Additional Properties, click Signer certificates.
  9. Click Add to add a signer certificate.
  10. In the Alias field, provide an alias that the signer certificate is referenced by in the key store.
  11. In the File name field, provide the fully qualified file name where the encoded signer certificate is located.
  12. Click OK and then save the changes to the master configuration.

Configure WebSphere Application Server to map incoming certificates to users in the registry

Edit online

About this task

WebSphere Application Server can now accept incoming certificates as an authentication mechanism, but the server does not know how to map the incoming certificates to users. You must 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.

The values for the settings depend on your certificate and user registry settings. Consider an example that shows a mapping of an incoming certificate to a user in a local LDAP registry. The WebSphere Application Server is currently configured to allow a user with the user ID user1 to log in. The user1 user wants to log in with a certificate with the following subject: "CN=user1, OU=yourserver". You could configure WebSphere Application Server to use the Common Name entry in the certificate as the user ID of the logged-in user by using the CERTIFICATE_FILTER mode for the Certificate mapping mode setting and the "uid=${SubjectCN}" value for the Certificate filter setting.

Tip: The Certificate filter option is a flexible way to map certificates to users, and the previous example is a simple one. For a complete list of options, see the WebSphere Application Server documentation.

Procedure

Complete the procedure for your registry:
  • If you use the Standalone LDAP registry, complete these steps:
    1. In WebSphere Application Server Integrated Solutions Console, click Security > Global security.
    2. From the list of Available realm definitions, select Standalone LDAP registry and click Configure.
    3. Under Additional Properties, click Advanced Lightweight Directory Access Protocol (LDAP) user registry settings.
    4. From the list of Certificate map mode, select CERTIFICATE_FILTER.
    5. In the Certificate filter field, enter your certificate filter option.
    6. Click OK and save the changes to the master configuration.
  • If you use the Federated repositories registry, complete these steps:
    1. In WebSphere Application Server Integrated Solutions Console, click Security > Global security.
    2. From the list of Available realm definitions, select Fedearted repository, and click Configure.
    3. Click each link in the Repository Identifier column and set the certificate mapping mode and the certificate filter.
      Note: If you use the Federated repositories, ensure that all of the Federated repositories are LDAP-based, and not local-file-based. WebSphere Application Server does not currently support certificate authentication with a Federated repository that includes a mix of local and LDAP-based realms.
    4. Click OK and save the changes to the master configuration.

Configure Engineering Workflow Management and Jazz Team Server applications to require certificate-based authentication

Edit online

About this task

WebSphere Application Server is now configured to allow certificate authentication and map incoming certificates to known users, but you must also configure the Engineering Workflow Management and Jazz® Team Server applications to accept certificate-based authentication.

By default, the jts.war and ccm.war 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, you must edit the <login-config> XML element of the application .war files.

Procedure

Complete the procedure to configure the applications:
  • If your application .war files are not deployed to WebSphere Application Server, complete these steps:
    1. Go to the directory where you installed ELM. The default path for the application .war files is: Jazz_Installation_Directory/server/webapps.
    2. Extract the contents of the jts.war and ccm.war files by using a compression program.
    3. Navigate to the 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 you must either delete or comment-out any other <login-config> XML elements.
    5. Save and close the web.xml file.
    6. Compress the content back into the .war files.
    7. Deploy the modified .war files in WebSphere Application Server. For more information, see Deploying applications for the IBM Engineering Lifecycle Management on WebSphere Application Server.
  • If your application .war files are already deployed to WebSphere Application Server, complete these steps:
    1. Go to the directory where your WebSphere Application Server is deployed. The default path for the jts.war is: WAS_Installation_Directory/AppServer/profiles/AppSrv01/installedApps/nodeName/jts_war.ear/jts.war/WEB_INF/web.xml and default path for ccm.war is: WAS_Installation_Directory/AppServer/profiles/AppSrv01/installedApps/nodeName/ccm_war.ear/ccm.war/WEB_INF/web.xml.
    2. Open the web.xml files for editing.
    3. 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 you must either delete or comment-out any other <login-config> XML elements.
    4. Save and close the web.xml files.
    5. In WebSphere Application Server Integrated Solutions Console, click Applications > Application Types > WebSphere enterprise applications.
    6. Select jts_war and click Update.
    7. Select Replace or add a single file.
    8. In the Specify the path beginning with the installed application archive file to the file to be replaced or added field, enter jts.war/WEB-INF/web.xml.
    9. Click Browse and select the same web.xml file that you modified earlier in the procedure.
    10. Click Next and continue until you save the application.
    11. Go back to the Enterprise Applications pane and stop and start the jts_war application.
    12. Repeat the preceding steps for the ccm.war application.

Using certificates in the Engineering Workflow Management Eclipse client

Edit online

About this task

Now that the WebSphere Application Server, Jazz Team Server, and CCM application are all configured to allow certificate-based authentication, you can configure the client to use certificates.

Procedure

Create a new repository connection and configure it to use the certificate authentication. The following image shows an example of a repository connection that is configured to use certificate authentication:
Repository connection