Debugging Kerberos is like Hades

We've all been there. You start debugging kerberos, and it starts getting warmer in the room. Ok, maybe not all of us. Debugging Kerberos certainly can feel an awful lot like Hades, though.

The Analogy

Debugging Kerberos is like Hades

Hades is the Greek God of the underworld or sometimes a reference for the place of the dead, generally. I promise, this analogy is not completely out of left field.

Kerberos is a computer protocal developed by MIT and used in many enterprise settings for authentication and authorization. However, it gets its name from Cerberus - the guard dog of Hades. As a result, feeling close to Hades when you are close to Kerberos is reasonable at some level.

Although there are many aspects of Hades we could highlight for the purposes of our analogy, we will focus on a few: heat, torment, eternal, inexplicable, aimless, and generally terrible.

The High Points

Why is debugging Kerberos so awful? A couple of reasons below. Particularly, reasons that can encourage us how not to make software:

• No documentation - Ok there is documentation, but much of it is just too theoretical to be useful. Further, much of programming in the 21st century is search-engine-foo. Unfortunately, searching Kerberos issues generally leads to Microsoft documentation from Windows XP. Despair usually ensues. If you have been there, I promise you are not alone.
• No logging - The next best problem for software: no logging. Kerberos has a knack for giving useless error messages or error messages that need to be run through a universal translation engine (which does not exist). Good luck finding out what a Generic preauthentication failure is.
  • TIP: Set the environment variable KRB5_TRACE=/tmp/somefile.log when debugging a Kerberos client. The client-spec sends client debug logs to that location!
• Little direction - This goes alongside the previous items. If you have theoretical docs and useless logging, the usual sources of direction and "next steps" are lost. Internet tutorials and a general sense for what I want to accomplish are about the only places I have found direction for Kerberos issues. Keep at it! Perseverance usually wins out in the end.
  • TIP: As with most debugging, try to simplify your case as much as possible first. Then slowly add pieces until you get to a working state.
• Cryptic configuration - To properly configure Kerberos, you typically need to master a bunch of unusual terminology (realm, kdc, ticket, cache, keytab), wade through a myriad of brackets, and pay particular attention to case. Not to mention the importance of tricky UDP networking rules and the directionless failure you get if you misstep. Tread carefully! A slew of confounding error messages are watching your every move.
• Little tolerance for humans - What is the difference between "analogous.dev" and "ANALOGOUS.DEV"? As far as your browser is concerned, nothing. As far as humans are generally concerned, maybe one reads more like shouting? As far as Kerberos is concerned, Realm not local to KDC while getting initial credentials. We humans need help doing software. Please help us, Kerberos. Make your logs better.
  • TIP: Yes, case matters in domain names to Kerberos. It feels like flailing, but in some cases it can actually help!

Put all of this together, and what do you get? It may not be Hades, but it is pretty close to eternal torment.

The Breakdown

Now that I have completed that rant, Kerberos has some really nice things about it. It is also worth noting that it has achieved success by being a pretty brilliant piece of software.

• Pass-through authentication to backend services
• Granular access controls
• Minimal password usage
• Integration into Windows
• Integration with security keys
• Quickly expiring sessions

This makes the protocol highly desirable for security, particularly in the enterprise. However, with the internet age upon us, browser-based paradigms like OAuth2 and JWT (JSON web tokens) are shaping up to replace Kerberos for most of these purposes.

In many large enterprises and backend systems (like databases), Kerberos still rules the day.

Closing

Although Kerberos is a necessary fixture in some peoples' lives (like mine) and nonexistent in others, I am hopeful that it can teach us important lessons about what makes good software and the interesting interplay of obligation versus enjoyment.

At very least, community, empathy, and a bit of laughter can get us through our struggles with this beast.