If you have implemented SPNEGO within your Domino environment for Web Clients, and a user is prompted for a name and password or a user receives access denied messages when connecting to a Domino server configured for Windows single sign-on for web clients.

This article describes what to do in the following two problem scenarios:

Also, at the end of this article, there is a summary of the Debug commands thatyou require for the Domino server in order to troublehsoot SPNEGO.

 

Troubleshooting a user is challenged to provide a user name and password

Step 1

A web user enters a URL in a browser to connect to a Domino server participating in Windows single sign-on.

For example, the user enters the URL:          http://domino.d-pit.com/names.nsf

If the user is prompted to log into the server, start by investigating the following:

  • Firstly, verify that the client is in a supported configuration (if so, then Windows single sign-on cannot be expected to work).
  • Check the user's browser configuration to ensure that it is set up for Windows single sign-on to the Domino server.
  • Turn on debugging at the Domino server, by adding the following notes.ini setting:
DEBUG_HTTP_SERVER_SPNEGO=1
  • Repeat the step to bring up a browser and enter the Domino URL.
  • When the user is prompted to log in, check the server console log for errors.

A very common error is "Attempt by HTTP client to authenticate using Windows NTLM security is not supported." An NTLM security error indicates that Windows single sign-on is not functioning.

Assuming that the client has a supported configuration including a proper browser configuration, there may be a Windows Kerberos configuration error. If Domino error messages do not provide sufficient information to understand the problem, continue troubleshooting.

Step 2

If your Domino server is properly configured for Windows single sign-on, you should see evidence that the server is participating in the SPNEGO protocol.

You can investigate by doing the following:

  • Turn on advanced debugging at the Domino server,by using the following notes.ini setting:
DEBUG_HTTP_SERVER_SPNEGO = 4
  • Repeat the step to bring up a browser and enter the Domino URL.
  • When the user is prompted to log in, check the server console log. When contacting a Domino server that is properly configured for Windows single sign-on, a debug statement similar to this is in the console log:
Negotiate - properly configured HTTP client should send an Authorization: Negotiate header containing SPNEGO token when repeating the request /names.nsf
  • If there is no SPNEGO negotiate message, there may be a Domino server configuration problem.
  • Check that your server is properly configured for SSO in the applicable Internet site document (or in the Server document if Internet sites configurations are disabled).
  • If you suspect a Domino server configuration issue, it is a good idea to first verify that basic SSO is functional when you do not have Windows single sign-on enabled.
  • Once you verify that SSO is functional without Windows single sign-on enabled, you should check that Windows single sign-on is properly enabled in your SSO configuration document.

If there is a SPNEGO negotiate message, check the server console log for further error. If the error message does not provide sufficient information to understand the problem, continue troubleshooting.

Step 3

If your Domino server is properly configured for Windows single sign-on and is participating in the SPNEGO protocol, Domino should be attempting to authenticate the user by SPNEGO Kerberos.

You can investigate by doing the following:

  • Turn on advanced debugging at the Domino server, by adding the following notes.ini setting, if not already set:
DEBUG_HTTP_SERVER_SPNEGO=4 
  • Repeat the step to bring up a browser and enter the Domino URL.
  • When the user is prompted to log in, check the server console log. You will see log statements similar to these:
SPNEGO> Starting SPNEGO Negotiate - properly configured HTTP client should send an Authorization: Negotiate header containing SPNEGO token when repeating the request /names.nsf
SPNEGO> Security token format received is SPNEGO NegTokenInit
  • If there is no indication that Domino is receiving a SPNEGO NegTokenInit, this likely indicates a Windows Kerberos configuration problem.
  • If the console log shows that Domino is receiving a SPNEGO NegTokenInit, you can collect more detailed information about Windows Kerberos operations by changing the debug spnego notes.ini setting to 5 and then repeating the browser access of the Domino URL. The additional logging to the server console shows native Windows calls being made by Domino, and can shed light on whether a particular Windows call is causing a problem.
