7.10. Using Client (Certificate-Based) Authentication

Directory Server allows certificate-based authentication for the command-line tools (which are LDAP clients) and for server-to-server connections (replication and chaining). Three things are required for the Directory Server to allow client authentication:

Note

A single configuration parameter, nsslapd-certdir, in cn=config in dse.ldif lists the directory containing the key, certificate, and security files. The directory name should be unique and specific to the server. For example, the /etc/dirsrv/slapd-instance_name directory contains the key and certificate databases only for the Directory Server instance called instance_name. That directory will not contain key and certificate databases for any other server or client, nor will any of the key, certificate, or other security-related files for instance_name be located in any other directory.
The certificate and key files have been consolidated into a single file, specified in the nsslapd-certdir parameter, and the key and certificate file is stored in the /etc/dirsrv/slapd-instance_name directory.
When a server receives a request from a client, it can ask for the client's certificate before proceeding.
After checking that a client certificate chain ends with a trusted CA, the server can optionally determine which user is identified by the client certificate and then look up that user's entry in the directory. Each certificate has the name of the identity it verifies in a subject name, called the subject DN. The server authenticates the user by comparing the information in the subject DN with the DN of the user's directory entry.
In order to locate user entries in the directory, a server must know how to interpret the subject names of certificates from different CAs. The mapping between the subject names of the certificates and the user DNs is defined in the certmap.conf file. This file provides three kinds of information for each listed CA:
  • It maps the distinguished name (DN) in the certificate to a branch point in the LDAP directory.
  • It specifies which DN values from the certificate (user name, email address, and so on) the server should use for the purpose of searching the directory.
  • It specifies whether the server should go through an additional verification process. This process involves comparing the certificate presented for authentication with the certificate stored in the user's directory entry. By comparing the certificate, the server determines whether to allow access or whether to revoke a certificate by removing it from the user's entry.
If more than one directory entry contains the information in the user's certificate, the server can examine all matching entries in order to determine which user is trying to authenticate. When examining a directory entry, the server compares the presented certificate with the one stored in the entry. If the presented certificate does not match any certificates or if the matching entries do not contain certificates, client authentication fails.
After the server finds a matching entry and certificate in the directory, it can determine the appropriate kind of authorization for the client. For example, some servers use information from a user's entry to determine group membership, which in turn can be used during evaluation of ACIs to determine what resources the user is authorized to access.

7.10.1. Configuring Directory Server to Accept Certificate-Based Authentication from LDAP Clients

Client authentication to the Directory Server will require or allow a user to use a certificate to establish its identity, in addition to the server having to present a certification. This is also called certificate-based authentication.
  1. On the client system, obtain a client certificate from the CA.
  2. Install the client certificate on the client system.
    Regardless of how the certificate is sent (either in email or on a web page), there should be a link to click to install the certificate.
    Record the certificate information that is sent from the CA, especially the subject DN of the certificate because the server must be configured to map it to an entry in the directory. The client certificate resembles the following: 
    -----BEGIN CERTIFICATE-----
MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBh
MCVVMxIzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0w
GwYDVQQLExRXaWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdC
BUZXN0IFRlc3QgVGVzdCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3
WhcNOTgwMzI2MDIzMzU3WjBPMQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTm
V0c2NhcGUgRGlyZWN0b3
------END CERTIFICATE-----
  3. Convert the client certificate into binary format using the certutil utility. 
    certutil -L -d certdbPath -n userCertName -r > userCert.bin
    certdbPath is the directory which contains the certificate database; for example, a user certificate for Mozilla Thunderbird is stored in $HOME/.thunderbird. userCertName is the name of the certificate, and userCert.bin is the name of the output file for binary format.
  4. On the server, map the subject DN of the certificate to the appropriate directory entry by editing the certmap.conf file.

    Note

    Do not map a certificate-based authentication certificate to a distinguished name under cn=monitor. Mapping a certificate to a DN under cn=monitor causes the bind operation to fail. Map the certificate to a target located elsewhere in the directory information tree. Make sure that the verifyCert parameter is set to on in the certmap.conf file. If this parameter is not set to on, Directory Server simply searches for an entry in the directory that matches the information in the certmap.conf file. If the search is successful, it grants access without actually checking the value of the userCertification and usercertificate;binary attributes.
  5. In the Directory Server, modify the directory entry for the user or identity (if it is another server) who owns the client certificate to add the usercertificate attribute.
    1. Select the Directory tab, and navigate to the user entry.
    2. Double-click the user entry, and use the Property Editor to add the usercertificate attribute, with the binary subtype.
      When adding this attribute, instead of an editable field, the server provides a Set Value button.
    3. Click Set Value.
      A file selector opens. Use it to select the binary file created in step 3.
    For information on using the Directory Server Console to edit entries, see Section 3.1.3, “Modifying Directory Entries”.
