14.3. Using SASL

Red Hat Directory Server supports LDAP client authentication through the Simple Authentication and Security Layer (SASL), an alternative to TLS/SSL and a native way for some applications to share information securely.
The SASL framework allows different mechanisms to be used to authenticate a user to the server, depending on what mechanism is enabled in both client and server applications. SASL also creates a layer for encrypted (secure) sessions. Using GSS-API, Directory Server utilizes Kerberos tickets to authenticate sessions and encrypt data.
Simple Authentication and Security Layer (SASL) is an abstraction layer between protocols like LDAP and authentication methods like GSS-API which allows any protocol which can interact with SASL to utilize any authentication mechanism which can work with SASL. Simply put, SASL is an intermediary that makes authenticating to applications using different mechanisms easier. SASL can also be used to establish an encrypted session between a client and server.
Directory Server uses SASL as an alternative TLS/SSL, particularly for environments which are using Kerberos to implement single sign-on. Directory Server allows user to use SASL to authenticate and bind to the server. This includes LDAP tools like ldapsearch and ldapmodify. For example:
/usr/lib64/mozldap/ldapsearch -p 389 -h server.example.com -o "mech=GSSAPI" -o "authid=dn:uid=jsmith,ou=people,dc=example,dc=com" -o realm=EXAMPLE.COM


SASL proxy authorization is not supported in Directory Server; therefore, Directory Server ignores any SASL authzid value supplied by the client.
Two primary pieces of information are required to use SASL with Directory Server:
  • The authentication method, in this example GSS-API
  • The user as whom you are authenticating (the authid or authorization ID)
Other information, such as the Kerberos realm, can also be passed with the command. The SASL options for Directory Server tools are described more in the Configuration and Command-Line Tool Reference.
When a client connects to Directory Server using SASL, the Directory Server takes the identity offered as the SASL authid and maps that entry back to an entry in the Directory Server. If the authid is defined as a DN (as in authid=dn:DN), this is done simply by matching the DN. It is also possible to use a username or a part of a DN, and these can be mapped to the directory entry using SASL identity mappings.

14.3.1. About SASL Identity Mapping

When processing a SASL bind request, the server matches, or maps, the SASL authentication ID used to authenticate to the Directory Server with an LDAP entry stored within the server. When using Kerberos, the SASL user ID usually has the format userid@REALM, such as scarter@EXAMPLE.COM. This ID must be converted into the DN of the user's Directory Server entry, such as uid=scarter,ou=people,dc=example,dc=com.
If the authentication ID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication ID automatically to the entry DN. Directory Server has some pre-configured default maps which handle most common configurations, and customized maps can be created. During a bind attempt, the first matching mapping rule is applied. If only one user identity is returned, the bind is successful; if none or more than one are returned, then the bind fails.
Be sure to configure SASL maps so that only one mapping rule matches the authentication string.
SASL mappings are configured by entries under a container entry:
dn: cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: sasl
SASL identity mapping entries are children of this entry:
dn: cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: mapping
Mapping entries are defined by three attributes:
  • nsSaslMapRegexString, the regular expression which is used to map the elements of the supplied authid
  • nsSaslMapFilterTemplate, a template which applies the elements of the nsSaslMapRegexString to create the DN
  • nsSaslMapBaseDNTemplate, which provides the search base or a specific entry DN to match against the constructed DN
For example:
dn: cn=mymap,cn=mapping,cn=sasl,cn=config
cn: mymap
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapFilterTemplate: (objectclass=inetOrgPerson)
nsSaslMapBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3
The nsSaslMapRegexString attribute sets variables of the form \1, \2, \3 for bind IDs which are filled into the template attributes during a search. This example sets up a SASL identity mapping for any user in the ou=People,dc=example,dc=com subtree who belongs to the inetOrgPerson object class.
When a Directory Server receives a SASL bind request with mconnors@EXAMPLE.COM as the user ID (authid), the regular expression fills in the base DN template with uid=mconnors,ou=people,dc=EXAMPLE,dc=COM as the user ID, and authentication proceeds from there.


