Information for System Administrators

Technical Information for System Administrators

How to set up a Kerberized PennKey service

Follow these steps so set up a Kerberized PennKey service.

  1. Acquire a User PennKey for yourself.
  2. Request a KAdmin PennKey which will allow you to create Service PennKeys for the domain name of the host on which you are installing.
  3. Create Service PennKeys for each service. For Unix-flavored servers this means using 'kadmin' and the Service PennKey must have the server DNS name in lowercase. For Windows domains this means creating a Cross Domain PennKey and the Microsoft domain must be in uppercase.
  4. Get Kerberos working. For Unix-flavored servers this means installing kerberos server software. For Windows domains this means configuring the system to authenticate to Penn's MIT KDC.
  5. Kerberize all relevant software requiring authentication, or determine other alternatives to clear-text password transmission, such as ssh or SSL/TLS.

KAdmin How-To

Non-User PennKeys include service principals, cross-realm trust principals, and Kerberos administration (KAdmin) principals. KAdmin principals are tied to third-level domains (e.g. "isc.upenn.edu"), and control the creation and management of non-user PennKeys within that domain.

Once a school or center has a KAdmin for their domain, that principal is used to create and manage other KAdmin principals for the same domain. If your school or center already has a Kerberos administrator, you should ask that person for help. If you don't know who your Kerberos administrator is, contact ISC Client Care.

If your domain does not already have a KAdmin, you will need to obtain approval from your school or center's IT Director. Then complete a request form, and coordinate the request via ISC Client Care. Please note, if the request sent via email, you must encrypt it using a trusted PGP key.

If your school or center does not currently have a KAdmin contact or if a new Domain has been created you will need to obtain approval from your school or center's IT Director. Then complete a request form, and coordinate the request via ISC Client Care. Please note, if the request is sent via email, you must encrypt it using a trusted PGP key.

KAdmin overview

Terms used
In MIT Kerberos documentation, principal is the term used for the userid belonging to a person or a program for using Kerberos. Penn uses PennKey as a friendlier synonym. They are interchangeable in the context of getting Kerberos to work.

For Kerberos use, each user must have a User PennKey, but each kerberized host must also have a Service Principal PennKey or a Cross-Realm Trust PennKey for each service (telnet, ftp, etc.).

Generic terms appear which you would need to change appropriately for your particular situation.

  • service: Service string as called for by the application, including host, pop, imap, krbtgt
  • dept.upenn.edu or theorg.upenn.edu: A DNS domain name for your organization.
  • machine: The specific host DNS domain name, which with the dept.upenn.edu makes the host's fully-qualified domain name (FQDN).
  • pennname: An individual's unique alphanumeric identifier assigned within the PennNames database and used in many Penn systems, including PennKey

KAdmin PennKey capabilities
KAdmin Pennkeys allow creating, changing and deleting other KAdmin PennKeys and Service Principal PennKeys within the DNS domain following the "kadmin-" string. Case is observed, and KAdmin and Service Principal PennKeys must list the DNS domain in lowercase whereas Cross-Realm Trust PennKeys must list the MS domain in uppercase. One KAdmin PennKey may even delete the KAdmin PennKey which created it.

In the examples below, the realm for Penn, @UPENN.EDU, is not included since it is the default if krb5.conf is set up right.

So the example KAdmin PennKey,

person11/kadmin-theorg.upenn.edu

may issue, change or delete all of these:

person54/kadmin-theorg.upenn.edu person55/kadmin-server1.theorg.upenn.edu person56/kadmin-www.suborg.theorg.upenn.edu ftp/theorg.upenn.edu host/server1.theorg.upenn.edu mynewservice/www.suborg.theorg.upenn.edu

but not these:

person54/kadmin-otherorg.upenn.edu
person55
person56/kadmin-www.upenn.edu
person57/kadmin-THEORG.UPENN.EDU
ftp/ourotherDNSdomain.upenn.edu

Schools' and Centers' role
During Kerberos initial introduction, ISC issued KAdmin PennKeys. However, after an authorized individual in a school or center receives a KAdmin PennKey for its DNS domains, ISC plans not to issue additional KAdmin or Service Principal PennKeys for that school or center. Instead, the school or center will control the issuance of its KAdmin, Service and Cross-Realm Trust PennKeys. A list of KAdmin PennKey issuers is available. Systems administrators and Local Support Providers (LSPs) may contact  ISC Client Care.

ISC continues to issue User PennKeys via the applications found in Register Your PennKey.

You'll need to understand the following privileges and assign them carefully. Carelessness with a KAdmin PennKey could undermine the security of systems in your school or center.

In particular, please be aware of the following points:

  1. Only give such privileges to people whom you consider to be very trustworthy.
  2. Make sure to properly authenticate people before issuing KAdmin PennKeys. Accepting requests and issuing keys in email is unacceptable unless requests are properly authenticated (using PGP for example) and passwords properly encrypted (again, PGP).
  3. You should keep records as you issue KAdmin PennKeys to help in removing privileges or revoking keys in the future.

Models for completing common tasks
Here are examples of commands that you may use as models when issuing, managing and administering PennKeys. For more details, see the man page for kadmin on your system or visit MIT's documentation website.

Login to the "kadmin" program and environment with your KAdmin PennKey

kadmin -p pennname/kadmin-dept.upenn.edu

You will be prompted for your password here. You will see the ">" prompt indicating you're in kadmin.

Exit from the "kadmin" program and environment

exit

You will return to your system prompt.

