You can configure your web application in Liberty 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
transportSecurity-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 line. See securityUtility command.
- Configure your server to enable SSL client authentication by adding the following lines
to the server.xml file:
<featureManager>
<feature>transportSecurity-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.