Troubleshooting Kerberos setup and secure searches

Introduction

This document gives troubleshooting steps and workarounds for common issues while configuring and deploying the Google Search Appliance with Kerberos. The document assumes that the steps listed in Kerberos authentication setup have been followed.

This document contains several "yes/no" questions. Under each question is a set of directions on how to answer the question and a list of possible root causes and their workarounds. The checklist will work best if the steps are followed in order. If the steps are followed out of order, it is possible to misdiagnose the issue, or to skip potential root causes. Generally if the answer to one of these questions is "no" then there is a problem in the Kerberos transactions which is detailed step by step in the diagram of this Google Search Appliance/Kerberos documentation. The exceptions for this are for Serving Checklist sections step 6 and step 7 where if the answer is "yes" there is an issue.

There is also a list of common troubleshooting tools at the bottom of this document.

In the event this guide does not resolve the configuration or serving issues, and you open a support case with Google Cloud, you may have to provide the complete ktpass keytab setup commandline (both input and output including the password entered). Google Cloud will use the ktpass information to configure the java Kerberos client tool to assist with diagnostics.

Terminology

  • Secure search - A search query (URL) with the access=a or access=s parameter. Users generally perform a "secure search" by selecting the "public and secure content" radio button on the search page.
  • SPN - Service Principal Name. The name that defines a service in Kerberos.
  • KDC - Key Distribution Center. The repository that clients use to get Kerberos tickets for services.

Prerequsites

Please verify your content server is using Kerberos (and not just NTLM). To verify Kerberos is used, go directly to the URL of a secure page on the content server using one of the header capturing browser extensions listed in the troubleshooting tools section. The HTTP server should return the WWW-Authenticate: Negotiate HTTP header. If the HTTP server does not return the header, then it likely does not support Kerberos.

Your browser also must respond back to the content servers "Negotiate" challenge with a Kerberos token embedded in the response (the response should be in the form "Authorization: Negotiate YIIFRwYG...." and not "Authorization: Negotiate TRIM..."). You can also use the MIT Kerberos client to verify kerberos.

Also, consider the following hotfixes for a Windows 2003 KDC:

  1. Verify your content server supports Kerberos
  2. Verify your browser supports Kerberos

Troubleshooting Keytab Import Errors

This section applies to potential validation errors you may see when importing the keytab into the GSA admin console.

-1765328360 Preauthentication failed
The appliance does support preauthentication, but this error will occur if there are other issues that cause a preauthentication failure. You should disable preauthentication for the GSA user in Active Directory to get the underlying error message. See http://technet.microsoft.com/en-us/library/bb742516.aspx for information on disabling preauthentication.

-1765328353 Decrypt integrity check failed
This means that the encryption key stored in the keytab doesn't match the key stored in the KDC for the principal. You should first reset the GSAs account password in Active Directory and then run ktpass again and verify that the password is entered correctly. We have also found that deleting and recreating the GSA user in Active Directory and following the entire user setup and using ktpass registration command solves this problem.

-1765328378 Client not found in Kerberos database
This means that the principal specified in the keytab was either not found in Active Directory or it was found multiple times. The principal name used in the keytab must match the userPrincipalName entry in ActiveDirectory for only the GSA's account. You can verify the principal name in the keytab by running the klist command:

  1. You can find which AD user is associated with the userPrincipalName by using ldifde. The ldifde command shown below should return just one entry, for the GSA's account.
    ldifde -f c:\upn_out.txt -d "DC=yourdomain,DC=com" -l * -r "(userprincipalname=HTTP/gsa1.yourdomain.com@YOURDOMAIN.COM)" -p subtree
  2. If there are several KDCs (especially mixed Windows 2003/2008), there is the possibility the userprincipalname (UPN) created on the keytab does not match exactly across all KDCs. You can try to set the other KDC hostnames one at a time on the GSA Admin Console and try to reimport the keytab. You can also run the above ldifde command on each Active Directory server (the -s option on ldifde specifies the domain controller hostname).
  3. If you have additional issues importing the keytab, consider running the GSA Kerberos Validation utility (the utility will validate some settings on the keytab and Active Directory). You may want to outright delete the GSA's user account in Active Directory completely, recreate it per the instructions and run ktpass. Sometimes there maybe lingering SPN's or configurations/passwords which can cause the above issues while performing keytab validation. While running ktpass, please pay special attention to the case sensitivity of the SPN and the username and password used (the password must match exactly what was entered while creating the user).

Serving Troubleshooting Checklist

This section applies to serving-related issues after the keytab was imported and kerberos serving is enabled on the GSA.

kinit and kdestroy. These programs can be run from the command line and are included in the MIT Kerberos client. See the troubleshooting tools for details on using and installing these applications.