DEBUG_HTTP_SERVER_SPNEGO=5
  • If Domino error messages do not provide sufficient information to understand the problem, continue troubleshooting.
Step 4

If there is a likely Windows Kerberos configuration problem, first check the Windows Active Directory configuration

  • For your Active Directory domain, your Windows administrator must have set the domain functional level to Windows Server 2003 or higher. Backwards compatible modes for Windows Server 2003 cannot be used (e.g. Windows Server 2003 set to use Windows 2000 mixed mode).
  • To check the domain functional level, do the following:
  1. Open the Active Directory Users and computers utility.
  2. Right-click the domain, and then click Properties.
  3. The information is located on the General tab.
  • Computers participating in Windows single sign-on must have clocks synchronized since Kerberos operations are sensitive to clock skew. You should correct clock skew whenever possible. If necessary, the Windows administrator can perform the following steps to increase the tolerance for clock skew:
  1. Launch the Group Policy Management console. (For example, on Windows Server 2008, click Start > Run, type gpmc.msc and click OK.)
  2. In the console tree, find your domain and expand the tree.
  3. Expand the Group policy objects.
  4. Under the Group policy objects, click Default Domain policy (which then appears at the right). On the Default Domain policy Settings tab, click Security settings, Account policies/Kerberos policy.
  5. Double-click Maximum tolerance for computer clock synchronization to edit the setting.
Step 5

While optional, it is often very helpful to use additional troubleshooting tools to investigate problems with Kerberos and HTTP activity. Additional information will help to determine next steps for troubleshooting.

  • For understanding where additional tools can be helpful, note the initial steps to accomplish Windows single sign-on:
  1. the client browser extracts the DNS name contained in the Domino URL
  2. the client browser constructs a Service Principal Name (SPN) from the DNS name
  3. the client browser requests a Kerberos service ticket for the SPN from Active Directory
  4. the client browser sends the Kerberos service ticket to the Domino server.

You can investigate whether the browser acquires the Kerberos service ticket for Domino, and passes the ticket to Domino.

For example, the browser constructs the following SPN:

HTTP/This email address is being protected from spambots. You need JavaScript enabled to view it.

The DNS name is domino.d-pit.com
The Active Directory domain that the Domino server's machine belongs to is AD.D-PIT.COM.

To use tools to investigate

Download and install the Windows Server 2003 resource kit tools. You can use one of these tools:

Klist.exe: Kerberos List is a command-line tool that is used to view and delete Kerberos tickets granted to the current user's logon session.

Kerbtray.exe: Kerberos Tray is a graphical user interface tool that is used to view and delete (purge) Kerberos tickets granted to the current user's logon session. You can view and delete (purge) the Kerberos ticket cache by right-clicking on the Kerberos Tray tool icon located in the notification area of the desktop.

After downloading and installing, use the resource kit tool (Kerbtray) to purge the user's current list of Kerberos tickets.

Repeat the step to bring up a browser and enter the Domino URL.

Use the resource kit tool to view the user's Kerberos tickets.

If there is no Kerberos ticket for the expected Domino SPN, there is likely a Kerberos configuration issue to resolve, therefore continue troubleshooting.

If there is a Kerberos ticket for the expected Domino SPN, you can use a network protocol analyzer, such as Wireshark, to collect data from the live network and to verify that the HTTP negotiation includes the Kerberos ticket being sent by the client to the Domino server. A trace of HTTP activity for a functional Windows single sign-on would include HTTP commands similar to these

client: get /names.nsf
Domino server: 401 unauthorized (WWW-Authenticate : Negotiate)
client: get /names.nsf Authorization : Negotiate (Kerberos ticket)
Step 6

If the client browser did not acquire a Kerberos ticket to the Domino server, consider whether the user and the Domino server are located in the same Active Directory domain, or are in different domains. If the user and Domino server are located in separate Active Directory domains (are registered in different Active Directories), the problem may be in your cross-domain set up.

