Configuring SASL External Authentication

The SASL EXTERNAL mechanism is used to allow a client to authenticate itself to the directory server using information provided outside of what is strictly considered LDAP communication. The directory server currently supports authentication using a client certificate presented to the server during SSL or StartTLS negotiation, for LDAP communication only.

Configuring the LDAP Connection Handler to Allow SASL EXTERNAL Authentication

For the directory server to be able to map the client certificate to a user entry, ensure that the connection handler is configured to handle client certificates. Use the dsconfig to set the following LDAP connection handler properties:

• ssl-client-auth-policy. Specifies whether the directory server prompts the client to present its own certificate during the SSL or StartTLS negotiation process. To support SASL EXTERNAL authentication, the value must be either optional or required. If the value is disabled, clients are not prompted to provide a certificate and no certificate is available for authentication.

• trust-manager-provider. Specifies the DN of the trust manager provider used to determine whether the directory server trusts the validity of the client certificate. If the directory server does not trust the client certificate, the SSL or StartTLS negotiation fails and it is not possible for the client to request SASL EXTERNAL authentication. If the directory server trusts illegitimate client certificates, it is possible for malicious users to forge certificates and impersonate any user in the directory. In most cases, the JKS or PKCS12 trust manager provider should be used and the corresponding trust store loaded only with the issuer certificates that are used to sign client certificates.

Note - The dsconfig command accesses the server configuration over SSL via the administration connector. As such, the relevant connection options must be specified, including how the SSL certificate is trusted. These examples use the -X option to trust all certificates.

The following example uses dsconfig to set LDAP connection handler properties:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager"-w password -X -n \
  set-connection-handler-prop --handler-name "LDAP Connection Handler"

Configuring the EXTERNAL SASL Mechanism Handler

SASL EXTERNAL bind requests are processed by the SASL mechanism handler. Use the dsconfig command to set the following SASL mechanism handler properties:

• java-class. Specifies the fully-qualified name of the Java class that provides the logic for the SASL mechanism handler. For the EXTERNAL mechanism, this value is always org.opends.server.extensions.ExternalSASLMechanismHandler. An advanced property.

• enabled. Indicates whether the EXTERNAL SASL mechanism is enabled for use in the directory server. If you do not want to allow clients to use SASL EXTERNAL authentication, change its value to false.

• certificate-mapper. Specifies the DN of the configuration entry for the certificate mapper to be used to map client certificates to user entries.

• certificate-validation-policy. Specifies whether the directory server attempts to locate the client certificate in the user's entry after establishing a mapping. If the value is always, the authentication succeeds only if the mapped user's entry contains the certificate presented by the client. If the value is ifpresent (the default value) and the user's entry contains one or more certificates, the authentication succeeds only if one of those certificates matches the one presented by the client. If the value is ifpresent and the user's entry does not contain any certificates, the authentication still succeeds based on the fact that it would have been accepted by the trust manager and mapped by the certificate mapper. If the value is never, the server does not attempt to match the certificate to a value in the user's entry even if that entry contains one or more certificates.

• certificate-attribute. Specifies the name of the attribute that holds user certificates to be examined if the certificate-validation-policy property has a value of either always or ifpresent.

The following example uses dsconfig to set EXTERNAL SASL mechanism handler properties:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager"-w password -X -n \
  set-sasl-mechanism-handler-prop --handler-name "EXTERNAL" --advanced