Here is an example of a user running klist, kinit and kdestroy from the command line where the SPN for the Google Search Appliance is HTTP/gsa.yourdomain.com. Notice that after the user runs kinit the ticket for the Google Search Appliance shows in the ticket cache. Also note that kdestroy is run to clear the ticket cache for future troubleshooting steps:

C:\Program Files\MIT\Kerberos\bin>klist 
Ticket cache: MSLSA: 
Default principal: user1@YOURDOMAIN.COM 
Valid starting		Expires 	  Service principal 
04/21/09 17:36:33 	04/22/09 03:36:33 krbtgt/YOURDOMAIN.COM@YOURDOMAIN.COM  
	renew until 04/28/09 17:36:33 

C:\Program Files\MIT\Kerberos\bin>kinit -S HTTP/gsa.yourdomain.com 
Password for user1@YOURDOMAIN.COM: 

C:\Program Files\MIT\Kerberos\bin>klist 
Ticket cache: MSLSA: 
Default principal: user1@YOURDOMAIN.COM 
Valid starting 		Expires 	  Service principal 
04/21/09 17:36:47 	04/22/09 03:36:47 krbtgt/YOURDOMAIN.COM@YOURDOMAIN.COM
	renew until 04/28/09 17:36:47 
04/21/09 17:36:47 	04/22/09 03:36:47 HTTP/gsa.yourdomain.com@YOURDOMAIN.COM  
	renew until 04/28/09 17:36:47  

C:\Program Files\MIT\Kerberos\bin>kdestroy

C:\Program Files\MIT\Kerberos\bin>klist
Ticket cache: MSLSA:
Default principal: user1@YOURDOMAIN.COM

Valid starting		Expires            Service principal
04/22/09 16:39:39	04/23/09 02:39:39  krbtgt/YOURDOMAIN.COM@YOURDOMAIN.COM
       renew until 04/29/09 16:39:39 

Note: This step assumes that when the user ran klist in step 2 the ticket for the Google Search Appliance was not in the list.

To verify if the user's computer is trying to obtain a ticket for the Google Search Appliance, you can run a packet capture between the KDC and the user's computer, while the user attempts a secure query. This can be done using a packet capturing application like Wireshark. See the troubleshooting tools section for links to download this utility.

