Previous Topic: TroubleshootingNext Topic: LanMan User Directories


Troubleshooting SSL Authentication Schemes

This section contains the following topics:

Overview

SSL Configuration

SSL Troubleshooting

Overview

Configuring the SSL Advanced Authentication Schemes requires Web Servers to be properly configured to use SSL. Most of the problems you may encounter configuring Authentication Schemes over SSL connections are likely to be SSL configuration issues. Therefore, the first step in troubleshooting Authentication Schemes over SSL is to verify that SSL is properly configured and working. This is done without the interaction of the CA SiteMinder® Web Agent so that these components can be individually analyzed.

Determine SSL Connection Ability

The first step in troubleshooting Authentication Schemes over SSL is to verify that SSL is properly configured and working. This is done without the interaction of the CA SiteMinder® Web Agent so that these components can be individually analyzed.

To determine whether you are able to establish an SSL connection

  1. Disable the CA SiteMinder® Web Agent protecting the realm for which you want to use an authentication scheme over SSL.

    Note: For information about disabling a Web Agent, see the Web Agent Configuration Guide.

  2. Using your browser, go to one of the following URLs (using a browser with a certificate):

    If this SSL connection is configured to require certificates, you will be prompted to select a certificate.

If you are unable to successfully establish this SSL connection, then see SSL Configuration for more information on configuring SSL. If you were able to establish this connection, but have not been successful in configuring CA SiteMinder®, see SSL Troubleshooting.

SSL Configuration

It is imperative that SSL be configured and working properly before using CA SiteMinder®. In order to make an SSL connection, you must be able to trust the certificate authority of an incoming certificate. For example, if a browser presents a certificate that was signed by VeriSign, you must have a VeriSign Certificate Authority installed and trusted in the Web Server. In addition to trusting client certificates that are presented, the server itself must have a certificate to present to the clients. The clients have to trust the Certificate Authority that issued the certificate. This allows for mutual authentication. Once these certificates have been installed, you can configure the Web Server to use SSL and require certificates, if desired.

For detailed SSL configuration information, see the documentation provided with your web server software. This section contains step-by-step instructions for configuring your Web Server and Web browser to successfully establish an SSL connection. If you have correctly configure SSL, but are still having problems making the connection, see the common problems at the end of the section.

Enable the Web Server to Trust Client Certificates in Netscape

If a certificate authority is already installed in the Web Server, go on to the next section. Otherwise, install a certificate for the Certificate Authority on the SSL Web Server.

To enable the Web Server to Trust Client Certificates in Netscape

  1. Obtain the Certificate Authority’s certificate and either keep it on your screen or save it to a file.
  2. In Netscape Server Administration, select Keys & Certificates.
  3. Click Install Certificate.
  4. In the Certificate For field, fill out the Server Security Chain.
  5. In the Certificate Name field, enter a description.
  6. If you saved your Certificate Authority’s certificate to a file, enter the file name in the Message is in this file field; otherwise, select the Message text (with headers) radio button and paste the certificate in the Message text (with headers) field.
  7. Click OK and restart the Web Server.
Configure the Netscape Web Server to use SSL

After installing the Netscape Web Server Certificate, you must configure the Netscape Web Server to use SLL by requiring certificates.

To require certificates for your SSL Web Server

  1. In Netscape Server Administration, click Admin Preferences.
  2. Click Encryption On/Off and ensure that Encryption is on.
  3. If you are running the Certificate or Certificate with Basic Authentication Scheme, you must require certificates. This is done under Encryption Preferences setting where Require Certificates must be set to On. From a browser that has a Certificate installed, verify that you can get to https://servername:port.

Note: Do not turn on Required Certificates for the Certificate or Basic Authentication Scheme.

Establish Trust for the Netscape Certificate Authority

If a certificate authority is installed in the Web Server, you can establish trust between the two.

To establish trust for the Netscape Certificate Authority

  1. In Netscape Server Administration, select Keys & Certificates.
  2. Select Manage Certificates.
  3. Select the Certificate Authority. The system displays a dialog detailing the certificate.
  4. Select Trust.
  5. Click OK and restart the Web Server.
Enable the Web Server to Trust Client Certificates in Windows

You must trust your client certificates by installing the appropriate Certificate Authority Certificates.

SSL Web Servers must have certificates for each Certificate Authority. Major certificate authorities may already be installed. You can configure certificates in Windows operating systems by using the Certificates snap-in. For information, see your Windows documentation.

Configure the IIS Web Server to use SSL

Be sure that a secure port has been enabled on the Web Server. Generally this is port 443. You can verify this through the Management Console by right-clicking on the Web Server and in the Web site tab you will see an SSL Port. Be sure a port number has been installed.

The advanced authentication schemes will create virtual directories in the Web Server. These directories will automatically be configured to require SSL and certificates as required by the specific authentication scheme. However, for testing purpose, you may want to create a test virtual directory. You can configure this virtual directory to require certificates through the Directory Security tab, Secure Communications.

https://servername:port/virtual directory - Ensure that the browser is asked for a certificate.

Install the IIS Web Server Certificate

If you have not already done so, you will need to generate a key for your Web server. This is done through the Management Console, Key Manager. Access the Key Manager by doing the following:

Note: Note this process may be slightly different for IIS 3 and IIS 4.

To install the IIS Web Server Certificate

  1. In the Management Console, right-click the Web Server and select Properties.
  2. Click the Directory Security tab.
  3. In the Secure Communications panel, click Key Manager.
  4. Under Key, select Create New Key and a Wizard will guide you through the process.

    Once you create a key, you can request a certificate using the file created in the steps mentioned earlier. Go to the Certificate Authority and request a certificate for this server. You will need to paste the certificate request information generated in Step 1 in order to receive a certificate. Once you received a certificate, go back to Management Console, Directory Security and click Key Manager to install the certificate for the key described in the next step.

  5. Right-click the key name and select Install Certificate.
  6. Restart the Web Server.
