Technical Notes

Using X.509 Client Certificate Authentication with Reflection for the Web
Technical Note 1756
Last Reviewed 01-Feb-2008
Applies To
Reflection for the Web version 8.0 or higher
Summary

Reflection for the Web provides an option for users to authenticate to the Reflection management server using X.509 client certificates, stored in the browser's keystore or on a smart card. This technical note describes how to set up this type of authentication.

Note: For information about configuring client certificate authentication to an SSL host, see Technical Note 1766.

Overview

X.509 client certificates can be used to authenticate users to the Reflection management server. The X.509 client certificates work with web browsers that support SSL—a security protocol that provides privacy and authentication for network traffic. In addition, the web server must also support the SSL protocol.

Client certificates can be acquired from a commercial Certification Authority (CA), such as VeriSign, Entrust, or Thawte. Anyone who purchases a client certificate from one of these vendors and who can access your Reflection web server will be successfully authenticated. Alternatively, an enterprise CA can be used to generate, sign, and distribute certificates locally.

The certificates can be stored in the client's browser certificate store, or on a client smart card. You can also use X.509 client authentication with LDAP authorization to restrict access to specific Reflection sessions.

Conditions for Using X.509 Certificates

To authenticate users with X.509 client certificates, several conditions must be met:

• The web server must be enabled for SSL and for Reflection X.509 client authentication.

• X.509 authentication is only supported when used in conjunction with the Jakarta Tomcat web server and servlet runner/application server.
• X.509 client certificate authentication must be enabled in the Reflection for the Web Administrative WebStation.
• Each client authorized to use Reflection resources must have a client certificate.
• The issuer of the client certificate must be trusted by the management server.
• Users must log on using an HTTPS URL. The redirect from an HTTP URL available in other authentication models does not work with X.509 client certificates.

To set up your environment to meet these conditions, follow the steps in the sections below.

Setting Up the Web Server

To confirm that the web server is enabled for SSL and for Reflection X.509 client authentication:

First, use your web server’s native administrative features to make sure SSL is enabled. If you used the automated installer to install Reflection for the Web, then SSL is already enabled. If you used the manual installation of Tomcat, you may need to create or import an SSL server certificate through the Certificate Wizard utility.

Then, set up the Reflection X.509 client authentication by opening a second port to authenticate the client. Follow the instructions for your scenario.

If you used the automatic installer, you do not need to configure anything else. Reflection sets up an X.509 authentication port and checks to make sure the port is available. The port number appears on the X.509 Client Certificate setup page when you set up access control.

Note: If you upgraded from an earlier version, when you configure access control on the X.509 Client Certificate setup page, the default port may not be correct. Check the server.xml file and either change server.xml to match the default in the Administrative WebStation, or change the default to match the value in server.xml (see steps below).

If you used the manual installation of the Tomcat servlet runner (using the zip file provided with Reflection), an X.509 client authentication port is defined on port 8083 by default. If a different port is needed, change the definition as follows.

1. On the web server, navigate to <install path>\ReflectionServer\jakarta-tomcat<-version>\conf.
2. Open the /server.xml file, where the port is listed.
3. Find this comment:

4. In the section that follows, locate the code that defines the port number.

5. Change the number to an available port number.

Setting Up Reflection

To enable X.509 client authentication in Reflection for the Web:

1. In the Administrative WebStation, click Access Control Setup > Configure.
2. Choose X.509 client certificate, and then click Next.
3. If necessary, enter the port used for X.509 client authentication.

4. Choose whether to use your LDAP database to assign Reflection sessions to users or groups. Click Next.
5. If you are using your LDAP database, enter information to allow Reflection to access your LDAP server. (Reflection skips this page if you are not using LDAP.) Click Next.
6. Review your access control settings and click Save Settings.

Obtaining Client Certificates

You can purchase or create client certificates.

Note: Regardless of the type of client certificate you choose to use, if you use your LDAP database to authorize session access, the common name (CN) on the client certificate must match the user’s identity in the LDAP directory.

Purchase a Certificate from a CA

