Applications that use Enterprise Single Sign-On cannot log on to remote applications if the ENTSSO service cannot communicate with the SSO credential database for 5 or more minutes (904702)


The information in this article applies to:

  • Microsoft Host Integration Server 2004
Important This article contains information about how to modify the registry. Make sure to back up the registry before you modify it. Make sure that you know how to restore the registry if a problem occurs. For more information about how to back up, restore, and modify the registry, click the following article number to view the article in the Microsoft Knowledge Base:

256986 Description of the Microsoft Windows registry

SUMMARY

Applications that use Enterprise Single Sign-On (ENTSSO) to log on to remote applications cannot log on if the ENTSSO service cannot communicate with the SSO credential database for 5 or more minutes. Host Integration Server 2004 applications receive logon failures as soon as the ENTSSO service cannot connect to the SSO credential database. These applications include Transaction Integrator applications, 3270 applications, and Advanced Program-to-Program Communication (APPC) applications.

Based on customer feedback, we have updated the ENTSSO service to provide more flexibility in how the service handles SSO credential database outages. A software update is available that adds configurable features to the ENTSSO service. You can use these features to change the behavior that you experience when the service cannot communicate with the SSO credential database.

INTRODUCTION

The ENTSSO service polls the SSO credential database every 30 seconds to make sure that any changes that you have made to the ENTSSO system are obtained in a timely manner.

The ENTSSO service is designed to take certain actions when the service cannot communicate with the SSO credential database. The Enterprise Single Sign-On administrators cannot modify the actions that the service takes under these conditions.

The ENTSSO service takes the following actions when the service cannot communicate with the SSO credential database during the service's typical polling process.

Static offline SSO credential database detection

The following event is logged every 30 seconds when one of the ENTSSO polls cannot contact the SSO credential database:Event ID: 10514
Source: ENTSSO
Description: An error occurred when trying to access the SSO database.
Function: GetGlobalInfo
File: infocache.cpp:1132
General network error. Check your network documentation.
SQL Error code: 0x0000000B
Error code: 0xC0002A21, An error occurred while attempting to access the SSO database. If the SSO credential database remains unavailable, the ENTSSO service will send a maximum of 10 polls before logging the following events. These events indicate that the SSO credential database is offline. Event ID: 10515
Source: ENTSSO
Description: Lost contact with the SSO database. Check that the SSO database is available.

Event ID: 10590
Source: ENTSSO
Description: Enterprise Single Sign-On is going offline The maximum time that the SSO credential database can be unavailable before the ENTSSO service indicates that the database is offline is approximately 5 minutes. This time represents 10 polls at a 30-second poll interval. The ENTSSO service does not offer a mechanism to increase this retry window.

The ENTSSO service continues to poll the SSO credential database after the 5 minute outage occurs. As soon as the ENTSSO service detects that the SSO credential database is available, the following event it logged and typical ENTSSO operations resume:Event ID: 10591
Source: ENTSSO
Description: Enterprise Single Sign-On is back online.

The credential cache is cleared

The credential cache is cleared when one of the regular ENTSSO polls cannot communicate with the SSO credential database. Because the ENTSSO polls are performed every 30 seconds, the credential cache is cleared within 30 seconds of the time that the SSO credential database becomes unavailable. When this behavior occurs, all applications that are configured to use ENTSSO for Single Sign-On (SSO) cannot log on to the external applications that they are configured to access.

You cannot change this behavior in the ENTSSO service.

MORE INFORMATION

Warning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall your operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.

Software update information

A supported feature that modifies the product's default behavior is now available from Microsoft, but it is only intended to modify the behavior that this article describes. Apply it only to systems that specifically require it. This feature may receive additional testing. Therefore, if the system is not severely affected by the lack of this feature, we recommend that you wait for the next Host Integration Server 2004 service pack that contains this feature.

To obtain this feature immediately, contact Microsoft Product Support Services. For a complete list of Microsoft Product Support Services telephone numbers and information about support costs, visit the following Microsoft Web site:

http://support.microsoft.com/contactus/?ws=support

File information

The English version of this software update has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time tool in Control Panel.
   Date         Time   Version    Size     File name
   ------------------------------------------------------------
   26-Jul-2005  00:18  4.0.125.0   71,168  Infocache.dll
   26-Jul-2005  00:18  4.0.125.0   81,920  Ssolookupserver.dll
   26-Jul-2005  00:18  4.0.125.0   60,928  Ssomappingserver.dll
   26-Jul-2005  00:19  4.0.125.0  115,712  Ssopsserver.dll
   16-Jun-2005  22:53              28,188  Ssox4.sql
Note Because of file dependencies, the most recent software update that contains these files may also contain additional files.
After you apply the update, you can make the following configuration changes:
  • You can configure offline SSO credential database detection.
  • You can configure the credential cache time-out property to make the cache remain available until the ENTSSO service indicates that the SSO credential database is offline.