For information on how to use TLS/SSL with ldapmodify, ldapdelete, and ldapsearch, see Section A.2, “Using SSL/TLS and Start TLS with LDAP Client Tools”.

7.10.2. Mapping DNs to Certificates

When a server performs client authentication, it interprets a certificate, extracts user information, and then searches the directory for that information. In order to process certificates from different CAs, the server uses a file called certmap.conf. This file contains instructions on how to interpret different certificates and how to search the directory for the information that those certificates contain.
In the Directory Server, a user entry has a format like the following: 
dn: uid=jsmith,ou=People,dc=example,dc=com
...

cn: John Smith
mail: jsmith@example.com
A subject DN, however, is almost always formatted differently than an LDAP DN. For example: 
cn=John Smith,e=jsmith@example.com,c=US,o=Example.com
The email attribute in the directory is almost always unique within the organization, as is the common name of the user. These attributes are also indexed by default, so they are easily searched, and are common attributes to be used in the subject names of certificates. The certmap.conf file can be configured so that the server looks for any mail or common name elements in the subject DN and matches them against the entries in the directory. Much like an ldapsearch, the cert mapping defines a search base (DNComps) and search filter (FilterComps). 
certmap Example     o=Example.com,c=US
Example:DNComps     dc
Example:FilterComps mail,cn
The certmap.conf file is stored in the /etc/dirsrv/slapd-instance_name/ folder. The file contains a default mapping as well as mappings for specific CAs.
The default mapping specifies what the server should do if a client certificate was issued by a CA that is not listed in certmap.conf. The mappings for specific CAs specify what the server should do for client certificates issued by those CAs. All mappings define the following:
  • Where in the directory the server should begin its search
  • What certificate attributes the server should use as search criteria
  • Whether the server should verify the certificate with one that is stored in the directory
Mappings have the following syntax: 
 certmap name issuer DN  
 name:property [value]  
 name:property [value]  
 ...
The first line of a mapping specifies the mapping's name as well as the DN for the issuer of the client certificate. The mapping can have any name, but the issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuerDN lines differ only in the number of spaces they contain, but the server would treat these two entries as different: 
certmap moz ou=Example CA,o=Example,c=US
certmap moz ou=Example CA,o=Example,c=US
The second and subsequent lines of a mapping identify the rules that the server should use when searching the directory for information extracted from a certificate. These rules are specified through the use of one or more of the following properties:
  • DNComps
  • FilterComps
  • VerifyCert
  • CmapLdapAttr
  • Library
  • InitFn
DNComps

DNComps is a comma-separated list of relative distinguished name (RDN) keywords used to determine where in the user directory the server should start searching for entries that match the information for the owner of the client certificate. The server gathers values for these keywords from the client certificate and uses the values to form a DN, which determines where the server starts its search in the directory.

For example, if the DNComps is set to use the o and c RDN keywords, the server starts the search from the o=org, c=country entry in the directory, where org and country are replaced with values from the DN in the certificate.
  • If there is not a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate to determine where to start searching.
  • If the DNComps entry is present but has no value, the server searches the entire directory tree for entries matching the filter specified by FilterComps.