The dc values are not case sensitive, so dc=EXAMPLE and dc=example are equivalent.
The Directory Server can also use a more inclusive mapping scheme, such as the following:
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This matches any user ID and map it an entry under the ou=People,dc=example,dc=com subtree which meets the filter cn=userId.
Mappings can be confined to a single realm by specifying the realm in the nsSaslMapRegexString attribute. For example:
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)@US.EXAMPLE.COM   
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This mapping is identical to the previous mapping, except that it only applies to users authenticating from the US.EXAMPLE.COM realm. (Realms are described in Section, “About Principals and Realms”.)
When a server connects to another server, such as during replication or with chaining, the default mappings for the will not properly map the identities. This is because the principal (SASL identity) for one server does not match the principal on the server where authentication is taking place, so it does not match the mapping entries.
To allow server to server authentication using SASL, create a mapping for the specific server principal to a specific user entry. For example, this mapping matches the ldap1.example.com server to the cn=replication manager,cn=config entry. The mapping entry itself is created on the second server, such as ldap2.example.com.
dn: cn=z,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: z
nsSaslMapRegexString: ldap/ldap1.example.com@EXAMPLE.COM
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Sometimes, the realm name is not included in the principal name in SASL GSS-API configuration. A second mapping can be created which is identical to the first, only without specifying the realm in the principal name. For example:
dn: cn=y,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: y
nsSaslMapRegexString: ldap/ldap1.example.com
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Because the realm is not specified, the second mapping is more general (meaning, it has the potential to match more entries than the first. The best practice is to have more specific mappings processed first and gradually progress through more general mappings.
There is no way to specify the order that mappings are processed. However, there is a way to control how SASL mappings are processed: the name. The Directory Server processes SASL mappings in reverse ASCII order. In the past two example, then the cn=z mapping (the first example) is processed first. If there is no match, the server processes the cn=y mapping (the second example).


SASL mappings can be added when an instance is created during a silent installation by specifying the mappings in an LDIF file and adding the LDIF file with the ConfigFile directive. Using silent installation is described in the Installation Guide.

14.3.2. Default SASL Mappings for Directory Server

The Directory Server has pre-defined SASL mapping rules to handle some of the most common usage.
Kerberos UID Mapping
This matches a Kerberos principal using a two part realm, such as user@example.com. The realm is then used to define the search base, and the user ID (authid) defines the filter. The search base is dc=example,dc=com and the filter of (uid=user).
dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: Kerberos uid mapping
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapBaseDNTemplate: dc=\2,dc=\3
nsSaslMapFilterTemplate: (uid=\1)
RFC 2829 DN Syntax
This mapping matches an authid that is a valid DN (defined in RFC 2829) prefixed by dn:. The authid maps directly to the specified DN.
dn: cn=rfc 2829 dn syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 dn syntax
nsSaslMapRegexString: ^dn:\(.*\)
nsSaslMapBaseDNTemplate: \1
nsSaslMapFilterTemplate: (objectclass=*)
RFC 2829 U Syntax
This mapping matches an authid that is a UID prefixed by u:. The value specified after the prefix defines a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database.
dn: cn=rfc 2829 u syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 u syntax
nsSaslMapRegexString: ^u:\(.*\)
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=\1)
UID Mapping
This mapping matches an authid that is any plain string that does not match the other default mapping rules. It use this value to define a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database.
dn: cn=uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: uid mapping
nsSaslMapRegexString: ^[^:@]+$
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=&)

14.3.3. Authentication Mechanisms for SASL in Directory Server