Configure offline SSO credential database detection

You can now configure the ENTSSO service to send more than 10 polls before the service indicates that the SSO credential database is offline. To do this, add the OfflineRetryCount registry entry to the following registry sub-key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ENTSSO

Then, set the registry entry for the number of polls that you want the ENTSSO service to send before the service indicates that the SSO credential database is offline.

To enable this feature, follow these steps:
  1. Click Start, click Run, type regedit in the Open box, and then click OK.
  2. Locate the following registry subkey:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ENTSSO

  3. Right-click ENTSSO, point to New, and then click Key.
  4. Type Runtime, and then press ENTER.
  5. Right-click Runtime, point to New, and then click DWORD Value.
  6. Type OfflineRetryCount, and then press ENTER.
  7. Double-click OfflineRetryCount, type the number of retries in the Value data box, and then click OK.

    Note By default, the Base value uses Hexadecimal. If you want to enter the value in decimal, switch the Base setting to Decimal.
  8. Quit Registry Editor.
  9. Stop and then restart the ENTSSO service.
The valid range for the OfflineRetryCount value is 10 through 4000 (decimal). If you enter a value that is less than 10, the default value of 10 will be used. If you enter a value that is more than 4000, the maximum value of 4000 will be used.

An OfflineRetryCount value of 10 means that if the connection to the SSO credential database is lost, the ENTSSO service will detect that the SSO credential database is offline after approximately 5 minutes. This time represents 10 polls at a 30-second poll interval. This setting is the default setting if you do not add the OfflineRetryCount value to the registry.

An OfflineRetryCount value of 4000 means that if the connection to the SSO credential database is lost, the ENTSSO service will not indicate that the database is offline for at least 33.33 hours. This time represents 4000 polls at 30-second poll intervals. The actual time here could be as long as 66 hours because the poll interval may extend past 30 seconds. Underlying error conditions may cause the poll interval to extend past 30 seconds when the SQL Server that is hosting the SSO credential database is unavailable.

When you are determining what OfflineRetryCount value to use in your environment, it may be best to assume that the poll interval is always 30 seconds. Therefore, you know the minimum time that the ENTSSO service will continue to operate before the service indicates that the SSO database is offline.

Configure the credential cache time-out property

When you have applied the update, the credential cache that the ENTSSO service uses will not be cleared immediately after the connection to the SSO credential database is lost. The ENTSSO service will continue to use the credential cache for SSO lookups until the ENTSSO service indicates that the SSO credential database is offline. If the OfflineRetryCount value is set to 10, the credential cache will still be used for 5 minutes. After 5 minutes, the ENTSSO service logs Event 10590 to indicate that the SSO credential database is offline.

The SSO credential database has a credential cache time-out property (credCacheTimeout). By default, the credCacheTimeout property is set to 60 minutes. User credentials that have been added to the credential cache will be automatically purged when the credential cache time-out is reached. If you set the OfflineRetryCount value so that the offline time-out is more than 60 minutes, you may want to increase the value of the credCacheTimeout property. You can increase this value so that cached credentials are not automatically purged when the SSO credential database is offline. You may want to increase this value in case the database is offline for more than 60 minutes.

To change the credCacheTimeout property value, run the following command at a command prompt in the Enterprise Single Sign-On directory (C:\Program Files\Common Files\Enterprise Single Sign-On):

ssomanage -updatedb update file

Note update file is a placeholder for an .xml file that contains the command to change the credCacheTimeout property value. The following code sample shows what information the .xml file must include.
<SSO>
    <globalInfo>
    <credCacheTimeout>60</credCacheTimeout>
    </globalInfo>
</SSO>
You can change the credCacheTimeout property value from 60 to the time-out value, in minutes, that meets your requirements. The maximum value for the credCacheTimeout property is 999,999,999. This value is the largest value that you can specify in the .xml file that you use to configure the SSO credential database.

The Enterprise Single Sign-On SDK contains a sample GlobalInfo.xml file that you can modify. This file is located in the following folder:

C:\Program Files\Common Files\Enterprise Single Sign-On\SDK\Samples\Manage

You can use the credential cache together with Host Integration Server 2004 applications such as Transaction Integrator (TI). Additionally, you can use the credential cache together with applications that access IBM DB2 by using the Host Integration Server 2004 Data Providers, and with other SNA applications.

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

905399 Host Integration Server 2004 applications that are configured to use the ENTSSO service do not use the credential cache for SSO lookup requests

REFERENCES

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

824684 Description of the standard terminology that is used to describe Microsoft software updates

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.
Modification Type:MinorLast Reviewed:7/26/2006
Keywords:kbHotfixServer kbQFE kbinfo kbpubtypekc KB904702
©2004 Microsoft Corporation. All rights reserved.