Set up Client Certificate Authentication

Set up Client Certificate Authentication

Overview

The supported scenario is a "client certificate only" setup that switches completely to this authentication method and does not allow form-based login via username and password. Other configuration scenarios are possible, but are neither recommended nor supported.

Configure IBM WAS for SSL support with client certificates

Define Quality of protection (QoP) settings for the new SSL Repertoire, do the following:

Choose Required from the Client Authentication list
Choose SSL_TLS from the Protocol list.
In the Provider section, select Predefined JSSE provider then choose IBMJSSE from the Select provider list.

Reference your key and trust files.
Create key and trust files using the IKEYMAN tool. Use the PKCS12 format for maximum browser compatibility. The key file contains the server certificate. The trust file contains either...

All the client certificates of users that will be authenticated
Certification authority certificate (CA key) used to verify the client certificates of users

Associate the secure transport chain with the new SSL Repertoire.

Configure the advanced LDAP security settings.
Certificate-based authentication requires that we configure the authentication mechanism so that one of the following conditions apply:

WAS maps the entire Distinguished Name (DN) from the subject field of the certificate to a corresponding Distinguished Name in the LDAP. To use this option, set the mapping technique in the LDAP configuration panel to exact.

WAS maps the entry in the subject field to a different attribute than the Distinguished Name in the user registry. To use this option, set up the mapping technique in the LDAP configuration panel to use the certificate filter option. Using the certificate filter option allows you more flexibility in using attributes other than the Distinguished Name to identify the users. For example, the filter...
uid=${SubjectCN}

...maps the SubjectCN field of the client certificate to the uid attribute in the LDAP.

Configure with external HTTP server

Regenerate the plug-in...
Servers | Web Servers | Web server Generate Plug-in

Update the HTTP server with the generated plug-in.

Restart the HTTP server for the changes to take effect.

Enable client certificate authentication in the Web server.
For IBM HTTP Server, search for security handbook.

Update wps.ear

We update wps.ear to change the authentication method and transport guarantee setting to support client certificate authentication.
Clustered environments: Complete this step on the primary node, then complete a full resynchronize to propagate the changes to all nodes.
From console, export, then extract, wps.ear.
Edit...
/path/to/exported/ear/installedApps/node/wps.ear/wps.war/WEB-INF/web.xml

...and change the login-config tag to the client certificate authentication method...
<login-config >    
    <auth-method>CLIENT-CERT</auth-method>    
    <realm-name>WPS</realm-name>    

    
</login-config>
Change the transport guarantee setting in the security constraint for the protected area to CONFIDENTIAL:
<security-constraint >    
    <web-resource-collection >       
        <web-resource-name/>      
        <url-pattern>/myportal/*</url-pattern>       
        <http-method>DELETE</http-method>       
        <http-method>GET</http-method>       
        <http-method>POST</http-method>       
        <http-method>PUT</http-method>       
        <http-method>HEAD</http-method>    
    </web-resource-collection>    
    <auth-constraint >     
        <description/>     
        <role-name>All Role</role-name>    
    </auth-constraint>    
    <user-data-constraint >       
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>    
    </user-data-constraint>
</security-constraint>
Save and close web.xml.

Redeploy wps.ear. See the following topic title in the Related task section for instructions: Redeploying the portal EAR file.

Clustered environments: Synchronize the nodes.

Log in to the dmgr.
Select System Administration > Nodes.
Select the nodes to synchronize from the list.
Click Full Resynchronize.
Update themes and settings
Modify the URLs for login and logout in the themes used in the scenario. The files containing the login and logout links can be different, depending on the theme. In more recent themes, these links might be located in Default.jsp. In older themes, these links might be located in either banner.jspf or mainMenu.jsp.
Find theme resources: See the Location of theme resources link in the Related section.
Clustered environments: Complete the following steps. Notice that in a clustered environment, the steps must be completed on the dmgr.
For the login link, use an arbitrary protected page. The login link will then implicitly trigger the SSL handshake in WAS due to the security constraint. For example, we can generate the URL to point to the protected welcome page:
<%-- Login button --%>
<%-- comment this to enable screen login --%>  <portal-logic:if loggedIn="no">
<portal-navigation:urlGeneration  contentNode="ibm.portal.Home.Welcome" home="protected">         
    <a tabIndex="7" class="toolbarLink" href='<%  wpsURL.write(escapeXmlWriter); %>'>       
    <portal-fmt:text key="link.login" bundle="nls.engine"/>   
    </a></portal-navigation:urlGeneration>
</portal-logic:if>
For the logout, we need to consider whether or not a logout should redirect you back to HTTP.
If so, we need to set the property redirect.logout.ssl in the configuration service to true. Also, set the host.port.http in the same service to the correct port. To stay in the HTTPS protocol after the logout, we do not need to complete any configuration steps here.
Remove the login portlet from all pages where it is placed; for example, the welcome and the login page.

To completely disable the entry points 'login portlet' and 'login URL' to HCL WebSphere Portal, complete the following steps: set the command.login property in the configuration service to the value LoginUserBlocked. This ensures that a login can only be triggered after being authenticated by WAS, in this case by the client certificate handshake.

Log on to the WAS admin console and go to...
Resources | Resource Environment | Resource Environment Providers | WP ConfigService | Additional Properties | Custom Properties

Click command.login and change the value from LoginUserAuth to LoginUserBlocked.

Click Save to save the changes to the master configuration.

Log out of the WAS admin console.

Stop and restart the appropriate servers to propagate the changes.
Verify the setup

Import one of the client certificates accepted by the server to the browser.

Launch the home page in this browser through an HTTP URL that is not secure; for example,
http://hostname.example.com:10039/wps/portal

Click the login link.

Verify the server switches to HTTPS and we are prompted for the client certificate.

After selecting and confirming the correct client certificate, we are redirected to the protected area served with HTTPS.

Parent Configure SSL
Previous topic: Configure SSL only for the login process
Next topic: Cryptographic hardware for SSL acceleration
Related concepts:
Understand the Portal v8.5 modularized theme
Create an SSL configuration
Quality of protection (QoP) settings