Configuring and troubleshooting SPNEGO for the Notes plug-in
If you are using SPNEGO for authentication, review this guide for configuring SPNEGO and resolving configuration issues.
Considerations
When configuring the Connections plug-ins for Notes in a SPNEGO environment there are a few things to consider. This article is a reference and troubleshooting guide for this type of configuration. In order to configure the Connections plug-ins for Notes with SPNEGO, open the Notes Preferences page and navigate to the Connections section. On the Advanced Server settings dialog, chose OS Credential. By default the authentication url is empty. The username will automatically be retrieved from the operating system. In general we recommend that you try to access Connections from a browser to make sure that single-sign on works (there might be some configuration steps required). Working SSO from the browser is a requirement.
Check the following items if authentication fails.
Windows registry settings
By default, Windows does not allow access to the TGT session key. This registry key is automatically set in the IBM Expeditor installation script. After the Notes installation completes, verify that the registry key is there. If the key is missing, create the key manually and reboot your machine. Furthermore, please report this issue to IBM.- Win XP
- HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos
- Value Name: allowtgtsessionkey
- Value Type: REG_DWORD
- Value: 0x01
- Vista / Win7 / Win8
- HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
- Value Name: allowtgtsessionkey
- Value Type: REG_DWORD
- Value: 0x01
Win7 / Win8 SPNEGO limitation
There is a known issue that if an ActiveDirectory account is also added into a local administrator group on the client computer, Microsoft restricts such clients from getting the session key for tickets, even if you set the allowtgtsessionkey registry key to 1. For more detail, see this Microsoft support article.
Make sure initial url is protected by SPNEGO
URLs accessed from the Notes client need to be protected by SPNEGO. The server must include a specific header in the return code so that the client can trigger the appropriate authentication module. To verify the authentication header, make use of tools to capture the network traffic, such as Fiddler (see Troubleshooting section).
Notes
looks for the negotiate header of the server response: www-authenticate:
Negotiate
. If this header does not show up as part of the
initial server responses, SPNEGO will not work with Notes.
- Open the Notes Preferences page and navigate to the Connections section.
- On the Advanced Server settings dialog, chose OS Credential.
- Specify the authentication url like this: https://<hostname>/activities/service/authredirect.jsp.
Windows hosts file
- 9.162.127.31 <server.ibm.com>
- 9.161.69.15 <server.ibm.com>
256-bit encryption issue
java.security.InvalidKeyException:
Illegal key size
. There are 2 potential solutions to fix
or get around this issue: - Solution 1: Fix the encryption issue. Override the US_export_policy.jar and local_policy.jar in C:\Program Files (x86)\IBM\Lotus\Notes\jvm\lib\security with files you can download after you register at this IBM site.
- Solution 2: Disable the unsupported encryption type on the KDC.
The following Kerberos trace shows that aes256 is selected as encryption
type:
Refer to this document to disable an unsupported encryption type on the KDC: Windows Configurations for Kerberos Supported Encryption Type.[KRB_DBG_TGS] KrbTgsReq:main: >>>KrbTgsReq: using checksum type hmac-sha1-96-aes256 for session key type aes256-cts-hmac-sha1-96 [KRB_DBG_CRYP] HMacSha196AES256CksumType:main: calculateKeyedChecksum: usage=6
Check proxy settings
Incorrect proxy settings will also have an impact on connectivity. The Notes client picks up OS proxy settings which can be specified via Internet Explorer or Firefox. If proxies are specified, but you can't connect, try using the "No Proxies" setting for the browser.
Prerequisites
The minimum requirements for this configuration are Notes 8.5.3 and IBM Connections for Notes plug-in 4.0. For best results, use the latest Connections plug-ins for Notes, available on the Greenhouse Solutions catalog.
Configuration requires cross-realm authentication, but single-realm authentication is in use
If the SPNEGO authentication happens in a cross-realm environment, where the client machine is in one realm while the SPNEGO protected server is in another realm, the authentication can succeed only if a krb5.ini configuration file is used, which is not required for the single-realm case.
The easiest way to determine if cross-realm authentication is needed is to determine which domain the user logs into when logging into Windows and compare that to the domain of the server that requires SPNEGO authentication. The username is in the format of DOMAIN\user. The domain of the server is indicated by the URL http://mydomain.mycompany.com/resource. If the domain of the username matches the full domain of the server, then single-realm authentication will work. If the domains do not match, you must create and deploy a krb5.ini file for cross-realm authentication.
[libdefaults]
default_realm = CLIENT.IBM.COM
default_tkt_enctypes = des-cbc-md5 rc4-hmac
default_tgs_enctypes = des-cbc-md5 rc4-hmac
[realms]
SERVER.IBM.COM = {
kdc = serverkdc.ibm.com:88
default_domain = server.ibm.com
}
CLIENT.IBM.COM = {
kdc = clientkdc.ibm.com:88
default_domain = client.ibm.com
}
[domain_realm]
.server.ibm.com = SERVER.IBM.COM
.client.ibm.com = CLIENT.IBM.COM
[capaths]
SERVER.IBM.COM = {
CLIENT.IBM.COM = .
}
CLIENT.IBM.COM = {
SERVER.IBM.COM = .
}
For more information, see this article on setting up Kerberos security. Troubleshooting steps:
- Fiddler is a tool that captures network traffic between client
and server. It helps troubleshoot connectivity related issues by looking
at the server response. To download and install Fiddler:
- Download and install Fiddler 2 from this site: http://www.fiddlertool.com/Fiddler2/version.asp.
- Start the Fiddler application.
- Start Notes and try to connect to IBM Connections.
- Click *.saz when done. to save the Fiddler trace as
- Enable finer logging for the Notes client to more accurately diagnose
problems.
- Open the file C:\Program Files\IBM\Lotus\Notes\Data\workspace\.config\rcpinstall.properties
- Add the following lines to the end of the file:
com.ibm.rcp.accounts.level=FINEST com.ibm.rcp.net.http.level=FINEST com.ibm.rcp.security.spnego.level=FINEST -Dcom.ibm.security.jgss.debug=all -Dcom.ibm.security.krb5.Krb5Debug=all
- Save the file and restart the Notes client.
- If none of these troubleshooting steps help to get you connected,
examine the logs and traces. Note: When you collect logs, only perform basic steps. For example, start Notes, try to connect Activities, and so on. Otherwise, the log files will get too big.
- To share logs with IBM, zip up the logs folder and include the Fiddler trace.