Enable the Web Server to Trust Client Certificates in Apache

If a certificate authority is already installed on your web server, go on to the next section. Otherwise, install a certificate for the CA on the SSL Web Server as follows.

To enable the Web Server to trust client certificates in Apache

  1. Download and build the following Apache components:
  2. Copy the CA certificate into the apache/conf/ssl.crt directory in x509 b64 format.
  3. Run make in the apache/conf/ssl.crt directory.
  4. Restart the Web Server.
Installing the Apache Web Server Certificate

The process for installing a certificate on an Apache Web Server varies with individual configurations. Consult the documentation for Mod_SSL and OpenSSL for details about how to configure these components.

SSL Troubleshooting

The following sections detail the most common problems encountered when dealing with SSL authentication schemes.

There Was No Prompt for a Certificate

If you were not prompted for a certificate, verify that SSL is configured appropriately. If the Web Agent is installed, disable the Web Agent. The first step is to verify a simple SSL connection.

To determine whether you are able to establish an SSL connection

  1. Disable the CA SiteMinder® Web Agent protecting the realm for which you want to use an authentication scheme over SSL.

    Note: For information about disabling a Web Agent, see the Web Agent Configuration Guide.

  2. Using your browser, go to one of the following URLs (using a browser with a certificate):

    If this SSL connection is configured to require certificates, you will be prompted to select a certificate.

After Following Previous Procedure, Still No Certificate Prompt

Perform the following five additional steps if you are still not receiving a certificate prompt.

Verify That All Firefox Browsers Are Configured to Ask Every Time

Firefox browsers can be configured to pass the same certificate automatically. This establishes the SSL connection using a certificate without prompting users to select a certificate.

Follow these steps:

  1. In the Firefox browser, select Options from the Firefox menu.
  2. Click Advanced.
  3. Click the Encryption tab.
  4. In the Certificates section, verify that the Ask me every time option is set.
Verify That All Web Servers Are Configured to Use SSL and Require Certificates
For Netscape Web Servers
  1. In the Netscape Server Administration, click Admin Preferences.
  2. Click Encryption On/Off and verify that the encryption is on, then click OK.
  3. Click Encryption Preferences and verify that Required Certificates is set.
  4. Restart the Web Server.
For IIS Web Servers

Verify that the virtual directories SMGetCredCert, SMGetCredCertOptional, SMGetCredNoCert are created and have the correct settings.

Note: As part of the CA SiteMinder® SSL Authentication setup, CA SiteMinder® configures SSL virtual directories based on the type of SSL connection required by the authentication scheme.

Verify the Following Settings for each SiteMinder Virtual Directory

To verify the following settings for each CA SiteMinder® Virtual Directory

  1. In the Management Console, right-click a virtual directory and select Properties.
  2. Click the Directory Security tab.
  3. Click Edit Secure Communications.
For Apache Web Servers

In the httpd.conf file, be sure to set SSLVerifyClient as follows:

Check the Web Server’s Certificate Expiration
Netscape Servers
  1. In the Netscape Server Administration, click Keys & Certificates.
  2. Click Manage Certificates.
  3. Click ServerCert.
  4. Verify that it is trusted, and has not expired. If it does not exist, or has expired, you will need to request a new certificate by following the steps in Install the Netscape Web Server Certificate.
IIS Servers
  1. In the Management Console, right-click the Web Server and select Properties.
  2. Click the Directory Security tab.
  3. In the Secure Communications panel, click Key Manager.
  4. Select a key to view its properties and verify that the key has not expired.
  5. If you need to make any changes, restart the Web Server.
Apache Servers

If an Apache Web Server certificate expires, you will receive an error messages at server startup that indicates the certificate has expired.

Verify Browser Certificate Validity

A missing certificate or an invalid certificate can prevent you from receiving a certificate prompt.

Open your Web browser and verify the validity of the browser certificate.

Note: For more information about viewing certificate information, see your vendor–specific documentation.

After Certificate Prompt, Authentication Failure Received
Apache Web Servers
Netscape Web Servers

Verify that the Certificate Authority for the certificate is listed and that the Trust for the certificate has not expired. If it is not there or is not valid, install a new CA certificate.

IIS Web Servers

Verify that the certificate is listed and that it is valid. If it is not present or is not valid, install a new certificate. If you are able to get to the destination directory, then certificates are installed correctly.

Verify Correct Policy Server and Web Agent Configuration

After completing the steps in the previous topic based on your specific web server, verify your policy server and web agent configuration.

To verify correct policy server and web agent configuration

  1. Check that the Policy Server is created correctly.
  2. Check that the Web Agent contains the correct Policy Server information.
  3. Verify that the Web Agent is enabled.
  4. Restart the Web Agent and Policy Server.
SiteMinder Policy Should Allow Access, but SSL-Authentication Failed Message Received

In this situation, there is a Policy that is being called, but the user is incorrectly being denied access. This can result from a number of configuration errors. Common errors include:

Error Not Found Message Received

This is generally caused from the Authentication Scheme Parameter being configured improperly. The redirect is not configured properly so the Web Server is unable to find the SSL Web Agent component.

More information:

Authentication Schemes

Running Certificate or Basic but Cannot Enter Basic credentials.

On Netscape Web Servers, the Certificate or Basic scheme requires the Web Server to have encryption turned on, but does not require certificates. Be sure that in the Encryption Preferences section of the Netscape Server Administration, the Require Certificate setting is set to No.