The following RDN keywords are supported for DNComps:
  • cn
  • ou
  • o
  • c
  • l
  • st
  • dc
  • e or mail (but not both)
  • mail
Keywords can be in either lower case or upper case.
FilterComps

FilterComps is a comma-separated list of RDN keywords used to create a filter by gathering information from the user's DN in the client certificate. The server uses the values for these keywords to form the search criteria for matching entries in the LDAP directory. If the server finds one or more entries in the directory that match the user's information gathered from the certificate, the search is successful and the server performs a verification (if verifycert is set to on).

For example, if FilterComps is set to use the e and uid attribute keywords (FilterComps=e,uid), the server searches the directory for an entry whose values for e and uid match the user's information gathered from the client certificate. Email addresses and user IDs are good filters because they are usually unique entries in the directory.
The filter needs to be specific enough to match one and only one entry in the directory.
The following RDN keywords are supported for FilterComps:
  • cn
  • ou
  • o
  • c
  • l
  • st
  • dc
  • e or mail (but not both)
  • mail
Keywords can be in either lower case or upper case.
VerifyCert

verifycert tells the server whether it should compare the client's certificate with the certificate found in the user's directory entry. The value is either on or off. Setting the value to on ensures that the server will not authenticate the client unless the certificate presented exactly matches the certificate stored in the directory. Setting the value to off disables the verification process.

CmapLdapAttr

CmapLdapAttr is the name of the attribute in the directory that contains subject DNs from all certificates belonging to the user. Because this attribute is not a standard LDAP attribute, this attribute must be added to the schema. See Section 8.4.2, “Creating Attributes” for information on adding schema elements.

If the CmapLdapAttr property exists in a certmap.conf mapping, the server searches the entire directory for an entry that contains the subject's full DN. The search criteria are the attribute named by CmapLdapAttr and the subject's full DN as listed in the certificate. If the search does not yield any entries, the server retries the search using the DNComps and FilterComps mappings. The search will take place more quickly if the attribute specified by CmapLdapAttr is indexed. For more information on indexing attributes, see Chapter 9, Managing Indexes.
Using CmapLdapAttr to match a certificate to a directory entry is useful when it is difficult to match entries using DNComps and FilterComps.
Library

Library is the pathname to a shared library or DLL. Use this property only to extend or replace the standard functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless there are very specialized mapping requirements.

InitFn

InitFn is the name of an init function from a custom library. You need to use this property only if you want to extend or replace the functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless you have very specialized mapping requirements.

7.10.3. Editing the certmap.conf File

  1. In a text editor, open /etc/dirsrv/slapd-instance_name/certmap.conf
  2. If necessary, make changes to the default mapping.
    For example, change the value for DNComps or FilterComps. To comment out a line, insert a # before it.
  3. If desired, create a mapping for a specific CA.
    The mapping should take the form certmap mappingName issuerDN.
    For example, to create a mapping named Example CA which has the issuer DN ou=example CA,o=example,c=US, enter the following: 
    certmap example CA ou=example CA,o=example,c=US
  4. Add property settings for a specific CA's mapping.
    Specify the Library and InitFn properties before adding any additional properties.
    When adding a property, use the form mappingName:propertyName value.
    For example, add a DNComps value of o, c for Example CA by entering the following line: 
    example CA:DNComps o, c
    For the Library and InitFn properties, a complete mapping looks like this: 
    certmap Example CA ou=example CA,o=example,c=US
Example CA:Library /ldapserver/ldap/servers/slapd/plugin.c
Example CA:InitFn plugin_init_dn
Example CA:DNComps o, c
Example CA:FilterComps e, uid
Example CA:VerifyCert on
Example CA:CmapLdapAttr certSubjectDN
  5. Save the certmap.conf file.

7.10.4. Example certmap.conf Mappings

In Example 7.1, “Default Mapping”, the server starts its search at the directory branch point containing the entry ou=organizationalUnit, o=organization, c=country, where the italics represent values from the subject's DN in the client certificate.