The easiest way to use X.509 client authentication is to purchase client certificates from a Certificate Authority (CA) such as VeriSign, Entrust, or Thawte. These commercial certificate vendors' root certificates are generally trusted by all web servers, including Tomcat.

However, because these client certificates are automatically trusted by most web servers, anyone who purchases a client certificate from one of these vendors and who can access your Reflection web server will be able to successfully authenticate.

To increase your security when using a client certificate purchased from a CA, use X.509 client authentication with LDAP authorization to restrict access to specific sessions.

Create a Certificate using CA Software

Alternately, you can generate your own client certificates for X.509 client authentication using CA software. Once created, import the root certificate into the management server's list of trusted CAs. (For details, see Importing the Root Certificate to the Web Server).

By itself, this does not alleviate the problem of other commercial CA certificates being automatically trusted; however, if you create your own certificate, then remove the commercial CA vendor’s root certificates from the management server's trusted list, this prevents users with client certificates signed by these vendors from being authenticated by Reflection.

Best Practices for Highest Security

For highest security using X.509 client authentication:

1. Use keytool to delete the default root certificates from the server's trusted list. See http://java.sun.com or the keytool documentation for details.
2. Import your enterprise self-created CA's root certificate to the management server trusted list. For further details, see Importing the Root Certificate to the Web Server.
3. Issue authorized users client certificates signed by using the trusted root certificate. Install these certificates to each client machine's browser. For details, see Installing the Client Certificate.
4. Use LDAP authorization to assign sessions only to those users who need them.

Importing the Root Certificate to the Web Server

During the initial SSL handshake, the web server checks the client certificate against its list of trusted certificate issuers. If you are using a certificate signed by your enterprise CA, or any CA that is not included in the web server’s default trusted list, you must import the certificate root to the trusted list.

Reflection versions 9.5 or higher

To view the management server’s list of trusted CA issuers, enter the following command at the command prompt:

Follow these steps to add a certificate to the Reflection trusted certificates list.

1. On the server, navigate to the directory that contains the JDK’s bin folder. For example, if Reflection was installed using the Windows automated installer, the location is:

2. Copy the certificate to the folder identified in step 1.
3. From a command prompt, enter the following command:

Reflection versions 8.0 through 9.01

Follow these steps to view the management server’s list of trusted CA issuers.

1. In the Administrative WebStation, click Security Setup (Settings in versions earlier than 8.5).
2. On the Certificates tab, scroll down and click “View or modify certificates trusted by the Reflection management server.”

Follow these steps to add a certificate to the Reflection trusted certificates list.

1. Place the certificate in the ReflectionData\certificates folder on the Reflection management server.
2. Return to the page that lists the certificates trusted by the Reflection management server. (In the Administrative WebStation, click Security (Settings in versions prior to 8.5). On the Certificates tab, click "View or modify certificates trusted by the Reflection management server.”
3. Click Import below the Import Trusted Certificates table.
4. Enter the certificate’s file name and a friendly name that enables you to identify the certificate in the trusted list.
5. Click Submit.
6. Restart the Reflection server.

Installing the Client Certificate

The client certificate is installed on each client machine using the browser's certificate installation wizard.

For Internet Explorer, double-click the client certificate to launch the installation wizard.

For Firefox, follow these steps:

1. Click Tools > Options.
2. Click the Advanced icon, and then click View Certificates.
3. Click Import, select the certificate, and then click OK.

For other web browsers, refer to the browser documentation for information on how to import client certificates.

Using an HTTPS URL

An HTTP connection (which provides no security) and an HTTPS connection (which directs the browser to make SSL connection) use different ports. If SSL on Reflection for the Web is not set up to use the default SSL port, 443, then the URL must include the port.

Note: The redirect from HTTP to HTTPS does not apply to X.509 client authentication. The user must log on using HTTPS.

Related Technical Notes

1766	SSL Client Certificates and Reflection for the Web
1879	SSL Client Certificates and Reflection for the Web Security Proxy
9988	Reflection for the Web Technical Notes