Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide

Setting Client Security Requirements

After you have performed all of the steps to secure your servers, additional security requirements can be set for your clients.

Client authentication is not essential to an SSL connection, but it does give extra assurance that encrypted information is being sent to the correct parties. You can use client authentication in a reverse proxy to make sure that your content server does not share information with unauthorized proxies or clients.

This section contains the following topics:

Requiring Client Authentication

You can enable the listen sockets for your Administration Server and each server instance to require client authentication. When client authentication is enabled, the client’s certificate is required before the server sends a response to a query.

Proxy Server supports authenticating client certificates by matching the CA in the client certificate with a CA trusted for signing client certificates. You can view a list of CAs trusted for signing client certificates on the Manage Certificates page through the Security tabs.

You can configure the Proxy Server to refuse any client that does not have a client certificate from a trusted CA. To accept or reject trusted CAs, client trust must be set for the CA. For more information, see Managing Certificates.

Proxy Server logs an error, rejects the certificate, and returns a message to the client if the certificate has expired. You can also view which certificates have expired on the Manage Certificates page.

You can configure your server to gather information from the client certificate and match it with a user entry in an LDAP directory. This process ensures that the client has a valid certificate and an entry in the LDAP directory. It can also ensure that the client certificate matches the one in the LDAP directory. To learn how to do this, Mapping Client Certificates to LDAP.

You can combine client certificates with access control, so that in addition to being from a trusted CA, the user associated with the certificate must match the access control rules (ACLs). For more information, see Using Access Control Files.

ProcedureTo Require Client Authentication

  1. Access either the Administration Server or the Server Manager and click the Preferences tab.

  2. Click the Edit Listen Sockets link.

  3. Click the link for the listen socket for which you are requiring client authentication.

  4. Use the Client Authentication drop-down list to require client authentication for the listen socket, and click OK.

Client Authentication in a Reverse Proxy

In a reverse proxy, you can configure client authentication according to any of the following scenarios:

For information about how to configure these scenarios, see Setting Up Client Authentication in a Reverse Proxy.

Setting Up Client Authentication in a Reverse Proxy

Client authentication in a secure reverse proxy provides further insurance that your connections are secure. The following instructions explain how to configure client authentication according to the scenario you choose.


Note –

Each scenario assumes that you have both a secure Client-to-Proxy connection and a secure Proxy-to-Content-Server connection.


ProcedureTo Configure the Proxy-Authenticates-Client Scenario

  1. Follow the directions for configuring the secure Client-to-Proxy and secure Proxy-to-Content Server scenario in “Setting up a Reverse Proxy” in Chapter 14, Using a Reverse Proxy.

  2. Access the Server Manager for a server instance and click the Preferences tab.

  3. Click the Edit Listen Sockets link, and then click the link for the desired listen socket in the table that displays.

    (Use the Add Listen Socket link to configure and add listen sockets.)

  4. Specify client authentication requirements:

    1. To permit access to all users with valid certificates:

      In the Security section, use the Client Authentication setting to require client authentication on this listen socket. If a server certificate has not been installed, this setting will not be visible.

    2. To permit access to only those users who have both valid certificates and are specified as acceptable users in access control:

      1. In the Security section, leave the Client Authentication setting set to off. If a server certificate has not been installed, this setting will not be visible.

      2. On the Server Manager Preferences tab for this server instance, click the Administer Access Control link.

      3. Select an ACL, and then click the Edit button.

        The Access Control Rules For page displays (authenticate first, if prompted).

      4. Turn access control on (select the Access control Is On checkbox if not already selected).

      5. Set your Proxy Server to authenticate as a reverse proxy.

        For more information, see Setting up a Reverse Proxy.

      6. Click the Rights link for the desired access control rule, specify access rights in the lower frame, and then click Update to update this entry.

      7. Click the Users/Groups link. In the lower frame. Specify users and groups, select SSL as the authentication method, and click Update to update this entry.

      8. Click Submit in the upper frame to save your entries.

        For more information about setting access control, see Chapter 8, Controlling Access to Your Server.

ProcedureTo Configure the Content Server-Authenticates-Proxy Scenario

  1. Follow the directions for configuring the secure Client-to-Proxy and secure Proxy-to-Content-Server scenario in Setting up a Reverse Proxy.

  2. On your content server, turn client authentication on.

    You can modify this scenario so that you have an unsecure client connection to the Proxy Server, a secure connection to the content server, and the content server authenticates the Proxy Server. To do so, you must turn encryption off and require the proxy to initialize certificates only as described in the following procedure.

ProcedureTo Configure the Proxy-Authenticates-Client and Content Server-Authenticates-Proxy scenario

  1. Follow the directions for configuring the Proxy-Authenticates-Client scenario in To Configure the Proxy-Authenticates-Client Scenario.

  2. On your content server, turn client authentication on.

Mapping Client Certificates to LDAP

This section describes the process that the Proxy Server uses to map a client certificate to an entry in an LDAP directory. Before mapping client certificates to LDAP, you must also configure the required ACLs. For more information, see Chapter 8, Controlling Access to Your Server.

When the server receives a request from a client, the server asks for the client’s certificate before proceeding. Some clients send the client certificate to the server along with the request.

The server tries to match the CA to the list of trusted CAs in the Administration Server. If a match does not exist, Proxy Server ends the connection. If a match exists, the server continues processing the request.

