Language and Page Formatting Options
9.9. 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
subjectfield of the certificate. 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
userCertificateattribute 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.9.1. Setting up Certificate-based Authentication
To enable certificate-based authentication:
- Enable encrypted connections. For details, see Section 9.4, “Enabling TLS”.
- Install the CA certificate and set the trust options for client and server connections. See Section 9.3.2, “Installing a CA Certificate”.
- Optionally, verify that the
CT,,trust options for client and server are set for the CA certificate:
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate get "Example-CA" Certificate Name: Example-CA Subject DN: CN=server.example.com,ST=Queensland,C=AU Issuer DN: CN=server.example.com,,ST=Queensland,C=AU Expires: 2021-05-09 10:57:54 Trust Flags: CT,,
- Create the
/etc/dirsrv/slapd-instance_name/certmap.conffile 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:DNCompsThis configures that for authenticating users who use a certificate that has the
o=Example Inc.,c=USissuer Distinguished Name (DN) set, Directory Server does not generate a base DN from the subject of the certificate, because the
DNCompsparameter is set empty for this issuer. Additionally, the settings for the
VerifyCertare inherited from the default entry.Certificates that have a different issuer DN than the specified one will use the settings from the
defaultentry and generate the base DN based on the
cnattributes 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
cnattribute from the certificate's subject. However, if the
eattribute in the subject.For further details and descriptions of the available parameters, see the description of the
certmap.conffile in the Red Hat Directory Server Configuration, Command, and File Reference.
- Enable client authentication. For example, to configure that client authentication is optional:
# dsconf -D "cn=Directory Manager" ldap://server.example.com security set --tls-client-auth="allowed"Alternatively, set the
requiredto configure that clients must use a certificate to authenticate.
- If you enabled that the authenticating certificate must match the one stored in the
userCertificateattribute of the user by setting
alias_name:VerifyCert onin the
/etc/dirsrv/slapd-instance_name/certmap.conffile, add the certificates to the user entries. See Section 9.9.2, “Adding a Certificate to a User”.
9.9.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
userCertificatebinary attribute of the user. If you enabled this feature by setting
alias_name:VerifyCert onin the
/etc/dirsrv/slapd-instance_name/certmap.conffile, you must add the certificate of the affected users to their directory entry.
You must store the certificate in the Distinguished Encoding Rules (DER) format in the
To store a certificate in the
userCertificateattribute of a user:
- If the certificate is not DER-formatted, convert it. For example:
# openssl x509 -in /root/certificate.pem -out /root/certificate.der -outform DER
- Add the certificate to the user's
userCertificateattribute. 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:< file:///root/example.der
For further details about using binary attributes, see Section 3.8, “Using Binary Attributes”.
9.9.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
EXTERNALSASL 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
EXTERNALSASL mechanism and to ignore any other bind method in the request:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-force-sasl-external=on Successfully replaced "nsslapd-force-sasl-external"
9.9.4. Authenticating Using a Certificate
To use the OpenLDAP client tools, to authenticate to a Directory Server instance that supports authentication using a certificate:
- Set the following environment variables to the corresponding paths for the CA certificate, the user key, and the user certificate. For example:
LDAPTLS_CACERT=/home/user_name/CA.crt LDAPTLS_KEY=/home/user_name/user.key LDAPTLS_CERT=/home/user_name/user.crtAlternatively, set the
TLS_CERTparameters in the
~/.ldaprcfile. For details, see the TLS OPTIONS section in the ldap.conf(5) man page.
- 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.