SSL/TLS Client authentication (AKA Mutual authentication) is similar to regular, server authentication except that the server requests a certificate from the client to verify the client is who they claim to be. The certificate must be an X.509 certificate and signed by a certificate authority (CA) trusted by the server.

When a server requests a certificate, the client has the option to send a certificate or attempt to connect without it. The server allows the connection if the client's certificate can be trusted. When a client attempts to connect without a certificate, the server might give the client access but at a lower security level.

Ultimately, SSL/TLS Client/Mutual authentication provides a more secure method for the server to verify the client's identity. This can be useful with IBM WebSphere Application Server (WAS) when a Web Server is configured on a remote machine in front of WAS. When the Web Server is located on a remote machine, communications between WAS and the Web Server Plug-in might occur over the Internet, which exposes the data. Enabling SSL/TLS Client/Mutual authentication will not only encrypt the data like the standard, Server authentication; but it will also provide a higher level of verification of the client entity to ensure the client can be trusted.

Here is a breakdown of how Client/Mutual authentication works:

 
How To Set Up SSL/TLS Client (Mutual) Authentication Between An IBM WebSphere Application Server And The IBM Web Server Plug-in

NOTE: These steps assume an IBM i HTTP Server and IBM WebSphere Application Server profile already exist.

1) Configure the IBM i HTTP Server for SSL/TLS Authentication.

• Please follow the instructions listed in the "Enable Apache HTTP for SSL/TLS " document to configure your IBM i HTTP Server for SSL/TLS Authentication. If your IBM i HTTP Server is already configured for SSL/TLS Authentication, please proceed to step 2.

2) Associate your IBM i Apache HTTP Server with your IBM WebSphere Application Server.

• NOTE: For an IBM i to IBM i Remote HTTP Server configuration, please refer to the "How To Associate A Remote IBM i Apache HTTP Server With An IBM WebSphere Application Server Profile at IBM i 5.4 and Later" document for more information on setting this up.
  
  - Ensure your ADMIN HTTP server is active.
  STRTCPSVR *HTTP HTTPSVR(*ADMIN)
  
  - Open a web browser and go to the following URL.
  • http://<serverName or IP address>:2001/HTTPAdmin
  • If you are unable to access the IBM Web Administration for i console application using the URL above, please contact the IBM i Global Support Center for further assistance by opening a Service Request online or by calling 1-800-IBM-SERV.
  
  - When prompted, sign into the console using an IBM i User Profile with *ALLOBJ and *IOSYSCFG special authorities.
  - Select Manage -> HTTP Servers.
  - Select your IBM i HTTP Server you wish to associate with your IBM WebSphere Application Server profile.
  - Click on the "WebSphere Application Server" link on the left-hand, vertical menu bar just above "Tools".
  - Select the IBM WebSphere Application Server installation and profile you wish to associate the IBM i HTTP Server with.
  - Select "All Applications" for the field "Indicate which installed applications should be mapped to the selected Web server."
  - Click the "OK" button to complete the association process.

3) Start your IBM WebSphere Application Server profile.

• NOTE: If your IBM WebSphere Application Server profile is already started, proceed to step 4.
  
  $WAS_PROFILE_ROOT/bin/startServer <serverName>
  
  You can also start your IBM WebSphere Application Server profile using the IBM Web Administration console (http://<serverName or IP address>:2001/HTTPAdmin). Just click on Manage -> Application Servers -> Select your WAS server from the drop-down box. Click on the green triangle to start it.

4) Open the IBM WebSphere Integrated Solutions Console.

• - Open a web browser and go to the following URL.
  • http://<serverName or IP address>:2001/HTTPAdmin
    
    If you are unable to access the IBM Web Administration for i console application using the URL above, please contact the IBM i Global Support Center for further assistance by opening a Service Request online or by calling 1-800-IBM-SERV.
  
  - When prompted, sign into the console using an IBM i User Profile with *ALLOBJ and *IOSYSCFG special authorities.
  - Select Manage -> Application Servers.
  - Select your IBM WebSphere Application Server profile from the drop-down server list.
  - Click on the "Launch Administrative Console" link on the left-hand, vertical menu bar under the "Tools" section.
  - Sign into the IBM WebSphere Integrated Solutions Console.

5) Modify the Virtual Host for your IBM i HTTP Server.

• - Expand the "Environment section" in the IBM WebSphere Integrated Solutions Console.
  - Click on the "Virtual hosts" link.
  - Click on the name of the virtual host assigned to your applications. NOTE: The virtual host, default_host, is used by default.
  - Click on the "Host Aliases" link under "Additional Properties".
  - Locate the entry for your IBM i HTTP Server port and click on the Host Name value.
  - Change the Host Name value to "*" to allow all host names and IP addresses access over the specified port.
  - Click the "OK" button and then click on the "Save" link at the top of the screen to save the changes to the Master Configuration.

6) Verify the IBM WebSphere Application Server profile (key.p12 and trust.p12) and Web Server (plugin-key.kdb) SSL/TLS key stores contain the same SSL/TLS certificates.

