Sun Enterprise Authentication Mechanism 1.0.1 Guide

Configuring KDC Servers

After installing the SEAM software, you must configure the KDC servers. Configuring a master KDC and at least one slave KDC provides the service that issues credentials. These credentials are the basis for SEAM, so the KDCs must be installed before attempting other tasks.

The most significant difference between a master and a slave KDC is that only the master can handle database administration requests. For instance, changing a password or adding a new principal must be done on the master KDC. These changes can then be propagated to the slave KDCs. Both the slave and master KDCs generate credentials; this provides redundancy in case the master KDC is not able to respond.

How to Configure a Master KDC

To provide a complete example, assume that you did not run the preconfiguration procedure. If you used the preconfiguration procedure when installing the software, then many of the files included in this procedure do not need to be edited; however, you should review the file contents.

In this procedure the following configuration parameters are used:

realm name = ACME.COM
DNS domain name = acme.com
master KDC = kdc1.acme.com
slave KDC = kdc2.acme.com
admin principle = kws/admin
online help URL = http://denver:8888/ab2/coll.384.1/SEAM/@AB2PageView/6956

Note -
Adjust the URL to point to the "SEAM Administration Tool" section, as described in the SEAM Installation and Release Notes.

Prerequisites for configuring a master KDC.

This procedure requires that the master KDC software is installed. In addition, DNS must be running. See "Swapping Master and Slave KDCs" for specific naming instructions if this master is to be swappable.

Become superuser on the master KDC.

Edit the Kerberos configuration file (krb5.conf).

You need to change the realm names and the names of the servers. See the krb5.conf(4) man page for a full description of this file. If you installed the SEAM software using the configuration files, verify the contents of the file instead of editing it.

kdc1 # cat /etc/krb5/krb5.conf
[libdefaults]
        default_realm = ACME.COM

[realms]
                ACME.COM = {
                kdc = kdc1.acme.com
                kdc = kdc2.acme.com
                admin_server = kdc1.acme.com
        }

[domain_realm]
        .acme.com = ACME.COM
#
# if the domain name and realm name are equivalent, 
# this entry is not needed
#
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log

[appdefaults]
    gkadmin = {
        help_url = http://denver:8888/ab2/coll.384.1/SEAM/@AB2PageView/6956
        }

In this example, the lines for domain_realm, kdc, admin_server, and all domain_realm entries were changed. The line for domain_realm is included to make the example complete, but this entry will not be created by the installation process if the realm and domain names are equivalent. In addition, the line defining the help_url was edited.

Edit the KDC configuration file (kdc.conf).

You need to change the realm name. See the kdc.conf(4) man page for a full description of this file. If you installed the SEAM software using the configuration files, verify the contents of the file instead of editing it.

kdc1 # cat /etc/krb5/kdc.conf
[kdcdefaults]
        kdc_ports = 88,750

[realms]
        ACME.COM= {
                profile = /etc/krb5/krb5.conf
                database_name = /var/krb5/principal
                admin_keytab = /var/krb5/kadm5.keytab
                acl_file = /var/krb5/kadm5.acl
                kadmind_port = 749
                max_life = 8h 0m 0s
                max_renewable_life = 7d 0h 0m 0s
        }

In this example, the realm name definition in the realms section was changed.

Create the KDC database using kdb5_util.

The kdb5_util command creates the KDC database and also, when used with the -s option, creates a stash file that is used to authenticate the KDC to itself before the kadmind and krb5kdc daemons are started.

kdc1 # /usr/krb5/sbin/kdb5_util create -r ACME.COM -s
Initializing database '/var/krb5/principal' for realm 'ACME.COM'
master key name 'K/M@ACME.COM'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: <type the key>
Re-enter KDC database master key to verify: <type it again>

The -r option followed by the realm name is not required if the realm name is equivalent to the servers name space domain name.

Edit the Kerberos access control list file (kadm5.acl).

Once populated, /etc/krb5/kadm5.acl should contain all of the principal names that are allowed to administer the KDC. The first entry added might look like the following:
kws/admin@ACME.COM *
This entry gives the kws/admin principal in the ACME.COM realm the ability to modify principals or policies in the KDC. The default installation includes an "*" to match all admin principals. This could be a security risk, so it is more secure to include a list of all of the admin principals.

Start kadmin.local.

The next sub-steps create principals used by SEAM.

kdc1 # /usr/krb5/sbin/kadmin.local
kadmin.local:

Add administration principals to the database using kadmin.local.

You can add as many admin principals as you need. You must add at least one admin principal to complete the KDC configuration process. For this example, a kws/admin principal is added. You can substitute an appropriate principal name instead of "kws."

