| You can specify the SSL client certificate authentication is to be used for authentication of a Web application by modifying the deployment descriptor for the Web module login configuration via the Application Assembly Tool or WSAD. Select the CLIENT-CERT authentication type and Integral or Confidential for the User Authorization . (The Integral and Confidential settings force the application to be accessed over SSL.) Naturally, you must configure your HTTP servers for SSL and client certificate authentication, usually over port 443, the standard HTTPS port. For Apache-based servers (such as the IBM HTTP Server), this is done via the httpd.conf configuration file. For the Domino HTTP server, it is done via the Server document in the Domino directory under the Ports> Internet Ports>Web page. When configuring the authentication options, you should set client certificates to be required rather than optional, which will force the client certificate to be sent in response to the initial resource request. This is necessary so that the certificate can then be passed to WAS via the WAS plug-in. To require client authentication for Domino HTTPS , specify "yes" for client certificate authentication and "no" for both the Name & password and Anonymous authentication options. The HTTPS port configuration will require that a server key pair and certificate be set up on the server side for the SSL server authentication handshake. You will need to provide the server keys and certificate in a format acceptable to the HTTP server. (For Domino HTTP server this format is the " keyring " or .kyr format.) Also a set of trusted signer certificates that can validate the client certificates will need to be specified on the server side. Usually, these trusted certificates consist of the Certificate Authority (CA) signer certificates that are obtained from the CAs used to sign the client certificates. For an application made available on the open Internet, you can require your clients to use commercial CAs for certificate signing. Keep in mind, however, that Domino provides its own CA function, which you can make available to your clients and also use for signing server certificates. Once the SSL port is configured on the HTTP server, ensure that WAS will accept this port under the virtual host name defined for the HTTP server. You may need to add the SSL port to the Virtual Host definition for the application server. Finally, there is one more area of server-side configuration required for WebSphere SSL client certificate authentication. This additional configuration is required to establish SSL between the HTTP server WAS plug-in and the WAS application server. On the WAS side, ensure that an SSL port is configured for the application server. The default WAS SSL port is 9443. You should specify a different server private key and certificate and trusted signer certificate files for this port other than the default self-signed server certificate that is provided by IBM. To do this, you need to first create a new SSL "repertoire" that represents a set of SSL key files. Using the WAS Web administrative interface, open the SSL page under the Security branch and create a new SSL Repertoire. On the SSL Repertoire configuration page, you can specify the server private key/public certificate file and password and the trusted signer certificates file (these may be the same file if one file contains all). These files must be in either Java Key Store (JKS) or PKCS#12 format. The WAS help documentation describes how to create these files containing self-signed certificates using the IKeyMan utility supplied with WAS. However, self-signed certificates are generally not as secure as CA signed certificates. If a commercial CA cannot be used, then using the Domino-provided CA function to sign the server certificate is the next best thing. Once the SSL repertoire is created, it can be associated with the 9443 port, via the Servers>server<n>>WebContainer>HTTPTransports configuration page. On the WAS plug-in side, you must edit the plug-in configuration XML file to tell the plug-in to use the SSL port configured above to connect to WAS for SSL requests . You must also specify a trusted certificates file so that the plug-in can authenticate the WAS server certificate on the SSL handshake. As is often the case with SSL, this trusted certificates file must be in a format different from that accepted for the WAS SSL port. Here the file must be in "CMS Database" format or ".kdb" format. A file in this format can be created by using the IKeyMan utility supplied with the IBM HTTP Server. If the WAS server certificate is CA-signed, then this trusted certificates file need only contain the CA signer certificate. If the certificate file is password protected, then you must create a "stash" file to specify the password to the plug-in. Here is a section of the plug-in configuration file showing the specification of the SSL port and certificate and stash files:
<Server Name="default_server"> <!-- The transport defines the hostname and ports that the Web server plugin will use to  communicate with the application server. --> <Transport Hostname="washost" Port="9080" Protocol="http"/> <Transport Hostname="washost" Port="9443" Protocol="https"> <Property Name="Keyring" value="/plugin/config/trustedcerts.kdb"/> <Property Name="Stashfile" value="/plugin/config/trustedcerts.sth"/> </Transport> </Server>
If you encounter problems with the plug-in after configuring for SSL, ensure that you have the latest fixes for the plug-in library files from the IBM WebSphere product Web site. There have been several fixes released for the plug-in, some specific to the Domino HTTP server plug-in. With the HTTP server set for SSL and client certificate authentication and SSL enabled between the HTTP plug-in and WAS, you are ready to test and use client certificate authentication for your Web application components within an SSO domain. Well, almost. The client certificates need to be installed into the user browsers (or clients). (The Domino CA function handles this very nicely as part of the certificate signing process.) In addition, you should ensure that the client certificate user names can be looked up in the WAS user registry. As mentioned earlier, WAS attempts to match the certificate user DN with a user DN in the LDAP directory, or you can specify a search filter for WAS to use for the certificate user name look up. Now we are finally there. With all of this set up, the initial authentication for a protected Web resource is made using the client certificate, and all other protected accesses are authenticated via the LTPA token. However, as mentioned previously, there is a problem with client certificate authentication to Domino resources. An initial client certificate authentication to a Domino resource won't work if the certificate user is defined only in a non-Domino LDAP directory. This is because Domino requires that the user certificate be stored in the Domino directory for certificate authentication. If client certificate authentication is used with SSO without storing the certificates in Domino, then the initial authentication must be to a WAS resource. | 