11.2. Configuring the Kerberos KDC

Install the master KDC first and then install any necessary secondary servers after the master is set up.

Important

Setting up Kerberos KDC manually is not recommended. The recommended way to introduce Kerberos into Red Hat Enterprise Linux environments is to use the Identity Management feature.

11.2.1. Configuring the Master KDC Server

Important

The KDC system should be a dedicated machine. This machine needs to be very secure — if possible, it should not run any services other than the KDC.
  1. Install the required packages for the KDC:
    [root@server ~]# yum install krb5-server krb5-libs krb5-workstation
  2. Edit the /etc/krb5.conf and /var/kerberos/krb5kdc/kdc.conf configuration files to reflect the realm name and domain-to-realm mappings. For example:
    [logging]
     default = FILE:/var/log/krb5libs.log
     kdc = FILE:/var/log/krb5kdc.log
     admin_server = FILE:/var/log/kadmind.log
    
    [libdefaults]
     default_realm = EXAMPLE.COM
     dns_lookup_realm = false
     dns_lookup_kdc = false
     ticket_lifetime = 24h
     renew_lifetime = 7d
     forwardable = true
     allow_weak_crypto = true
    
    [realms]
      EXAMPLE.COM = {
      kdc = kdc.example.com.:88
      admin_server = kdc.example.com
      default_domain = example.com
     }
    
    [domain_realm]
     .example.com = EXAMPLE.COM
     example.com = EXAMPLE.COM
    A simple realm can be constructed by replacing instances of EXAMPLE.COM and example.com with the correct domain name — being certain to keep uppercase and lowercase names in the correct format — and by changing the KDC from kerberos.example.com to the name of the Kerberos server. By convention, all realm names are uppercase and all DNS host names and domain names are lowercase. The man pages of these configuration files have full details about the file formats.
  3. Create the database using the kdb5_util utility.
    [root@server ~]# kdb5_util create -s
    The create command creates the database that stores keys for the Kerberos realm. The -s argument creates a stash file in which the master server key is stored. If no stash file is present from which to read the key, the Kerberos server (krb5kdc) prompts the user for the master server password (which can be used to regenerate the key) every time it starts.
  4. Edit the /var/kerberos/krb5kdc/kadm5.acl file. This file is used by kadmind to determine which principals have administrative access to the Kerberos database and their level of access. For example:
    */admin@EXAMPLE.COM  *
    Most users are represented in the database by a single principal (with a NULL, or empty, instance, such as joe@EXAMPLE.COM). In this configuration, users with a second principal with an instance of admin (for example, joe/admin@EXAMPLE.COM) are able to exert full administrative control over the realm's Kerberos database.
    After kadmind has been started on the server, any user can access its services by running kadmin on any of the clients or servers in the realm. However, only users listed in the kadm5.acl file can modify the database in any way, except for changing their own passwords.

    Note

    The kadmin utility communicates with the kadmind server over the network, and uses Kerberos to handle authentication. Consequently, the first principal must already exist before connecting to the server over the network to administer it. Create the first principal with the kadmin.local command, which is specifically designed to be used on the same host as the KDC and does not use Kerberos for authentication.
  5. Create the first principal using kadmin.local at the KDC terminal:
    [root@server ~]# kadmin.local -q "addprinc username/admin"
  6. Start Kerberos using the following commands:
    [root@server ~]# systemctl start krb5kdc.service
    [root@server ~]# systemctl start kadmin.service
  7. Add principals for the users using the addprinc command within kadmin. kadmin and kadmin.local are command line interfaces to the KDC. As such, many commands — such as addprinc — are available after launching the kadmin program. Refer to the kadmin man page for more information.
  8. Verify that the KDC is issuing tickets. First, run kinit to obtain a ticket and store it in a credential cache file. Next, use klist to view the list of credentials in the cache and use kdestroy to destroy the cache and the credentials it contains.

    Note

    By default, kinit attempts to authenticate using the same system login user name (not the Kerberos server). If that user name does not correspond to a principal in the Kerberos database, kinit issues an error message. If that happens, supply kinit with the name of the correct principal as an argument on the command line:
    kinit principal

11.2.2. Setting up Secondary KDCs