After verifying that the certificate is from a trusted CA, the server maps the certificate to an LDAP entry by doing the following:

The server uses a certificate mapping file called certmap.conf to determine how the LDAP search is performed. The mapping file tells the server what values to take from the client certificate such as the end user’s name, email address, and so on. The server uses these values to search for a user entry in the LDAP directory, but first the server must determine where in the LDAP directory to start the search. The certificate mapping file also tells the server where to start.

Once the server knows where to start the search and what to search for, it performs the search in the LDAP directory (second point). If it finds no matching entry or more than one matching entry, and the mapping is not set to verify the certificate, the search fails.

The following table lists the expected search result behavior. You can specify the expected behavior in the ACL. For example, you can specify that the Proxy Server accepts only you if the certificate match fails. For more information about how to set the ACL preferences, see Using Access Control Files.

Table 5–1 LDAP Search Results

LDAP Search Result  

Certificate Verification ON  

Certificate Verification OFF  

No entry found 

Authentication fails 

Authentication fails 

Exactly one entry found 

Authentication fails 

Authentication succeeds 

More than one entry found 

Authentication fails 

Authorization fails 

After the server finds a matching entry and certificate in the LDAP directory, the server can use that information to process the transaction. For example, some servers use certificate-to-LDAP mapping to determine access to a server.

Using the certmap.conf File

Certificate mapping determines how a server looks up a user entry in the LDAP directory. You can use the certmap.conf file to configure how a certificate, designated by name, is mapped to an LDAP entry. You edit this file and add entries to match the organization of your LDAP directory, and to list the certificates you want your users to have. Users can be authenticated based on user ID, email address, or any other value used in the subjectDN. Specifically, the mapping file defines the following information:

The certificate mapping file is found in the following location:

server-root/userdb/certmap.conf

The file contains one or more named mappings, each applying to a different CA. A mapping has the following syntax:

certmap name issuerDNname:property [value]

The first line specifies a name for the entry and the attributes that form the distinguished name found in the CA certificate. The name is arbitrary and can be defined to whatever you prefer. However, issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuer DN lines differ only in the spaces separating the attributes, but the server treats these two entries as different:

certmap sun1 ou=Sun Certificate Authority,o=Sun,c=UScertmap sun2 ou=Sun Certificate Authority, o=Sun, c=US


Note –

If you are using Oracle Directory Server Enterprise Edition and experiencing problems in matching the issuer DN, check the Directory Server error logs for useful information.


The second and subsequent lines in the named mapping match properties with values. The certmap.conf file has six default properties. You can also use the certificate API to customize your own properties. The default properties are:

Table 5–2 Attributes for x509v3 Certificates

Attribute  

Description  

c

Country 

o

Organization 

cn

Common name 

l

Location 

st

State 

ou

Organizational unit 

uid

UNIX/Linux userid 

email

Email address 

For more information about these properties, refer to the examples described in Sample Mappings.

Creating Custom Properties

The client certificate API can be used to create your own properties. Once you have a custom mapping, you reference the mapping as follows:

name:library path_to_shared_libraryname:InitFN name_of_init_function

For example:

certmap default1 o=Sun Microsystems, c=US default1:library /usr/sun/userdb/plugin.so default1:InitFn plugin_init_fn default1:DNComps ou o c default1:FilterComps l default1:verifycert on

Sample Mappings

The certmap.conf file should have at least one entry. The following examples illustrate the different ways certmap.conf can be used.

Example #1 certmap.conf File With Only One Default Mapping

certmap default defaultdefault:DNComps ou, o, cdefault:FilterComps e, uiddefault:verifycert on

Using this example, the server starts its search at the LDAP branch point containing the entry ou=orgunit, o=org, c=country, where the italicized text is replaced with the values from the subject’s DN in the client certificate.

The server then uses the values for e-mail address and user ID from the certificate to search for a match in the LDAP directory. When an entry is found, the server verifies the certificate by comparing the one sent by the client to the one stored in the directory.

Example #2 certmap.conf File With Two Mappings

The following example file has two mappings: one for default and another for the US Postal Service.

certmap default defaultdefault:DNCompsdefault:FilterComps e, uid

certmap usps ou=United States Postal Service, o=usps, c=USusps:DNComps ou,o,cusps:FilterComps eusps:verifycert on

When the server receives a certificate from anyone other than the US Postal Service, it uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client’s email address and user ID. If the certificate is from the US Postal Service, the server starts its search at the LDAP branch containing the organizational unit and searches for matching email addresses. Also the server verifies the certificate. Other certificates are not verified.


Caution – Caution –

The issuer DN (that is, the CA’s information) in the certificate must be identical to the issuer DN listed in the first line of the mapping. In the previous example, a certificate from an issuer DN that is o=United States Postal Service,c=US will not match because the DN has no space between the o and the c attributes.


Example #3 Searching the LDAP Database

The following example uses the CmapLdapAttr property to search the LDAP database for an attribute called certSubjectDN, whose value exactly matches the entire subject DN taken from the client certificate. This example assumes that the LDAP directory contains entries with the attribute certSubjectDN

certmap myco ou=My Company Inc, o=myco, c=USmyco:CmapLdapAttr certSubjectDNmyco:DNComps o, c myco:FilterComps mail, uid myco:verifycert on

If the client certificate subject is:

uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

the server first searches for entries that contain the following information:

certSubjectDN=uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server uses DNComps and FilterComps to search for matching entries. In this example, the server searches for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.