kadmin.local: addprinc kws/admin
Enter password for principal kws/admin@ACME.COM: <type the password>
Re-enter password for principal kws/admin@ACME.COM: <type it again>
Principal "kws/admin@ACME.COM" created.
kadmin.local:

Create a keytab file for kadmin using kadmin.local.

This command sequence creates a special keytab file with principal entries for kadmin and changepw. These principals are needed for the kadmind service.

kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc1.acme.com
Entry for principal kadmin/kdc1.acme.com with kvno 3, encryption type DES-CBC-CRC
          added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local: ktadd -k /etc/krb5/kadm5.keytab changepw/kdc1.acme.com
Entry for principal changepw/kdc1.acme.com with kvno 3, encryption type DES-CBC-CRC 
          added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:

Quit kadmin.local

You have added all of the required principals for the next steps.
kadmin.local: quit

Start the Kerberos daemons.

kdc1 # /etc/init.d/kdc start
kdc1 # /etc/init.d/kdc.master start

Start kadmin.

At this point, you can add principals using the SEAM Administration Tool. The command line example is shown for simplicity. You must log on with one of the admin principal names that you created earlier in this procedure.

kdc1 # /usr/krb5/sbin/kadmin -p kws/admin
Enter password: <Enter kws/admin password>
kadmin:

Create the master KDC host principal using kadmin.

The host principal is used by Kerberized applications (such as klist and kprop) as well as Kerberized services (such as ftp and telnet).
kadmin: addprinc -randkey host/kdc1.acme.com Principal "host/kdc1.acme.com@ACME.COM" created. kadmin:

Optional: Create the master KDC root principal using kadmin.

This principal is used for authenticated NFS-mounting, and so might not be necessary on a master KDC.

kadmin: addprinc root/kdc1.acme.com
Enter password for principal root/kdc1.acme.com@ACME.COM: <type the password>
Re-enter password for principal root/kdc1.acme.com@ACME.COM: <type it again>
Principal "root/kdc1.acme.com@ACME.COM" created.
kadmin:

Add the master KDCs host principal to the master KDCs keytab file.

Adding the host principal to the keytab file allows for this principal to be used automatically.

kadmin: ktadd host/kdc1.acme.com
kadmin: Entry for principal host/kdc1.acme.com with
  kvno 3, encryption type DES-CBC-CRC added to keytab
  WRFILE:/etc/krb5/krb5.keytab
kadmin: quit

Quit kadmin
kadmin: quit

Add an entry for each KDC into the propagation configuration file (kpropd.acl).

See the kprop(1M) man page for a full description of this file. If you installed the SEAM software using the configuration files, verify the contents of the file instead of editing it.
kdc1 # cat /etc/krb5/kpropd.acl host/kdc1.acme.com@ACME.COM host/kdc2.acme.com@ACME.COM

Optional: Synchronize the master KDCs clock using NTP or another clock synchronization mechanism.

It is not necessary to install and use NTP, but every clock must be within default time defined in the libdefaults section of the krb5.conf file in order for authentication to succeed. See "Synchronizing Clocks between KDCs and SEAM Clients" for information about NTP.

How to Configure a Slave KDC

In this procedure, a new slave KDC named kdc3 is configured. To provide a complete example, it is assumed that you did not use the preconfiguration procedure when installing the software or had not defined kdc3 as a slave when running the preconfiguration procedure. If you used the procedure and identified kdc3 as a slave, then many of the files included in this procedure do not need to be edited, but you should review the contents of the files.

This procedure uses the following configuration parameters:

realm name = ACME.COM
DNS domain name = acme.com
master kdc = kdc1.acme.com
slave kdc = kdc2.acme.com and kdc3.acme.com
admin principle = kws/admin
online help URL = http://denver:8888/ab2/coll.384.1/SEAM/@AB2PageView/6956

Note -
Adjust the URL to point to the "SEAM Administration Tool" section, as described in the SEAM Installation and Release Notes.

Prerequisites for configuring a slave KDC.

This procedure requires that the master KDC has been configured and that the SEAM slave KDC software has been installed on kdc3. See "Swapping Master and Slave KDCs" for specific instructions if this slave is to be swappable.

On the master KDC: Become superuser.

On the master KDC: Start kadmin.

You must log on with one of the admin principal names that you created when configuring the master KDC.

kdc1 # /usr/krb5/sbin/kadmin -p kws/admin
Enter password: <Enter kws/admin password>
kadmin:

