Kerberos Administration Guide

153 Pages·2017·0.69 MB·English

Kerberos Administration Guide
Release 1.20.1
MIT

CONTENTS
1 Installationguide 1
2 ConfigurationFiles 11
3 Realmconfigurationdecisions 41
4 Databaseadministration 45
5 Databasetypes 69
6 Accountlockout 73
7 ConfiguringKerberoswithOpenLDAPback-end 77
8 Applicationservers 79
9 Hostconfiguration 83
10 Backupsofsecurehosts 87
11 PKINITconfiguration 89
12 OTPPreauthentication 95
13 SPAKEPreauthentication 97
14 Addressingdictionaryattackrisks 99
15 PrincipalnamesandDNS 101
16 Encryptiontypes 103
17 HTTPSproxyconfiguration 107
18 Authenticationindicators 109
19 Administrationprograms 111
20 MITKerberosdefaults 145
21 Environmentvariables 149
22 Troubleshooting 151
i
23 Advancedtopics 153
24 Variouslinks 161
Index 163
ii
CHAPTER
ONE
INSTALLATION GUIDE
1.1 Contents
1.1.1 Installing KDCs
When setting up Kerberos in a production environment, it is best to have multiple replica KDCs alongside with a
primary KDC to ensure the continued availability of the Kerberized services. Each KDC contains a copy of the
Kerberos database. The primary KDC contains the writable copy of the realm database, which it replicates to the
replicaKDCsatregularintervals. Alldatabasechanges(suchaspasswordchanges)aremadeontheprimaryKDC.
ReplicaKDCsprovideKerberosticket-grantingservices,butnotdatabaseadministration,whentheprimaryKDCis
unavailable. MIT recommends that you install all of your KDCs to be able to function as either the primary or one
of the replicas. This will enable you to easily switch your primary KDC with one of the replicas if necessary (see
SwitchingprimaryandreplicaKDCs). Thisinstallationprocedureisbasedonthatrecommendation.
Warning:
• TheKerberossystemreliesontheavailabilityofcorrecttimeinformation. Ensurethattheprimaryandall
replicaKDCshaveproperlysynchronizedclocks.
• It is best to install and run KDCs on secured and dedicated hardware with limited access. If your KDC is
alsoafileserver,FTPserver,Webserver,orevenjustaclientmachine,someonewhoobtainedrootaccess
throughasecurityholeinanyofthoseareascouldpotentiallygainaccesstotheKerberosdatabase.
InstallandconfiguretheprimaryKDC
InstallKerberoseitherfromtheOS-providedpackagesorfromthesource(Seedo_build).
Note: Forthepurposeofthisdocumentwewillusethefollowingnames:
kerberos.mit.edu - primary KDC
kerberos-1.mit.edu - replica KDC
ATHENA.MIT.EDU - realm name
.k5.ATHENA.MIT.EDU - stash file
admin/admin - admin principal
SeeMITKerberosdefaultsforthedefaultnamesandlocationsoftherelevanttothistopicfiles. Adjustthenamesand
pathstoyoursystemenvironment.
1
KerberosAdministrationGuide,Release1.20.1
EditKDCconfigurationfiles
Modifytheconfigurationfiles,krb5.conf andkdc.conf,toreflectthecorrectinformation(suchasdomain-realmmap-
pingsandKerberosserversnames)foryourrealm. (SeeMITKerberosdefaultsfortherecommendeddefaultlocations
forthesefiles).
Mostofthetagsintheconfigurationhavedefaultvaluesthatwillworkwellformostsites. Therearesometagsinthe
krb5.conf filewhosevaluesmustbespecified,andthissectionwillexplainthose.
If the locations for these configuration files differs from the default ones, set KRB5_CONFIG and
KRB5_KDC_PROFILEenvironmentvariablestopointtothekrb5.confandkdc.confrespectively. Forexample:
export KRB5_CONFIG=/yourdir/krb5.conf
export KRB5_KDC_PROFILE=/yourdir/kdc.conf
krb5.conf
If you are not using DNS TXT records (see Mapping hostnames onto Kerberos realms), you must specify the de-
fault_realm in the [libdefaults] section. If you are not using DNS URI or SRV records (see Hostnames for KDCs
andKDCDiscovery),youmustincludethekdctagforeachrealminthe[realms]section. Tocommunicatewiththe
kadminserverineachrealm,theadmin_servertagmustbesetinthe[realms]section.
Anexamplekrb5.conffile:
[libdefaults]
default_realm = ATHENA.MIT.EDU
[realms]
ATHENA.MIT.EDU = {
kdc = kerberos.mit.edu
kdc = kerberos-1.mit.edu
admin_server = kerberos.mit.edu
}
kdc.conf
Thekdc.conffilecanbeusedtocontrolthelisteningportsoftheKDCandkadmind,aswellasrealm-specificdefaults,
thedatabasetypeandlocation,andlogging.
Anexamplekdc.conffile:
[kdcdefaults]
kdc_listen = 88
kdc_tcp_listen = 88
[realms]
ATHENA.MIT.EDU = {
kadmind_port = 749
max_life = 12h 0m 0s
max_renewable_life = 7d 0h 0m 0s
master_key_type = aes256-cts
supported_enctypes = aes256-cts:normal aes128-cts:normal
# If the default location does not suit your setup,
# explicitly configure the following values:
# database_name = /var/krb5kdc/principal
2 Chapter1. Installationguide
KerberosAdministrationGuide,Release1.20.1
# key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
# acl_file = /var/krb5kdc/kadm5.acl
}
[logging]
# By default, the KDC and kadmind will log output using
# syslog. You can instead send log output to files like this:
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmin.log
default = FILE:/var/log/krb5lib.log
ReplaceATHENA.MIT.EDUandkerberos.mit.eduwiththenameofyourKerberosrealmandserverrespec-
tively.
Note: You have to have write permission on the target directories (these directories must exist) used by
database_name,key_stash_file,andacl_file.
CreatetheKDCdatabase
You will use the kdb5_util command on the primary KDC to create the Kerberos database and the optional
stash_definition.
Note: Ifyouchoosenottoinstallastashfile,theKDCwillpromptyouforthemasterkeyeachtimeitstartsup. This
meansthattheKDCwillnotbeabletostartautomatically,suchasafterasystemreboot.
kdb5_util will prompt you for the master password for the Kerberos database. This password can be any string. A
goodpasswordisoneyoucanremember,butthatnooneelsecanguess. Examplesofbadpasswordsarewordsthat
canbefoundinadictionary, anycommonorpopularname, especiallyafamousperson(orcartooncharacter), your
usernameinanyform(e.g.,forward,backward,repeatedtwice,etc.),andanyofthesamplepasswordsthatappearin
thismanual. Oneexampleofapasswordwhichmightbegoodifitdidnotappearinthismanualis“MITiys4K5!”,
whichrepresentsthesentence“MITisyoursourceforKerberos5!”(It’sthefirstletterofeachword,substitutingthe
numeral“4”fortheword“for”,andincludesthepunctuationmarkattheend.)
The following is an example of how to create a Kerberos database and stash file on the primary KDC, using the
kdb5_utilcommand. ReplaceATHENA.MIT.EDUwiththenameofyourKerberosrealm:
shell% kdb5_util create -r ATHENA.MIT.EDU -s
Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
master key name 'K/[email protected]'
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 master password.
Re-enter KDC database master key to verify: <= Type it again.
shell%
ThiswillcreatefivefilesinLOCALSTATEDIR/krb5kdc(oratthelocationsspecifiedinkdc.conf):
• twoKerberosdatabasefiles,principal,andprincipal.ok
• theKerberosadministrativedatabasefile,principal.kadm5
• theadministrativedatabaselockfile,principal.kadm5.lock
1.1. Contents 3
KerberosAdministrationGuide,Release1.20.1
• thestashfile,inthisexample.k5.ATHENA.MIT.EDU.Ifyoudonotwantastashfile,runtheabovecommand
withoutthe-soption.
FormoreinformationonadministratingKerberosdatabaseseeOperationsontheKerberosdatabase.
AddadministratorstotheACLfile
Next,youneedcreateanAccessControlList(ACL)fileandputtheKerberosprincipalofatleastoneoftheadmin-
istratorsintoit. Thisfileisusedbythekadmind daemontocontrolwhichprincipalsmayviewandmakeprivileged
modificationstotheKerberosdatabasefiles. TheACLfilenameisdeterminedbytheacl_filevariableinkdc.conf;the
defaultisLOCALSTATEDIR/krb5kdc/kadm5.acl.
FormoreinformationonKerberosACLfileseekadm5.acl.
AddadministratorstotheKerberosdatabase
Next you need to add administrative principals (i.e., principals who are allowed to administer Kerberos database)
to the Kerberos database. You must add at least one principal now to allow communication between the Kerberos
administrationdaemonkadmindandthekadminprogramoverthenetworkforfurtheradministration. Todothis,use
the kadmin.local utility on the primary KDC. kadmin.local is designed to be run on the primary KDC host without
usingKerberosauthenticationtoanadminserver;instead,itmusthavereadandwriteaccesstotheKerberosdatabase
onthelocalfilesystem.
TheadministrativeprincipalsyoucreateshouldbetheonesyouaddedtotheACLfile(seeAddadministratorstothe
ACLfile).
Inthefollowingexample,theadministrativeprincipaladmin/adminiscreated:
shell% kadmin.local
kadmin.local: addprinc admin/[email protected]
No policy specified for "admin/[email protected]";
assigning "default".
Enter password for principal admin/[email protected]: <= Enter a password.
Re-enter password for principal admin/[email protected]: <= Type it again.
Principal "admin/[email protected]" created.
kadmin.local:
StarttheKerberosdaemonsontheprimaryKDC
Atthispoint,youarereadytostarttheKerberosKDC(krb5kdc)andadministrativedaemonsontheprimaryKDC.To
doso,type:
shell% krb5kdc
shell% kadmind
Eachserverdaemonwillforkandruninthebackground.
Note: Assuming you want these daemons to start up automatically at boot time, you can add them to the KDC’s
/etc/rcor/etc/inittabfile. Youneedtohaveastash_definitioninordertodothis.
Youcanverifythattheystartedproperlybycheckingfortheirstartupmessagesinthelogginglocationsyoudefined
inkrb5.conf (see[logging]). Forexample:
4 Chapter1. Installationguide
KerberosAdministrationGuide,Release1.20.1
shell% tail /var/log/krb5kdc.log
Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
shell% tail /var/log/kadmin.log
Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
Anyerrorsthedaemonsencounterwhilestartingwillalsobelistedintheloggingoutput.
As an additional verification, check if kinit(1) succeeds against the principals that you have created on the previous
step(AddadministratorstotheKerberosdatabase). Run:
shell% kinit admin/[email protected]
InstallthereplicaKDCs
YouarenowreadytostartconfiguringthereplicaKDCs.
Note: AssumingyouaresettingtheKDCsupsothatyoucaneasilyswitchtheprimaryKDCwithoneofthereplicas,
you should perform each of these steps on the primary KDC as well as the replica KDCs, unless these instructions
specifyotherwise.
CreatehostkeytabsforreplicaKDCs
EachKDCneedsahostkeyintheKerberosdatabase. Thesekeysareusedformutualauthenticationwhenpropa-
gatingthedatabasedumpfilefromtheprimaryKDCtothesecondaryKDCservers.
OntheprimaryKDC,connecttoadministrativeinterfaceandcreatethehostprincipalforeachoftheKDCs’host
services. Forexample, iftheprimaryKDCwerecalledkerberos.mit.edu, andyouhadareplicaKDCnamed
kerberos-1.mit.edu,youwouldtypethefollowing:
shell% kadmin
kadmin: addprinc -randkey host/kerberos.mit.edu
No policy specified for "host/[email protected]"; assigning "default"
Principal "host/[email protected]" created.
kadmin: addprinc -randkey host/kerberos-1.mit.edu
No policy specified for "host/[email protected]"; assigning "default"
Principal "host/[email protected]" created.
ItisnotstrictlynecessarytohavetheprimaryKDCserverintheKerberosdatabase,butitcanbehandyifyouwantto
beabletoswaptheprimaryKDCwithoneofthereplicas.
Next,extracthostrandomkeysforallparticipatingKDCsandstorethemineachhost’sdefaultkeytabfile. Ideally,
youshouldextracteachkeytablocallyonitsownKDC.Ifthisisnotfeasible,youshoulduseanencryptedsessionto
sendthemacrossthenetwork. ToextractakeytabdirectlyonareplicaKDCcalledkerberos-1.mit.edu, you
wouldexecutethefollowingcommand:
kadmin: ktadd host/kerberos-1.mit.edu
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type aes256-cts-hmac-sha384-192 added to keytab FILE:/etc/krb5.keytab.
1.1. Contents 5
KerberosAdministrationGuide,Release1.20.1
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.
IfyouareinsteadextractingakeytabforthereplicaKDCcalledkerberos-1.mit.eduontheprimaryKDC,you
shoulduseadedicatedtemporarykeytabfileforthatmachine’skeytab:
kadmin: ktadd -k /tmp/kerberos-1.keytab host/kerberos-1.mit.edu
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Thefile/tmp/kerberos-1.keytabcanthenbeinstalledas/etc/krb5.keytabonthehostkerberos-1.
mit.edu.
ConfigurereplicaKDCs
Databasepropagationcopiesthecontentsoftheprimary’sdatabase,butdoesnotpropagateconfigurationfiles,stash
files,orthekadm5ACLfile. Thefollowingfilesmustbecopiedbyhandtoeachreplica(seeMITKerberosdefaults
forthedefaultlocationsforthesefiles):
• krb5.conf
• kdc.conf
• kadm5.acl
• masterkeystashfile
Movethecopiedfilesintotheirappropriatedirectories,exactlyasontheprimaryKDC.kadm5.aclisonlyneededto
allowareplicatoswapwiththeprimaryKDC.
ThedatabaseispropagatedfromtheprimaryKDCtothereplicaKDCsviathekpropd daemon. Youmustexplicitly
specifytheprincipalswhichareallowedtoprovideKerberosdumpupdatesonthereplicamachinewithanewdatabase.
Createafilenamedkpropd.aclintheKDCstatedirectorycontainingthehostprincipalsforeachoftheKDCs:
host/[email protected]
host/[email protected]
Note: IfyouexpectthattheprimaryandreplicaKDCswillbeswitchedatsomepointoftime,listthehostprincipals
fromallparticipatingKDCserversinkpropd.aclfilesonalloftheKDCs. Otherwise,youonlyneedtolisttheprimary
KDC’shostprincipalinthekpropd.aclfilesofthereplicaKDCs.
Then,addthefollowinglineto/etc/inetd.confoneachKDC(adjustthepathtokpropd):
krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
Youalsoneedtoaddthefollowinglineto/etc/servicesoneachKDC,ifitisnotalreadypresent(assumingthat
thedefaultportisused):
krb5_prop 754/tcp # Kerberos replica propagation
Restartinetddaemon.
Alternatively,startkpropdasastand-alonedaemon. Thisisrequiredwhenincrementalpropagationisenabled.
6 Chapter1. Installationguide