Create another KAdmin PennKey

addprinc +requires_preauth pennname/kadmin-lowercasednsofhost.dept.upenn.edu

Create a Service Principal PennKey

addprinc -randkey +requires_preauth +allow_svr service/machine.dept.upenn.edu

See "Export a Service Principal PennKey" below.

Export a Service Principal PennKey to a "keytab" file with a randomized password (only on Unix-like systems). Note: First see "Create a Service Principal PennKey" above.

ktadd service/machine.dept.upenn.edu

That command saves the Service Principal PennKey with the default name /etc/krb5.keytab. To save it somewhere else (for instance, to allow using kadmin on your local, non-shared computer and thereafter transfer the keytab file securely to the multi-user computer on which the service runs), use the following:

ktadd -k /path/here/alt.keytab service/machine.dept.upenn.edu

Create a Cross-Realm Trust PennKey with a known password

addprinc +allow_svr krbtgt/MSDOMAIN.DEPT.UPENN.EDU

Note: Window 2000 domain must be in caps. You must use a KAdmin PennKey which likewise uses caps. For instance, logging in with this KAdmin PennKey would allow creating the previous Cross-Realm Trust PennKey:pennname/kadmin-DEPT.UPENN.EDU.

Enter password for principal "krbtgt/MSDOMAIN.DEPT.UPENN.EDU":
Re-enter password for principal "krbtgt/MSDOMAIN.DEPT.UPENN.EDU":

Password for "krbtgt/MSDOMAIN.DEPT.UPENN.EDU@UPENN.EDU" changed.

Note: Be sure to make it a strong password.

Reset password on KAdmin PennKey to a selected password for someone who has forgotten their password:

cpw pennname/kadmin-machine.dept.upenn.edu

Enter password for principal "pennname/kadmin-machine.dept.upenn.edu":
Re-enter password for principal "pennname/kadmin-machine.dept.upenn.edu":

Password for "pennname/kadmin-machine.dept.upenn.edu@UPENN.EDU" changed.

Note: Be sure to make it a strong password.

For Cross-Realm Trust PennKeys, you'll instead need to delete the PennKey and recreate with a different password. Otherwise, the internal "kvno" kerberos value will no longer be 1, currently a Microsoft requirement.

Reset a password for a User or KAdmin PennKey when you know the password

Unix: "kpasswd" program (see man page)
Mac: The ticket manager
Win32: Leash32

Note: Though kadmin can be used for this, the extra complexity comes with no benefits.

For Cross-Realm Trust PennKeys, you'll instead need to delete the PennKey and recreate with a different password. Otherwise, the internal "kvno" kerberos value will no longer be 1, currently a Microsoft requirement.

Delete another KAdmin, Service or Cross-Realm Trust PennKey

delete_principal pennname/kadmin-dept.upenn.edu
Are you sure you want to delete the principal "pennname/kadmin-dept.upenn.edu"? (yes/no): yes

It is possible but unwise to delete the KAdmin PennKey with which you logged in to the kadmin program.

Requesting KAdmin principal

If there is a need to assign a kadmin who will have authority to administer a campus domain, a request would go to ISC Client Care who should gather and verify the appropriate information. Once that process is complete an email should be sent by ISC Client Care to the ISC Kerberos support team in the following format:

Kerberos Admin,

Please create PennKey(s) as specified below.  Thanks.  

Please deliver  the password(s) using:    
[   ] PGP-encrypted mail to the already-authenticated owner  
[   ] Sealed envelope for pickup and in-person authentication  
[   ] Secure Share    

(An 'X' in a box below includes that PennKey type in this request.)    
[   ] User PennKey  
[   ] KAdmin PennKey(s), numbering:       

Required info  
-------------  
PennName    :   
E-Mail      :   
Full Name   :       

Following for KAdmin PennKeys only  
----------------------------------  
KAdmin PennKey      :   
Email address       :       (of the person authorizing the creation of the KAdmin PennKey)  
Position/department :      (of the authorizing person)      

Provider Desk PGP Key ID  :   
PGP Public Key follows.    

NOTE: Requestors who prefer to receive credentials via a PGP 
encrypted email must provider their PGP public key upon  submitting the request to ISC Client Care.

Windows cross-realm trust

What follows are step-by-step instructions on how to create a Cross-Domain Realm PennKey and password in Penn's KDC using the kadmin program.

You first need a KAdmin PennKey and password, which allows you to manage PennKeys for the Microsoft realm or the Penn DNS domain name named in the PennKey. To acquire a KAdmin PennKey, see the central IT contact for your school or center who issues KAdmin PennKeys.

Getting started with KAdmin

Make sure you have:

  • A KAdmin PennKey and password.
  • Downloaded the Windows version of the kadmin installer and execute kadmsetup to initiate the installation.

Create a Cross-Realm Trust PennKey

(1) Run kadmin. Use your new KAdmin PennKey and password to authenticate to the kadmin session. At the kadmin prompt type:

addprinc +allow_svr krbtgt/MSDomainName@UPENN.EDU

Example: "addprinc +allow_svr krbtgt/ISC-KERBTEST.UPENN.EDU@UPENN.EDU"

(2) You'll be prompted for a password please select a secure password. Please remember this password, you will need to use it later. Also note that the password is subject to our the password-checking rules.

While the principal is being created, you should see something similar to:

"No policy specified for krbtgt/ISC-KERBTEST.UPENN.EDU@UPENN.EDU
assigning default. Principal created."

(3) At the kadm.exe prompt type: exit.