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:
- 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_tcontext, 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 /etcdirectory.
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.