CA SiteMinder® Federation Standalone Guide › User Directory Connections for Authentication › How to Connect to an LDAP User Directory Over SSL

How to Connect to an LDAP User Directory Over SSL

Connecting to an LDAP user directory over SSL requires that you configure the system to use the certificate database files.

Follow the instructions in the subsequent sections to configure the connection over SSL.

Note: CA Directory does not support this method of configuring SSL.

Before You Configure an LDAP Connection over SSL

Review the following points before configuring an LDAP user directory connection over SSL:

• Verify that your directory server is SSL-enabled.
• Verify that the database files are in the Netscape database version file format (cert8.db). The Policy Server uses a Mozilla LDAP SDK to communicate with LDAP directories.

  Important! Do not use Microsoft Internet Explorer to install certificates into your cert8.db database file.

• (Active Directory) Considering the following points:
  • If the user directory connection is configured with the AD namespace, the SSL process that is documented in the subsequent topics does not apply. The AD namespace uses the native Windows certificate repository when establishing an SSL connection. When configuring the AD namespace to communicate over SSL:
    • Verify that the user directory connection is configured for a secure connection.

On the computer hosting the Active Directory instance, verify that the root CA certificate and the server certificate are added to the service certificate store.

Create the Certificate Database Files

To create the certificate database files, use the Mozilla Network Security Services (NSS) certutil application that is included with the Policy Server

Note: The following procedure details the specific options and arguments to complete the task. For a complete list of the NSS utility options and arguments, refer to the Mozilla documentation on the NSS project page.

Important! Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command-line window with administrator permissions. Open the command-line window this way, even if your account has administrator privileges.

Follow these steps:

1. From a command prompt, navigate to the installation bin directory.

   Example: C:\Program Files\CA\SiteMinder\bin

   Note: Windows has a native certutil utility. Verify that you are working from the Policy Server bin directory, or you can inadvertently run the Windows certutil utility.

2. Enter the following command:

   certutil -N -d certificate_database_directory
   

   -N

   Creates the cert8.db, key3.db, and secmod.db certificate database files.

   -d certificate_database_directory

   Specifies the directory in which the certutil tool is to create the certificate database files.

   Note: If the file path contains spaces, bracket the path in quotes.

   The utility prompts for a password to encrypt the database key.

3. Enter and confirm the password.

   NSS creates the required certificate database files:

   • cert8.db
   • key3.db
   • secmod.db

Example: Create the Certificate Database Files

certutil -N -d C:\certdatabase

Add the Root Certificate Authority to the Certificate Database

To add the root Certificate Authority (CA), use the Mozilla Network Security Services (NSS) certutil application, which is in the Policy Server.

Note: The following procedure details the specific options and arguments to complete the task. For a complete list of the NSS utility options and arguments, refer to the Mozilla documentation on the NSS project page.

Important! Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command-line window with administrator permissions. Open the command-line window this way, even if your account has administrator privileges.

Follow these steps:

1. From a command prompt, navigate to the Policy Server installation bin directory.

   Example: C:\Program Files\CA\SiteMinder\bin

   Note: Windows has a native certutil utility. Verify that you are working from the bin directory of the NSS utility, or you can inadvertently run the Windows certutil utility.

2. Run the following command:

   certutil -A -n alias -t trust_arguments -i root_CA_path -d certificate_database_directory
   

   -A

   Adds a certificate to the certificate database.

   -n alias

   Specifies an alias for the certificate.

   Note: If the alias contains spaces, bracket the alias with quotes.

   -t trust_arguments

   Specifies the trust attributes to apply to the certificate. The three available trust categories are expressed in this order: "SSL, email, object signing". In each category position, you can use zero or more of the following attribute arguments.

   p

   Valid peer.

   P

   Trusted peer. This argument implies p.

   c

   Valid CA.

   T

   Trusted CA to issue client certificates. This argument implies c.

   C

   Trusted CA to issue server certificates (SSL only). This argument implies c.

   Important! This argument is required for the SSL trust category.

   u

   Certificate can be used for authentication or signing.

   -i root_CA_path

   Specifies the path to the root CA file. The path includes the certificate name. The valid extensions for a certificate include cert, .cer, and .pem.

   Note: If the file path contains spaces, bracket the path in quotes.

   -d certificate_database_directory

   Specifies the path to the directory that contains the certificate database.

   Note: If the file path contains spaces, bracket the path in quotes.

Example: Adding a Root CA to the Certificate Database

certutil -A -n "My Root CA"  -t "C,," -i C:\certificates\cacert.cer -d C:\certdatabase

Add the Server Certificate to the Certificate Database

To enable communication over SSL, add the server certificate to the certificate. Use the Mozilla Network Security Services (NSS) certutil application, which is available with the Policy Server.

Note: The following procedure details the specific options and arguments to complete the task. For a complete list of the NSS utility options and arguments, refer to the Mozilla documentation on the NSS project page.

Important! Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command-line window with administrator permissions. Open the command-line window this way, even if your account has administrator privileges.

Follow these steps:

1. From a command prompt, navigate to the Policy Server installation bin directory.

   Example: C:\Program Files\CA\SiteMinder\bin

   Note: Windows has a native certutil utility. Verify that you are working from the bin directory of the NSS utility, or you can inadvertently run the Windows certutil utility.