When using Wireshark to run a packet capture, you should see the TGS-REQ packet sent to the Kerberos port (usually port 88) on the KDC server. The example below shows a Wireshark capture of a Kerberos transaction:

  1. Can the user's computer get a Kerberos ticket for the Google Search Appliance?
    • If the user's computer can not get a ticket for the Google Search Appliance or received the error "Server not found in Kerberos database" then there may be a duplicate SPN configured for the Google Search Appliance. This issue can be diagnosed by running ldifde. The duplicate spn troubleshooting document gives detailed info on how to diagnose this issue.
    • The configuration steps were not run properly to add the Google Search Appliance as a service to the domain. Make sure that the steps listed in the Enrolling the Search Appliance in the KDC Domain and Creating a Keytab File were run correctly.
  2. Does the Google Search Appliance send a WWW-Authenticate: Negotiate HTTP header to the user when the user does a secure search?

    To verify if the WWW-Authenticate: Negotiate HTTP header is sent to the user's browser, you can use one of the header capturing browser extensions listed in the troubleshooting tools section to examine the HTTP headers between the user's browser and the Google Search Appliance when the user does a secure search. See Step 1 in the Google Search Appliance authentication using Kerberos document to see what the headers should look like.

    If you do not see the WWW-Authenticate: Negotiate HTTP header these are some likely causes:

  3. Does the user's computer get a Kerberos ticket for the Google Search Appliance during a secure search?

    Verify you can use the application called klist to see your kerberos tickets. See an example below where klist is run from the command line on a Windows machine. Assuming that the canonical hostname for the Google Search Appliance is gsa.yourdomain.com, the ticket for the Google Search Appliance is the last one in the list.

    C:\Program Files\MIT\Kerberos\bin>klist
    Ticket cache: MSLSA:
    Default principal: user1@YOURDOMAIN.COM
    Valid starting          Expires           Service principal
    04/21/09 17:36:47       04/22/09 03:36:47 krbtgt/YOURDOMAIN.COM@YOURDOMAIN.COM
            renew until 04/28/09 17:36:47
    04/21/09 17:36:47    04/22/09 03:36:47 HTTP/gsa.yourdomain.com@YOURDOMAIN.COM
            renew until 04/28/09 17:36:47 
      

    If the ticket for the Google Search Appliance is in the list, you can skip to step 5. Otherwise continue to the next step.

  4. Does the user's computer request a ticket for the Google Search Appliance during a secure search?

    Note: There may be more than one KDC in your environment, so you should be careful when filtering by IP on your packet capture.

    If you open the Kerberos request packet (the packet marked "TGS-REQ") you can drill down into the Kerberos details. The request must be for the SPN of the Google Search Appliance. Here is an example of the Kerberos request packet assuming that the SPN for the Google Search Appliance is HTTP/gsa.yourdomain.com:

    If the user's computer does not send a Kerberos request for the Google Search Appliance, this is one possible cause:

    • The user's browser likely does not support Kerberos or does not trust the Google Search Appliance. Verify that you have followed the directions for configuring web browsers for Kerberos authentication. If you are using Internet Explorer 7 it is possible that the Security settings that you see in your browser do not reflect the Security Settings that the browser is using. If this is the case you will see this message: "Some settings are managed by your system administrator" in the Internet Options->Security tab. See this kb for more information.
  5. Does the user's browser send the Authorization: Negotiate HTTP header to the Google Search Appliance during a secure search?

    Note: This step assumes that when the user ran klist in step 3 the ticket for the Google Search Appliance was in the list.

    To verify if the user's browser sends this header to the Google Search Appliance, you can use one of the header capturing browser extensions listed in the troubleshooting tools section to examine the HTTP headers between the user's browser and the Google Search Appliance. See step 3 in the Google Search Appliance authentication using Kerberos document to see an example of the header that the user should send. If the user does not send the Authorization: Negotiate HTTP header then this is the likely cause:

    • The user is using Internet Explorer, and the browser is running into an issue with the size of the Kerberos ticket. See this Microsoft KB article for more info on resolving this issue.
  6. Is the user prompted for credentials during a secure search?

    If the user is prompted for credentials when the user does a secure search then these are the likely causes (some of these issues can be identified by running the GSA Kerberos Validation Utility):

    • The user that was setup for the Google Search Appliance was not trusted for delegation. To verify, make sure that step 6 in the Enrolling the Search Appliance in the KDC Domain and Creating a Keytab File was followed.
    • The keytab that the Google Search Appliance uses has a lower key version number (KVNO) than what is recorded in the KDC. This can happen if the keytab was created on a Windows 2000 Server and the user requests a service from a Windows 2003 Server. See this Microsoft KB for more details.

      This can also happen if an old version of the keytab is used. To verify if there is a KVNO mismatch, first run klist on the keytab. This will show the KVNO in keytab. Here is an example. The KVNO is in bold.

      C:\Program Files\MIT\Kerberos\bin>klist -e -k c:\workspace\KerberosTest\gsa1.keytab
      
      Keytab name: FILE:c:\workspace\KerberosTest\gsa1.keytab
      KVNO Principal
      ---- --------------------------------------------------------------------------
      14 HTTP/gsa1.yourdomain.com@YOURDOMAIN.COM (DES cbc mode with RSA-MD5) 
      

      To find the version number that the KDC is using, run the ldifde command as shown below on the KDC.
      ldifde -f c:\spn_out.txt -d "DC=yourdomain,DC=com" -l *,msDS-KeyVersionNumber -r "(serviceprincipalname=HTTP/gsa1*)" -p subtree
      
      dn: CN=gsa1,CN=Users,DC=yourdomain,DC=com
      changetype: add
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: user
      cn: gsa1
      ...
      sAMAccountName: gsa1
      ...
      userPrincipalName: HTTP/gsa1.yourdomain.com@YOURDOMAIN.COM
      ...
      servicePrincipalName: HTTP/gsa1.yourdomain.com
      ....
      msDS-KeyVersionNumber: 15  
      

      In the case above the user would be unable to authenticate to the Google Search Appliance, since the keytab is at version 14 and the KDC is at version 15. To workaround this issue the keytab would need to be recreated by running the ktpass command again.

    • There are multiple accounts in Active Directory with the same SPN as the GSA. If you run the ldifde command above for the exact SPN of the GSA (not wildcarded like HTTP/gsa*) and see more than one account returned in the output, you will have to remove that SPN entry in all accounts, completely delete the GSAs user account in AD and recreate (then run ktpass over again).
    • The keytab was created with an incorrect password. To workaround this issue first reset the GSA's account password in AD and then recreate the keytab.
    • The account for the Google Search Appliance does not have the DES encryption type set. To verify, make sure that step 3 in Enrolling the Search Appliance in the KDC Domain and Creating a Keytab File was followed.
    • Clock Skew between the KDC,GSA and Windows workstation. Kerberos tickets have timestamps/validity periods (usually 5mins) so if the KDC or workstation time is off by a certain amount the GSA will reject the ticket. Verify the timesettings on the GSA (NTP server), the KDCs or work station.
    • A DNS alias for the Google Search Appliance was used when the ktpass command was run. Make sure to use the canonical DNS name for the Google Search Appliance when running the ktpass command. To verify if the hostname is a DNS alias run nslookup on the hostname of the Google Search Appliance. If you are using an alias the output will look similar to this:
      C:\Users\gsa_user>nslookup gsacname.yourdomain.com Name: gsa.yourdomain.com Address: 10.1.1.1 Aliases: gsacname.yourdomain.com
      In the above case gsa.yourdomain.com should be used instead of gsacname.yourdomain.com when running the ktpass command, since gsacname.yourdomain.com is a DNS alias.
  7. Does the user's browser receive a blank page or a "Page could not be displayed" message during a secure search?

    This could be due to Google Search Appliance issue 1665783 or 1737434 where the appliance cannot handle Kerberos tickets larger than 8k or 16k. These issues are in all versions of software prior to 5.2.0.G32. 1665783 was fixed in 5.2.0.G32. There is a patch available for 1737434 on 5.2.0.G32.

  8. Does the Google Search Appliance return Kerberos protected search results during a secure search?

    If the Google Search Appliance does not return Kerberos protected search results these are the likely causes:

    • The content server does not support Kerberos. To verify, go directly to the URL of the result that you expect to be returned using one of the header capturing browser extensions listed in the troubleshooting tools section. The HTTP server should return the WWW-Authenticate: Negotiate HTTP header. If the HTTP server does not return the header, then it likely does not support Kerberos. Here is a link describing how to enable Kerberos on an IIS server. Here is a link on how to enable Kerberos on a Sharepoint Server.
    • The user does not have permission to view the URL. To verify, the user can put the URL directly into his or her browser to see if he or she can access it.
    • The Google Search Appliance is configured to crawl the Kerberos protected content with a DNS alias. To verify, run nslookup on the content server's hostname. See step 1 for more details on running nslookup and finding an alias. If an alias is returned then the Google Search Appliance was configured to crawl a content server with its alias. To workaround this issue, an SPN for the alias needs to be added to the KDC. See Scenario 2 in this kb article for detailed information on how to do this.
    • If there are several KDCs (especially mixed Windows 2003/2008), there is the possibility the serviceprincipalname (SPN) for your content server may not exist exactly across all KDCs. You can try to set the other KDC hostnames one at a time on the GSA Admin Console and attempt a new secure search after deleting all cookies on your browser between each test. In addition, try to run the ldifde and search for (serviceprincipalname=HTTP/SPN_of_your_content_server*) on each KDC.
    • You will need to disable then re-enable Kerberos on the GSA if you have changed the hostname of your KDC. In order to disable Kerberos, uncheck "Enable Kerberos support" at the bottom of the Serving > Universal Login Auth Mechanisms > Kerberos Based page in Admin Console, then click Save. To re-enable Kerberos, check "Enable Kerberos support" and click Save. Feature Request 5148814, once implemented, will eliminate the need for this.