Review the list of requirements for Windows single sign-on to work across Active Directory domains. Verify that your setup adheres to all the requirements, particularly that the Windows trust between Active Directory domains is set up as a Forest trust.

Step 7

There may be a problem with the SPN in Active Directory which you should suspect if:

  • the client browser did not acquire a Kerberos ticket to the Domino server, or
  • the client browser did acquire a Kerberos ticket to the Domino server but a tool such as Wireshark reports a Kerberos error (for example, KRB5_KRB_AP_ERR_MODIFIED)

Your Active Directory administrator can investigate the Windows SPN in Active Directory using the Domino ldapsearch command line tool.

Use this syntax to research your SPN:

ldapsearch -h <domain controller name> -D <administrator distinguished name> -w <administrator password> -b <starting point for the search> "serviceprincipalname=<YourSPN>" dn  
For example, to research your SPN HTTP/ domino.d-pit.com :

ldapsearch -h domino.d-pit.com -D "cn=administrator,cn=users,dc=ad,dc=d-pit,dc=com" -w myAdminPwd -b "dc=ad,dc=d-pit,dc=com" "serviceprincipalname= HTTP/domino.d-pit.com " dn

Step 8

If required HOST SPNs have been mistakenly altered or deleted, you will not have a functioning Windows single sign-on.

Each computer in an Active Directory domain by default has HOST SPNs assigned. A HOST SPN is separate from the HTTP SPN needed for Windows single sign-on to your Domino server. However, when the Windows administrator is editing SPNs, problems will arise if the computer's HOST SPN is accidentally altered or deleted.

Normally you will see the HOST SPNs when you execute "setspn -l" for your server, for example: setspn -l domino

In this case you would see these HOST SPNs listed:

HOST/DOMINO
HOST/domino.d-pit.com

If your Windows administrator must reset the HOST SPNs for your server computer, the Windows administrator can use the "setspn -r", for example, setspn -r domino1.

Step 9

When the Kerberos authentication portion of Windows single sign-on has succeeded, you will see an indication in your Domino server console log, if SPNEGO debug logging is set to level 2 or higher.

  • Turn on informational debugging at the Domino server by adding the following notes.ini setting, if not already set to a higher level: DEBUG_HTTP_SERVER_SPNEGO = 2A Kerberos authentication success message is similar to this:
SPNEGO> User jbloggs@ AD.D-PIT.COM  authenticated by Kerberos service HTTP/This email address is being protected from spambots. You need JavaScript enabled to view it.

When Kerberos authentication succeeds, usually Windows single sign-on will also succeed. An error occurring after Kerberos authentication succeeds often causes an Access denied message to be displayed, rather than a prompt for the user to provide a user name and password. See next scenario for access denied scenarios.

Troubleshoot a user receives an Access Denied message

Step 1

A web user enters a URL in a browser to connect to a Domino server participating in Windows single sign-on. For example, the user enters the following URL

http://domino.d-pit.com/names.nsf

If the user is denied access, start by investigating the following:

If the user has a Mozilla / Firefox browser, the problem may be that the client is attempting to access a Domino server configured for Windows single sign-on while the client is located on the Internet, or not logged into the Active Directory domain.

To address this problem, provide your Mozilla/Firefox user with an alternate URL for accessing Domino in any scenario in which Windows single sign-on is not supported. The alternate URL should be set to prompt the user to login to Domino using a user name and password. Having an alternate URL may require setting up a Domino Internet site with a security configuration that disables Windows single sign-on.

If the user has a Mozilla / Firefox browser and can't access Domino in a setting where Windows single sign-on should be supported, check the user's browser configuration to ensure that it is set up for Windows single sign-on to the Domino server.

Regardless of browser type, check that the user's name (or group name) is listed on the Domino Access Control List and is granted access rights. If so, continue troubleshooting.

Step 2