On the master KDC: Add slave host principals to the database, if not already done, using kadmin.

In order for the slave to function, it must have a host principal.
kadmin: addprinc -randkey host/kdc3.acme.com Principal "host/kdc3@ACME.COM" created. kadmin:

Optional: On the master KDC, create the slave KDC root principal using kadmin.

This principal is only needed if the slave will be NFS-mounting an authenticated file system.

kadmin: addprinc root/kdc3.acme.com
Enter password for principal root/kdc3.acme.com@ACME.COM: <type the password>
Re-enter password for principal root/kdc3.acme.com@ACME.COM: <type it again>
Principal "root/kdc3.acme.com@ACME.COM" created.
kadmin:

Quit kadmin
kadmin: quit

On the master KDC: Edit the Kerberos configuration file (krb5.conf).

You need to add an entry for each slave. See the krb5.conf(4) man page for a full description of this file.If you defined kdc3 as a slave server when running the preconfiguration procedure, verify the contents of the file instead of editing it.

kdc1 # cat /etc/krb5/krb5.conf
[libdefaults]
        default_realm = ACME.COM

[realms]
                ACME.COM = {
                kdc = kdc1.acme.com
                kdc = kdc2.acme.com
                kdc = kdc3.acme.com
                admin_server = kdc1.acme.com
        }

[domain_realm]
        .acme.com = ACME.COM
#
# if the domain name and realm name are equivalent, 
# this entry is not needed
#        
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log

[appdefaults]
    gkadmin = {
        help_url = http://denver:8888/ab2/coll.384.1/SEAM/@AB2PageView/6956

On the master KDC: Add an entry for each slave KDC into the database propagation configuration file (kpropd.acl).

See the kprop(1M) man page for a full description of this file. If you defined kdc3 as a slave server when running the preconfiguration procedure, verify the contents of the file instead of editing it.
kdc1 # cat /etc/krb5/kpropd.acl host/kdc1.acme.com@ACME.COM host/kdc2.acme.com@ACME.COM host/kdc3.acme.com@ACME.COM

On all Slaves: Copy the KDC administration files from the master KDC server.

This step needs to be followed on all slave KDCs, since the master KDC server has updated information that each KDC server needs. If you defined kdc3 as a slave server when running the preconfiguration procedure, verify the contents of the files instead of copying them. You can use ftp or a similar transfer mechanism to grab copies of the following files from the master:
- /etc/krb5/krb5.conf
- /etc/krb5/kdc.conf
- /etc/krb5/kpropd.acl

On the new slave: Add the slave's host principal to the slave's keytab file using kadmin.

You must log on with one of the admin principal names that you created when configuring the master KDC. This entry will allow kprop and other Kerberized applications to function.

kdc3 # /usr/krb5/sbin/kadmin -p kws/admin
Enter password: <Enter kws/admin password>
kadmin: ktadd host/kdc3.acme.com
kadmin: Entry for principal host/kdc3.acme.com with
  kvno 3, encryption type DES-CBC-CRC added to keytab
  WRFILE:/etc/krb5/krb5.keytab
kadmin: quit

On the master KDC: Add slave KDC names to the cron job, which automatically runs the backups, by running crontab -e.

Add the name of each slave KDC server at the end of the kprop_script line. If you defined kdc3 as a slave server when running the preconfiguration procedure, verify the contents of the file instead of editing it.
10 3 * * * /usr/krb5/lib/kprop_script kdc2.acme.com kdc3.acme.com
You might also want to change the time of the backups. This configuration starts the backup process every day at 3:10 AM.

On the master KDC: Back up and propagate the database using kprop_script.

If a backup copy of the database is already available, it is not necessary to complete another backup. See "How to Manually Propagate the Kerberos Database to the Slave KDCs" for further instructions.
kdc1 # /usr/krb5/lib/kprop_script kdc3.acme.com Database propagation to kdc3.acme.com: SUCCEEDED

On the new slave: Create a stash file using kdb5_util.

kdc3 # /usr/krb5/sbin/kdb5_util stash
kdb5_util: Cannot find/read stored master key while reading master key
kdb5_util: Warning: proceeding without master key

Enter KDC database master key: <type the key>

On the new slave: Start the KDC daemon (krb5kdc).
kdc3 # /etc/init.d/kdc start

Optional: On the new slave, synchronize the master KDCs clock using NTP or another clock synchronization mechanism.

It is not necessary to install and use NTP, but every clock must be within the default time defined in the libdefaults section of the krb5.conf file in order for authentication to succeed. See "Synchronizing Clocks between KDCs and SEAM Clients" for information about NTP.