Troubleshooting tools

  • GSA Kerberos Validation Utility- A VBScript html-application (.hta) that validates DNS settings, keytab, AD entry and user settings. Requires the keytab and installing the MIT Kerberos client (link provided below).
  • GSA Kerberos Test Client- A Java application that mimics a web browser searching a GSA using Kerberos. Allows an administrator to analyze the Kerberos tickets.
  • Wireshark- This is a packet capturing tool.
  • Live Http Headers- This is an extension for the Firefox browser that shows the HTTP headers between the browser and server.
  • ieHttpHeaders- This is an extension for Internet Explorer browser that shows the HTTP headers between the browser and server.
  • klist- This is a command line utility that shows the Kerberos tickets for a user. This utility is included in the MIT distribution of Kerberos. Download the Kerberos package and install to use this utility. Also the Windows Server Resource Kits include the Windows klist version, but it does not have the ability to read keytabs which is why it is recommended to install the MIT version.
  • kinit- This is a command line utility that allows a user to request a Kerberos tickets for a particular service. This utility is included in the MIT distribution of Kerberos.Download the Kerberos package and install the binary to use this utility.
  • kdestroy- This is a command line that deletes the Kerberos tickets for a user. This utility is included in the MIT distribution of Kerberos. Download the Kerberos package and install to use this utility.
  • nslookup - This is a command line utility that can query the records on a DNS server. This utility is included by default on most Windows machines.
  • ldifde - A command line utility that is used to extract information form Active Directory. This tool can be used to view Kerberos service information on a KDC. This tool comes standard on Windows 2000 and Windows 2003 Server.
Was this helpful?
How can we improve it?