Kerberos has a number of annoying dependencies that makes it difficult to work with.
Fortunately, Jespa has it's own Kerberos implementation that completely eliminates some confusing and fickle problems with the conventional toolchains. Jespa does not use krb5.conf or keytab files, there are no dependencies on other packages, no dependencies on the host and no cryptic Windows commands to run.
The Jespa HssSetup program can quickly and easily create the required Windows Computer account and, at any time, validate that it is working.
Jespa can log every field and flag of every Kerberos message, decrypting elements wherever possible, every server or client referral, SRV lookup and CLDAP ping.
Jespa makes setting up and debugging Kerberos relatively easy.
But there are issues, mostly to do with the circumstances required for clients to initiate Kerberos, that must be understood and considered.
This document describes the possible failure modes of Kerberos and how to resolve them.
See also: Kerberos authentication troubleshooting guidance
The following is a summary of requirements and corresponding failures, in protocol sequence order, that can occur when a browser client attempts to access a Kerberos protected website:
The user must be logged into the client workstation or device with their AD DS credentials. Otherwise, the browser will display the network credentials dialog.
Resolution: Silent SSO is not possible if the user is not logged into the workstation or device with their AD DS credentials. If valid AD DS credentials are supplied into the browser network credentials dialog, the user should be successfully authenticated by acquiring and submitting a Kerberos ticket (or by falling back to NTLM if necessary) just as they would if Silent SSO were performed.
The target URL must be in the "Local intranet" zone settings of the client workstation or device. Otherwise, the browser will display the network credentials dialog.
Resolution: Add the target URL to the "Local intranet" zone settings by searching for "inetcpl.cpl" to open the Internet Options dialog. Select Security > Local intranet > Sites and add the target URL like:
https://hrt.sebank.corp
For production sites, this setting is more easily applied using a Global Policy Object (GPO).
The browser host must have network access to:
Otherwise, the client will fallback to NTLM.
Resolution: If issue 1 is satisfied, this implies that the client device has the required network access. Laptops and mobile devices roaming out of the AD DS network may continue to do Silent SSO with a cached ticket or NTLM.
The time on the client and the selected KDC must be synced within 5 minutes. Otherwise, the client will fallback to NTLM.
Resolution: Ensure that the time is set correctly on the client and KDCs. Take care to consider the timezone and AM/PM.
The target SPN must be set on the HSS Computer account. Otherwise, the client will fallback to NTLM (unless issue is 7b).
If the hostname is a non-DNS name like "localhost" or an IP address, the client will fallback to NTLM.
Resolution: If HssSetup is used to create the HSS Computer account, the SPN should be set correctly and this issue will not occur. Otherwise, run the v) Validate option in HssSetup to detect and, if necessary, fix any SPN issues.
If the particular user being authenticated is in many groups, the server may generate a "Request header too large" error.
This error will be recorded in the application server error log and not the Jespa log file.
Resolution: If the Authorization header is too large for the application server, it will be necessary to increase the maximum header size.
See also: Increasing Request Header Size for Users in Many Groups
There are multiple Kerberos failure modes that cause the client browser to display the network credential dialog and trigger the HSS to log the following exception:
java.security.GeneralSecurityException: HMAC failure
at jespa.krb5.Crypto.decrypt(Crypto.java:235)
The HMAC failure error means that Jespa failed to decrypt the ticket submitted by the client.
The possible causes of HMAC failure are:
If the Computer account password is changed (such as by using HssSetup with the P) Password change option), the HSS will fail to decrypt any tickets issued to clients before the change.
Resolution: Instruct users to lock and unlock their workstations. This will purge the offending tickets.
For Remote Desktop connections, simply disconnect / reconnect.
Or run the following command in a cmd console on the workstation or device:
>klist purge
Preferably, the Computer account password should only be changed during maintenance hours.
Users may not encounter this failure until the HSS authentication state in the HTTP session expires or is removed by logging out and they may not encounter the issue at all if their Kerberos ticket expires first.
If the target SPN is set on an account different from the HSS Computer account, Jespa will fail to decrypt the ticket because it will be encrypted with the Kerberos base key of the wrong account.
Resolution: If HssSetup is used to create the HSS Computer account, the SPN should be set correctly and this issue should never occur.
Regardless, run the v) Validate option in HssSetup to detect and, if necessary, fix any SPN issues.
Then, if necessary, instruct users to purge any stale tickets (such as by locking and unlocking their workstations).
If the Computer account password is simply incorrect, Jespa will fail to decrypt Kerberos tickets.
Resolution: If HssSetup is used to create the HSS Computer account, this issue should never occur because HssSetup validates the password immediately after setting it.
Regardless, run the v) Validate option in HssSetup to determine if the password is correct and, if necessary, reset it with the R) Password reset option.
Then, if necessary, instruct users to purge any stale tickets (such as by locking and unlocking their workstations).
See also: The HssSetup Console Menu Program
Note that issues 1-5 occur at the client before it submits an HTTP request to the server. Meaning server logs will record nothing.