9.9. Using Certificate-based Client Authentication
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.
- 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
- 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
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.
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: < /root/example.der
9.9.3. Forcing the
EXTERNAL SASL Mechanism for Bind Requests
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.
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
- 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