Client certificate authentication for FTM

Authentication for the Operations and Administration Console (OAC) and RESTful APIs and SOAP Web Services uses a user registry that is configured in WebSphere® Liberty. Client certificate authentication is supported when enabled and configured for four Liberty components.

These Liberty components are shown in the following list.
  • Operations and Administration Console (OAC)
  • Business Rules web services
  • Gateway web services
  • Common Services web services

For more information about Operations and Administration Console (OAC), see Operations and Administration Console (OAC).

For more information about RESTful APIs and SOAP Web Services, see RESTful APIs and SOAP Web Services.

By default, client certificate authentication uses the basic realm to authenticate users. The default certificate mapping mode is the PRINCIPAL_CN mapping mode to authenticate the username.

To use client certificate authentication, complete the following steps. For information about adding trusted certificates in Liberty, see https://www.ibm.com/docs/en/was-liberty/nd?topic=liberty-adding-trusted-certificates-in.
  1. Import the extra client certificates to the Liberty truststore. For more information about adding trusted certificates in Liberty, see User-supplied certificates for external applications.
  2. Enable client certificate authentication by creating the web-app-auth-method.xml file with following XML stanza. 
    <server>
  <variable name="WEB_APP_AUTH_METHOD" defaultValue="CLIENT_CERT"/>
</server>
  3. Copy the file to the Liberty configuration dropins folder. Client certificate authentication is supported with the basic and LDAP user registries. The following sections describe additional configuration that might be needed.

Client certificate authentication with basic user registry

Client certificate authentication defaults to using the basic realm to authenticate users. The basic registry XML file is where the fxhadmin user is defined. However, when a custom configuration such as the client certificate authentication Liberty dropin is detected, the basic-registry.xml file is not added to Liberty. You need to explicitly define the basic registry whenever you customize the server.xml file.

For the default basic registry, include the following stanza in the default basic registry XML that goes in the Liberty configuration dropins folder.
<server>
  <basicRegistry id="basic" realm="BasicRealm">
    <user name="fxhadmin" password="${FXH_PASSWORD}"/>
  </basicRegistry>
  <administrator-role>
    <user>fxhadmin</user>
  </administrator-role>
</server>

Client certificate authentication with LDAP user registry

If you want to use a custom LDAP user registry, you need to define a certificate filter. A certificate filter identifies which elements from the certificate are used to find the user in the LDAP registry. For more information, see LDAP certificate map mode and Configuring LDAP user registries in Liberty in the IBM® WebSphere Liberty documentation.

When a custom configuration such as the client certificate authentication Liberty dropin is detected, the basic-registry.xml file is not added to Liberty. You need to explicitly define the LDAP user registry whenever you customize the server.xml file.