View the steps required to configure HCL Digital Experience for SSL client
certificate authentication. 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.
About this task
Complete the following steps to configure HCL Digital Experience for SSL
client certificate authentication:Note: See related references section on how to setup
WAS for SSL support with client certification.
Procedure
-
Ensure you complete the following steps when you configure IBM®
WebSphere® Application
Server for SSL support with client certificates:
-
When you define the 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.
For more information, see the
Quality of Protection
topic in the
WebSphere®
Application Server Information Center.
-
Ensure you reference the correct key and trust files. You should create
new key and trust files using the IKEYMAN tool and the PKCS12 format for
maximum browser compatibility.
Note: The key file must contain the server certificate. The trust file
must contain either all the client certificates of users that will
be authenticated or a certification authority certificate (CA key)
that can be used to verify the client certificates of users.
-
Associate the secure transport chain with the new SSL Repertoire.
-
Configure your advanced LDAP security settings. Certificate-based
authentication requires that you configure the authentication mechanism
so that one of the following conditions apply:
- WebSphere®
Application Server maps the entire Distinguished Name
(DN) from the subject field of the certificate to a
corresponding Distinguished Name in your LDAP. To use this
option, set the mapping technique in the LDAP configuration
panel to exact.
- WebSphere®
Application Server maps the entry in the subject field
to a different attribute than the Distinguished Name in your
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 your LDAP.
-
Complete the following steps if you use an external HTTP server:
-
Regenerate the plug-in. Go to . Select the Web server and click
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 your Web server. For IBM
HTTP Server (IHS), refer to http://www.redbooks.ibm.com/ and search
for security handbook for the latest information about WebSphere® Application
Server.
-
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.
-
Export wps.ear.
See the following topic title in the Related task section for
instructions: Exporting the portal EAR file.
-
Go to the directory where you exported wps.ear:
path_to_exported_EAR/installedApps/node_name/wps.ear/wps.war/WEB-INF
Note: You might need to extract the exported EAR before you
can edit any files.
-
Edit the web.xml file located in the exported ear
directory under /wps.war/WEB-INF.
-
Change the login-config tag to the client certificate authentication
method.
<login-config id="LoginConfig_1">
<auth-method>CLIENT-CERT</auth-method>
<realm-name>WPS</realm-name>
<!--<form-login-config id="FormLoginConfig_1">
<form-login-page>/redirect</form-login-page>
<form-error-page>/error.html</form-error-page>
</form-login-config> -->
</login-config>
-
Change the transport guarantee setting in the security constraint for
the protected area to CONFIDENTIAL:
<security-constraint id="SecurityConstraint_1">
<web-resource-collection id="WebResourceCollection_1">
<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 id="AuthConstraint_1">
<description/>
<role-name>All Role</role-name>
</auth-constraint>
<user-data-constraint id="UserDataConstraint_4">
<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 Deployment Manager.
- Select .
- Select the nodes to synchronize from the list.
- Click Full Resynchronize.
-
Update the themes and settings.
-
Modify the URLs for login and logout in the themes that are used in
your scenario. In the default theme, these are
located in the banner_toolbar.jspf and
mainMenu.jsp files in the PortalServer_root/installer/wp.ear/installableApps/wps.ear/wps.war/themes/
directory.The files that contain 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.
Finding 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 Deployment Manager.
-
Remove the login portlet from all pages where it is placed; for
example, the welcome and the login page.
-
If you want to completely disable the entry points 'login portlet' and
'login URL' to HCL Digital Experience, 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 WebSphere® Application Server, in
this case by the client certificate handshake.
- Log on to the WebSphere® Integrated Solutions Console.
- Go to .
- Click WP ConfigService.
- Click Custom Properties under the
Additional Properties heading.
- 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 WebSphere® Integrated Solutions Console.
-
Stop and restart the appropriate servers to propagate the changes. For specific
instructions, see Starting and stopping servers, deployment managers, and node
agents.
-
Verify your setup.
-
Import one of the client certificates that are accepted by the server
to your 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,
where hostname.example.com is the fully qualified
host name of the server where Portal is running and
10039 is the default transport port that is
created by WebSphere®
Application Server. The port number might be different for your
environment..
-
Click the login link.
-
Verify that the server switches to HTTPS and you are prompted for the
client certificate.
-
After selecting and confirming the correct client certificate, you are
redirected to the protected area served with HTTPS.