Directory Server support the following SASL encryption mechanisms:
  • EXTERNAL. EXTERNAL, as with TLS/SSL, performs certificate-based authentication. This method uses public keys for strong authentication.
  • CRAM-MD5. CRAM-MD5 is a simple challenge-response authentication method. It does not establish any security layer, unlike GSS-API. Both DIGEST-MD5 and GSS-API are much more secure, so both of those methods are recommended over CRAM-MD5.
  • DIGEST-MD5. DIGEST-MD5 is a mandatory authentication method for LDAPv3 servers. While it is not as strong as public key systems or Kerberos authentication methods, it is preferred over plain text passwords and does protect against plain text attacks.
  • Generic Security Services (GSS-API). Generic Security Services (GSS) is a security API that is the native way for UNIX-based operating systems to access and authenticate Kerberos services. GSS-API also supports session encryption, similar to TLS/SSL. This allows LDAP clients to authenticate with the server using Kerberos version 5 credentials (tickets) and to use network session encryption.
    For Directory Server to use GSS-API, Kerberos must be configured on the host machine. See Section 14.3.4, “About Kerberos with Directory Server”.


    GSS-API and, thus, Kerberos are only supported on platforms that have GSS-API support. To use GSS-API, it may be necessary to install the Kerberos client libraries; any required Kerberos libraries will be available through the operating system vendor.
CRAM-MD5, DIGEST-MD5, and GSS-API are all shared secret mechanisms. The server challenges the client attempting to bind with a secret, such as a password, that depends on the mechanism. The user sends back the response required by the mechanism.


DIGEST-MD5 requires clear text passwords. The Directory Server requires the clear text password in order to generate the shared secret. Passwords already stored as a hashed value, such as SHA1, cannot be used with DIGEST-MD5.

14.3.4. About Kerberos with Directory Server

Kerberos v5 must be deployed on the host for Directory Server to utilize the GSS-API mechanism for SASL authentication. GSS-API and Kerberos client libraries must be installed on the Directory Server host to take advantage of Kerberos services.
On Red Hat Enterprise Linux, the supported Kerberos libraries are MIT Kerberos version 5.
The concepts of Kerberos, as well as using and configuring Kerberos, are covered at the MIT Kerberos website, http://web.mit.edu/Kerberos/. About Principals and Realms

A principal is a user in the Kerberos environment. A realm is a set of users and the authentication methods for those users to access the realm. A realm resembles a fully-qualified domain name and can be distributed across either a single server or a single domain across multiple machines. A single server instance can also support multiple realms.


Kerberos realms are only supported for GSS-API authentication and encryption, not for DIGEST-MD5.
Realms are used by the server to associate the DN of the client in the following form, which looks like an LDAP DN:
For example, Mike Connors in the engineering realm of the European division of example.com uses the following association to access a server in the US realm:
Babara Jensen, from the accounting realm of US.example.com, does not have to specify a realm when to access a local server:
If realms are supported by the mechanism and the default realm is not used to authenticate to the server, then the realm must be specified in the Kerberos principal. Otherwise, the realm can be omitted.


Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server. About the KDC Server and Keytabs

