Upgrade Considerations - Legacy Authentication Methods - Foundation 23.1 - Foundation 23.1 - Ready - OnBase - Essential - Premier - Standard - external - Standard - Essential - Premier

Legacy Authentication Methods

Legacy Authentication Methods
Foundation 23.1

The following upgrade considerations have been compiled by OnBase subject matter experts. These upgrade considerations are general and applicable to most OnBase solutions and network environments and should be considered each time an upgrade is performed.

Carefully consider the impact of making any changes, including those listed below, prior to implementing them in a production environment.

For additional general information about upgrading OnBase, refer to the Upgrade Guidelines reference manual , and visit the Hyland Community at: https://www.hyland.com/community.

The following information is specific to Integration for Single Sign-On.


If your single sign-on solution includes single sign-on for PeopleSoft Enterprise, see also the upgrade considerations in the Single Sign-On for PeopleSoft Enterprise appendix.

Foundation EP1

The Active Directory - Basic authentication method was removed after OnBase 18. Client logins attempting to use this method will fail in OnBase versions after 18.

To continue using Active Directory to synchronize user groups with Integration for Single Sign-On, you must first change the authentication method of OnBase to either Active Directory - Enhanced or LDAP. Details on configuring OnBase to use these authentication methods is available in the Standard Authentication chapter of the Legacy Authentication Methods module reference guide.

After configuring OnBase authentication, the authentication method configured under Synchronize User Groups in Integration for Single Sign-On must be changed to match the new authentication method, or to not synchronize user groups. Integration for Single Sign-On is configured using the Single Sign On Config utility.

General Deployment Considerations

In versions of OnBase prior to version 17, a default User Group did not need to be configured to allow for the creation and synchronization of users and groups when Integration for Single Sign-On used Active Directory or LDAP. In version 17 and above, a default User Group must be configured in order for the creation and synchronization of users and groups with Integration for Single Sign-On, even when using Active Directory or LDAP. A default User Group is assigned in the Configuration module by selecting System Generated User Settings from the Utils menu.


System-generated users inherit all rights and permissions given to the default user group selected. Since users are generated automatically, it is recommended that you create a default user group that is granted only the most basic rights, not allowing system-generated users to perform any kind of processing, editing, or configuration tasks.

Version Numbering

In some instances, the version number of Integration for Single Sign-On may have changed. If you experience issues after an upgrade, ensure that the version number of Integration for Single Sign-On is correct in the web.config file of the OnBase Web Server.

To determine the installed version of Integration for Single Sign-On:

  1. Locate the SingleSignOnConfig.exe file. In a default installation, this executable is located at C:\Program Files (x86)\Hyland\Single Sign On\
  2. Right click the SingleSignOnConfig.exe file and select Properties from the right-click menu.
  3. Select the Details tab. The version is listed under Product version.

    To determine the version configured for the OnBase Web Server:

  4. Locate the web.config file for the OnBase Web Server.
  5. Open the web.config file in a plain-text editor, such as Notepad.

    Do not open the web.config file in a binary-text editor, such as Microsoft Word. Binary editors can introduce characters that cannot be parsed by the application.

  6. Locate the Hyland.Authentication element.
  7. Ensure that the Version listed in the Type attribute matches the version of the executable. For example:
Server Considerations

When the OnBase Web and Application Servers are upgraded, the web.config files of the servers are replaced, which means the previously configured single sign-on instance is removed.

After upgrading the Web and Application Servers you must reconfigure Integration for Single Sign-On using the Single Sign-On Configuration Utility.

If the single sign-on configuration information is copied from a backup copy of the previous versions of the web.config files, in most cases reconfiguration is not required.

If you experience issues after an upgrade with copied configuration information, ensure that the version number of Integration for Single Sign-On is correct in the web.config file of the OnBase Web Server. See the General Deployment Considerations section (above) for details on checking the version number.