7.10. Using Client (Certificate-Based) Authentication
- The server must have SSL turned on. See Section 7.4, “Setting up TLS/SSL” for more information.
- The Directory Server must trust the CA who issued the certificate to the client, as described in step 6 of Section 7.3.2, “Trusting the Certificate Authority”.
- The subject DN in the certificate must be mapped in the user DN through a mapping in the
certmap.conffile, as in Section 7.10.2, “Mapping DNs to Certificates”.
dse.ldiflists 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_namedirectory 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.
nsslapd-certdirparameter, and the key and certificate file is stored in the
certmap.conffile. 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.
7.10.1. Configuring Directory Server to Accept Certificate-Based Authentication from LDAP Clients
- On the client system, obtain a client certificate from the CA.
- 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-----
- Convert the client certificate into binary format using the
certutil -L -d certdbPath -n userCertName -r > userCert.bincertdbPath 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
.binis the name of the output file for binary format.
- On the server, map the subject DN of the certificate to the appropriate directory entry by editing the
NoteDo not map a certificate-based authentication certificate to a distinguished name under
cn=monitor. Mapping a certificate to a DN under
cn=monitorcauses the bind operation to fail. Map the certificate to a target located elsewhere in the directory information tree. Make sure that the
verifyCertparameter is set to
certmap.conffile. 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.conffile. If the search is successful, it grants access without actually checking the value of the
- 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
For information on using the Directory Server Console to edit entries, see Section 3.1.3, “Modifying Directory Entries”.
- Select the Directory tab, and navigate to the user entry.
- Double-click the user entry, and use the Property Editor to add the
usercertificateattribute, with the
binarysubtype.When adding this attribute, instead of an editable field, the server provides abutton.
- Click.A file selector opens. Use it to select the binary file created in step 3.
ldapsearch, see Section A.2, “Using SSL/TLS and Start TLS with LDAP Client Tools”.
7.10.2. Mapping DNs to Certificates
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.
dn: uid=jsmith,ou=People,dc=example,dc=com ... cn: John Smith mail: firstname.lastname@example.org
certmap.conffile 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 (
certmap Example o=Example.com,c=US Example:DNComps dc Example:FilterComps mail,cn
certmap.conffile is stored in the
/etc/dirsrv/slapd-instance_name/folder. The file contains a default mapping as well as mappings for specific CAs.
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
certmap name issuer DN name:property [value] name:property [value] ...
certmap moz ou=Example CA,o=Example,c=US certmap moz ou=Example CA,o=Example,c=US
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.
DNCompsis set to use the
cRDN keywords, the server starts the search from the
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
DNCompsentry in the mapping, the server uses either the
CmapLdapAttrsetting or the entire subject DN in the client certificate to determine where to start searching.
- If the
DNCompsentry is present but has no value, the server searches the entire directory tree for entries matching the filter specified by
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
FilterCompsis set to use the
uidattribute keywords (
FilterComps=e,uid), the server searches the directory for an entry whose values for
uidmatch 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.
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
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 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.
CmapLdapAttrproperty exists in a
certmap.confmapping, the server searches the entire directory for an entry that contains the subject's full DN. The search criteria are the attribute named by
CmapLdapAttrand 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
FilterCompsmappings. The search will take place more quickly if the attribute specified by
CmapLdapAttris indexed. For more information on indexing attributes, see Chapter 9, Managing Indexes.
CmapLdapAttrto match a certificate to a directory entry is useful when it is difficult to match entries using
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 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
- In a text editor, open
- If necessary, make changes to the default mapping.For example, change the value for
FilterComps. To comment out a line, insert a
- If desired, create a mapping for a specific CA.The mapping should take the form
certmapmappingName issuerDN.For example, to create a mapping named
Example CAwhich has the issuer DN
ou=example CA,o=example,c=US, enter the following:
certmap example CA ou=example CA,o=example,c=US
- Add property settings for a specific CA's mapping.Specify the
InitFnproperties before adding any additional properties.When adding a property, use the form mappingName:propertyName value.For example, add a
Example CAby entering the following line:
example CA:DNComps o, cFor the
InitFnproperties, 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
- Save the
7.10.4. Example certmap.conf Mappings
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
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.
certmap.conffile 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
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.
CmapLdapAttrproperty to search the directory for an attribute called
certSubjectDNwhose value exactly matches the entire subject DN in the client certificate:
Example 7.3. A Mapping with an Attribute Search
certmap MyCo ou=My Company Inc,o=MyCo,c=US MyCo:CmapLdapAttr certSubjectDN MyCo:DNComps o, c MyCo:FilterComps mail, uid MyCo:verifycert on
uid=jsmith,o=example Inc,c=US, then the server searches for entries that have
FilterCompsto search for matching entries. For the client certificate described above, the server would search for
uid=jsmithin all entries under
7.10.5. Allowing and Requiring Client Authentication to the Console
- Click the Configuration tab.
- With the top server entry highlighted in the left navigation pane, click the Encryption tab in the main window.
- 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.
NoteTo use certificate-based authentication with replication, configure the consumer server either to allow or to require client authentication.
NoteThe Directory Server must already be configured to run over TLS/SSL or Start TLS for client authentication to be enabled.
- Save the changes, and restart the server. For example:
service dirsrv restart
[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
nsSSLClientAuthparameter can be set to
7.10.6. Forcing SASL/EXTERNAL Mechanisms for Bind Requests
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.
[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