Kerberos is a protocol which allows users or servers to authenticate to a server securely over an insecure connection. As with protocols like TLS and SSL, Kerberos generates and issues session keys which encrypt information. A Kerberos server, then, has two functions: as an authenticating server to validate clients and as a ticket granting server.
Because of this, the Kerberos server is called a key distribution center or KDC.
See the operating system documentation for information on installing and configuring a Kerberos server.
When a client authenticates to the Directory Server using GSS-API, the KDC sends a session key, followed by a ticket granting ticket (TGT). The TGT contains the client's ID and network address, a validity period, and the session key. The ticket and the ticket's lifetime are parameters in the Kerberos client and server configuration. In many systems, this TGT is issued to the client when the user first logs into the operating system.
Command-line utilities provided with the operating system — including kinit, klist, and kdestroy — can acquire, list, and destroy the TGT. These tools usually use a file called a keytab to the issued keys. This file is created by the Kerberos administrator by exporting the key from the KDC.
In order to respond to Kerberos operations, the Directory Server requires access to its own cryptographic key. The Kerberos key is written in the keytab file. The keytab gives the credentials that the Directory Server uses to authenticate to other servers. Directory Server assigns a keytab through the KRB5_KTNAME environment variable in its startup script (/etc/sysconfig/dirsrv):
KRB5_KTNAME=/etc/dirsrv/ds.keytab ; export KRB5_KTNAME
When the Directory Server authenticates to the server, it is as if it is running a kinit command to initiate the connection:
kinit -k -t /etc/dirsrv/ds.keytab ldap/FQDN@REALM
The Directory Server uses the service name ldap. Its Kerberos principal is ldap/host-fqdn@realm, such as ldap/ldap.corp.example.com/EXAMPLE.COM. The host-fqdn must be the fully-qualified host and domain name, which can be resolved by all LDAP and Kerberos clients through both DNS and reverse DNS lookups. A key with this identity must be stored in the server's keytab in order for Kerberos to work.
Whatever server the Directory Server is authenticating to must have a SASL mapping that maps the Directory Server's principal (its user entry, usually something like ldap/server.example.com@EXAMPLE.COM) to a real entry DN in the receiving server.
On Red Hat Enterprise Linux, the client-side Kerberos configuration is in the /etc/krb5.conf.
For information on setting up the service key, see the Kerberos documentation.
Example 14.4, “KDC Server Configuration” shows a KDC server configured with the company.example.com realm.

