An icon image (description text to the right)

Using the Kerberos Application on Mac OS X

This web page has instructions for the Kerberos application for Mac OS X.

These instructions reflect the Kerberos application on Mac OS X 10.3. While the Kerberos application is similar on previous OS X releases, not all features described below may be available or located in the same place.

MIT users should consult the Kerberos for Macintosh at MIT documentation, which reflects the currently supported version.

Table of contents

If you're not familiar with Kerberos authentication and terms such as Kerberos tickets, go to What Is Kerberos? to learn the concepts and terms.

Opening the Kerberos application

To open the Kerberos application:

If you have installed the Mac OS X Kerberos Extras, go to the Applications folder, open the Utilities folder, and open the Kerberos icon.

Otherwise, you will need to navigate to the /System/Library/CoreServices directory (use the Go To Folder... item in the Finder's Go menu), and open the Kerberos icon from there. (You may want to install the Kerberos Extras or make your own alias in a more convenient location.)

Result: The Kerberos application window is displayed.

Kerberos application dialog box illustration

Obtaining Kerberos tickets

  1. Click on the New button, choose Get Tickets... from Tickets menu, or press Command-N.

    Result: The Authenticate to Kerberos dialog appears:

    Authenticate to Kerberos dialog illustration

  2. Type your Kerberos username in the name box. (This is not necessarily the same as your Mac OS X username.)

    If you want to log in using a principal that contains an instance (if you are unfamiliar with this term, don't worry about it), enter a slash after your username and then type the instance, e.g. "username/instance". (This is the v5 style of specifying instances.)

    By default the Kerberos Login dialog box displays the name of the person who last used it to get tickets. If you have never gotten tickets it will display your username.

  3. Enter your password into the password text field.

  4. If you need to change realms, click once in the Realm field/popup list and choose the desired realm. If the desired realm is not present in the list, you can also type it into the Realm field. This will only work if you have a Kerberos configuration file (edu.mit.Kerberos) that already includes the realm, or your site is set up for automatic configuration of Kerberos realms (ie: DNS SRV records). If neither of these are true, you should consult your system administrator for a proper Kerberos configuration file. You can also edit what realms are in the configuration file by using the Edit Realms feature of the Kerberos application.

  5. Click on OK.

    Result: If authentication is successful, a ticket entry appears in the Kerberos application window:

    Single user logged in illustration

    An entry for your new Kerberos tickets appears in the Ticket Cache list, and the tickets in this new cache appear in the Tickets list.

    By default, Kerberos tickets are valid for 10 hours. You can shorten the duration for which tickets are valid at the time you log in. Refer to Specifying ticket lifetime when logging in for instructions on how to do this. You can also change the default ticket lifetime. Refer to Changing Preferences to find out how to do this.

    If you get a Kerberos error, it may be for any of the following reasons:

    • You've entered either your Kerberos username or password incorrectly. Try again, making sure that the CAPS LOCK key is not turned on.
    • You may not have authorization to log into the realm specified. If you're authorized to log into a different realm, refer to Using the realms editor to make another realm available, and then choose it from the realms popup list when logging in.
    • The realm you specified does not have an entry in your configuration file and/or your site does not have auto/DNS configuration for that realm. Contact your site administrator.
    • There is a problem with your authorization for the realm you're using. Contact your site administrator.


    The Kerberos application allows more than one Kerberos user to log into the same Macintosh (note this is not the same as having two Mac OS X users logged in at the same time). An additional person can log in by completing steps 1 - 4 again.

    Each additional person who has logged in receives an entry in the ticket list:

    Multiple users logged in illustration

    The active Kerberos user, i.e., the username whose tickets are used for authentication appears in the Active User box. This username is also underlined in the ticket list.

    To change active users, follow the procedure in the next section, Changing active users.

    If you log out of Mac OS X, all tickets for all Kerberos users will be destroyed.

    Once the duration of your tickets has ended, your tickets will be listed as "expired":

    Tickets expired illustration

    Specifying ticket lifetime when logging in



    If you want to change the length of time that your tickets are valid upon logging in, you can do it through the Authenticate to Kerberos dialog box. To do this,

    1. Click on the New button, choose Get Tickets from Tickets menu, or press Command-N.

      Result: The Authenticate to Kerberos dialog box appears.

    2. Click on the gear menu in the lower left corner of the dialog and select the Ticket Options... menu item.

      Result: A ticket options sheet appears over the Authenticate to Kerberos dialog:

      Change tickets lifetime illustration

    3. Place the mouse pointer on the Get tickets that are valid for: slider and drag it to the desired time indicated above the slider.

    4. Click on the OK button to save your changes and return to the Autheticate to Kerberos dialog.

    5. Enter your Kerberos username (if it's not already displayed) and password, then click on the OK button.

      Result:If your login is successful, you've obtained tickets that are valid for the lifetime you specified.


    The next time you log in, the lifetime of the tickets you obtain will be the same as the time you specified during the previous login, unless you repeat this procedure or force a constant default lifetime (see Changing preferences for instructions on how to do this).
  6. You can also change other Kerberos ticket options from the Authenticate to Kerberos dialog. See Changing preferences for more information about each option.

About the ticket list

Below the Kerberos window's toolbar are the Ticket Cache list and the Tickets list. The ticket cache list shows all the principals that are currently authenticated in the current Mac OS X user's session. The tickets list shows the tickets in the selected ticket cache.

Each principal has a set of Kerberos tickets belonging to it. When you log in with Kerberos, you get a ticket-granting ticket which then allows you to get other tickets from other applications (also called services). Then for each application you run that requires Kerberos authentication, you get a service ticket.

Each line in the Ticket Cache list has three elements:

Instead of a time, you may see either "expired" or "not valid" in the Time Remaining column. "Expired" means that your tickets have no time remaining and so are no longer valid; "not valid" means they are no longer valid for some other reason, usually because your Mac's IP address has changed since you obtained the tickets. In either case, you need to renew your tickets. Kerberos for Macintosh will also prompt you automatically to renew if you try to use a service requiring Kerberos tickets.

If you want to see details of tickets associated with each principal, select that principal in the Ticket Cache list. Tickets for that list will appear in the Tickets list:

Expanded ticket list illustration

In the Tickets list, you will see a list of the tickets (credentials) belonging to that principal. If the principal is authenticated for both versions of Kerberos, the tickets are grouped by version underneath a subheading for each version (see picture above).

You can display even more detailed information about each ticket using the Ticket Info window. See the Displaying ticket information section.

Changing active users

The current, active user specifies which Kerberos principal will be used for authentication when you work with an application that requires Kerberos authentication. If more than one Kerberos user is logged in, you may want to change the active user before using such an application.

Use one of the following techniques to change the active user:

Result: The new active user is displayed in the toolbar Active User menu and also appears bold in the ticket list.

Changing active user illustration

Destroying tickets

To destroy tickets, select an entry in the Ticket Cache list then click on the Destroy button, or choose Destroy Tickets from the Tickets menu.

Result: The ticket entry is removed from the ticket list. If other Kerberos users are logged in, their usernames remain in the ticket list and their tickets are valid for the remaining time indicated.

Renewing tickets

If your tickets have expired, or you want to extend the lifetime of existing tickets, you may want to renew your tickets.

As of Mac OS X 10.3 and later, Kerberos for Macintosh supports the "renewable" property for tickets. If your site allows tickets to have this property, you can renew tickets up for a set amount of time without re-entering your password, as long as your current tickets are still valid (that is, haven't expired). By default, Kerberos for Macintosh tries to get tickets with the "renewable" property; you can change this in the Authenticate to Kerberos dialog options or in the Kerberos application preferences.

By default, the Kerberos application will automatically attempt to renew your tickets if you leave it running (you can close the main window for convenience). Once half your ticket's lifetime has expired, if it has the "renewable" property, the Kerberos application will automatically issue a renew request for it. It will keep doing this up until the renewable time limit. You can control this behavior by checking or unchecking the "Auto-renew renewable tickets" checkbox in the Kerberos application preferences.

You can see if a ticket is renewable, and for how long, by using the ticket information window. See Displaying ticket information below.

If your tickets are expired, or you choose not to use the auto-renew feature and want to renew your tickets before they expire, or your tickets do not support the "renewable" property, use the Renew Tickets command.

  1. Select a Kerberos principal in in the Ticket Cache list.

    Result: The Renew button is activated.

     

  2. Click on the Renew button, choose Renew Tickets from the Tickets menu, or press Command-R.

    Result: Either your tickets are renewed to their full lifetime (if your ticket had the "renewable" property and were not expired), or the Kerberos Login dialog box is displayed (if your tickets didn't have the "renewable" property or they were expired).

     

  3. If the Authenticate to Kerberos dialog is displayed, enter your password.

     

  4. If you want to change the lifetime of the tickets you're obtaining, see Specifying ticket lifetime when logging in for instructions.

     

  5. Click on OK.

    Result: The tickets' lifetime is extended either to the lifetime you specified when logging in or to the maximum duration set under Preferences... (the default is 10 hours). To change the default tickets' lifetime, see Changing Preferences. If you are very close to the maximum renewable lifetime, your tickets will only be good for the time remaining until the end of the renewable lifetime, which may be shorter than your requested lifetime.

Displaying ticket information

If you are interested in more information about your Kerberos tickets, the Kerberos application can display detailed information about each ticket in the Tickets list by using the Get Ticket Info command. To display detailed ticket information:

  1. Select a Kerberos principal in the Ticket Cache list.

     

  2. Select a ticket entry in the Tickets list. (Note that you can only get info about individual ticket items - the non-bold lines. You may have to twiddle down the arrow next to the main entry to see the individual ticket items.)

     

  3. Either click on the Info button in the toolbar, choose Get Ticket Information from the Tickets menu, or press Command-I.

    Result: The Ticket Info window appears:

      The Ticket Info window

    At the top of the ticket info window is the principal who owns the ticket, the service that the ticket was obtained for, the Kerberos version of the ticket and the ticket's status. The rest of the information is divided into several panes for easier reading:

    • Times - The exact time the ticket was issued, the start and end time that the ticket is valid for, and when the ticket is renewable until (if applicable), all in local time. Also a status field to tell you if the ticket is valid, expired, or not valid for another reason.
    • Flags (for v5 tickets only) - The properties, such as forwardable and renewable, of the ticket.
    • IP Addresses - The IP addresses for which the ticket is valid. v5 tickets may be valid for multiple or no addresses, so you may see more than one or none listed, although typically you will only see none or one listed. v4 tickets can have no more and no less than one address, so you will only see one listed.
    • Encryption - For v5 tickets, lists both the session key and service principal key encryption types of the ticket. For v4 tickets, lists the string to key type of the ticket

     

  4. When you are done looking at the ticket information, you can close the Ticket Info window using its close box.

You can have more than one ticket info window open at once. If the tickets are destroyed, the ticket info window will close.

Changing your password

You can change your Kerberos password by using the Change Password... command.

To change your password,

  1. Click on the boldfaced username line in the ticket list to select it.

    Result: The Change Password... button is activated:

     

  2. Click on the Change Password... button or choose Change Password... from the Tickets menu.

    Result: The Kerberos Change Password dialog box appears with the name of the user selected previously at the top:

    Change password dialog box illustration

     

  3. Enter the password you're using now in the "Enter your old password" box.

     

  4. Click once in the "Enter your new password" box, or press the <tab> key, and type the new password.

     

  5. Click once in the "Enter your new password again" box, or press the <tab> key, and type the new password a second time, exactly as you typed in the previous step.

     

  6. Click on OK.

    Result: Either you will receive a confirmation that your password has been changed, if you entered either your old password incorrectly or the entries for the new password don't match exactly, you'll get an error. You may also receive an error from the Kerberos server if you try to choose an insecure password.

    This password stays in effect until you change it again using either the Kerberos application or the equivalent procedure on another Kerberos client on another platform.

Dock icon features

The Kerberos application's dock icon has several features to help you quickly determine the status of the active user's tickets and to manage your Kerberos tickets.

Graphical ticket status & time remaining indicator

In the dock icon, the color of the key in the dock icon changes to indicate the status of the active user's tickets. Below the key is a display of the time remaining in the active user's tickets in the form hours:minutes (the time remaining display can be turned off in the Preferences dialog). The possible states are:

Kerberos Dock Icon with valid tickets

Gold badge: The active user has valid tickets.
Kerberos Dock Icon with tickets which are about to expire

Red badge: The active user's tickets are near expiration (less than 5 minutes lifetime remain).
Kerberos Dock Icon with no valid tickets

No badge: The active user's tickets have expired, or no tickets are in the cache.

Kerberos Dock Icon when Kerberos is not running

No "running" triangle: The Kerberos application is not running.

You can close the ticket list window without quitting the Kerberos application, so that you can still have the dock icon showing without cluttering your screen with a window you don't always need open.

Kerberos Dock Menu

If you control-click (or click and hold down for a few seconds) on the Kerberos application's dock icon while the application is running, the Kerberos dock menu will appear:

Kerberos Dock Icon menu

(If the only option you see in the Kerberos Dock Menu is "Show in Finder", the Kerberos application is not running.)

The Dock Menu items perform the following functions:

Get Tickets... - Displays the Kerberos Login dialog, allowing you to get tickets for a new user (or new tickets for an existing user).

Destroy Tickets - Destroys the active user's tickets (the active user is indicated by a checkmark next to the user's principal in the user list). If no users are authenticated, this option will be disabled.

Renew Tickets... - Renews the active user's tickets (the active user is indicated by a checkmark next to the user's principal in the user list). If the tickets do not have the renewable property, will display the Kerberos Login dialog, otherwise, renewal will happen automatically. If no users are authenticated, this option will be disabled.

Validate Tickets - Validates the active user's tickets (the active user is indicated by a checkmark next to the user's principal in the user list). This is only necessary if you have post-dated tickets (ie: tickets whose start time was in the future when they were acquired). This option is not commonly used.

Change Password... - Brings up the change password dialog for the active user (the active user is indicated by a checkmark next to the user's principal in the user list).

Available tickets (variable text) - These are the principals of the currently authenticated users. The active user is marked with a checkmark. You can change the active user by choosing another principal from the menu.

Keep In Dock/Remove from Dock - Changes whether or not the Kerberos application icon appears in the dock when the application is not running.

Show In Finder - Opens the folder containing the Kerberos application in the Finder.

Hide - Hides, but does not quit, the Kerberos application.

Quit - Quits the Kerberos application.

Using the realms editor

The Kerberos application realms editor can be used to set which Kerberos realms appear in the Authenticate to Kerberos dialog's realms popup list and to edit the system Kerberos configuration. For more information about the system Kerberos configuration, see the Kerberos Preferences documentation.

Most users should only need to use the Realms Editor to add realms to the Authenticate to Kerberos dialog realms popup list. Most sites are either configured for automatic Kerberos configuration via DNS SRV records or provide an installer to place a site-specific Kerberos configuration file on your machine.

To bring up the Kerberos realms editor, choose Edit Realms... from the Edit menu or press Command-E.

Result: The Edit Realms dialog box appears (see illustrations below).

The edit realms dialog is divided into two halves. The left half of the dialog contains the Realm list, + and - buttons to add and remove realms, and a Make Default button to change the library default realm.

Note that the library default realm is not the same realm as the one that appears by default in the Authenticate to Kerberos dialog realms popup list. The library default realm is a system-wide setting which determines which realm the popup menu and other tools default to using. If a user has already set a preference for the popup menu, this setting will not override it.

The right half of the dialog is a tab view which reflects the realm configuration for the realm which has been selected in the realms list. These are divided into three groups: settings, servers and domains.

Settings:

Edit favorite realms dialog box illustration

Servers:

Edit favorite realms dialog box illustration

Clicking on the servers tab displays the servers for the selected realm. If your realm uses DNS SRV records for automatic configuration, you can leave this list blank. Otherwise you can use the + and - buttons to add and remove servers.

Each server has 4 fields associated with it:


Domains:

Edit favorite realms dialog box illustration

Clicking on the domains tab displays the DNS domains which this realm serves. These domains are used to determine what realm is used when contacting a given server. For example, in the above list the domain "mit.edu" uses the realm "ATHENA.MIT.EDU". So when contacting a server "myserver.mit.edu", Kerberos would try to use the realm "ATHENA.MIT.EDU".

If your realm has the same name as the domain (ie: domain "example.com" and realm "EXAMPLE.COM"), you can leave this list blank. Otherwise you can use the + and - buttons to add and remove domains.

If you have more than one domain listed for a given realm, you can choose which one of them is the default domain with the Make Default button. This domain is used when translating v4 principals to v5 principals. v4 principals do not have fully qualified server host names and v5 ones do (ie: imap/mailserver@ATHENA.MIT.EDU becomes imap/mailserver.mit.edu@ATHENA.MIT.EDU), so Kerberos needs to know the primary domain for the realm. If no default domain is specified, Kerberos will assume that the realm and domain name are the same.

Note that you can only list a domain under one realm since each domain must map to a single realm. If you attempt to list the same domain for two realms, the realms editor will give you an error.


At the bottom of the dialog is the Configure additional realms automatically using DNS checkbox. This setting determines whether or not DNS is used to automatically determine Kerberos server information for a realm (ie: the information in the servers tab). Normally you want this setting on, however if you are in on a slow network, unchecking this checkbox and specifying the servers in the servers tab may improve Kerberos performance.

When you have finished adding and/or removing realms, click on OK.

Result:If you've added one or more realms, they are now available from the Authenticate to Kerberos dialog box. If you've removed any realms, they are no longer available for use unless you add them again later on.

To find out how to change the default realm in the Authenticate to Kerberos dialog, refer to Changing preferences.


Changing preferences

You can make certain customizations to the Kerberos application by using the Preferences... command. Many of these customizations also affect the Authenticate to Kerberos dialog anytime another application brings it up.

  1. From the Kerberos (application) menu, choose Preferences...

    Result:The Preferences dialog box appears (see illustrations below).

  2. The Kerberos preferences are divided into several groups, with a tab for each group. Click on the tab for the preferences you want to modify:
    • Behavior - preferences that control the way the Kerberos application displays information and other behaviors
    • Default Principal - preferences that control the default username and realm options for the Authenticate to Kerberos dialog
    • Default Ticket Options - preferences that control the default ticket options for the Authenticate to Kerberos dialog
    • Time Ranges - preferences that control the minimum, maximum, and default settings of the ticket lifetime and renewable lifetime sliders in the Authenticate to Kerberos dialog


  3. Make changes to any of the following:

    Behavior:

    Kerberos preferenes dialog with the behavior tab selected
    • Auto-renew renewable tickets (default=on): When this option is checked, Kerberos.app will automatically renew any tickets that have the "renewable" property once they reach half or less of their valid lifetime. You must leave the Kerberos application running for this option to be useful.
    • Display time remaining in dock icon (default=on): When this option is checked, the time remaining in the active user's tickets will be displayed in the Kerberos application's dock icon.
    • Remember ticket list window position and size (default=on): When this option is checked, the Kerberos application will remember the dimensions and location of ticket list window.
    • After the Kerberos application is launched (default="Always open ticket list window"): This option controls whether the Kerberos application displays the ticket list window when the application is launched. You may not want the window displayed if you primarily use the dock icon and menu.
      • Always open ticket list window: The ticket list window will always be displayed when the Kerberos application is launched, regardless of its state when the application was last quit.
      • Never open ticket list window: The ticket list window will never be displayed when the Kerberos application is launched, regardless of its state when the application was last quit.
      • Remember if the ticket list window was last open: The ticket list window will be displayed when the Kerberos application is launched if it was open when the Kerberos application was last quit, and not displayed if it was closed when the application was last quit.

    Default Principal:

    Kerberos preferenes dialog with the default principal tab selected
    • Remember name and realm from last Kerberos login/Always default to this name and realm (default = "Remember name and realm from last Kerberos login"): This radio button lets you chose whether to remember the name and realm in the Authenticate to Kerberos dialog box after each time you get tickets, or to always use the name and realm specified in the Name and Realm text fields in this tab.

      If you never want the name and realm filled in, just choose "Always default to this name and realm" and make the Name and Realm fields empty.

      Note: Changes you make to these options only take effect the next time you obtain tickets. Any tickets that you currently have maintain the options and lifetimes that were set when you obtained them.

    Default Ticket Options:

    Kerberos preferenes dialog with the default ticket options tab selected
    • Remember ticket options from last Kerberos login/Use these ticket options (default = "Remember ticket options from last login"): This radio button lets you choose whether to retain the ticket properies and lifetime options in the Authenticate to Kerberos dialog box after each time you log in, or to always use the options specified in this tab each time.

      Note: Changes you make to these options only take effect the next time you obtain tickets. Any tickets that you currently have maintain the options and lifetimes that were set when you obtained them.
      • Lifetime (default=10 hours) (only applies if "Use these ticket options" is selected): To change the duration for which tickets will be valid, place the mouse pointer on the Lifetime slider and drag it to desired time indicated above the slider.
      • Get tickets that can be forwarded to other machines (default=on) (only applies if "Use these ticket options" is selected): Tickets that you've obtained on your machine are valid on another machine to which you are connecting. (We recommend that you leave this option turned on.) Only applies to Kerberos v5 tickets.
      • Get tickets without IP addresses (NAT mode) (default=on) (only applies if "Use these ticket options" is selected): Request tickets that will not contain any IP addresses. This feature is required to use many Kerberos v5 services behind a NAT. Only applies to Kerberos v5 tickets.
      • Get tickets that can be renewed for (default = on) (only applies if "Use these ticket options" is selected): Request tickets with the "renewable" property, so that they can be renewed without re-entering your password as long as your existing tickets are valid. Tickets can be renewed in this way for the length of time specified by the slider (which defaults to 7 days). Your site may not allow you to get tickets with the renewable property, or may not allow them to be renewable for as long as you request.


    Time Ranges:

    Kerberos preferenes dialog with the time ranges tab selected
    • Using the edit fields in this preferences panel, you can set the minimum and maximum range of the ticket lifetime and renewable lifetime sliders displayed by the Kerberos Login dialog. These settings only control the minimum and maximum lifetimes your Macintosh requests from the Kerberos server; the Kerberos server may not allow tickets longer or shorter than certain lifetimes, or not allow tickets longer or shorter than certain renewable lifetimes. Defaults are 10 minutes minimum ticket lifetime, 10 hours maximum ticket lifetime, 10 minutes miniumt renewable lifetime, 7 days maximum renewable lifetime.


  4. Click on OK to save the changes you've made.