You can follow steps described in the previous scenario (user is challenged to provide user name and password) in order to determine whether the Domino server has received a Kerberos service ticket for the user.

If the client browser does not acquire a Kerberos ticket and furthermore if there is no evidence of HTTP activity at the Domino server when the user browses to the Domino URL, there is likely a DNS issue for the client to resolve the Domino server DNS name.

Your network administrator should help you to diagnose the DNS problem.

Step 3

Check for an indication of Kerberos authentication in your Domino server console log, if logging is set to level 2 or higher.

Turn on informational debugging at the Domino server, by adding the following notes.ini setting, if not already set to a higher level:

DEBUG_HTTP_SERVER_SPNEGO=2

If desired, collect your debug output from the Domino server into a file, by adding the similar notes.ini setting: debug_outfile=c:\tmp\notes.log Repeat the step to bring up a browser and enter the Domino URL.

A Kerberos authentication success message in the server console log is similar to this:

SPNEGO> User jbloggs@ AD.D-PIT.COM  authenticated by Kerberos service HTTP/This email address is being protected from spambots. You need JavaScript enabled to view it.
Step 4

If the Kerberos authentication portion of Windows single sign-on has succeeded, the Domino server may be having difficulty determining the user's corresponding Domino name, and therefore cannot match the user to a person or group listed on the Domino Access Control List.

If name mapping has failed, you will see a Kerberos name in the session login debug message if you enable this server notes.ini variable:

WEBSESS_VERBOSE_TRACE=1

Repeat the step to bring up a browser and enter the Domino URL.

If Domino knows only the user's Kerberos name, a session login debug message may be similar to this:

SessionManager::LoginUser HTTP Sessions> Logging in user ( jbloggs@ AD.D-PIT.COM )
Step 5

If the Kerberos authentication portion of Windows single sign-on has succeeded, a failure to map the user's Kerberos name to a Domino name may be the result of consistency errors in the directory records associated with the user's Kerberos name. You can collect more detailed information about name mapping.

Set the following server notes.ini variables:

LOGLEVEL_NAME_MAPPING=1
WEBAUTH_VERBOSE_TRACE=1

Repeat the step to bring up a browser and enter the Domino URL.

Look in the server console log for name mapping errors.

Step 6

If the user's Kerberos name is being correctly mapped to a Domino name, you might still encounter other name mapping issues related to the user's LTPA token that represents the user after Kerberos authentication is complete. You can investigate name in the user's LTPA token, to assist your diagnosis of further name mapping issues.

Set the following server notes.ini variable:

DEBUG_SSO_TRACE_LEVEL=1

Repeat the step to bring up a browser and enter the Domino URL.

Look in the server console log for SSO API messages showing the user's SSO information.

 

Summary of Debug Commands / Parameters for SPNEGO

Disable

    set config DEBUG_SSO_TRACE_LEVEL=0
    set config DEBUG_HTTP_SERVER_SNPEGO=0
    set config WEBAUTH_VERBOSE_TRACE=0
    set config CONSOLE_LOG_ENABLED=0

Enable

    set config DEBUG_SSO_TRACE_LEVEL=2
    set config DEBUG_HTTP_SERVER_SNPEGO=4
    set config WEBAUTH_VERBOSE_TRACE=1
    set config CONSOLE_LOG_ENABLED=1  

 

CONSOLE_LOG_ENABLED      - Enables/Disabled logging of all console output to 
                           the IBM_Technical_Support\console.log file

DEBUG_SSO_TRACE_LEVEL    - Allows debugging of the SSO token - after a restart 
                           of the HTTP ("restart task http")

DEBUG_HTTP_SERVER_SPNEGO - Allows debugging of SPNEGO tokens - after a restart 
                           of the HTTP ("restart task http")

WEBAUTH_VERBOSE_TRACE    - Enable debugging for the authentication web-resolution 
                           mapping of names and DA to external LDAP - with immediate effect