Using X.509 Client Certificate Authentication with Reflection for the Web

  • 7022225
  • 15-Apr-2004
  • 13-Mar-2018


Reflection Security Gateway 2014
Reflection for the Web 2014 (All Editions)
Reflection for the Web 2011 (All Editions)
Reflection for the Web 2008 (All Editions)


Reflection for the Web and Reflection Security Gateway provide 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.


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.

Note: The feature described in this technical note has been deprecated and will be removed from the product in a future version. Some editions of Reflection for the Web and Reflection Security Gateway provide an alternative configuration that allows X.509 authentication using HTTP or HTTPS. It is recommended to use the alternative configuration.

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.


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 automated 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 performed a 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

Reflection for the Web 2014, 2011, and Reflection Security Gateway 2014, 2011

<install path>\ReflectionServer\apache-tomcat<-version>\conf

Reflection for the Web 2008

<install path>\ReflectionServer\jakarta-tomcat<-version>\conf
  1. Open the /server.xml file, where the port is listed.
  2. Find this comment:
"Define an SSL HTTP/1.1 Connector on port 8083 for X.509 client authentication"
  1. In the section that follows, locate the code that defines the port number.

For example, port="8083"

  1. 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.

Note: If you used the automated installer to set up Reflection, the installer selects an X.509 port (8083, for instance) and the Access Control Setup wizard presents that port as a default.

Click Next.

  1. Choose whether to use your LDAP database to assign Reflection sessions to users or groups. Click Next.
  2. 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.
  3. 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 the Java keytool to delete the default root certificates from the server's trusted list. See for keytool documentation.
  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.

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

keytool -list -v -keystore <path>cacerts

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:

For Reflection for the Web 2014, 2011, and Reflection Security Gateway 2014, 2011: ReflectionServer\jre\bin\

For Reflection for the Web 2008: ReflectionServer\_jvm\bin\

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

keytool -v -importcert -file <file containing certificate> -keystore "<path>cacerts" -alias <friendly name>

Note: The default password for the cacerts keystore file is changeit. System administrators should change the password and the default access permission of that file when adding a certificate.

Replace <file containing certificate> with the certificate's file name, and replace <friendly name> with a name that enables you to identity the certificate in the trusted list. For example:

For Reflection for the Web 2014, 2011, and Reflection Security Gateway 2014, 2011:

keytool –v –importcert –file clientcert.pfx –keystore "c:\program files\Attachmate\ReflectionServer\jre\lib\security\cacerts" –alias JoanSimmonsCertificate

For Reflection for the Web 2008:

keytool –v –importcert –file clientcert.pfx –keystore "c:\program files\ReflectionServer\_jvm\lib\security\cacerts" –alias JoanSimmonsCertificate

Note: For more information about the keytool command, enter keytool at the command prompt for a list of parameters.

  1. Restart the Reflection Server to apply this change.

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 4, follow these steps:

  1. Click Tools > Options.
  2. Click the Advanced icon. On the Encryption tab, 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.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 1756.