9.8. Using Certificate-based Client Authentication

Directory Server supports certificate-based authentication of LDAP clients and for server-to-server connection, such as replication.
Depending on the configuration, the client can or must authenticate using a certificate, if you enabled certificate-based authentication. After verifying the certificate, the server searches for the user in the directory, based on the attributes in the subject field of the certiticate. If the search return exactly one user entry, Directory Server uses this user for all further operations. Optionally, you can configure that the certifiate used for authentication must match the Distinguished Encoding Rules (DER)-formatted certificate stored in the userCertificate attribute of the user.
Benefits of using certificate-based authentication:
  • Improved efficiency. When using applications that prompt once for the certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
  • Improved security. The use of certificate-based authentication is more secure than non-certificate bind operations because certificate-based authentication uses public-key cryptography. Bind credentials cannot be intercepted across the network. If the certificate or device is lost, it is useless without the PIN, so it is immune from third-party interference like phishing attacks.

9.8.1. Setting up Certificate-based Authentication

To enable certificate-based authentication:
  1. Enable encrypted connections. For details, see Section 9.4, “Enabling TLS”.
  2. Install the CA certificate and set the trust options for client and server connections. See Section 9.3.3, “Installing a CA Certificate”.
  3. Optionally, verify that the CT,, trust options for client and server are set for the CA certificate: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -L
Certificate Nickname                Trust Attributes
                                    SSL,S/MIME,JAR/XPI

Example CA                          CT,,
  4. Create the /etc/dirsrv/slapd-instance_name/certmap.conf file to map information from the certificate to Directory Server users. For example: 
    certmap default         default
default:DNComps         dc
default:FilterComps     mail,cn
default:VerifyCert      on

certmap example         o=Example Inc.,c=US
example:DNComps
    This configures that for authenticating users who use a certificate that has the o=Example Inc.,c=US issuer Distinguished Name (DN) set, Directory Server does not generate a base DN from the subject of the certificate, because the DNComps parameter is set empty for this issuer. Additionally, the settings for the FilterComps and VerifyCert are inherited from the default entry.
    Certificates that have a different issuer DN than the specified one will use the settings from the default entry and generate the base DN based on the cn attributes in the subject of the certificate. This enables Directory Server to start the search under a specific DN, without searching the whole directory.
    For all certificates, Directory Server generates the search filter using the mail and the cn attribute from the certificate's subject. However, if the mail does not exist in the subject, Directory Server will automatically use the value of the certificate's e attribute in the subject.
    For further details and descriptions of the available parameters, see the description of the certmap.conf file in the Red Hat Directory Server Configuration, Command, and File Reference.
  5. Enable client authentication. For example, to configure that client authentication is optional: 
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x -Z

dn: cn=encryption,cn=config
changetype: modify
replace: nsSSLClientAuth
nsSSLClientAuth: allowed
    Alternatively, set the nsSSLClientAuth parameter to required to configure that clients must use a certificate to authenticate.

    Important

    The Directory Server Console does not support client authentication. If you set nsSSLClientAuth to required, you cannot use the Console to manage the instance.
  6. If you enabled that the authenticating certificate must match the one stored in the userCertificate attribute of the user by setting alias_name:VerifyCert on in the /etc/dirsrv/slapd-instance_name/certmap.conf file, add the certificates to the user entries. See Section 9.8.2, “Adding a Certificate to a User”.

9.8.2. Adding a Certificate to a User

When you set up certificate-based authentication, you can set that the certificate used to authenticate must match the one stored in the userCertificate binary attribute of the user. If you enabled this feature by setting alias_name:VerifyCert on in the /etc/dirsrv/slapd-instance_name/certmap.conf file, you must add the certificate of the affected users to their directory entry.

Important

You must store the certificate in the Distinguished Encoding Rules (DER) format in the userCertificate attribute.
To store a certificate in the userCertificate attribute of a user:
  1. If the certificate is not DER-formatted, convert it. For example: 
    # openssl x509 -in /root/certificate.pem -out /root/certificate.der -outform DER
  2. Add the certificate to the user's userCertificate attribute. For example: 
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user_name,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate: < /root/example.der
For further details about using binary attributes, see Section 3.1.8, “Using Binary Attributes”.

9.8.3. Forcing the EXTERNAL SASL Mechanism for Bind Requests

At the beginning of a TLS session, the client sends its certificate to the server. Then, it sends its bind request. Most clients issue the bind request using the EXTERNAL SASL mechanism, which signals Directory Server that it needs to use the identity in the certificate for the bind, instead of the credentials in the bind request.
However, if a client uses simple authentication or anonymous credentials, this information is missing. In this case, the TLS session fails with invalid credentials, even if the certificate and the client identity in the certificate was valid.
To configure that Directory Server forces clients to use the EXTERNAL SASL mechanism and to ignore any other bind method in the request: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=config
changetype: modify
replace: nsslapd-force-sasl-external
nsslapd-force-sasl-external: on

9.8.4. Authenticating Using a Certificate

To use the OpenLDAP client tools, to authenticate to a Directory Server instance that supports authentication using a certificate:
  1. Set the following environment variables to the corresponding paths for the CA certificate, the user key, and the user certificate. For example: 
    LDAPTLS_CACERTFILE=/home/user_name/CA.crt
LDAPTLS_KEYFILE=/home/user_name/user.key
LDAPTLS_CERTFILE=/home/user_name/user.crt
    Alternatively, set the TLS_CACERT, TLS_KEY, and TLS_CERT parameters in the ~/.ldaprc file. For details, see the TLS OPTIONS section in the ldap.conf(5) man page.
  2. Connect to the server. For example: 
    # ldapwhoami -H ldaps://server.example.com:636
If you use a different client, see the client application's documentation for how to connect using certificate-based authentication.