Menu Close
Settings Close

Language and Page Formatting Options

Chapter 7. Configuring certificate-based authentication

Directory Server supports certificate-based authentication of LDAP clients and server-to-server connections, such as in replication topologies.

Depending on the configuration, clients can or must authenticate using a certificate. After verifying the certificate, based on the attributes in the subject field of the certificate, the server searches for the user in the directory. If the search return exactly one user entry, Directory Server uses this user for all further operations. Optionally, you can configure that the certificate used for authentication must match the Distinguished Encoding Rules (DER)-formatted certificate stored in the userCertificate attribute of the user entry.

Benefits of using certificate-based authentication:

  • Improved efficiency: Authenticating with the certificate database password and then using that certificate for all subsequent bind or authentication operations is more efficient than repeatedly providing a bind distinguished name (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. Attackers cannot intercept bind credentials across the network. If the certificate or device is lost, it is useless without the PIN, so it is immune to third-party interference such as phishing attacks.

7.1. Setting up certificate-based authentication


  • You enabled TLS encryption in Directory Server.
  • You set the CT flags for the certificate authority (CA) certificate in the network security services (NSS) database.


  1. Create a /etc/dirsrv/slapd-instance_name/certmap.conf file to map information from the certificate to Directory Server users:

    certmap default         default
    default:DNComps         dc
    default:FilterComps     mail,cn
    default:VerifyCert      on
    certmap example         cn=Example CA

    With this configuration, for certificates issued by cn=Example CA, 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 cn=Example CA 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 attribute does not exist in the subject, Directory Server will automatically use the value of the certificate’s e attribute in the subject.

  2. Enable certificate-based authentication. For example, to configure certificate-based authentication as optional, enter:

    # dsconf -D "cn=Directory Manager" ldap:// security set --tls-client-auth="allowed"

    Use the --tls-client-auth=required option to configure certificate-based authentication as mandatory.

  3. Optional: If you configured certificate-based authentication as required, enable the nsslapd-require-secure-binds parameter:

    # dsconf -D "cn=Directory Manager" ldap:// config replace nsslapd-require-secure-binds=on

    This setting ensures that users cannot bypass the certificate-based authentication by using an unencrypted connection.

  4. Optional: If Directory Server should use the identity from the certificate instead of the credentials in the bind request, configure Directory Server to use the EXTERNAL simple authentication and security layer (SASL) mechanism:

    # dsconf -D "cn=Directory Manager" ldap:// config replace nsslapd-force-sasl-external=on

    With this setting, Directory Server ignores any other bind method than the identity in the certificate.

  5. Restart the instance:

    # dsctl instance_name restart

Next steps:

  • If you have configured Directory Server so that the authenticating certificate must match the one stored in the userCertificate attribute of the user, add the certificates to the user entries. For details, see Section 7.2, “Adding a certificate to a user”

7.2. Adding a certificate to a user

When you set up certificate-based authentication, you can configure the server so that the certificate used to authenticate must match the one stored in the userCertificate binary attribute of the user. If you enabled this feature, you must add the certificate of the affected users to their directory entry.


  • You enabled certificate-based authentication in Directory Server.
  • You have a client certificate issued by a certificate authority (CA) that is trusted by the server.
  • The client certificate is in distinguished encoding rules (DER)-formatted.
  • The client certificate meets the requirements set in /etc/dirsrv/slapd-instance_name/certmap.conf on the server.


  1. If the certificate is not in DER format, convert it. For example, to convert a certificate from privacy enhanced mail (PEM) to DER, enter:

    # openssl x509 -in /home/user_name/certificate.pem -out /home/user_name/certificate.der -outform DER
  2. Add the certificate to the user’s userCertificate attribute:

    # ldapmodify -D "cn=Directory Manager" -W -H ldaps:// -x
    dn: uid=user_name,ou=People,dc=example,dc=com
    changetype: modify
    add: userCertificate
    userCertificate:< file:///home/user_name/example.der


  1. Authenticate as the user using certificate-based authentication:

    1. Set the following environment variables to the corresponding paths to the CA certificate, the user key, and the user certificate:


      Alternatively, set the TLS_CACERT, TLS_KEY, and TLS_CERT parameters in the ~/.ldaprc file of the current user.

    2. Connect to the server:

      # ldapwhoami -H ldaps:// -Y EXTERNAL
      dn: uid=example,ou=people,dc=example,dc=com

Additional resources

  • The TLS OPTIONS section in the ldap.conf(5) man page