2. Run the following command:

   certutil -A -n alias -t trust_arguments -i server_certificate_path -d certificate_database_directory
   

   -A

   Adds a certificate to the certificate database.

   -n alias

   Specifies an alias for the certificate.

   Note: If the alias contains spaces, bracket the alias with quotes.

   -t trust_arguments

   Specifies the trust argument. The three available trust categories for each certificate are expressed in this order: "SSL, email, object signing". In each category position, you can use zero or more of the following attribute arguments:

   p

   Valid peer.

   P

   Trusted peer. This argument implies p.

   Important! This argument is required for the SSL trust category.

   -i server_certificate_path

   Specifies the path to the server certificate. The path includes the certificate name. The valid extensions for a certificate include.cert, .cer, and .pem.

   Note: If the file path contains spaces, bracket the path in quotes.

   -d certificate_database_directory

   Specifies the path to the directory that contains the certificate database.

   Note: If the file path contains spaces, bracket the path in quotes.

   NSS adds the server certificate to the certificate database.

Example: Adding a Server Certificate to the Certificate Database

certutil -A -n "My Server Certificate" -t "P,," -i C:\certificates\servercert.cer -d C:\certdatabase

Verify that the Certificates are in the Database

To verify that the certificates are in the certificate database, use the Mozilla Network Security Services (NSS) certutil application. Policy Server includes this tool.

Note: The following procedure details the specific options and arguments to complete the task. For a complete list of the NSS utility options and arguments, refer to the Mozilla documentation on the NSS project page.

Important! Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command-line window with administrator permissions. Open the command-line window this way, even if your account has administrator privileges.

Follow these steps:

1. From a command prompt, navigate to the Policy Server installation bin directory.

   Example: C:\Program Files\CA\SiteMinder\bin

   Note: Windows has a native certutil utility. Verify that you are working from the bin directory of the NSS utility, or you can inadvertently run the Windows certutil utility.

2. Run the following command:

   certutil -L -d certificate_database_directory
   

   -L

   Lists all of the certificates in the certificate database.

   -d certificate_database_directory

   Specifies the path to the directory that contains the certificate database.

   Note: If the file path contains spaces, bracket the path in quotes.

   This command displays the root CA alias, the server certificate alias, and the trust attributes you specified when adding the certificates to the certificate database.

Example: List the Certificates in the Certificate Database

certutil -L -d C:\certdatabase

SSL-enable the LDAP User Directory Connection

After pointing the system to the correct certificate database, enable the SSL-secured connection to the LDAP user directory. SSL further secures the communication between the Policy Server and the user directory.

Note: The following procedure assumes that you have an LDAP connection working properly.

Follow these steps:

1. Log in to the Administrative UI.
2. Select the User Directory tab.

   The User Directory List is displayed.

3. Click Action, Modify next to the LDAP entry you want to SSL-enable.
4. Verify that the Server field in the Configure LDAP User Directory section contains the correct server and port value for the SSL connection. SSL often uses a different port than a non-SSL connection.
5. Select the Secured Connection check-box in the Connection Credentials section.
6. Click Save.

   You return to the User Directory dialog.

7. In the User Directory list, select Action, Test Connection next to the LDAP entry that is SSL-enabled.

   A message at the top of the dialog either confirms that the SSL is properly configured reports and error.

The user directory connection is configured to communicate over SSL.

Establish a Connection to the Certificate Database

Connecting to an LDAP user directory over SSL requires that the system point to the proper certificate database. This database must contain the cert8.db and key3.db files.

The XPSConfig tool, which is shipped with the product, enables you to specify the path to the certificate database using the LdapObjCertDbPath setting.

Follow these steps:

1. Open a command window.
2. Navigate to federation_install_dir.
3. Enter XPSConfig. The command is case-sensitive on UNIX platforms.
4. Enter SM.
5. Enter the number for the LdapObjCertDbPath setting.
6. Enter C to change the value.
7. Specify the path to the certificate database for the Enter New Value prompt.

   Example:

   C:\Program Files\CA\Federation Standalone\ldaps\certdb
   

8. Enter Q until you exit from XPSConfig.

   The new value is saved.

The correct certificate database is now in use.

Verify the SSL Connection to the LDAP Directory

Verify the SSL connection and so you are sure that the user directory connection is secured.

Follow these steps:

1. Log in to the Administrative UI.
2. Select User Directory.

   The User Directories screen appears. The table lists the names of existing user directory connections.

3. Select Action, Modify next to the name of the user directory you want to test.

   The directory settings display.

4. Click View Contents.

   If SSL is properly configured, the Directory Contents screen appears and lists the contents of the user directory.

Troubleshoot the SSL Connection to the LDAP User Directory

The list following specifies actions you can take when you encounter problems connecting to the LDAP user directory using SSL:

• Verify that you can connect to the user directory without using a secured connection.
• Verify that SSL is enabled for the LDAP server you are using.
• Verify that the SSL port of the LDAP server is reachable from the CA SiteMinder® Federation Standalone host.
• Verify that the system is pointing to the directory that contains the certificate database files.
• Verify that that the certificate database directory contains the cert8.db and the key3.db files.
• Verify that the LDAP server configuration (including port), the connection credentials and the search root are configured correctly in the Administrative UI.