WAS v8.5 > Secure applications > Secure the Liberty profile and its applications > Configuring web security related properties for the Liberty profile

Configure the web application and server for client certificate authentication

We can configure the web application on the Liberty profile using SSL client authentication.

This topic assumes that we have already created the SSL certificates.

Client certificate authentication occurs if the server-side requests the client-side send a certificate. A WebSphere server can be configured for client certificate authentication on the SSL configuration. To do this, add the ssl-1.0 Liberty feature to server.xml, along with code that tells the server the keystore information for authentication.

1. Ensure the deployment descriptor for the web application specifies client certificate authentication as the authentication method to use.

   Check the deployment descriptor includes the following element:

   <auth-method>CLIENT-CERT</auth-method>

   You can use a tool such as Rational Application Developer to create the deployment descriptor.

2. Optional: Generate an SSL certificate using the command prompt.

3. Configure your server to enable SSL client authentication by adding the following lines to server.xml:

      < featureManager>
           <feature>ssl-1.0</feature>    < featureManager>
   
      < ssl id="defaultSSLConfig" 
               keyStoreRef="defaultKeyStore" 
               trustStoreRef="defaultTrustStore" 
               clientAuthenticationSupported="true" />    
       < keyStore id="defaultKeyStore" 
                     location="key.jks" 
                     type="JKS" 
                     password="defaultPWD" />    
   
       < keyStore id="defaultTrustStore" 
                location="trust.jks" 
                type="JKS" 
                password="defaultPWD" />

   • If we 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 we 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 we do not specify either clientAuthentication or clientAuthenticationSupported, or we specify clientAuthentication="false" or clientAuthenticationSupported="false", the server does not request that a client send a certificate during the handshake.

4. Add a client certificate to your browser. See the documentation of your browser for adding client certificates.

5. Verify the server trusts any client certificates used.

6. Make sure any client certificates used for client authentication are mapped to a user identity in your registry.

   • For the basic registry, the user identity is the common name (CN) from the distinguished name (DN) of the certificate.

   • For a LDAP registry, the DN from the client certificate must be in the LDAP registry.

7. To use basic authentication, user ID and password only, if client certificate authentication does not succeed, add the following line to your server.xml file.
   < webAppSecurity allowFailOverToBasicAuth="true" />

   If we specify allowFailOverToBasicAuth="false" or do not specify allowFailOvertoBasicAuth, and the client certificate authentication does not succeed, the request generates a 403 Authentication error message, and the client is not prompted for basic authentication.

Parent topic: Secure communications with the Liberty profile

Parent topic: Configuring web security related properties for the Liberty profile

Related concepts:
Liberty profile: Authentication
Liberty profile: securityUtility command