KerbMinder is a tool for Mac OS X that keeps a logged-in user’s Kerberos ticket current by attempting to renew or refresh it automatically any time a user logs in or the network state changes. It only presents a UI if it needs the user to supply a password.
The password can be saved to the keychain so all subsequent renewals can use it. Should the saved password get out of sync with the domain — e.g. after the user changes their password — the keychain will automatically remove the old saved password and the user will be prompted to enter one.
KerbMinder is designed to provide a seamless, single sign-on (SSO) experience in in environments where
- users have network-authenticated mobile accounts and often work off of corporate networks via VPN.
- users would like the benefits of Kerberos SSO without having to bind the computer to a directory service.
That’s right! With KerbMinder, you can do away with binding Macs to Active Directory. If KerbMinder detects that you are not bound to AD, the first time it runs it will prompt for a username and domain.
If you want to skip the details, download the installer now.
The largest share of gratitude goes to Purdue Pharma L.P. for the following reasons:
- inspiring and funding the development of KerbMinder.
- providing a clear project scope.
- testing the software through its stages of development.
- agreeing to the project’s release as open source.
Portions of KerbMinder were inspired by code written by these fine humans (links point to the inspiring code, where possible):
- Francois ‘ftiff’ Levaux-Tiffreau, who is personally responsible for all the changes introduced in v1.3.
- Joe Chilcote
- Graham Gilbert
- Gary Larizza
- Per Olofsson
I’d also like to thank
- Allister Banks for pointing out an effective dig command to test for domain reachability.
- Tim Sutton for telling me about Pashua.
- Mac OS X 10.8.5 or newer, including El Capitan (10.11.x)
- Python 2.7 (part of OS)
- crankd (PyMacAdmin, included as a submodule)
- Pashua (included)
How It Works
KerbMinder has a few components that operate in tandem.
KerbMinder logs its activity to the system log. You can open up Console.app and filter for “kerbminder” to see what it’s up to.
Part of the PyMacAdmin project, crankd is an always-on LaunchDaemon configured to look for network changes. Specifically, it monitors the System Configuration framework’s
State:/Network/Global/IPv4 subkey, which blips any time a network interface gains or loses an IPv4 address. When a change is detected, it calls the following script.
This script’s main purpose is to determine if any ethernet interface (e.g. en0, en1, etc.) has an ip address. When called, it first sleeps for 30 seconds, allowing sufficient time for a wi-fi or VPN connection to be established. Then (with the help of
networksetup -listnetworkserviceorder) it gets a list of ethernet interfaces in service priority order and goes down that list looking for the first one with an ip address.
If an interface with an IP address is found, it touches a trigger file (
/Library/Application Support/crankd/kmfiles/trigger) that the following script watches. This handoff in duties is necessary because this script runs as a LaunchDaemon in the root context, but Kerberos ticket renewals must be done in the user’s context.
This script runs both when the user logs in, and as a triggered LaunchAgent. It refreshes or renews Kerberos tickets based on their discovered status. Before attempting a renewal, it first checks for domain reachability.
If a ticket is refreshable and non-expired, it is refreshed silently. If a ticket is expired or nor present, the script checks if the password has been saved in the keychain. If a keychain entry exists, the saved password is used to retrieve a ticket. If an entry does not exist, the user is prompted for their password (using a secure entry dialog box) and allowed two tries to reduce the chances of account lockout. Two incorrect password attempts results in a warning dialog. If an incorrect attempt results in a locked account, the user is informed that their account is locked.
If the password is correct the ticket is renewed and, if the user has checked the Remember this password in my keychain option, that password is saved to the keychain so future renewals can occur without user interaction. If the password becomes out of sync with the domain — e.g. after the domain password has been changed — then the stored keychain item is purged and the user is prompted for their password.
Pashua.py and Pashua.app
Pashua is a tool for creating native Aqua dialog windows. KerbMinder uses it to display a password prompt window with a checkbox to optionally save the password.
The simple way
Download a KerbMinder release package and run it. No reboot or logout is necessary, but admin privileges are required.
The manual way
First, clone or download & unzip the KerbMinder repo to your computer, and cd into the repo from the terminal. (All subsequent paths that do not start with a slash are relative to the root of this repo.) Next, install crankd by running the installer in the pymacadmin directory using root privileges:
Copy files from the repo to their correct locations:
|sudo cp -R Library/Application\ Support/crankd /Library/Application\ Support/|
|sudo cp Library/LaunchDaemons/com.googlecode.pymacadmin.crankd.plist /Library/LaunchDaemons/|
|sudo cp Library/LaunchAgents/org.pmbuko.kerbminder.plist /Library/LaunchAgents/|
|sudo cp Library/Preferences/com.googlecode.pymacadmin.crankd.plist /Library/Preferences/|
Download Pashua.app, mount the disk image, copy Pashua.app to the correct location, and remove the quarantine attribute:
|sudo cp -Rp /Volumes/Pashua/Pashua.app /Library/Application\ Support/crankd/|
|sudo xattr -d com.apple.quarantine /Library/Application\ Support/crankd/Pashua.app|
Set the correct permissions:
|sudo chown -R root:admin /Library/Application\ Support/crankd|
|sudo chmod 777 /Library/Application\ Support/crankd/kmfiles|
|sudo chmod 755 /Library/Application\ Support/crankd/*.py|
|sudo chown -R root:wheel /Library/LaunchDaemons/com.googlecode.pymacadmin.crankd.plist|
|sudo chmod 644 /Library/LaunchDaemons/com.googlecode.pymacadmin.crankd.plist|
|sudo chown -R root:wheel /Library/LaunchAgents/org.pmbuko.kerbminder.plist|
|sudo chmod 644 /Library/LaunchAgents/org.pmbuko.kerbminder.plist|
|sudo chown -R root:wheel /Library/Preferences/com.googlecode.pymacadmin.crankd.plist|
|sudo chmod 644 /Library/Preferences/com.googlecode.pymacadmin.crankd.plist|
Finally, start the LaunchDaemon and LaunchAgent. (Note the lack of sudo on the second command):
|sudo launchctl load /Library/LaunchDaemons/com.googlecode.pymacadmin.crankd.plist|
|launchctl load /Library/LaunchAgents/org.pmbuko.kerbminder.plist|
The latest release of my ADPassMon software lets users enable/disable KerbMinder via a menu item.