Example 7.1. Default Mapping

certmap default     default
default:DNComps     ou, o, c
default:FilterComps e, uid
default:verifycert  on
The server then uses the values for e (email address) and uid (user ID) from the certificate to search for a match in the directory before authenticating the user. When it finds a matching entry, the server verifies the certificate by comparing the certificate the client sent to the certificate stored in the directory.
Example 7.2, “An Additional Mapping” shows the contents of a sample certmap.conf file that defines a default mapping as well as a mapping for MyCA:

Example 7.2. An Additional Mapping

certmap default     default
default:DNComps
default:FilterComps e, uid
certmap MyCA        ou=MySpecialTrust,o=MyOrg,c=US
MyCA:DNComps        ou,o,c
MyCA:FilterComps    e
MyCA:verifycert     on
When the server gets a certificate from a CA other than MyCA, the server uses the default mapping, which starts at the top of the directory tree and searches for an entry matching the client's email address (e) and user ID (uid). If the certificate is from MyCA, the server starts its search at the directory branch containing the organizational unit specified in the subject DN and searches for email addresses (e) that match the one specified in the certificate. If the certificate is from MyCA, the server verifies the certificate. If the certificate is from another CA, the server does not verify it.
Example 7.3, “A Mapping with an Attribute Search” uses the CmapLdapAttr property to search the directory for an attribute called certSubjectDN whose value exactly matches the entire subject DN in the client certificate:
If the subject DN in the client certificate is uid=jsmith,o=example Inc,c=US, then the server searches for entries that have certSubjectDN=uid=jsmith,o=example 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. For the client certificate described above, the server would search for uid=jsmith in all entries under o=example Inc,c=US.

7.10.5. Allowing and Requiring Client Authentication to the Console

Client authentication must be explicitly set in the Directory Server.
  1. Click the Configuration tab.
  2. With the top server entry highlighted in the left navigation pane, click the Encryption tab in the main window.
  3. Set whether to require or allow client authentication to the Directory Server.
    • Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
    • Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request.
    • Require client authentication. With this option, the server requests authentication from the client.
      If client authentication is required, then SSL cannot be used with the Console because The Directory Server Console does not support client authentication.

    Note

    To use certificate-based authentication with replication, configure the consumer server either to allow or to require client authentication.

    Note

    The Directory Server must already be configured to run over TLS/SSL or Start TLS for client authentication to be enabled.
  4. Save the changes, and restart the server. For example: 
    service dirsrv restart
To change the server configuration from requiring client authentication to allowing it through the command line, reset the nsSSLClientAuth parameter: 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 636 -h server.example.com -x

dn: cn=encryption,cn=config
changetype: modify
replace: nsSSLClientAuth
nsSSLClientAuth: allowed
The nsSSLClientAuth parameter can be set to off, allowed, and required.

7.10.6. Forcing SASL/EXTERNAL Mechanisms for Bind Requests

The assumption with certificate-based authentication is that the Directory Server will use the identity in the presented certificate to process the BIND request.
There are two steps that the client takes at the beginning of an SSL session to use certificate authentication. First, the client sends its certificate to the Directory Server. Then, it sends its bind request. Most clients issue the bind request using the SASL/EXTERNAL mechanism, which is important because it signals to the Directory Server that it needs to use the identity in the certificate for the bind, not any credentials in the bind request.
However, some clients use simple authentication or anonymous credentials when they send the bind request. The client still assumes that the Directory Server will use the identity in the certificate for the bind identity, but there is nothing in the bind request to tell the Directory Server that is what it should do. In that case, the SSL session fails with invalid credentials, even if the certificate and the client identity in that certificate are valid.
A configuration option in the Directory Server (nsslapd-force-sasl-external) forces clients in certificate-based authentication to use the SASL/EXTERNAL method and to ignore any simple bind method given with the request.
This attribute is off by default, but it can be turned on: 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 636 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-force-sasl-external
nsslapd-force-sasl-external: on