After you have completed the process to secure your servers, you can set additional security requirements for your clients.
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.
The Sun Java System Web 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 the Manage Certificates page under Security in the Administration Server. There are four types of CAs:
Untrusted CA (not matched)
Trusted Server CA (not matched)
Trusted Client CA (matched)
Trusted Client/Server CA (will be matched)
You can configure the web server to refuse any client that does not have a client certificate from a trusted CA. To accept or reject trusted CAs, you must have set client trust for the CA. For more information, see Managing Certificates.
The Sun Java System Web Server logs an error, rejects the certificate, and returns a message to the client if the certificate has expired. You can view a list of certificates that have expired in the Administration Servers Manage Certificates page.
You can configure your server to collect information from the client certificate and match it with a user entry in an LDAP directory. This ensures that the client has a valid certificate and an entry in the LDAP directory, and also ensure that the client certificate matches the one in the LDAP directory. To learn how to do this, see Mapping Client Certificates to LDAP.
You can combine client certificates with access control. 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.
You can also process information from client certificates. For more information, see the Sun Java System Web Server 6.1 SP8 NSAPI Programmer’s Guide.
To require client authentication, perform the following steps:
Access either the Administration Server or the Server Manager and choose the Preferences tab.
From the Server Manager you must first select the server instance from the drop-down list.
Click the Edit Listen Sockets link.
The Edit Listen Sockets page appears.
Click the Listen Socket Id link corresponding to the listen socket you are requiring client authentication for.
The Edit Listen Socket page appears.
To require client authenticate for the listen socket, select Required from the Client Authentication drop-down list.
Click OK.
From the Server Manager, click Apply, and then Restart for changes to take effect.
Currently, there is a single certificate trust database per web server instance. All the secure virtual servers running under that server instance share the same list of trusted client CAs. If two virtual servers require different trusted CAs, then these virtual servers should be run in different server instances with separate trust databases.
This section describes the process followed by the Sun Java System Web Server to map a client certificate to an entry in an LDAP directory.
When the server gets a request from a client, it asks for the client’s certificate before proceeding. Some clients send the client certificate to the server along with the request.
Before mapping client certificates to LDAP, you need to set up the required ACLs. For more information, see Chapter 10, Controlling Access to Your Server.
The server tries to match the CA to the list of trusted CAs in the Administration Server. If there is no match, the Sun Java System Web Server terminates the connection. If a match occurs, 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 using the following methods:
Mapping the issuer and subject DN from the client certificate to a branch point in the LDAP directory.
Searching the LDAP directory for an entry that matches the information about the subject (end-user) of the client certificate.
(Optional) Verifying the client certificate with another certificate in the LDAP entry that corresponds to the DN.
The server uses a certificate mapping file called the certmap.conffile to determine how to do conduct LDAP search. The mapping file provides the server with values to get from the client certificate (such as the end-user’s name and email address). The server uses these values to search for a user entry in the LDAP directory. First the server needs to determine where in the LDAP directory it needs to start its search. The certificate mapping file also tells the server where to start.
Once the server knows where to start its search and what it needs to search for (step 1), it performs the search in the LDAP directory (step 2). 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. For a complete list of the expected search result behavior, see the following Table 6-1. Note that you can specify the expected behavior in an ACL. For example, you can specify that Sun Java System Web Server accepts only you if the certificate match fails. For more information regarding how to set ACL preferences, see Using Access Control Files.
Table 6–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, it can use that information to process the transaction. For example, some servers use certificate-to-LDAP mapping to determine access to another server.
Certificate mapping determines how a server scans user entry in the LDAP directory. You can use the certmap.conf to configure how a certificate, designated by name, is mapped to an LDAP entry. You edit this file and add entries to match the structure of your LDAP directory and to list the certificates you want your users to have. Users can be authenticated based on userid, email, or any other value used in the subjectDN. Specifically, the mapping file defines the following information:
The LDAP tree location the server from where begins its search
Certificate attributes that the server should use as search criteria when searching for the entry in the LDAP directory
Whether or not the server goes through an additional verification process
The certificate mapping file is located 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> <issuerDN>
<name>:<property> [<value>]
The first line specifies a name for the entry and the attributes that form the distinguished name found in the CA certificate. You can select any name for the entry. However, the issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuerDN lines have different space separating the attributes, but the server treats these as two separate entries
certmap sun1 ou=Sun Certificate Authority,o=Sun, c=US certmap sun2 ou=Sun Certificate Authority, o=Sun, c=US
If you are using the Sun Java System Directory Server and experiencing problems in matching the issuerDN, 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 use the certificate API to customize your own properties):
The DNComps is a list of comma-separated attributes that determines the location in the LDAP directory the server starts searching for entries that match the user’s information (that is, the owner of the client certificate). The server gathers values for these attributes from the client certificate and uses the values to form an LDAP DN, which then determines where the server starts its search in the LDAP directory. For example, if you set DNComps to use the o and c attributes of the DN, the server starts the search from the o=<org>, c=<country> entry in the LDAP directory, where <org> and <country> are replaced with values from the DN in the certificate.
If there isn’t a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate (that is, the end-user’s information).
If the DNComps entry is present but has no value, the server searches the entire LDAP tree for entries matching the filter.
FilterComps is a list of comma-separated attributes that can create a filter by gathering information from the user’s DN in the client certificate. The server uses the values for these attributes to form the search criteria to match entries in the LDAP directory. If the server finds one or more entries in the LDAP directory that match the user’s information gathered from the certificate, the search is successful and the server optionally performs a verification.
For example, if the FilterComps is set to use the email and userid attributes (FilterComps=e,uid), the server searches the directory for an entry with values for email and userid that match the end user’s information collected from the client certificate. Email addresses and userids are good filters because they are usually unique entries in the directory. The filter needs to be specific enough to match unique entry in the LDAP database.
For a list of the x509v3 certificate attributes, see the following table:
Attribute |
Description |
---|---|
Country |
|
Organization |
|
Common name |
|
Location |
|
State |
|
Organizational unit |
|
UNIX/Linux userid |
|
Email address |
The attribute names for the filters need to be attribute names from the certificate, not from the LDAP directory. For example, some certificates have an e attribute for the user’s email address; whereas LDAP calls refers to this attribute as mail.
The verifycert tells the server whether it should compare the client’s certificate with the certificate found in the LDAP directory. It takes two values: on, and off. You should only use this property if your LDAP directory contains certificates. This feature is useful to ensure your end-users have a valid, unrevoked certificate.
The CmapLdapAttr attribute is a name for the attribute in the LDAP directory that contains subject DNs from all certificates belonging to the user. The default value for this property is certSubjectDN. This attribute is not a standard LDAP attribute. To use this property, you have to extend the LDAP schema. For more information, see Introduction to SSL.
If this property exists in the certmap.conf file, the server searches the entire LDAP directory for an entry whose attribute (named with this property) matches the subject’s full DN (taken from the certificate). If the search does not find any entries, the server retries the search using the DNComps and FilterComps mappings.
This approach to matching a certificate to an LDAP entry is useful when it is difficult to match entries using DNComps and FilterComps.
The Library property whose value is a pathname to a shared library or DLL. Use this property when you create your own properties using the certificate API. For more information, see the Sun Java System Web Server 6.1 SP8 NSAPI Programmer’s Guide.
InitFn is a property whose value is the name of an init function from a custom library. Use this property if you create your own properties using the certificate API.
For more information on these properties, refer to the examples described in Sample Mappings.
You can use the client certificate API to create your own properties. For information on programming and using the client certificate API, see the Sun Java System Web Server 6.1 SP8 NSAPI Programmer’s Guide.
Once you have a custom mapping, you reference the mapping as follows:
<name>:library <path_to_shared_library> <name>: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
The certmap.conf file should have at least one entry. The following examples illustrate the different ways you can use the certmap.conf file.
This example represents a 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 text within <> is replaced with the values from the subject’s DN in the client certificate.
The server then uses the values for email address and userid from the certificate to search for a match in the LDAP directory. When it finds an entry, the server verifies the certificate by comparing the one the client sent to the one stored in the directory.
The following example file has two mappings: one for default and another for the US Postal Service (USPS):
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 gets a certificate from someone other than the USPS , it uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client’s userid and email address. If the certificate is from the USPS, the server starts its search at the LDAP branch containing the organizational unit and searches for matching email addresses. Note that if the certificate is from the USPS, the server verifies the certificate; other certificates are not verified.
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 there is not a space between the o and the c attributes.
The following example uses the CmapLdapAttr property to scan the LDAP database for the certSubjectDN attribute whose value exactly matches the entire subject DN taken from the client certificate.
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 will use DNComps and FilterComps to search for matching entries. In this example, the server would search for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.
This example assumes the LDAP directory contains entries with the certSubjectDN attribute.