You can configure your web application on the Liberty profile
using SSL client authentication.
About this task
Client certificate authentication occurs if the server-side
requests that the client-side send a certificate. A WebSphere® server can be configured for
client certificate authentication on the SSL configuration. To do
this, you add the ssl-1.0 Liberty feature to the server.xml file,
along with code that tells the server the keystore information for
authentication.
For details of which aspects of SSL are supported,
see Liberty features.
Procedure
- Ensure that the deployment descriptor for your web application
specifies client certificate authentication as the authentication
method to use.
Check that the deployment descriptor
includes the following element:
<auth-method>CLIENT-CERT</auth-method>
Note: You
can use a tool such as Rational® Application
Developer to create the deployment descriptor.
- Optional: Generate an SSL certificate using
the command prompt. See Liberty profile: securityUtility command.
- Configure your server to enable SSL client authentication
by adding the following lines to the server.xml file:
<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 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.
- Add a client certificate to your browser. See the documentation
of your browser for adding client certificates.
- Make sure the server trusts any client certificates that
are used.
- 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 Lightweight Directory Access Protocol (LDAP) registry,
the DN from the client certificate must be in the LDAP registry.
- 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" />
Note: If
you 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.