When there are multiple KDCs for a given realm, one KDC (the master KDC) keeps a writable copy of the realm database and runs kadmind. The master KDC is also the realm's admin server. Additional secondary KDCs keep read-only copies of the database and run kpropd.
The master and slave propagation procedure entails the master KDC dumping its database to a temporary dump file and then transmitting that file to each of its slaves, which then overwrite their previously received read-only copies of the database with the contents of the dump file.
To set up a secondary KDC:
  1. Install the required packages for the KDC:
    [root@slavekdc ~]# yum install krb5-server krb5-libs krb5-workstation
  2. Copy the master KDC's krb5.conf and kdc.conf files to the secondary KDC.
  3. Start kadmin.local from a root shell on the master KDC.
    1. Use the kadmin.local add_principal command to create a new entry for the master KDC's host service.
      [root@slavekdc ~]# kadmin.local -r EXAMPLE.COM
       Authenticating as principal root/admin@EXAMPLE.COM with password.
      kadmin: add_principal -randkey host/masterkdc.example.com
      Principal "host/masterkdc.example.com@EXAMPLE.COM" created.
      kadmin: ktadd host/masterkdc.example.com
      Entry for principal host/masterkdc.example.com with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/masterkdc.example.com with kvno 3, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/masterkdc.example.com with kvno 3, encryption type DES with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/masterkdc.example.com with kvno 3, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/etc/krb5.keytab.
      kadmin: quit
    2. Use the kadmin.local ktadd command to set a random key for the service and store the random key in the master's default keytab file.

      Note

      This key is used by the kprop command to authenticate to the secondary servers. You will only need to do this once, regardless of how many secondary KDC servers you install.
  4. Start kadmin from a root shell on the secondary KDC.
    1. Use the kadmin.local add_principal command to create a new entry for the secondary KDC's host service.
      [root@slavekdc ~]# kadmin -p jsmith/admin@EXAMPLE.COM -r EXAMPLE.COM
      Authenticating as principal jsmith/admin@EXAMPLE.COM with password.
      Password for jsmith/admin@EXAMPLE.COM:
      kadmin: add_principal -randkey host/slavekdc.example.com
      Principal "host/slavekdc.example.com@EXAMPLE.COM" created.
      kadmin: ktadd host/slavekdc.example.com@EXAMPLE.COM
      Entry for principal host/slavekdc.example.com with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/slavekdc.example.com with kvno 3, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/slavekdc.example.com with kvno 3, encryption type DES with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
      Entry for principal host/slavekdc.example.com with kvno 3, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/etc/krb5.keytab.
      kadmin: quit
    2. Use the kadmin.local ktadd command to set a random key for the service and store the random key in the secondary KDC server's default keytab file. This key is used by the kpropd service when authenticating clients.
  5. With its service key, the secondary KDC could authenticate any client which would connect to it. Obviously, not all potential clients should be allowed to provide the kprop service with a new realm database. To restrict access, the kprop service on the secondary KDC will only accept updates from clients whose principal names are listed in /var/kerberos/krb5kdc/kpropd.acl.
    Add the master KDC's host service's name to that file.
    [root@slavekdc ~]# echo host/masterkdc.example.com@EXAMPLE.COM > /var/kerberos/krb5kdc/kpropd.acl
  6. Once the secondary KDC has obtained a copy of the database, it will also need the master key which was used to encrypt it. If the KDC database's master key is stored in a stash file on the master KDC (typically named /var/kerberos/krb5kdc/.k5.REALM), either copy it to the secondary KDC using any available secure method, or create a dummy database and identical stash file on the secondary KDC by running kdb5_util create -s and supplying the same password. The dummy database will be overwritten by the first successful database propagation.
  7. Ensure that the secondary KDC's firewall allows the master KDC to contact it using TCP on port 754 (krb5_prop), and start the kprop service.
  8. Verify that the kadmin service is disabled.
  9. Perform a manual database propagation test by dumping the realm database on the master KDC to the default data file which the kprop command will read (/var/kerberos/krb5kdc/slave_datatrans).
    [root@masterkdc ~]# kdb5_util dump /var/kerberos/krb5kdc/slave_datatrans
  10. Use the kprop command to transmit its contents to the secondary KDC.
    [root@slavekdc ~]# kprop slavekdc.example.com
  11. Using kinit, verify that the client system is able to correctly obtain the initial credentials from the KDC.
    The /etc/krb5.conf for the client should list only the secondary KDC in its list of KDCs.
    [realms]
      EXAMPLE.COM = {
      kdc = slavekdc.example.com.:88
      admin_server = kdc.example.com
      default_domain = example.com
     }
  12. Create a script which dumps the realm database and runs the kprop command to transmit the database to each secondary KDC in turn, and configure the cron service to run the script periodically.

11.2.3. Kerberos Key Distribution Center Proxy

In some deployments, only the HTTPS port (443 using TCP) is accessible and not the default Kerberos ports. Clients can obtain Kerberos credentials using the IdM HTTPS service as a proxy. This reverse proxy enables accessing Kerberos-authenticated services through HTTPS.
Kerberos Key Distribution Center Proxy (KKDCP) provides this functionality in IdM.

Configuring KKDCP in Your Deployment

On an IdM server, KKDCP is enabled by default.
On an IdM client, you must enable KKDCP:
  1. Reconfigure the /etc/krb5.conf file as described in Section 11.3, “Configuring a Kerberos Client”.
  2. Restart the SSSD service:
    # systemctl restart sssd.service

Verifying That KKDCP Is Enabled on an IdM Server

The KKDCP is automatically enabled each time the Apache web server starts, if the attribute and value pair ipaConfigString=kdcProxyEnabled exists in the directory. In this situation, the symbolic link /etc/httpd/conf.d/ipa-kdc-proxy.conf is created.
To verify if the KKDCP feature is enabled, check that the symbolic link exists:
$ ls -l /etc/httpd/conf.d/ipa-kdc-proxy.conf
lrwxrwxrwx. 1 root root 36 Aug 15 09:37 /etc/httpd/conf.d/ipa-kdc-proxy.conf -> /etc/ipa/kdcproxy/ipa-kdc-proxy.conf

Disabling KKDCP on an IdM Server

  1. Remove the ipaConfigString=kdcProxyEnabled attribute and value pair from the directory:
    # ipa-ldap-updater /usr/share/ipa/kdcproxy-disable.uldif
  2. Restart the httpd service on the IdM server:
    # systemctl restart httpd.service