• NOTE: The plugin-key.kdb keystore used by the IBM i Web Server MUST have the exact same signer and personal SSL/TLS certificates used by IBM WebSphere Application Server in its key.p12 and trust.p12 key stores.
  
  - Click on Security -> "SSL certificate and key management" in the IBM WebSphere Integrated Solutions Console.
  - Click on "Key stores and certificates" under the "Related Items" section.
  - Click on the "CMSKeystore" key store.
  - Click on "Signer certificates" and make note of the Fingerprint ($FNGRPRT) value.
  - Go back to the "CMSKeystore" key store.
  - Click on "Personal certificates" and make note of the Serial Number ($SRLNBR) value as well as the "Alias" value ($ALIAS).
  • NOTE: The Alias listed here will be used in the next step.
  - Go back to "SSL certificate and key management" -> "Key stores and certificates".
  - Click on "NodeDefaultKeyStore" or "CellDefaultKeyStore".
  - Click on "Personal certificates" and compare the Serial Number listed to the value of $SRLNBR previously identified in the CMSKeyStore. These values should match.
  - Go back to "SSL certificate and key management" -> "Key stores and certificates".
  - Click on "NodeDefaultTrustStore" or "CellDefaultTrustStore".
  - Click on "Signer certificates" and compare the Fingerprint listed to the value of $FNGRPRT previously identified in the CMSKeyStore. These values should match.

7) Implement the custom Web Server Plug-in property "CertLabel".

• - Click on Servers -> Server Types -> Web servers in the IBM WebSphere Integrated Solutions Console.
  - Click on the name of the web server you wish to configure.
  - Click on "Plug-in properties" under the "Additional Properties" section.
  - Click on "Custom Properties" under the "Additional Properties" section.
  - Click on the "New..." button.
  - Set the following:
  • Name: CertLabel
    Value: $ALIAS (variable value you identified in step 6)
  
  NOTE: These values are case sensitive.
  
  - Click the "OK" button and then click on the "Save" link at the top of the screen to save the changes to the Master Configuration.

8) Generate and propagate the Web Server Plug-in.

• - Click on Servers -> Server Types -> Web servers in the IBM WebSphere Integrated Solutions Console.
  - Select the check box next to your web server.
  - Click the "Generate Plug-in" button.
  - Click the "Propagate Plug-in" button.

9) Copy the Web Server Plug-in key store files to the $WAS_PROFILE/config/$WEB_SERVER/ directory.

• - Click on Servers -> Server Types -> Web servers in the IBM WebSphere Integrated Solutions Console.
  - Click on the name of the web server you wish to configure.
  - Click on "Plug-in properties" under the "Additional Properties" section.
  - Click on the "Copy to Web server key store directory" button.

10) Configure your WebSphere Application Server profile to use Client Authentication.

• - Click on Security -> "SSL certificate and key management" in the IBM WebSphere Integrated Solutions Console.
  - Click on "SSL Configurations" under the "Related Items" section.
  - Click on the "New..." button to create a new SSL configuration item.
  - Specify a name for the configuration. i.e. ClientAuth
  - Set the Trust store name to NodeDefaultTrustStore/CellDefaultTrustStore.
  - Set the Keystore name to NodeDefaultKeyStore/CellDefaultKeyStore.
  - Click the "OK" button and then click on the "Save" link at the top of the screen to save the changes to the Master Configuration.
  - Click on the newly created SSL Configuration item.
  - Click on "Quality of protection (QoP) settings" under the "Additional Properties" section.
  - Change the "Client authentication" field to "Required".
  • NOTE: The setting "Required" means WAS will require a client certificate. The setting "Supported" indicates WAS will ask for a client certificate. If one is not provided by the client, it will proceed with normal SSL/TLS authentication.
  - Click the "OK" button and then click on the "Save" link at the top of the screen to save the changes to the Master Configuration.
  - Click on Security -> "SSL certificate and key management"
  - Click on "Manage endpoint security configurations" under the "Configuration settings" section.
  - Under "Inbound", expand nodes -> <node> -> servers -> <server>
  - Click on the "WC_defaulthost_secure" endpoint.
  - Under "Specific SSL configuration for this endpoint", check the "Override inherited values" box.
  - Select the newly created SSL configuration object from the drop-down list.
  - Click on the "Update certificate alias list" button.
  - Select the certificate alias to use under the "Certificate alias in key store" item.
  - Click the "OK" button and then click on the "Save" link at the top of the screen to save the changes to the Master Configuration.

11) Restart your IBM i HTTP Server and WebSphere Application Server profiles.

• IBM i HTTP Server
  • ENDTCPSVR *HTTP HTTPSVR(<HTTPserver>)
    STRTCPSVR *HTTP HTTPSVR(<HTTPserver>)
    
    You can also stop and start your IBM i HTTP Server using the IBM Web Administration console (http://<serverName or IP address>:2001/HTTPAdmin). Just click on Manage -> HTTP Servers -> Select your HTTP server from the drop-down box. Click on the red square to stop the server. Click on the green triangle to start it.
  
  IBM WebSphere Application Server
  • $WAS_PROFILE_ROOT/bin/stopServer <serverName>
    $WAS_PROFILE_ROOT/bin/startServer <serverName>
    
    You can also stop and start your IBM WebSphere Application Server profile using the IBM Web Administration console (http://<serverName or IP address>:2001/HTTPAdmin). Just click on Manage -> Application Servers -> Select your WAS server from the drop-down box. Click on the red square to stop the server. Click on the green triangle to start it.

12) Congratulations! You have successfully enabled Client/Mutual Authentication between your Web Server Plug-in and WebSphere Application Server. You should now be able to successfully access your application over your IBM HTTP Server SSL/TLS port.

If you are unable to access your web applications after configuring Client/Mutual Authentication, please contact the IBM i Global Support Center for further assistance by opening a Service Request online or by calling 1-800-IBM-SERV.