7.12. Using Kerberos GSS-API with SASL

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.

7.12.1. Authentication Mechanisms for SASL in Directory Server

Directory Server support the following SASL encryption mechanisms:
  • PLAIN. PLAIN sends cleartext passwords for simple password-based authentication. This is not a preferred mechanism for most applications because of its relative lack of strength, but it can be used in some situations where anonymous access is disabled and an arbitrary UID (not a DN) is used to authenticate to the server because SASL can map the UID to a directory entry.
  • 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 7.12, “Using Kerberos GSS-API with SASL”.

    Note

    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.

Note

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.

7.12.2. About Kerberos in Directory Server

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/.

7.12.2.1. 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.

Note

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:
uid=user_name/[server_instance],cn=realm,cn=mechanism,cn=auth
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:
uid=mconnors/cn=Europe.example.com,cn=engineering,cn=gssapi,cn=auth
Babara Jensen, from the accounting realm of US.example.com, does not have to specify a realm when to access a local server:
uid=bjensen,cn=accounting,cn=gssapi,cn=auth
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.

Note

Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server.

7.12.2.2. 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

Note

The Directory Server must be able to access the host keytab and the krb5.conf file for GSS-API authentication in SASL. For this host keytab file to be properly labeled in SELinux in the dirsrv_config_t context, the file must be in the /etc directory.
Only the host keytab and krb5.conf must be in /etc. The user key tabs can still be in any directory.
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.

Note

The Directory Server must be able to access the krb5.conf file for GSS-API authentication in SASL. For these files to be properly labeled in SELinux in the dirsrv_config_t context, the file must be in the /etc directory.
For information on setting up the service key, see the Kerberos documentation.
Example 7.4, “KDC Server Configuration” shows a KDC server configured with the company.example.com realm.

Example 7.4. KDC Server Configuration

[libdefaults]
     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
[realms]
  COMPANY.EXAMPLE.COM = {
     kdc = kdcserver.company.example.com:88
     admin_server =adminserver.company.example.com:749
     default_domain = company.example.com
  }
[appdefaults]
  pam = {
     debug = true
     ticket_lifetime = 36000
     renew_lifetime = 36000
     forwardable = true
     krb4_convert = false
  }
[logging]
  default = FILE:/var/krb5/kdc.log
  kdc = FILE:/var/krb5/kdc.log
  admin_server = FILE:/var/log/kadmind.log

7.12.3. 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

7.12.4. 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.