Example 14.4. KDC Server Configuration

     ticket_lifetime = 24000 
     default_realm = COMPANY.EXAMPLE.COM 
     dns_lookup_realm = false 
     dns_lookup_kdc = false 
     ccache_type = 1 
     forwardable = true 
     proxiable = true 
     default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc 
     default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc 
     permitted_enctypes = des3-hmac-sha1 des-cbc-crc 
     kdc = kdcserver.company.example.com:88 
     admin_server =adminserver.company.example.com:749 
     default_domain = company.example.com 
  pam = { 
     debug = true 
     ticket_lifetime = 36000 
     renew_lifetime = 36000 
     forwardable = true 
     krb4_convert = false 
  default = FILE:/var/krb5/kdc.log 
  kdc = FILE:/var/krb5/kdc.log 
  admin_server = FILE:/var/log/kadmind.log Setting up Kerberos on Solaris

As mention, Directory Server SASL authentication requires Kerberos to be properly configured on a system. Two settings on Solaris systems — the Kerberos authentication mechanism and the system keytab — have to be reconfigured for SASL to work as the Directory Server expects.
Kerberos authentication is required to use SASL with the Directory Server. On Solaris, however, the Kerberos module (kerberos_v5) is not the first one listed in the Solaris /etc/gss/mech file. This is the default /etc/gss/mech file:
diffie_hellman_640_0   dh640-0.so.1
diffie_hellman_1024_0   dh1024-0.so.1
kerberos_v5 1.2.840.113554.1.2.2 gl/mech_krb5.so gl_kmech_krb5
If the kerberos_v5 module isn't the first one listed, then kinit fails even if the keytab file is working and /etc/krb5/krb5.conf is properly configured. To allow SASl to work on Solaris, move the kerberos_v5 line to the top of the file:
kerberos_v5 1.2.840.113554.1.2.2 gl/mech_krb5.so gl_kmech_krb5    
diffie_hellman_640_0   dh640-0.so.1
diffie_hellman_1024_0   dh1024-0.so.1
The second thing that needs reconfigured on Solaris is the Kerberos encryption type in the system's keytab file for both users and the server. The encryption needs to be changed to des-cbc-crc. This can be done using the ktadd command on Solaris:
ktadd -k User.keytab -e des-cbc-crc:normal User@EXAMPLE.COM
ktadd -k Server.keytab -e des-cbc-crc:normal ldap/FQDN@EXAMPLE.COM

14.3.5. Configuring SASL Identity Mapping

SASL identity mapping can be configured from either the Directory Server or the command line. For SASL identity mapping to work for SASL authentication, the mapping must return one, and only one, entry that matches and Kerberos must be configured on the host machine. Configuring SASL Identity Mapping from the Console

  1. In the Directory Server Console, open the Configuration tab.
  2. Select the SASL Mapping tab.
  3. To add a new SASL identity mapping, select the Add button, and fill in the required values.
    • Name. This field sets the unique name of the SASL mapping.
    • Regular expression. This field sets the regular expression used to match the DN components, such as \(.*\). This field corresponds to the nsSaslMapRegexString value in the SASL mapping LDIF entry.
    • Search base DN. This field gives the base DN to search to map entries, such as ou=People,dc=example,dc=com. This field corresponds to the nsSaslMapBaseDNTemplate value in the SASL mapping LDIF entry.
    • Search filter. This field gives the search filter for the components to replace, such as (objectclass=*). This field corresponds to the nsSaslMapFilterTemplate value in the SASL mapping LDIF entry.
To edit a SASL identity mapping, highlight that identity in the SASL Mapping tab, and click Modify. Change any values, and save.
To delete a SASL identity mapping, highlight it and hit Delete. A dialog box comes up to confirm the deletion. Configuring SASL Identity Mapping from the Command Line

To configure SASL identity mapping from the command line, use the ldapmodify utility to add the identity mapping scheme. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com 

dn: dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This matches any user's common name and maps it to the result of the subtree search with base ou=People,dc=example,dc=com, based on the filter cn=userId.


When SASL maps are added over LDAP, they are not used by the server until it is restarted. Adding the SASL map with ldapmodify adds the mapping to the end of the list, regardless of its ASCII order.

14.3.6. Configuring SASL Authentication at Directory Server Startup

SASL GSS-API authentication has to be activated in Directory Server so that Kerberos tickets can be used for authentication. This is done by supplying a system configuration file for the init scripts to use which identifies the variable to set the keytab file location. When the init script runs at Directory Server startup, SASL authentication is then immediately active.
The default SASL configuration file is in /etc/sysconfig/dirsrv.
If there are multiple Directory Server instances and not all of them will use SASL authentication, then there can be instance-specific configuration files created in that directory named dirsrv-instance. For example, dirsrv-example. The default dirsrv file can be used if there is a single instance on a host.
To enable SASL authentication, uncomment the KRB5_KTNAME line in the /etc/sysconfig/dirsrv (or instance-specific) file, and set the keytab location for the KRB5_KTNAME variable. For example:
# In order to use SASL/GSSAPI the directory
# server needs to know where to find its keytab
# file - uncomment the following line and set
# the path and filename appropriately
KRB5_KTNAME=/etc/dirsrv/krb5.keytab ; export KRB5_KTNAME

14.3.7. Using an External Keytab

A default keytab file is specified in the Directory Server start script and is used by the Directory Server automatically. However, it is possible to specify a different keytab file, referencing a different principal, by manually running kinit and then specifying the cached credentials.
To specify the cached kinit credentials, add the principal as the KRB5CCNAME line in /etc/sysconfig/dirsrv:
KRB5CCNAME=/tmp/krb_ccache ; export KRB5CCNAME
kinit principalname   
# how to provide the password here is left as an exercise
# or kinit -k -t /path/to/file.keytab principalname
chown serveruid:serveruid $KRB5CCNAME 
# so the server process can read it
# start a cred renewal "daemon"
( while XXX ; do sleep NNN ; kinit ..... ; done ) &
# the exit condition XXX and sleep interval NNN are left as an exercise
The server has no way to renew these cached credentials. The kinit process must be run manually, external to Directory Server processes, or the server could begin receiving SASL bind failures when the server attempts to use expired credentials.