Legacy Authentication Methods Onbase Foundation Ep4 Module Refere PDF

Legacy Authentication Methods
Reference Guide
Foundation EP4
Copyright
Information in this document is subject to change without notice. The software described in this document is
furnished only under a separate license agreement and may be used or copied only according to the terms of
such agreement. It is against the law to copy the software except as specifically allowed in the license
agreement. This document or accompanying materials contains certain information which is confidential
information of Hyland Software, Inc. and its affiliates, and which is subject to the confidentiality provisions
agreed to by you.
All data, names, and formats used in this document’s examples are fictitious unless noted otherwise.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under
copyright law, no part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or
for any purpose, without the express written permission of Hyland Software, Inc. or one of its affiliates.
Hyland® and Hyland Software®, as well as Hyland product names, are registered and/or unregistered
trademarks of Hyland Software, Inc. and its affiliates in the United States and other countries. All other
trademarks, service marks, trade names and products of other companies are the property of their respective
owners.
© 2020 Hyland Software, Inc. and its affiliates. All rights reserved.
Document Name ................................................................................... Legacy Authentication Methods
Department/Group.......................................................................................................... Documentation
Revision Number ............................................................................................................Foundation EP4
© 2020 Hyland Software, Inc. and its affiliates ii

Table of Contents
GENERAL INFORMATION AND REQUIREMENTS

Overview ....................................................................................................................................................1
Authentication Methods.........................................................................................................................2
Internal Security.................................................................................................................................................... 4
Active Directory Enhanced................................................................................................................................... 4
Active Directory Federation Services (AD FS) .................................................................................................... 4
Hyland Identity Provider (IdP) Server .................................................................................................................. 5
LDAP Security ....................................................................................................................................................... 5
Integration for Single Sign-On ............................................................................................................................. 5
Single Sign-On for PeopleSoft Enterprise ........................................................................................................... 6
Requirements ............................................................................................................................................6
General Requirements ......................................................................................................................................... 6
Active Directory and LDAP Authentication ......................................................................................................... 6
Extended Character Sets ............................................................................................................................. 7
LDAP Directory Service ................................................................................................................................ 7
Single Sign-On for PeopleSoft Enterprise ........................................................................................................... 8
Upgrade Considerations .........................................................................................................................8
Standard Authentication ...................................................................................................................................... 8
Single Sign-On for PeopleSoft Enterprise ......................................................................................................... 11
Contacting Support ............................................................................................................................... 11
STANDARD AUTHENTICATION
Overview ................................................................................................................................................. 13
Requirements ......................................................................................................................................... 14
Extended Character Sets ................................................................................................................................... 14
LDAP Directory Service ...................................................................................................................................... 14
Upgrade Considerations ...................................................................................................................... 15
Configuring Directory Service Authentication .............................................................................. 15
Source of Security Information ......................................................................................................................... 16
Internal Security .......................................................................................................................................... 17
Active Directory Enhanced ......................................................................................................................... 17
Adding, Editing, or Removing an Active Directory Domain ............................................................... 19
Adding an Active Directory Domain.............................................................................................. 19
Editing an Active Directory Domain .............................................................................................. 21
Removing an Active Directory Domain......................................................................................... 23
Migrating Users from Active Directory Basic to Active Directory Advanced ................................... 23
Mapping Active Directory Users and Groups ..................................................................................... 24
Creating and Mapping User Groups Directly from Active Directory Groups.............................. 25
Creating Users from Active Directory Users or Groups............................................................... 26
© 2020 Hyland Software, Inc. and its affiliates iii

Table of Contents
Adding Users to Additional User Groups in Active Directory Enhanced .................................... 26

Creating Exclusions for User or Group Mappings in Active Directory Enhanced ............................ 27
Managing User Groups Manually ....................................................................................................... 28
Removing Users and User Groups from Active Directory Enhanced Mappings .............................. 28
Additional Options for Active Directory Enhanced Authentication .................................................. 30
Evaluating the Authentication of Active Directory Enhanced Users ................................................ 30
Active Directory API Authentication Settings ........................................................................................... 31
LDAP Security ............................................................................................................................................. 33
LDAP General Server Settings ............................................................................................................ 36
Server Bind Method ............................................................................................................................. 37
User Mapping ....................................................................................................................................... 38
Group Mapping .................................................................................................................................... 39
User and Group Association ............................................................................................................... 40
Configuring Multiple LDAP Servers .................................................................................................... 41
Primary, Backup, and Disabled Servers........................................................................................ 41
Exhaustive Searches ..................................................................................................................... 43
Windows Integration and Trusted Domains ...................................................................................... 44
Interactive User Authentication......................................................................................................................... 45
Active Directory Username Mapping Attribute................................................................................................. 45
Additional Information When Used with Active Directory Enhanced ...................................................... 46
Additional Considerations for LDAP Security ........................................................................................... 47
Synchronize User Attributes on Auto-Logon .................................................................................................... 47
Authentication Only on Auto-Logon .................................................................................................................. 47
Synchronizing Users and User Groups .............................................................................................. 48
Integrating User Groups with Domain User Groups......................................................................................... 48
Adding Users with LDAP .................................................................................................................................... 49
Adding Users with Active Directory Enhanced ................................................................................................. 49
Enabling Automatic Logins .................................................................................................................. 50
Standard Client ................................................................................................................................................... 50
OnBase Patient Window .................................................................................................................................... 51
Additional Active Directory Authentication Steps for Firefox .................................................................. 51
Unity Client.......................................................................................................................................................... 52
Modifying Configuration Files ................................................................................................................... 52
Web Client........................................................................................................................................................... 52
Modifying Configuration Files ................................................................................................................... 53
Multiple Sites Configuration ...................................................................................................................... 53
Single Sign-On with Standard Authentication ................................................................................ 53
EnableAutoLogin ................................................................................................................................................ 54
forceSSOAutoLoginOverDomain....................................................................................................................... 54
Required Configuration Settings for Non-Interactive Active Directory Authentication ..... 54
Registering a Service Principal Name (SPN) and Configuring Delegation in Microsoft Windows ............... 55
Configuring the Application Server ................................................................................................................... 56
Configuring Web Applications........................................................................................................................... 58
Additional Settings ............................................................................................................................... 60
© 2020 Hyland Software, Inc. and its affiliates iv

Table of Contents
Enforcing User Password Security.................................................................................................................... 61

Understanding System Password Policies ............................................................................................... 61
Password Policies for Importing and Exporting Configuration Items ............................................. 62
Creating a Password Policy ....................................................................................................................... 62
Copying Password Policies ....................................................................................................................... 69
Organizing Password Policies ................................................................................................................... 71
Resetting All User Passwords ................................................................................................................... 73
Additional Setting for the Web Server............................................................................................................... 74
Setting Access to the Application Pools ................................................................................................... 75
Opening Multiple Web Client Sessions ..................................................................................................... 76
CONFIGURING ACTIVE DIRECTORY FEDERATION SERVICES (AD FS)

Overview ................................................................................................................................................. 77
Certificates Used and Key Locations ................................................................................................................ 77
Licensing .................................................................................................................................................. 78
Configuration ......................................................................................................................................... 79
Configuring the AD FS Server ............................................................................................................................ 80
Adding a Relying Party Trust ..................................................................................................................... 80
Configuring AD FS Endpoints .................................................................................................................... 82
Configuring the Application Server for AD FS .................................................................................................. 82
Configuring the Web Server for AD FS .............................................................................................................. 83
HTTPS Certificate ....................................................................................................................................... 83
Editing the Web.config File of the Web Server ......................................................................................... 84
Integrating With Domain User Groups .............................................................................................................. 86
Configuring the Unity Client, MRM Unity Client, and Office Business Application for AD FS........................ 87
Configuring Disconnected Scanning for AD FS................................................................................................ 88
Configuring Patient Window for AD FS............................................................................................................. 89
Configuring Studio for AD FS............................................................................................................................. 90
Configuring the Unity Management Console for AD FS .................................................................................. 91
Configuring Report Services for AD FS ............................................................................................................. 92
Troubleshooting .................................................................................................................................... 93
Logging Client Events to the Event Log ............................................................................................................ 93
Verbose Logging on the AD FS Server .............................................................................................................. 93
Common Errors Encountered When Using AD FS............................................................................................ 93
A SignInResponse message may only redirect within the current application ...................................... 94
Bootstrap Token was Empty ...................................................................................................................... 94
Client found response content type of text/html, but expected text/xml ............................................... 94
Failed to connect. User '' does not belong to any user groups. ............................................................... 94
HTTP 400 Bad Request .............................................................................................................................. 95
Object not set for an instance of an object .............................................................................................. 95
OEM Authentication Failed ........................................................................................................................ 95
SAML Assertions are not included in token .............................................................................................. 95
The issuer of the security token was not recognized by the IssuerNameRegistry ................................ 95
© 2020 Hyland Software, Inc. and its affiliates v

Table of Contents
The same client browser session has made X requests in the last Y seconds. Contact your administrator
for details. ................................................................................................................................................... 95
The type initializer for Hyland.Canvas.CanvasClientConfiguration threw an exception ....................... 96
This page cannot be displayed .................................................................................................................. 96
Value cannot be null ................................................................................................................................... 96
Web Client displays a login page ............................................................................................................... 96
INTEGRATION FOR SINGLE SIGN-ON

Overview ................................................................................................................................................. 97
Licensing............................................................................................................................................................. 98
Limitations .......................................................................................................................................................... 98
Pre-Installation ...................................................................................................................................... 99
Installation ............................................................................................................................................ 102
Running the Installer ........................................................................................................................................104
Deploying Integration for Single Sign-On ...................................................................................... 105
Direct Client/Server Model...............................................................................................................................107
Authentication Server Model ...........................................................................................................................109
Web Server Configuration ........................................................................................................................110
App Server Configuration .........................................................................................................................113
Additional Configuration for Single Sign-On ................................................................................ 116
Enabling Single Sign-On for the Web Server...................................................................................................116
Allowing Multiple Web Client Logins from the Same Workstation .......................................................117
Enabling Automatic User Creation with Single Sign-On ................................................................................117
Synchronizing User Groups Via Active Directory ...........................................................................................118
Web.Config Settings ........................................................................................................................................119
Enable Auto Log In ...................................................................................................................................119
Strip the Domain from a Username .........................................................................................................120
Session Timeout .......................................................................................................................................120
Redirect to Custom Page on Authentication Failure ..............................................................................121
Force SSO Auto Log In .............................................................................................................................121
Single Sign-On with Active Directory or LDAP Authentication ......................................................................121
EnableAutoLogin ......................................................................................................................................121
forceSSOAutoLoginOverDomain .............................................................................................................122
SAML SSO Configuration ................................................................................................................... 122
CAS SSO Configuration ...................................................................................................................... 126
Using Custom Authenticators .......................................................................................................... 127
Enabling Custom Authenticators ....................................................................................................................128
Authentication Server Configuration Requirements ..............................................................................128
Configuring a Custom Authenticator ......................................................................................................128
Enabling OnBase Entrust ................................................................................................................... 129
.NET Requirements ..........................................................................................................................................130
OnBase Entrust Token Overview .....................................................................................................................130
© 2020 Hyland Software, Inc. and its affiliates vi

Table of Contents
Installing the Token Generator for Use with a LOB Application....................................................................131

Adding the Token Generator to a LOB Application ........................................................................................131
Token Generator Code Example .....................................................................................................................132
Configuring the Line-of-Business Application ................................................................................................133
Configuring ......................................................................................................................................................137
Configuring the Web Server .....................................................................................................................138
Asymmetric Token Type ..........................................................................................................................140
Symmetric Token Type ............................................................................................................................141
Configuring the Application Server .................................................................................................................143
SINGLE SIGN-ON FOR PEOPLESOFT ENTERPRISE

Licensing ................................................................................................................................................ 145
Upgrade Considerations .................................................................................................................... 145
Requirements ....................................................................................................................................... 146
Server Locations...............................................................................................................................................146
PeopleSoft Configuration .................................................................................................................. 146
Creating the PeopleSoft User Account ...........................................................................................................147
Creating the Permission List ...................................................................................................................147
Creating the Role ......................................................................................................................................148
Creating the User ......................................................................................................................................148
Configuring PeopleSoft to Create the SSO Authentication Token................................................................148
Single Sign-On Configuration ........................................................................................................... 149
Setup .................................................................................................................................................................149
Web Server and Application Server Configuration.........................................................................................150
Web.config Settings .........................................................................................................................................152
© 2020 Hyland Software, Inc. and its affiliates vii

G ENERAL INFORMATION AND REQUIREMENTS
Overview
OnBase security comprises two components: authentication and authorization. Authentication
asserts the identity of an individual and authorization determines what an identity has
permissions to do. This module reference guide focuses on authentication in OnBase, which
includes standard logins, advanced login methods, non-interactive/automatic logins, and single
sign-on.
Significant value is achieved by consolidating authentication methods across an enterprise or

across even a few systems. Users achieve increased productivity by having fewer passwords to
remember and fewer log ins to accomplish in the course of their work. An improvement in
overall system security is also achieved with fewer passwords because users are less likely to
use a simple password that is easily compromised or to resort to writing down their multiple
passwords.
A standard OnBase installation provides support for the standard OnBase user name and
password authentication, Active Directory Authentication, and LDAP authentication.
• Active Directory authentication allows users to be logged into OnBase automatically,
based upon the user’s domain login. This is an effective method for controlling single
authentication over a LAN.
• LDAP authentication logs users in to OnBase based on an LDAP query (from directory
services such as Active Directory). This is also effective over a LAN.
The three authentication methods that OnBase supports out-of-the-box work well for most
customers when OnBase and any other applications or web pages are used on a company
intranet.
Active Directory and LDAP authentication schemes have the added security benefit that users
need only remember one password, making it less likely that they will write their passwords
down where someone can find them. You can also choose whether you want users to be
prompted for login credentials when accessing OnBase or if users are logged in to OnBase
automatically based on the credentials supplied when they logged on to their workstation.
When OnBase is being tightly integrated with another system and access is required over an
extranet or the Internet, customers should use the single sign-on authentication method.
Customers may also desire to use a single authentication method for all of their systems,
including OnBase, and to support a single sign-on so that a user can access all systems without
re-authenticating once their session is established.
This manual is written on the assumption that the System Administrator has the necessary
knowledge regarding the company’s network authentication schemes, and understands how
they work.
© 2020 Hyland Software, Inc. and its affiliates 1

General Information and Requirements
Caution: These options provide the ability to implement global security changes to your
OnBase system and should never be made available to non-administrative users. If configured
incorrectly, your OnBase system may be made more vulnerable and users can be locked out of
OnBase.
Authentication Methods
The following options are available to define how OnBase authenticates users. This module
reference guide explains how to configure OnBase to allow for tighter security controls and a
more streamlined user experience by integrating user authentication with existing Active
Directory and LDAP authentication schemes, as well as several single sign-on vendors.
This table provides a high-level overview of the authentication methods available, with links to
more detailed sections following the table.
Authentication Method Interactive/Automatic Login Notes
Internal Security By default, users are prompted to provide

Standard OnBase login if no other authentication credentials to log in to OnBase (interactive
mode is configured. login).
Does not require additional licensing. See Internal Does not allow syncing OnBase user accounts
Security on page 4. with domain users and groups.
Non-interactive/automatic logins can be
accomplished with the AL command-line switch
or by converting to the Active Directory
Advanced or LDAP methods.
Active Directory - Enhanced By default, users are not prompted to provide

Windows-based integrated security method that credentials to log in to OnBase (non-interactive/
provides control over domain group mappings. automatic login). The user account currently
logged in to the workstation is used to
Does not require additional licensing. See Active
automatically authenticate the user in OnBase.
Directory Enhanced on page 4.
Allows for syncing OnBase user accounts with
domain users and groups. Can be configured to
failover to interactive logins.
In order for non-interactive logins to work with
modules that require the Web or Application
Server, the user’s workstation must be joined to
the same Windows domain as the server.

Active Directory Federation Services (AD FS) By default, users of modules that use the
The OnBase Web Server and Application Server OnBase Web or Application Server (Core-based
can be configured to use Microsoft Active modules) are not prompted to provide
Directory Federation Services (AD FS) credentials to log in to OnBase (non-interactive/
authentication. automatic login). The user account currently
authenticated in AD FS is used to automatically
In order to use AD FS Authentication, you must be
authenticate the user in Core-based OnBase
licensed for Single Sign-On for Microsoft
modules.
Active Directory Federation Services . See
Active Directory Federation Services (AD FS) on Allows for syncing OnBase user accounts with
page 4. domain users and groups. Does not failover to
interactive logins.
AD FS can be used with the OnBase Web and
Unity Clients. AD FS does not apply to logins to
the OnBase Client and Configuration modules.
LDAP By default, users are not prompted to provide

Authenticates users in OnBase based on the credentials to log in to OnBase (non-interactive/
user’s account on an LDAP server. Users are automatic login). The user account currently
granted rights in OnBase based on their LDAP logged in to the workstation is used to
group memberships, which must correspond to automatically authenticate the user in OnBase.
OnBase User Groups. Allows for syncing OnBase user accounts with
Does not require additional licensing. See LDAP domain users and groups. Does not failover to
Security on page 5. interactive logins.
In order for non-interactive logins to work with
modules that require the Web or Application
Server, the user’s workstation must be joined to
the same Windows domain as the server.
Single Sign-On (SSO) By default, users of the OnBase Web Client are
Single sign-on is third-party software that not prompted to provide credentials to log in to
authenticates users to multiple services without OnBase (non-interactive/automatic login). The
requiring the user to log in multiple times. The user account currently authenticated with the
Integration for Single Sign-On module allows the configured SSO vendor is used to automatically
OnBase Web Client to integrate with most single authenticate the user in the Web Client.
sign-on vendors. Allows for syncing OnBase user accounts with
Requires additional licensing that is dependent domain users and groups. Does not failover to
on the SSO authenticator used. See Integration interactive logins.
for Single Sign-On on page 5. SSO does not apply to logins to the OnBase
Client and Configuration modules, the Unity
Client, or modules that are not accessed through
the Web Client.

Single Sign-On for PeopleSoft By default, users of the OnBase integrations for
A single sign-on solution specific to OnBase PeopleSoft are not prompted to provide
integrations with PeopleSoft. credentials to log in to OnBase (non-interactive/
automatic login). The user account currently
In order to use Single Sign-On for PeopleSoft
authenticated with the PeopleSoft SSO vendor is
Enterprise, you must be licensed for Single Sign-
used to automatically authenticate the user in
On for PeopleSoft Enterprise . See Single Sign- OnBase.
On for PeopleSoft Enterprise on page 6.
Does not allow syncing OnBase user accounts
with domain users and groups. Does not failover
to interactive logins.
This authentication option is only supported in
the PeopleSoft integrations.
Internal Security
Internal security is the default authentication method and is enabled for all OnBase systems,
unless it has been modified by accessing the Directory Service Authentication dialog box. With
Internal security, users are authenticated using OnBase credentials and they are prompted for
their credentials each time they log in.
There is no further configuration and no additional licensing required to use Internal security.
See Standard Authentication on page 13.
Active Directory Enhanced

Active Directory - Enhanced is a Windows-based integrated security method that provides
control over domain group mapping. OnBase user rights are granted to the user based on the
rights granted to the OnBase User Groups that the user’s account or Active Directory group is
mapped to. An Active Directory user or group can be mapped to one or more OnBase User
Groups, and OnBase User Groups can be mapped to one or more Active Directory groups or
users. This method can be configured to allow users to log in to OnBase automatically based
on the credentials supplied when they logged in to their workstation, or to be prompted for
those login credentials when accessing OnBase.
There is no additional licensing required to use Active Directory Enhanced.

Active Directory Federation Services (AD FS)

The OnBase Web Server can be configured to use Microsoft Active Directory Federation
Services (AD FS) authentication, allowing users to authenticate in OnBase using the Web Client
or Unity Client using their Active Directory credentials.

In order to use AD FS Authentication, you must be licensed for Single Sign-On for Microsoft
Active Directory Federation Services .
See Configuring Active Directory Federation Services (AD FS) on page 77.
Hyland Identity Provider (IdP) Server

Starting in OnBase Foundation EP1, the Hyland Identity Provider (IdP) server was replaced with
Hyland Identity and Access Management (IAM) services, which includes a new Hyland IdP
server.
See the Identity and Access Management Services module reference guide for complete
details on installing and configuring the updated Hyland IdP server.
See the Integrating With Hyland IAM Services module reference guide for complete details on
configuring the various OnBase clients to use IAM Services for authentication.
LDAP Security
LDAP Security authenticates users in OnBase based on the user accounts on an LDAP server.
Users are granted rights in OnBase based on their LDAP group memberships, which must
correspond to OnBase User Groups. This method can be configured to allow users to log in to
OnBase automatically based on the credentials supplied when they authenticated against the
LDAP server, or to be prompted for those login credentials when accessing OnBase.
There is no additional licensing required to use LDAP.

Integration for Single Sign-On

Single sign-on is third-party software that authenticates users to multiple services without
requiring the user to log in multiple times. It is most effective when users need to authenticate
to multiple services over a WAN, but also over complex LANs where users must authenticate to
multiple and disparate services.
The Integration for Single Sign-On module allows the OnBase Web Client to integrate with
most single sign-on vendors so that a user is automatically logged in to OnBase as part of a
single sign-on solution. When a user attempts to access OnBase, Integration for Single Sign-On
communicates with the configured single sign-on vendor to authenticate the user.
Note: Integration for Single Sign-On is not supported for use with the OnBase Client or Unity
Client. For other automatic login options, see Standard Authentication on page 13.

In order to use Integration for Single Sign-On, you must be licensed for Integration for Single
Sign-On . Depending on the single sign-on scheme you are using, one of the following additional
database licenses is also required:
• Single Sign-On for CA eTrust SiteMinder
• Single Sign-On for Fiserv
• Single Sign-On for IBM Tivoli Access Manager
• Single Sign-On for Microsoft Active Directory Service
• Single Sign-On for OnBase Entrust
• Single Sign-On for PeopleSoft Enterprise
• Single Sign-On for SAP Enterprise Portal
• Single Sign-On for SAML
• Single Sign-On for TriCipher Armored Credential Systems
See Integration for Single Sign-On on page 97.
Single Sign-On for PeopleSoft Enterprise

Single Sign-On for PeopleSoft Enterprise is a single sign-on solution, specific to OnBase
integrations with PeopleSoft, that allows users to log in to OnBase automatically using
PeopleSoft credentials, when OnBase is accessed from an enabled PeopleSoft page.
In order to use Single Sign-On for PeopleSoft Enterprise, you must be licensed for Single Sign-
On for PeopleSoft Enterprise .
See Single Sign-On for PeopleSoft Enterprise on page 145.
Requirements
The following sections outline requirement information specific to Legacy Authentication
Methods in OnBase Foundation EP4.
General Requirements
For general requirement information that applies to Legacy Authentication Methods and other
modules, see the sections on the following topics in the Installation Requirements manual:
Active Directory and LDAP Authentication

The following additional requirements must be met when using Active Directory and LDAP
authentication.

Extended Character Sets

Certain characters in some locales are not stored correctly in an ANSI database and can
prevent user logins if the user account names or passwords contain the unsupported
characters.
In order to use Active Directory or LDAP authentication in OnBase environments that include
any workstations set to a locale that uses an extended character set (for example, the dotted
capital I and dotless lower case I in Turkish and Azeri locales), the OnBase database should be
a Unicode collation.
LDAP Directory Service

For LDAP authentication, the directory service software must be compatible with LDAP version
3.

The following certificates are used by OnBase or AD FS to complete authentication. Make sure
you have the required certificates before attempting configuration.
• AD FS SSL: The SSL certificate used by IIS on the AD FS server to encrypt traffic. It is
required. The private key resides on the AD FS server, and the OnBase Web Server
and the client machine must trust the issuer (ROOT CA) of the certificate.
• Token Encryption: The certificate used by AD FS to encrypt the token sent to the
client. It is not required but it is recommended.
• Token Signing: The certificate used by AD FS to sign SAML tokens. It is required. The
the public key resides on the OnBase Web Server.
• Request Signing: The certificate used by OnBase to sign the request sent to the AD
FS server. It is not required but it is recommended.
• Web Server SSL: The SSL certificate used by IIS on the OnBase Web Server to
encrypt traffic. It is required. The private key resides on the OnBase Web Server, and
the AD FS server and the client machine must trust the issuer (ROOT CA) of the
certificate.
Note: OnBase using AD FS authentication does not support CNG (Cryptographic Next
Generation) certificates.
All certificates should be in the local computer account. If the OnBase Application Server is on
a different machine from the OnBase Web Server, the certificates on both servers must match.
All private keys should be stored in the Local Computer\Personal certificate store. Private keys
in that store should have a matching public key stored in either the Local Computer\Trusted
Root Certification Authorities or Local Computer\Trusted People certificate stores. All other
public keys should be stored in the Local Computer\Trusted People certificate store.

The Application Pool Identity account or impersonation account configured for the servers
requires Read access to the certificates.
Certificate thumbprints are used to correctly identify the certificate to use for communication.
The thumbprint value can be found in the certificate manager.

The OnBase Entrust Single Sign-On provider targets Microsoft .NET Framework version 3.5.
This may be different from the .NET requirements of other areas of your overall OnBase
solution.

The following additional requirements must be met to configure and use Single Sign-On for
PeopleSoft Enterprise:
• PeopleTools version 8.48 or higher.
• The PRTL_SS_CI PeopleSoft API component interface.
• The OnBase Integration for Single Sign-On must be installed on the OnBase web
server.
Note: In order for an OnBase user to be automatically logged in to OnBase using single sign-on
when OnBase is accessed through a PeopleSoft page, that user’s OnBase user name must
match exactly that user’s PeopleSoft user ID. The user’s passwords do not have to match.
Upgrade Considerations
The following upgrade considerations are for the various methods of authenticating in OnBase.
Standard Authentication
The following information is specific to Standard Authentication.
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 authenticate users, you must change the configuration to
Active Directory - Enhanced . The Auto-Configure Using Matching Group Names option is
intended to assist in the migration from an existing Active Directory - Basic authentication
method to the Active Directory - Enhanced method.
Non-Interactive Active Directory Authentication — T


The following information is specific to configuring Active Directory Federation Services (AD
FS).
General Considerations — When the OnBase Web and Application Servers are upgraded, the
web.config files of the servers are replaced, which means the previously configured AD FS
instance is removed.
Before upgrading, the web.config files of the servers should be backed up. The AD FS
configuration information can be copied from the backup of the previous versions of the
web.config files into the upgraded versions. In most cases, additional reconfiguration is not
required as long as the certificates did not change.
The following items should also be noted when configuring AD FS:

• The default website name in the web.config files is case sensitive and must match
exactly in all places it is configured.
• The OnBase Application Server requires signing certificates for both AD FS and the
Web application.
• The AD FS Server requires signing certificates for both the AD FS Server and the Web
application.
• The account running the AD FS service on the AD FS server, and the account running
the application pools on the OnBase Web and Application Servers, need read access
to the private key of the SSL certificate.

The following information is specific to Integration for Single Sign-On.
Note: 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.
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.
Caution: 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:

1. Locate the web.config file for the OnBase Web Server.
2. Open the web.config file in a plain-text editor, such as Notepad.
Note: 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.
3. Locate the Hyland.Authentication element.

4. 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.

Upgrading PeopleTools — If you have upgraded PeopleTools to version 8.54 or greater for use
with Single Sign On, you must reconfigure the Single Sign On module to point to a web service
for authentication (the service in the Hyland.Authentication.PeopleSoft.war file).
Contacting Support
When contacting your solution provider, please provide the following information:
• The OnBase module where the issue was encountered.
• The OnBase version and build.
• The type and version of the connected database, such as Microsoft SQL Server 2014
or Oracle 12c, and any Service Pack that has been installed.
• The operating system that the workstation is running on, such as Windows 10 or
Windows Server 2012 R2, and any Service Pack that has been installed. Check the
supported operating systems for this module to ensure that the operating system is
supported.
• The name and version of any application related to the issue.
• The version of Internet Explorer and any Service Pack that has been installed, if
applicable.
• A complete description of the problem, including actions leading up to the issue.
• Screenshots of any error messages.

Supplied with the above information, your solution provider can better assist you in correcting
the issue.

S TANDARD AUTHENTICATION
Standard authentication options include Internal security, Active Directory Advanced, and
LDAP, which are configured in the Directory Service Authentication dialog box of the OnBase
Configuration module. That configuration information is covered in this chapter.
Note: 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 authenticate users, you must change the configuration to Active
Directory - Enhanced . The Auto-Configure Using Matching Group Names option is intended to
assist in the migration from an existing Active Directory - Basic authentication method to the
Active Directory - Enhanced method.
To configure the single sign-on integrations or AD FS, see the corresponding configuration
chapters:
• Configuring Active Directory Federation Services (AD FS) on page 77
• Integration for Single Sign-On on page 97
• Single Sign-On for PeopleSoft Enterprise on page 145
Standard authentication is natively available in OnBase. To access it, append the -ROMANZO
switch to the Configuration module executable before launching it.
Caution: Before using features enabled by the -ROMANZO switch, ensure that you understand
the feature and implications of any changes to your system. Contact your service provider with
any questions regarding these features. Features enabled by the -ROMANZO switch should not
be made available to the casual user. Remove the -ROMANZO switch after completing
necessary actions.
Overview
OnBase has a native authentication method and can also use Active Directory or LDAP to
authenticate users. These standard authentication methods require no additional licensing, but
Active Directory and LDAP do require additional configuration. This section briefly describes
the standard authentication methods.
Tip: To use Active Directory authentication with the OnBase Web Server, see Configuring Active
Directory Federation Services (AD FS) on page 77.


Note: 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 authenticate users, you must change the configuration to Active
Directory Enhanced . The Auto-Configure Using Matching Group Names option is intended to
assist in the migration from an existing Active Directory Basic authentication method to the
Active Directory Enhanced method.
Requirements
The following requirements apply to standard authentication.
Extended Character Sets

Certain characters in some locales are not stored correctly in an ANSI database and can
prevent user logins if the user account names or passwords contain the unsupported
characters.
In order to use Active Directory or LDAP authentication in OnBase environments that include
any workstations set to a locale that uses an extended character set (for example, the dotted
capital I and dotless lower case I in Turkish and Azeri locales), the OnBase database should be
a Unicode collation.
LDAP Directory Service

For LDAP authentication, the directory service software must be compatible with LDAP version
3.

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 Standard Authentication.

OnBase 18. Client logins attempting to use this method will fail in OnBase versions after 18. To
continue using Active Directory to authenticate users, you must change the configuration to
Active Directory - Enhanced . The Auto-Configure Using Matching Group Names option is
intended to assist in the migration from an existing Active Directory - Basic authentication
method to the Active Directory - Enhanced method.
Non-Interactive Active Directory Authentication — T
Configuring Directory Service Authentication

In order to access the Directory Service Authentication dialog box you must launch the
Configuration module with the ROMANZO switch applied.
the implications of any changes to your system. Contact your service provider with any
questions regarding these features. Features enabled by the -ROMANZO switch should not be
made available to the casual user. Remove the -ROMANZO switch after completing necessary
actions.

To access the Directory Service Authentication dialog, select Directory Service

Authentication from the Utils menu in the Configuration module. The options available in this
dialog are described in the sections below.
See:
• Source of Security Information on page 16
• Interactive User Authentication on page 45
• Active Directory Username Mapping Attribute on page 45
• Synchronize User Attributes on Auto-Logon on page 47
• Authentication Only on Auto-Logon on page 47
Source of Security Information

The options under Source of Security Information define how OnBase authenticates users.
• Internal Security on page 17
• Active Directory Enhanced on page 17
• Active Directory API Authentication Settings on page 31
• LDAP Security on page 33

Internal Security
There is no further configuration required to use Internal security.
Tip: See also, Enforcing User Password Security on page 61.
Active Directory Enhanced

An Active Directory user or group can be mapped to one or more OnBase User Groups, and
OnBase User Groups can be mapped to one or more Active Directory groups or users. Group
mapping and user authentication is achieved using the Active Directory Security ID (SID) of the
group and user logging in, so name matching is not required with Active Directory Enhanced.
This also allows OnBase to support multiple domains that may have different users with the
same user name.
Note: The Active Directory Enhanced authentication scheme configured under Directory
Service Authentication is different from Active Directory Federation Services (AD FS). For
details on configuring OnBase to use AD FS, see Configuring Active Directory Federation
Services (AD FS) on page 77.

To authenticate users using Active Directory Enhanced, select Active Directory - Enhanced in
the Directory Service Authentication dialog box, then click the Settings button. The Active
Directory - Enhanced dialog box is displayed.
Caution: Setting your OnBase system to use Active Directory Enhanced security cannot be
undone.
• The Configured Active Directory Domains pane in the upper left of the dialog box
lists the Active Directory domains available for mapping.
Tip: The default view is a flattened list with user membership under each group. To view the
domains in a standard Active Directory hierarchy, right click in the Configured Active Directory
Domains pane and select View > Organizational Unit (OU) View from the right-click menu. The
Active Directory - Enhanced dialog box will display the most recently used view the next time it
is accessed.
Disabled domains are visually represented in the Configured Active Directory

Domains pane by a dark screen on the icon, as shown beside A in the following
illustration. B represents an enabled domain.

• The upper right pane of the dialog box lists the OnBase User Groups available for
mapping.
• The Evaluation Results pane in the lower left of the dialog box displays the results
when an Active Directory user or group is evaluated for authentication.
• The Options pane in the lower right provides for the configuration of additional
options that can be applied to Active Directory authentication.
Adding, Editing, or Removing an Active Directory Domain

To make an Active Directory domain available for mapping it must be added to the Configured
Active Directory Domains pane. The settings for domains that have been added can be edited,
or the domain can be removed.
Adding an Active Directory Domain

To add an Active Directory Domain:
1. Click the + button above the Configured Active Directory Domains pane or select Add
Domain from the right-click menu.
The Add New Domain dialog box is displayed.

2. Enter the name of the domain in the Domain field. This must be the actual name of a
domain and the server must be online to complete the configuration.
3. Ensure that Enabled is selected. If Enabled is deselected, the domain is not used to
authenticate against.
Disabled domains are visually represented in the Configured Active Directory Domains
pane by a dark screen on the icon, as shown beside A in the following illustration. B
represents an enabled domain.
4. Select Alternate Binding Credentials to specify the user account against which the
security context for the domain should be resolved. If this option is deselected, the
security context of the user currently logged in to Windows, or of the impersonation
account when OnBase is being accessed using the OnBase application server, is used to
resolve the groups within the domain.
Tip: It is a best practice to deselect the Alternate Binding Credentials option and use the
default account to obtain the security context.

5. Select Resolve Group Foreign Security Principals to resolve User Group Foreign
Security Principals that are mapped to OnBase groups. This setting has no effect on
User Foreign Security Principals.
If this option is deselected, User Group Foreign Security Principals are not included
when authenticating a user against the domain.
In order for a User Group Foreign Security Principal to resolve, the domain in which it
resides must also be a configured domain in OnBase.
Note: Selecting this option may increase login time for users.
6. Select Use SSL When Available to use an HTTPS binding between the client and the
server. The server must be configured to support HTTPS bindings.
7. Click Add . If the Domain name entered is not valid or the server is offline, the Could not
resolve domain error is displayed.
8. Click Apply to save the configuration changes and continue working in the Active
Directory - Enhanced dialog box, or click OK to save the configuration changes and
close the Active Directory - Enhanced dialog box.
Editing an Active Directory Domain

To edit the settings of an Active Directory domain:
1. Select the domain in the Configured Active Directory Domains pane.
2. Select Edit Domain Settings from the right-click menu.
The Edit Domain Settings dialog box is displayed.
Note: The Domain name cannot be changed once it is added. To change the name of a domain,
it must be removed then added as a new domain. See Removing an Active Directory Domain on
page 23.

3. Select Enabled to include this domain in authentication. If Enabled is deselected, the

domain is not used to authenticate against.
Disabled domains are visually represented in the Configured Active Directory Domains
pane by a dark screen on the icon, as shown beside A in the following illustration. B
represents an enabled domain.
4. Select Alternate Binding Credentials to specify the user account against which the
security context for the domain should be resolved. If this option is deselected, the
security context of the user currently logged in to Windows, or of the impersonation
account when OnBase is being accessed using the OnBase application server, is used to
resolve the groups within the domain.
Tip: It is a best practice to deselect the Alternate Binding Credentials option and use the
default account to obtain the security context.
5. Select Resolve Group Foreign Security Principals to allow authentication for groups in
trusted foreign domains that are mapped to OnBase groups. If this option is deselected,
groups that are part of a foreign trusted domain are not included when authenticating a
user against the domain.

6. Select Use SSL When Available to use an HTTPS binding between the client and the
server. The server must be configured to support HTTPS bindings.
7. Click Save .
Removing an Active Directory Domain

To remove an Active Directory Domain:
1. Select the domain in the Configured Active Directory Domains pane.
2. Click the - button above the Configured Active Directory Domains pane or select
Remove Domain from the right-click menu.
Caution: Removing a domain with mappings to OnBase User Groups also removes the
mappings in OnBase.
3. Click Yes at the Warning to remove the domain and all its mappings to OnBase User
Groups.
Note: You are not prompted to confirm this action if no OnBase User Group mappings are
configured for the domain.
Migrating Users from Active Directory Basic to Active Directory

Advanced
The Auto-Configure Using Matching Group Names option is intended to assist in the migration
from an existing Active Directory Basic authentication method to the Active Directory Enhanced
method. Since Active Directory Basic matched group names that correspond to OnBase User
Groups, an initial configuration of Active Directory Enhanced authentication can be completed
by mapping groups with matching names in OnBase and Active Directory that are not already
mapped to OnBase.

To automatically map Active Directory groups that correspond to existing OnBase User Groups:
1. Select a domain in the Configured Active Directory Domains pane of the Active
Directory - Enhanced dialog box.
2. Select Auto-Configure using matching Group Names from the right-click menu. Any
Active Directory groups that have the same name as OnBase User Groups are mapped
to those User Groups in OnBase, if they are not already mapped.
When the configuration is finished, the Auto-Configuration dialog box is displayed. This
dialog box displays text results of the auto-configuration. Click OK to continue.
Note: After using auto-config to map User Groups, it is a best practice to review the mappings
that were created to ensure they match your security needs. Auto-configured mappings can be
changed or removed in the same way as any mappings.
Mapping Active Directory Users and Groups

Active Directory users and groups are mapped to OnBase User Groups. OnBase user rights are
granted to the user based on the rights granted to the OnBase User Groups that the user’s
account or Active Directory group is mapped to.
An Active Directory user or group can be mapped to one or more OnBase User Groups, and
OnBase User Groups can be mapped to one or more Active Directory groups or users.
Active Directory users or groups can also be excluded from specific OnBase User Groups, or
from authenticating in OnBase altogether.
To map an Active Directory user or group to an OnBase User Group, use drag-and-drop mouse
functionality:
1. Select a user or group in the Configured Active Directory Domains pane of the Active
Directory - Enhanced dialog box and hold down the left mouse button.
Note: Foreign Security Principals do not appear in the Configured Active Directory Domains
pane.

2. Drag the selected user or group into the OnBase Groups pane (upper right) and release
the mouse button when the selected object is over the OnBase User Group you are
mapping it to.
Tip: To expand all OnBase user groups, right-click in the OnBase Groups list and select Expand
All . To collapse all OnBase user groups, right-click in the OnBase Groups list and select
Collapse All .
To remove user group mappings, see Removing Users and User Groups from Active Directory
Enhanced Mappings on page 28.
Creating and Mapping User Groups Directly from Active Directory Groups
OnBase User Groups can be created in OnBase using the Active Directory group you want to
map it to. These groups can also be automatically mapped upon creation in OnBase.
1. Select a group in the Configured Active Directory Domains pane of the Active Directory
- Enhanced dialog box.
2. Right click the selected group and select Create Corresponding OnBase Group . The
Create OnBase Group dialog box is displayed.
3. Enter the name for the new User Group in OnBase in the Group Name field. The Active
Directory group name is entered by default.

4. Select Immediately Map to Active Directory Group to automatically map the new
OnBase User Group to the Active Directory group selected. If this option is not selected,
the group will have to be mapped manually.
5. Click OK .
Creating Users from Active Directory Users or Groups

OnBase user accounts can be created from their Active Directory records.
1. Select a user or group in the Configured Active Directory Domains pane of the Active
Directory - Enhanced dialog box.
2. Right click the selected user or group and select the corresponding option:
• Create Corresponding OnBase User for each AD User in this Group
• Create Corresponding OnBase User
3. You are prompted to confirm this action.
The value of the Active Directory sAMAccountName attribute is set as the user name for users
created in OnBase in this way.
Adding Users to Additional User Groups in Active Directory Enhanced

Once a user account has been authenticated and created in OnBase, it is available to be added
to user groups via the User Groups & Rights dialog box. However, users cannot be added to
additional user groups via the User Groups & Rights dialog box unless they belong to the
corresponding Active Directory groups or the OnBase user group is configured as manually-
managed.
Tip: For more information about manually-managed user groups, see Creating and Mapping
User Groups Directly from Active Directory Groups on page 25.
If a user is added to a user group that is not managed manually and is not mapped to a
corresponding Active Directory group to which the user belongs, the user is removed from the
user group. For example, a user added to the HR - Managers user group via the User Groups &
Rights dialog box must also belong to an Active Directory group that is mapped to the HR -
Managers OnBase user group. If the user is not found in the mapped Active Directory group, the
user is automatically removed from the OnBase user group.
To add users to additional OnBase user groups, map them to the specific user groups via the
Active Directory - Enhanced dialog box, or ensure that they belong to the Active Directory
groups that are mapped to the desired OnBase user groups.
In addition, you can add users to OnBase user groups that are configured as manually-managed
user groups. These OnBase user groups are not affected by Active Directory authentication,
and users are not removed from these groups upon authentication because these groups are
configured so that they cannot be mapped to Active Directory groups. For more information
about manually-managed user groups, see Creating and Mapping User Groups Directly from
Active Directory Groups on page 25.
Users added directly to a user group in the Active Directory - Enhanced dialog box are not
removed from the user group. See Mapping Active Directory Users and Groups on page 24 for
more information about adding users directly to OnBase user groups.

Creating Exclusions for User or Group Mappings in Active Directory

Enhanced
User privileges should be managed primarily through the use of group mappings, which are
inclusive. However, if it is necessary to specifically prevent a Windows group or user from
being associated with a particular OnBase User Group, that user or group can be mapped to the
Exclusions for the OnBase User Group. Adding a user or group to the Exclusions is analogous
to the Windows Deny permission.
To explicitly exclude an Active Directory user or group from an OnBase User Group, use drag-
and-drop mouse functionality in the Active Directory - Enhanced dialog box:
1. Expand the OnBase User Group in the Groups pane by clicking the + beside the User
Group name. The mapped users and groups are displayed, as well as the Exclusions
node.
2. Select a user or group in the Configured Active Directory Domains pane or the Groups
pane and hold down the left mouse button.
3. Drag the selected user or group onto the Exclusion node and release the mouse button.
That user or group is excluded from the selected OnBase User Group.
If a user or group is excluded from a User Group in OnBase, that user or the group’s members
are not granted the OnBase rights for that User Group. However, if a user or group is mapped to
multiple OnBase User Groups, the user or group’s members will retain any rights to OnBase
User Groups they are not excluded from.
For example, if a user is a member of both OnBase User Group A and B, and both User Groups
have Indexing rights, then the user retains Indexing rights in OnBase if they are only excluded
from User Group A or B, because they are still a member of the other group.

To prevent an Active Directory user or members of an Active Directory group from logging in to
OnBase altogether, add them to the root Exclusions node at the bottom of the Groups pane:
Managing User Groups Manually

OnBase user groups that are not mapped to Active Directory groups can be set as manually-
managed user groups. These groups are managed entirely through user group administration
instead of Active Directory. No Active Directory group can be mapped to the OnBase user
group, and Active Directory authentication does not affect membership of the OnBase user
group.
To configure an OnBase user group as a manually-managed user group:
1. Select a user group in the OnBase Groups list. You can also select multiple user groups
to configure as manually managed.
2. Right-click a selected user group.
3. Select Manage Manually from the right-click menu. All user groups selected are
configured as manually managed.
The words (Managed manually) denote manually-managed user groups in the OnBase Groups
list.
To remove this setting, right-click a user group and select Manage Automatically . You can also
select multiple user groups. All user groups selected have the Manage Manually setting
removed and are configured as automatically managed.
Tip: Hold down the Shift key and select the first and last user group to select the range, or hold
down the Ctrl key and select the individual user groups.
Removing Users and User Groups from Active Directory Enhanced

Mappings
When an Active Directory user has been mapped to an OnBase user group, and the user is then
removed from the OnBase user group via the User Groups & Rights dialog or the User Names &
Passwords dialog, a new dialog is displayed prompting you to choose whether or not you want
to remove the corresponding Active Directory mapping as well.

If you want the user’s Active Directory mapping to the OnBase user group to be removed, click
Yes . If you do not want to remove the user’s Active Directory mapping to the OnBase user
group, click No .
To manually remove an Active Directory mapping to an OnBase user or user group:
1. Select a user or group in the OnBase User Groups pane of the Active Directory -
Enhanced dialog box and hold down the left mouse button.
2. Drag the selected user or group into the Configured Active Directory Domains pane and
release the mouse button.
Tip: To expand all OnBase user groups, right-click in the OnBase Groups list and select Expand
All . To collapse all OnBase user groups, right-click in the OnBase Groups list and select
Collapse All .
To remove multiple mappings:

1. Select the users or user groups to remove the mapping from in the OnBase User Groups
pane of the Active Directory - Enhanced dialog box.
Tip: Hold down the Shift key and select the first and last user group to select the range, or hold
down the Ctrl key and select the individual user groups.
2. Right click a selected user or user group in the OnBase User Groups pane.
3. Select Remove Mapping from the right-click menu. The mapping is removed for all
selected users and user groups.

Additional Options for Active Directory Enhanced Authentication

Additional options can be configured for Active Directory Enhanced authentication. These
options are applied to all domains configured. The additional options are located in the Options
pane in at the lower right of the Active Directory Enhanced dialog box:
• Search User’s Login Domain Only: When this option is selected, only the domain the
user is logging in from is used to authenticate the user. This option should be used
when multiple domains are mapped to an OnBase User Group, but each user’s group
membership in Windows is limited to their own domain.
• No Serverless Binds: In environments where multiple domains are configured, and
there is no trust between domains, enabling this feature may improve the time it
takes users to log in. This option configures OnBase to avoid bind attempts that are
likely to timeout and will immediately issue domain-specific binds instead.
• Failover to Interactive Mode : If this option is selected, a login dialog box prompts
the user to enter credentials (interactive login) if a user is attempting to authenticate
from a domain that is not mapped. The user must still be able to authenticate against
one of the domains configured in order to log in successfully, even if they are not
currently logged in to one of those domains.
Note: The Interactive User Authentication settings configured on the Directory Service
Authentication dialog are still respected even with the Failover to Interactive Mode option
selected.
Evaluating the Authentication of Active Directory Enhanced Users

To evaluate the results of an authentication attempt in OnBase for an Active Directory user:
1. Select the user in the Configured Active Directory Domains pane in the Active Directory
- Enhanced dialog box.
2. Select Evaluate Group Membership for... from the right click menu. The evaluation is
completed and the results are displayed in the Evaluation Results pane.
The results include information regarding the ability of OnBase to resolve the user in Active
Directory; the ability of OnBase to bind to the domain, group, or user object; and the results of
the user’s record in OnBase.

Active Directory API Authentication Settings

After your system has been configured to use Active Directory Enhanced, the Active Directory
API Authentication Settings option is available under the Utils menu. These settings allow
system administrators to prevent the OnBase API being used for brute-force password
discovery attacks.
1. Configure the settings in the Active Directory API Authentication Settings dialog:
Option Description
Security Level
Active Incorrect login attempts are tracked and further login

attempts are prevented if the failure threshold is reached.
Inactive Incorrect login attempts are not tracked and no failure

threshold is enforced.
Forbid AD Authentication Any Active Directory login attempt using the API connection
method automatically fails.

Option Description
Destination
Internal Mail The OnBase user account that receives NT API

Authentication Security notifications via internal mail.
External Mail The external email address that receives NT API

Authentication Security notifications.
Notification
Failed Login Notification Select how to report notices of failed login attempts. They
can be logged in the Event Log and sent to the Internal
Mail or External Mail addresses.
Account Lockout Notification Select how to report notices of users locked out of their
accounts. They can be logged in the Event Log and sent to
the Internal Mail or External Mail addresses.
System Lockout Notification Select how to report a notice of the system locking out all
attempted connections using the API. It can be logged in the
Event Log and sent to the Internal Mail or External Mail
addresses.
Lockouts
System Lockout If the configured threshold of failed logins is reached, all

future attempts to login using the API fail.
• Interval: The amount of time in minutes that must
elapse between failed login attempts.
• Number of Failures: The number of failed login
attempts that can occur in the Interval configured.
• Number of Timed Lockouts: The number of System
Timed Lockouts that can occur before all logins using
the API are locked out.
System Timed Lockout If the configured threshold of failed logins is reached, the
system is locked out from using the API to login for the
length of time configured.
attempts that can occur in the Interval configured before
API connection attempts are locked out.
• Duration: The amount of time in minutes that API
connection attempts are locked out.

Option Description
Account Lockout If the configured threshold of failed logins is reached, all

future attempts by that user to login using the API fail.
• Number of Timed Lockouts: The number of Account
Timed Lockouts that can occur before all logins by that
user using the API are locked out.
Account Timed Lockout If the configured threshold of failed logins is reached, that
user is locked out from using the API to login for the length
of time configured.
• Duration: The amount of time in minutes that API
connection attempts are locked out.
2. Click Apply .
LDAP Security
The following items should be considered before using LDAP Security:

• If the LDAP server is an Active Directory server, one of the Active Directory
authentication methods should be used instead.
• LDAP does not support nested groups.
• LDAP servers are not discoverable in the same way as Active Directory with domain
controllers.
• In order to allow for redundancy, every LDAP server (primary and backup) must be
configured separately.
• The LDAP directory service software must be compatible with LDAP version 3.

To authenticate users using LDAP authentication, select LDAP in the Directory Service
Authentication dialog box, then click the Settings button. The LDAP Servers dialog is
displayed.
Caution: Setting your OnBase system to use LDAP cannot be undone.
To delete a server, select it in the LDAP pane and click Delete .

To configure a new server to authenticate against, click Add . To edit a server’s configuration,
select it in the LDAP pane and click Edit . The LDAP Server Settings dialog is displayed.
The options available in this dialog are described below. Once the LDAP Server Settings have
been configured, click Save .
Tip: See also Configuring Multiple LDAP Servers on page 41 for details on configuring more
than one LDAP server.

LDAP General Server Settings

These settings are used to locate the LDAP server on the network.
Setting Function
Name Assign a name to this LDAP server configuration. Multiple

configurations may be stored so this name should be unique.
Enable Select Enable to enable the server or deselect it to disable a

server. Disabled servers are not used for authentication. Servers
can also be enabled/disabled from the right-click menu options.
Host The fully qualified domain name or IP address of the LDAP

server.
Port The port used by the LDAP server (the default value is 389). Port
numbers can be up to 6 digits long.
Use SSL Select Use SSL to use an HTTPS binding between the client and
the LDAP server. The server must be configured to support
HTTPS bindings and the correct Port must be assigned (the
HTTPS port is usually 636).
Independent User and Group Select Independent User and Group Search Roots to search
Search Roots two different structure trees within a User Directory. This
enables the Group Search Root (DN format) field, which allows
you to search for groups within a specified sub-tree in addition
to searching for users within a specified sub-tree via the User
Search Root (DN format) field.
This option is disabled by default.

Setting Function
User Search Root (DN format) Enter the name of the sub-tree directory to search for users on
the LDAP server. Users are expected to be unique within the
specified sub-tree, as identified by the OnBase User Name
Attribute .
Group Search Root (DN Enter the name of the sub-tree directory to search for groups on
format) the LDAP server. Groups are expected to be unique within the
specified sub-tree, as identified by the OnBase Group Name
Attribute .
Server Bind Method

LDAP requires some form of authentication (server bind) in order to perform searches. Some
LDAP servers allow an anonymous bind, while others require user authentication. OnBase
access must be configured to perform searches on the LDAP server.
Setting Function
Anonymous This is the recommended setting if the server supports

searches with an anonymous bind.
Current User Credentials Authenticates against the currently logged in user. This only
works with Active Directory.
Proxy User Authenticate against a specific user account. The user need
only have sufficient rights to performs searches and read
entries. Enter the user’s distinguished name in the User DN
field and supply the Password . Passwords up to 50
characters are supported.
Pre-6.2 version compatibility Select this option to store the password in the database as
plain text for compatibility with pre-6.2 versions. If this option
is not selected the password is encrypted when stored in the
database.

User Mapping
Configure how a user entry is stored on the LDAP in order to allow OnBase to locate a particular
user and its associated groups on the server.
Note: Disabled LDAP users should also be removed from any LDAP group that is mapped to an
OnBase User Group.
Setting Description
LDAP Class Name The name of the objectClass within the directory that is used to
represent a user entry. This value varies, depending on how the network
is set up. The suggested values are user for Active Directory and
inetOrgPerson for NDS.
OnBase User Name The name of the attribute within the user entry objectClass that
Attribute corresponds to the user name within OnBase. The suggested values
are samAccountname for Active Directory and uid for NDS.
Note: Many configuration settings depend on how your network and

directory device are set up. For example, if a login uses first and last
names, the matching LDAP attribute for the OnBase User Name
Attribute field is Common Name or cn .
Fullname attribute The name of the attribute within the user entry objectClass that
corresponds to the user’s full name. This setting is optional and is used
to populate the User’s Real Name field in OnBase when a user account
is automatically created in OnBase using LDAP user data (see
Synchronize User Attributes on Auto-Logon on page 47).
The suggested values are name for Active Directory and givenname
for Netware eDirectory.

Setting Description
Email Address The name of the attribute within the user entry objectClass that
attribute corresponds to the user’s email address. This setting is optional and is
used to populate the User’s Email field in OnBase when a user account
is automatically created in OnBase using LDAP user data (see
Synchronize User Attributes on Auto-Logon on page 47).
Both Active Directory and Netware use mail for the Email Address
attribute value.
Group Mapping
Configure how a group entry is stored on the LDAP server in order to allow OnBase to locate the
user groups a user belongs to.
OnBase User Group.
Setting Description
LDAP Class Name The name of the objectClass that corresponds to a group entry. The
suggested values are group for Active Directory and groupOfNames for
NDS.
OnBase Group Name The name of the attribute within the group entry objectClass that
Attribute corresponds to the group name within OnBase. The suggested values
are samAccountname for Active Directory and uid for NDS . It is also
possible to use dn , but not all LDAP servers have an attribute that
matches dn .

User and Group Association

Configure how users and groups are associated on the LDAP server. Either the user entry
contains the list of associated user groups, or the group entry contains the list of associated
users.
OnBase User Group.
Setting Description
User/Group Association Select the class that contains the list attribute.
Attribute The name of the list attribute.
DN of User/Group Each attribute value within the list is expected to match the
distinguished name of the related entry.
Attribute of User/Group Each attribute value within the list is expected to match the
attribute in the Attribute of User/Group field.

Configuring Multiple LDAP Servers

Multiple LDAP servers can be configured for authentication. Once all the LDAP servers to
authenticate against have been added, they can be further organized into server groups with
Primary and Backup servers, using the options under the LDAP pane of the LDAP servers
dialog:
If more than one LDAP server is configured the first server in the list is used for authentication.
If that server fails or is disabled, the next server in the list is tried and the process continues
until a valid server is found or the list is exhausted.
Note: The next server in the list is only tried if the current server cannot be used. If a server is
valid but the login fails due to an invalid user name or password, no further authentication
attempts are made on the other servers.
Primary, Backup, and Disabled Servers

A server that is set as Primary marks the start of a new server group. Each server listed after a
primary server is considered a backup to that server, until the next primary server is
encountered, which marks the start of a new server group.
When organizing servers as primary or backup servers, the order of the servers in the list is
important, as the list is used to define server groups. A primary server should be followed by
one or more backup servers before the next primary server, such that the primary server and
the backup servers that follow it are considered one server group. To move a server up or down
in the list, select the server to move and click Move Up or Move Down , as appropriate.
When OnBase attempts to authenticate against the servers listed, the backup servers are only
searched if a connection cannot be made to the primary server for that server group. If a user
cannot be authenticated in a server group, the next server group is used to attempt
authentication. If a server is disabled, it is not included in authentication attempts.

Once a successful connection is made and the user is authenticated, the remainder of the
server groups are not searched.
• To make a server a primary server, select it from the list and right-click it. Select
Primary from the Type right-click menu options.
• To make a server a backup server, select it from the list and right-click it. Select
Backup from the right-click menu options.
Note: The first server listed is always considered a primary server, even if its Type is set to
Backup .
• To enable or disable a server, select it from the list and right-click it. Select Disabled
from the Status right-click menu options to disable it. Select Enabled to enable it.

Exhaustive Searches
When authenticating a user, OnBase does not search the remainder of the server groups once
the user is authenticated. To override this behavior and continue searching all server groups, in
order to determine a full list of the user’s user groups, select Exhaustive Search on the LDAP
Servers dialog.
With this option selected, OnBase continues to search the server groups for the user even after
the user has been authenticated.
Note: If a server is disabled, it is not searched for users even if Exhaustive Search is selected.
Whether a server is enabled or disabled is listed under the Status column. See Primary, Backup,
and Disabled Servers on page 41 to enable or disable a server.

Windows Integration and Trusted Domains

You can add trusted domains to authenticate against in the Windows Integration pane of LDAP
Servers dialog.
To add a trusted domain to the list, enter the domain name in the field at the bottom of the
Windows Integration pane and click Add . To delete a domain from the list, select it in the list
and click Delete .
To allow logins only for users in domains added to the trusted domains list, select Restrict
Autologon to Windows User in Trusted Domains . To allow authentication to all available
domains, deselect this option.

Interactive User Authentication

Select the Interactive User Authentication option to prompt users for network/domain
authentication credentials in order to log in to OnBase.
Note: This setting has no effect on single sign-on, PeopleSoft single sign-on, or AD FS logins.
This can be useful in situations where multiple OnBase users all use the same workstation
under the same domain log in (for example, a generic scanning workstation).
• Select Thick Client to require a log in to the OnBase Client and Configuration
modules.
• Select Core Services to require a log in to all Core-based modules.
Note: Anonymous access to the OnBase Web Server and Application Server virtual directories
should be enabled when Interactive User Authentication is enabled.
If Interactive User Authentication is not selected, users are not prompted to log in to OnBase
(non-interactive/automatic login). The domain account currently logged in to the workstation is
used to authenticate the user in OnBase.
Note: If Interactive User Authentication is disabled, additional configuration is required to

allow non-interactive/automatic logins for Active Directory. See Required Configuration
Settings for Non-Interactive Active Directory Authentication on page 54.
Active Directory Username Mapping Attribute

The Active Directory Username Mapping Attribute option is for use with Active Directory -
Enhanced or LDAP authentication methods.
The Active Directory Username Mapping Attribute option allows administrators to specify
which Active Directory attribute to correlate with the user names of the associated OnBase
user accounts. OnBase uses the value of the sAMAccountName attribute by default, but any
attribute that contains the user name values of the corresponding OnBase accounts can be
used.
Caution: The value of the Active Directory attribute configured as the Active Directory
Username Mapping Attribute must be unique across all Active Directory users and must be
populated for all Active Directory users. If an attribute with a non-unique value is used it is
possible that multiple Active Directory users will be mapped to a single user account in
OnBase.

For example, if user John Smith logs in to Windows as jsmith001 , then the value of the
sAMAccountName attribute is jsmith001 . However, his user name in OnBase is JSMITH , which
corresponds to the value of the displayName attribute in Active Directory. So in order for the
jsmith001 Active Directory account to be successfully mapped to the JSMITH OnBase user
account, the Active Directory Username Mapping Attribute must be set to displayName , not
sAMAccountName .
Note: The Active Directory Username Mapping Attribute value does not affect how users log
in using interactive mode (enabled by the Interactive User Authentication options). For
interactive mode logins, the user must always log in using their network/domain account name,
which is the value of the sAMAccountName attribute. After the user is authenticated in the
domain, OnBase uses the Active Directory Username Mapping Attribute to determine the user
name in OnBase.
Additional Information When Used with Active Directory

Enhanced
When OnBase is configured to use Active Directory - Enhanced as the Source of Security
Information , the Active Directory Security ID (SID) is always used to look up users in OnBase. If
a matching SID is found for a user in OnBase, that user is logged in to OnBase. In this case, if a
matching SID is found, the Username Mapping Attribute value is not used.
If a matching SID is not found, the Username Mapping Attribute value is used to match an
OnBase user name to an Active Directory user. The following logic is employed when looking up
users in this way:
• If a match is found between the OnBase user name and the Username Mapping
Attribute value, and the SID is not populated in OnBase for that user, the
corresponding SID is populated in OnBase for that user account. Future
authentications ignore the Username Mapping Attribute value because the SID is
used during user lookup.
Attribute value, and a SID is already populated for that user name in OnBase with a
SID that does not match the SID of the user currently logging in, then a new user
account is created in OnBase for the current user logging in, based on the SID of that
user. In this case, the Username Mapping Attribute value is populated as the user
name of the new user account in OnBase. Future authentications ignore the
Username Mapping Attribute value because the SID is used during user lookup. This
allows OnBase to support multiple domains that may have different users with the
same user name.
Note: In cases where a new user account is created and the Username Mapping Attribute
value matches an existing OnBase user name, a number is appended to the new user name in
OnBase (e.g., User, User2, User3, and etc.).

• If a match is not found between the OnBase user name and the Username Mapping
Attribute value, a new user account is created in OnBase based on the SID of the
user logging in. In this case, if a new OnBase user account is created, the Username
Mapping Attribute value is populated as the user name in OnBase. Future
authentications ignore the Username Mapping Attribute value because the SID is
used during user lookup.
Additional Considerations for LDAP Security

In order to use the Active Directory Username Mapping Attribute option with LDAP security
you must also edit the LDAP server settings to change the attribute for the user class that
maps to the OnBase user so that the LDAP attribute corresponds to the Active Directory
attribute being used.
When using LDAP, OnBase determines the currently logged-in Windows user and extracts the
specified Active Directory Username Mapping Attribute value ( sAMAccountName by default),
then uses that value to query the LDAP server for a matching user.
Synchronize User Attributes on Auto-Logon

Select the Synchronize User Attributes on Auto-Logon option to automatically update the
user’s OnBase account with changes made to the logged-in user’s real name, user name, or
email address in LDAP or Active Directory Enhanced since the last login. The default behavior
is to not update these attributes in OnBase.
Note: If the user’s real name, user name, or email is deleted, that attribute is not deleted from
OnBase. If updating the user name from the Active Directory user name would result in a
duplicate user name in OnBase, then the user name is not changed in OnBase.
To use this feature with LDAP, the LDAP configuration must include values for the Fullname
and Email Address attributes (see User Mapping on page 38).
Authentication Only on Auto-Logon

If this option is selected, LDAP and Active Directory Enhanced logins do not perform any group
membership synchronization with the external system. The external system is only used to
perform user authentication. All group membership configuration must be completed in
OnBase.
This means that OnBase no longer creates a new user account the first time a user logs in to
OnBase. In order to add the user to OnBase, an administrator must manually create the user
account.
Note: This setting does not affect the behavior of the Synchronize User Attributes on Auto-
Logon option.

Synchronizing Users and User Groups

Users and User Groups in OnBase can be synchronized with Active Directory and LDAP users
and groups.
See:
• Integrating User Groups with Domain User Groups on page 48
• Adding Users with LDAP on page 49
• Adding Users with Active Directory Enhanced on page 49
Integrating User Groups with Domain User Groups

To remove users from an OnBase User Group when they are removed from the corresponding
domain user group, in order to keep a one-to-one relationship between the domain and OnBase
User Groups, complete the following steps:
1. In the Configuration module, select User Groups/Rights from the Users menu. The User
Groups & Rights dialog box is displayed.
2. Select a user group from the list and click the Authentication Settings button. The
Authentication Settings dialog box is displayed.
3. Select Remove users from this group if no matching domain group found .
Note: The Remove users from this group if no matching domain group found option is not
available when OnBase is configured for Active Directory - Enhanced authentication. With
Active Directory - Enhanced authentication, this functionality is the default behavior.
4. Click OK .

With this option enabled, the OnBase User Group is checked against the corresponding domain
user group at log in. If the user logging in is a member of the OnBase User Group but is not a
member of the corresponding domain user group, the user is removed from that OnBase User
Group. Additionally, the user is removed from load-balanced Workflow queues they no longer
have access to because of their removal from OnBase User Groups, and their work is returned
to an unassigned state.
Caution: This option also removes users from OnBase User Groups if the user groups do not
exist on the domain. Make sure your OnBase User Groups have the same names as the
corresponding domain user groups. The group names do not need to have matching cases (for
example, AdminUsers is considered the same as adminusers or ADMINUSERS).
Adding Users with LDAP

When logging in to OnBase with a user name that doesn’t exist in OnBase, the user is
automatically added to OnBase as long as:
• The user is authenticated on the LDAP server
• The corresponding User Groups exist in OnBase.
Note: When a user that does not exist in OnBase first logs on to OnBase, the user must use a
Client of the same OnBase version as the OnBase database. If an older Client version is used,
users may not appear in the Configuration module even though they are added to OnBase.
When a user account is created in this way, the user’s email address and real name values are
populated in OnBase using the values from the domain. The user is also added to the OnBase
User Groups that correspond to the domain user groups that the user is a member of.
Note: If a User Template has been configured in OnBase, those user settings are applied to
new user accounts. See User Groups & Rights in the System Administration module reference
guide for details.
Adding Users with Active Directory Enhanced

When OnBase is configured to use Active Directory - Enhanced as the Source of Security
Information , the Active Directory Security ID (SID) is always used to look up users in OnBase. If
a matching SID is found for a user in OnBase, that user is logged in to OnBase.
If a matching SID is not found, the Active Directory Username Mapping Attribute value is used
to match an OnBase user name to an Active Directory user. The default value of the Username
Mapping Attribute is sAMAccountName , which is the Windows UserID attribute.

The following logic is employed when adding users in this way:

Attribute value, and the SID is not populated in OnBase for that user, the
corresponding SID is populated in OnBase for that user account.
Attribute value, and a SID is already populated for that user name in OnBase with a
SID that does not match the SID of the user currently logging in, then a new user
account is created in OnBase for the current user logging in, based on the SID of that
user. In this case, the Username Mapping Attribute value is populated as the user
name of the new user account in OnBase. This allows OnBase to support multiple
domains that may have different users with the same user name.
Note: In cases where a new user account is created and the Username Mapping Attribute
value matches an existing OnBase user name, a number is appended to the new user name in
OnBase (e.g., User, User2, User3 and etc.).
• If a match is not found between the OnBase user name and the Username Mapping
Attribute value, a new user account is created in OnBase based on the SID of the
user logging in. In this case, if a new OnBase user account is created, the Username
Mapping Attribute value is populated as the user name in OnBase.
Enabling Automatic Logins

The OnBase Client, Unity Client, and Web Client can all be configured to enable non-interactive/
automatic logins.
If Active Directory Enhanced or LDAP is enabled, users are automatically logged in to OnBase
without having to provide credentials, unless Interactive User Authentication is also enabled.
If Internal security is used or Interactive User Authentication is enabled, users are prompted
for their credentials when logging in to OnBase. If Active Directory Enhanced or LDAP is
enabled, the user must provide their network credentials. If Internal security is enabled, users
must provide their OnBase credentials.
Note: Service Accounts in OnBase cannot log in using non-interactive/automatic logins.
Standard Client
To enable automatic logins for the OnBase Client, append the -AL command line switch to the
OnBase Client and Configuration module shortcuts.
To add users to OnBase when the -AL switch is applied to the OnBase Client, user accounts
must be configured for Integrated Security Logon Only , which allows users to be created
without a password. For more information about this option, see the System Administration

OnBase Patient Window

The following procedure describes how to configure the OnBase Patient Window for autologin
using Active Directory authentication.
To configure the OnBase Patient Window for autologin:
1. Open the Web.config file from the PatientWindow directory.
2. Set EnableAutoLogin to true .
3. Clear the default_username and default_password values, if they are configured.
4. Save Web.config.
5. Open Internet Information Services (IIS) Manager by typing inetmgr in a Run dialog box
and clicking OK .
6. Navigate to the PatientWindow application in the Connections pane.
7. Double-click Authentication in the right pane.
8. Set Anonymous Authentication to Disabled .
9. Set Windows Authentication to Enabled .
10. Close IIS Manager.
Additional Active Directory Authentication Steps for Firefox

If the OnBase Patient Window is configured for autologin using Active Directory authentication,
Firefox users who access the application will be prompted for their credentials by the browser.
To allow Firefox users to access the OnBase Patient Window without being prompted, use the
following workaround.
Note: The following steps affect only the current workstation and the currently logged-on user.
For enterprise deployments, the specified settings would need to be modified in the pref.js file
found in each user’s Firefox profile. Consider using the tools described at the following site:
https://wiki.mozilla.org/Deployment:Deploying_Firefox#Deployment_Tools
To allow Firefox users to access the OnBase Patient Window without being prompted:
1. Open Firefox.
2. Type about:config into the address bar.
3. Click I accept the risk! if prompted.
4. Locate the following settings by typing trusted in the Search field provided:
• network.automatic-ntlm-auth.trusted-uris (for NTLM)
• network.negotiate-auth.trusted-uris (for Kerberos)
5. Double-click each setting and enter a comma-delimited list of trusted web servers. For
example:
srv-web001,srv-web002,srv-web003
When a Firefox user accesses the OnBase Patient Window through any of these servers,
the browser will not prompt the user for credentials.

6. Restart Firefox. If the user who logged on to the computer has permission to access the
OnBase Patient Window’s virtual directory, the browser will not prompt the user for
credentials.
Note: If you encounter the error HTTP Error 401.1 - Unauthorized: Access is denied due to
invalid credentials , see the Microsoft KB article located at the following URL:
http://support.microsoft.com/kb/871179
Note: To allow Mac users to log on using Active Directory authentication, you may need to
perform additional steps outside the scope of this documentation. Consult a Mozilla Firefox
reference source for more information.
Unity Client
To enable the Unity Client for LDAP or Active Directory Enhanced authentication for a service
location, you must set the AuthenticationType attribute in the service location node of the
Unity Client configuration file to NTAuthentication :
AuthenticationType="NTAuthentication"
This attribute is automatically set to NTAuthentication if you installed the Unity Client with NT/
LDAP Authentication enabled.
The Unity Client automatically logs in if there is only one service location configured. If there is
more than one service location configured for the Unity Client, the user must select the service
location to attempt an login for.
If this value is set to Standard , or if Core Services Interactive User Authentication option is
selected in the OnBase Configuration module, the Unity Client uses standard OnBase
authentication and the user is presented with a login dialog box. User accounts must be
configured in OnBase for any users who have to log on in this way.
Modifying Configuration Files

When UAC is enabled, administrators may be unable to modify Web.config or other *.config
files. To address this issue, the administrator should open a text editor (such as Notepad) by
right-clicking it and selecting Run as administrator . The administrator can then open the
*.config file from within the text editor. Because the text editor is running with administrator
privileges, the configuration file can be modified and saved using that application.
Web Client
To enable the Web Client for LDAP or Active Directory Enhanced authentication, you must set
the EnableAutoLogin key of the OnBase Web server’s Web.Config file to true : <add
key="EnableAutoLogin" value="true"/>
This attribute is automatically set to true if you installed the OnBase Web Server with the NT/
LDAP Authentication installer option selected.

If this value is set to false , the Web Client, and any modules that access OnBase using the Web
Server, prompts the user for OnBase credentials (interactive login). User accounts must be
configured in OnBase for any users who have to log in by supplying credentials.
Tip: See also, Additional Settings on page 60.
Modifying Configuration Files

When UAC is enabled, administrators may be unable to modify Web.config or other *.config
files. To address this issue, the administrator should open a text editor (such as Notepad) by
right-clicking it and selecting Run as administrator . The administrator can then open the
*.config file from within the text editor. Because the text editor is running with administrator
privileges, the configuration file can be modified and saved using that application.
Multiple Sites Configuration

If you need some modules to use LDAP or Active Directory Enhanced authentication and others
to use standard OnBase authentication to log in, two instances of the OnBase web server must
be installed to different virtual directories (e.g., http://web-server/AppNet1 and http://web-
server/AppNet2 ). One instance of the OnBase web server is then configured with the
EnableAutoLogin value set to true , meaning the LDAP or Active Directory Enhanced configured
for the data source is used to log in, while the other has it set to false , meaning standard
OnBase authentication is used to log in, regardless of the LDAP or Active Directory Enhanced
configuration.
Note: If this value is set to false , user accounts must be configured in OnBase for any users
who have to log in using standard OnBase authentication.
The modules are then configured to access OnBase using the appropriate OnBase web server
for the desired authentication method. Both OnBase web servers can still connect to the same
data source and will work together as one system.
Single Sign-On with Standard Authentication

Integration for Single Sign-On can be used with LDAP or Active Directory Enhanced
authentication.
To use Integration for Single Sign-On, set both the EnableAutoLogin and
forceSSOAutoLoginOverDomain web.config settings to true . These settings are described
below.

EnableAutoLogin
EnableAutoLogin - Set this value to true if LDAP, Active Directory - Enhanced, or Integration for
Single Sign-On is configured as the authentication method for logging in to OnBase. This
means the source of user credentials is not OnBase. If the configured authentication method is
also set to require interactive authentication, where the user must provide a user name and
password to log in, then the user must provide the expected credentials to log in to the Web
Client when EnableAutoLogin is set to true .
Note: If logins from the OnBase Web Client should use a single sign-on store for the source of
authentication credentials (even when OnBase is configured to use Active Directory -
Enhanced), the forceSSOAutoLoginOverDomain setting must also be set to true .
Set EnableAutoLogin to false to require interactive authentication using Internal security,

which requires the user to provide their OnBase user name and password to log in to the Web
Client, even when LDAP, Active Directory - Enhanced, or Integration for Single Sign-On is set as
the authentication method.
Internal security takes precedence over the configured authentication method, even when using
Integration for Single Sign-On. This can be useful for environments where users may need to
log in to OnBase with their own user name and password on a group workstation, or users do
not have credentials for Active Directory or LDAP.
forceSSOAutoLoginOverDomain
forceSSOAutoLoginOverDomain - Set this value to true when OnBase is configured for LDAP or
Active Directory - Enhanced authentication but single sign-on should be used for authentication
when OnBase is accessed using the Web Client.
If single sign-on is configured and forceSSOAutoLoginOverDomain is set to false , users must
log in to the Web Client using the authentication method configured in the Directory Service
Authentication settings (standard, LDAP, or Active Directory - Enhanced) with respect to the
EnableAutoLogin setting.
Required Configuration Settings for Non-Interactive

Active Directory Authentication
Additional configuration is required to maintain the authentication credentials of web
applications in OnBase when the following conditions are met:
• OnBase is configured to use Active Directory - Enhanced as the authentication
method
• OnBase is configured to use non-interactive/autologons

Non-interactive authentication is configured in OnBase by de-selecting the Interactive User

Authentication options in the Directory Service Authentication dialog box. When non-
interactive authentication is used, the domain account currently logged in to the workstation is
used to authenticate the user in OnBase.
Note: If Active Directory - Enhanced is not the authentication method configured, or

Interactive User Authentication is enabled, additional configuration is not required.
This section describes the additional configuration required in order to use non-interactive/
autologon Active Directory authentication with OnBase web applications, including the OnBase
Application Server.
To complete the additional configuration you must configure the Microsoft Windows
environment, configure the OnBase Application Server, and configure the web applications of
your OnBase modules.
These processes are described in the following sections:
• To configure the Microsoft Windows environment, see Registering a Service Principal
Name (SPN) and Configuring Delegation in Microsoft Windows on page 55.
• To configure the OnBase Application Server, see Configuring the Application Server
on page 56.
• To configure OnBase web applications, see, Configuring Web Applications on page
58.
Tip: Additional information may be available in the Directory Service Authentication

whitepaper, available from your first line of support.
Registering a Service Principal Name (SPN) and

Configuring Delegation in Microsoft Windows
Before configuring any OnBase web applications, you must first:
• Register a Service Principal Name (SPN) to a domain account in Microsoft Windows
• Set the registered SPN account to trust delegation in Active Directory
Note: The SPN only needs to be registered once for the HTTP service on the server, even
though a server may host one or more OnBase web applications.
The domain account that is registered as the SPN must be the same as the application pool
identity that is running all of the application pools for OnBase web applications on the server.

The SPN is registered using the Microsoft Windows Setspn command-line tool. To successfully
register the SPN, you must have domain administrative privileges on the server or be logged in
under a user account with those privileges delegated to it.
Note: Setspn is a Microsoft tool. For complete details on registering SPNs and using the
Setspn tool, see the documentation provided by Microsoft for Windows servers. The example
included in this section is for illustration purposes only.
For example, to register the SPN for the HTTP service, for fully qualified domain name
myserver.mydomain.net , to the application pool identity jdoe , type:
Setspn -s HTTP/myserver.mydomain.net mydomain\jdoe
After registering the SPN you must also set that user account to trust delegation. This is
configured in Microsoft Windows by launching the Active Directory Users and Computers
toolkit with elevated administrator privileges.
Note: Active Directory is a Microsoft product. Complete details on using and configuring Active
Directory can be found in the documentation provided by Microsoft.
In the Active Directory Users and Computers toolkit:

1. Navigate to the Users dialog.
2. Search for the domain account you registered the SPN to.
3. Open the properties for that account and select the Delegation tab.
4. Configure that account to trust delegation for services.
Note: It is considered a best practice to use constrained delegation by selecting Trust the user
for delegation to specified service only and selecting Use Kerberos only . However, if other
services are using the same account, this configuration may not always be possible. For more
information on constrained delegation, see the Kerberos Constrained Delegation information
available from Microsoft.
Configuring the Application Server

The OnBase Application Server can be optimized for non-interactive Active Directory
authentication using the Optimize for Windows Authentication tool in the Web Application
Management Console.
Note: Before configuring any OnBase web applications, ensure that the identity running the
application pool for the module is registered as the SPN. See Registering a Service Principal

To use the Optimize for Windows Authentication tool and configure the Application Server:
1. Launch the Web Application Management Console.
Tip: For complete details on installing and using the Web Application Management Console,
see the Web Application Management Console module reference guide.
2. Click Open Web Application in the upper left of the window.

3. Select the Application Server from the Select the web application to configure list.
4. Select Tools | Optimize for Windows Authentication .
5. Click Yes in the confirmation dialog that is displayed.
6. Save the configuration and close the Web Application Management Console.
7. In Microsoft Windows, launch the Internet Information Services (IIS) Manager with
elevated administrator privileges.
Note: IIS is a Microsoft product. Complete details on using IIS and the IIS Manager can be
found in the documentation available from Microsoft.
8. In the Sites area, configure the following settings for the web application of the OnBase
Application Server.
Setting Configuration
IIS | Authentication | Set to Enabled .

Anonymous Authentication
IIS | Authentication | ASP.NET Set to Disabled .

Impersonation
IIS | Authentication | Windows Set to Disabled .

Authentication
Note: Additionally, Negotiate must be at the top of the list of
providers. To access the providers list, right click Windows
Authentication and select Providers .
9. If the OnBase Application Server is hosted on a different server from the other OnBase
web applications, you must also complete the following configuration:
a. Under Management , launch the Configuration Editor for the web application of the
OnBase module.
b. From the Section drop-down list, navigate to the system.webServer/security/
authentication/windowsAuthentication path.
c. Set the value of useAppPoolCredentials to False .
10. Under the Default Web Site , expand the pages under the OnBase Application Server and
select the AuthService.asmx page.

11. Configure the following settings for the AuthService.asmx page.
IIS | Authentication | Set to Disabled .

IIS | Authentication | ASP.NET Set to Disabled .

Impersonation
IIS | Authentication | Windows Set to Enabled .

Authentication
12. In the Application Pools area, configure the following setting for the application pool of
the OnBase Application Server.
Process Model | Identity The domain account you registered the SPN to (see
Registering a Service Principal Name (SPN) and Configuring
Delegation in Microsoft Windows on page 55).
13. Recycle the application pool of the OnBase Application Server for the changes to take
effect.
Tip: To configure the OnBase web applications that use the Application Server, see Configuring
Web Applications on page 58.
Configuring Web Applications

A web application is any OnBase module installed to IIS that presents a web-based interface to
the user. This includes, but is not limited to, modules such as the OnBase Web Server,
DeficiencyPop, and the OnBase Patient Window.
If a module requires the OnBase Application Server to connect to OnBase but is not installed to
IIS, that module does not require additional configuration as long as the Application Server is
configured correctly (see Configuring the Application Server on page 56). This includes
modules like the OnBase Unity Client.

Several OnBase modules can be optimized for non-interactive Active Directory authentication
using the Optimize for Windows Authentication tool in the Web Application Management
Console.
Note: Before configuring any OnBase web applications, ensure that the identity running the
application pool for the module is registered as the SPN. See Registering a Service Principal
To use the Optimize for Windows Authentication tool and configure a web application:
1. Launch the Web Application Management Console.
Tip: For complete details on installing and using the Web Application Management Console,
see the Web Application Management Console module reference guide.
2. Click Open Web Application in the upper left of the window.

3. Select the module from the Select the web application to configure list. The
configuration for that module is loaded into the Web Application Management Console.
Note: If the OnBase module you are configuring is not in the list, it cannot be optimized using
the Web Application Management Console. You may need to manually change the settings
described in the remainder of this procedure.
a. Click Tools | Optimize for Windows Authentication .

b. Click Yes in the confirmation dialog that is displayed.
4. Save the configuration and close the Web Application Management Console.
5. In Microsoft Windows, launch the Internet Information Services (IIS) Manager with
elevated administrator privileges.
Note: IIS is a Microsoft product. Complete details on using IIS and the IIS Manager can be
found in the documentation available from Microsoft.
6. In the Sites area, confirm that the following settings for the web application of the
OnBase module are configured correctly.
IIS | Authentication | Set to Enabled .

Note: For some OnBase modules this setting may need to
be set to Disabled . However, this is not the preferred
configuration because setting it to Disabled may cause
performance issues.

IIS | Authentication | ASP.NET Set to Enabled .

Impersonation
Note: Additionally, the Impersonation setting must be set to
Authenticated User .
IIS | Authentication | Windows Set to Enabled .

Authentication
7. Under Management , launch the Configuration Editor for the web application of the
OnBase module.
8. From the Section drop-down list, navigate to the system.webServer/security/
authentication/windowsAuthentication path.
9. Set the value of useAppPoolCredentials to True .
10. In the Application Pools area, confirm that the following setting for the application pool
of the web application is configured correctly.
Process Model | Identity The domain account you registered the SPN to (see
Registering a Service Principal Name (SPN) and Configuring
Delegation in Microsoft Windows on page 55).
11. Recycle the application pool of the OnBase module for the changes to take effect.
12. Repeat this process for each OnBase web application in your environment.
Tip: To configure the OnBase Application Server, see Configuring the Application Server on
page 56.
Additional Settings
The following sections contain information on additional settings related to standard
authentication.

Enforcing User Password Security

Password security is configured and primarily enforced using password policies, which are
sets of rules designed to enhance the security of user passwords in your OnBase solution. A
password policy forces users to create and use passwords that conform to the configured
rules. A default password policy is applied globally to all User Groups in your OnBase solution.
Additional password policies are then defined to support OnBase User Groups that require
more restrictive password policies. For example, a User Group with access to confidential
business documents should have a more restrictive password policy than User Groups without
access to confidential business documents.
See the following sections for more information on configuring password policies. In rare
circumstances, it may be necessary to reset all user passwords. For more information on this
action, see Resetting All User Passwords on page 73.
Note: Password policies are only enforced for Normal System Security authentication. With
Active Directory or LDAP authentication, only the Lockout After Idle <n> Days Password Policy
setting is respected.
Understanding System Password Policies

With each OnBase installation, two pre-defined password policies are created by default to help
establish good security practices. The High Security policy is created as the recommended
level of security, and the Medium Security policy is applied as the default password policy if no
default password policy is defined for your system. These policies cannot be modified or
deleted.
The Medium Security policy enforces the following rules:
• Passwords must be a minimum length of 8 characters
• No more than 2 characters can be repeated consecutively
• Passwords expire the first time users log on
• Accounts are locked after 5 failed attempts to log on
• Locks on accounts with too many failed attempts to log on are released after 15
minutes
• Accounts are locked after they are idle for 180 days
The High Security policy enforces the following rules:
• User names cannot be embedded in passwords
• Passwords must be a minimum length of 15 characters
• No more than 2 characters can be repeated consecutively
• Passwords cannot be reused within 5 password changes
• Passwords cannot be changed more than once within 24 hours
• Passwords expire every 180 days
• Passwords expire the first time users log on

• Accounts are locked after 5 failed attempts to log on

• Administrators must manually release locks on accounts with too many failed
attempts to log on
• Accounts are locked after they are idle for 60 days
Password Policies for Importing and Exporting Configuration Items

Configuration items can be exported from one database and imported into another database
using the Configuration Import/Export Wizards. Items are exported to an export package, which
is then imported to another database. Password policies can be applied to the passwords used
to import and create export packages, though not all policy settings apply to export package
passwords.
If you are creating export packages and want to enforce a password policy for them, a separate
export password policy should be created that reflects its intended use. The following items
should be noted for export package passwords:
• Passwords must be at least 14 characters in length. If a password policy is being
used that requires fewer than 14 characters, the export cannot be completed.
• The Rotation , Change Frequency , and Account Lockout options are not enforced on
export package passwords. Complexity and Content Quotas settings are enforced.
Creating a Password Policy

Note: Password policies are only enforced for standard OnBase authentication. With Active
Directory or LDAP authentication, only the Lockout After Idle <n> Days Password Policy setting
is respected.

To create a password policy:

1. Select Users | Password Policies .
2. The Password Policies dialog box is displayed:
3. Right-click and select New Policy or select the New Policy toolbar button:

4. The Password Policy dialog box is displayed:
5. Type a unique name for the password policy in the Policy Name field.
6. Type a description of the password policy in the Description field.

7. Configure the remaining settings in the Password Policy dialog box. These settings are
described in the tables below.
Note: For settings that include a text field, the number entered in the text field must be greater
than 0 .
Use a combination of options in the Password Policy dialog box to create a restrictive
password policy. For example, select all four check boxes in the Content Quotas
section. Use a value of 3 for Require <n> Alphabetic Characters , Require <n> Numeric
Characters , and Require <n> Special Characters . Use a value of 2 for Satisfy at Least
<n> Quota Rules . Select the Maximum Overall Length check box and specify a value of
6 . In this example, the Maximum Overall Length setting works together with the
Content Quotas settings to provide a restrictive password policy.
Complexity Description
Require Alphanumeric Characters When selected, the password can only contain
Only alphanumeric characters (letters and/or numbers).
Disallow Embedded User Name When selected, the password cannot contain the user’s
OnBase user name.
Maximum Repeated Consecutive When selected, the number in the corresponding text
Characters field is the maximum number of repeated consecutive
characters that the password can contain.
For example, if this number is set to 2 , password is an
allowable password, while passsword is not allowed.
Common Substring Maximum When selected, the number in the corresponding text
Length field is the maximum number of common, consecutive
characters that can be reused in a new, user-entered
password.
For example, if this number is set to 3 , and the current
password is PASS123 , a new user-entered password
could be PAS3210 or 0123PAS but could not be, for
instance, PASS321 or 123PASS . Since PASS
represents more than three common, consecutive
characters between the old password and new password,
PASS cannot be used anywhere in the new password.
Maximum Overall Length When selected, the number in the corresponding text
field is the maximum number of characters that the
password can contain.
Minimum Overall Length When selected, the number in the corresponding text
field is the minimum number of characters that the
password can contain.

Content Quotas Description
Require <n> Alphabetic Characters When selected, the number in the corresponding text
field is the minimum number of alphabetic characters
that the password must contain.
Require <n> Numeric Characters When selected, the number in the corresponding text
field is the minimum number of numeric characters that
the password must contain.
Require <n> Special Characters When selected, the number in the corresponding text
field is the minimum number of special characters that
the password must contain.
Special characters are the following characters: ~ ` ! @ #
$%^&*()_-+=[{]}\|;:'",<.>/?
Require <n> Uppercase Characters When selected, the number in the corresponding text
field is the minimum number of uppercase characters
Require <n> Lowercase Characters When selected, the number in the corresponding text
field is the minimum number of lowercase characters
Satisfy at Least <n> Quota Rules When selected, the number in the corresponding text
field is the minimum number of configured Content
Quotas that the password needs to satisfy to be
considered a valid password. This number must be less
than the number of configured Content Quotas .
For example, a password policy requires that passwords
include five alphabetic characters and five special
characters. The Satisfy at Least <n> Quota Rules
setting is set to 1 . In this example, the following
passwords all satisfy the configured Content Quotas :
• Keyword
• 12345
• Keyword12345
Note: The MANAGER and ADMINISTRATOR User Groups are exempt from Rotation settings.

Rotation Description
Prevent Reuse When selected, previously used passwords cannot be

reused.
Note: This setting cannot be used in conjunction with the

Prevent Reuse Within <n> Changes or Prevent Reuse
Within <n> Days settings.
Prevent Reuse Within <n> When selected, previously used passwords can be reused.
Changes The number in the corresponding text field is the minimum
number of password changes that must occur before a
previously used password can be reused.
For example, a password policy dictates that when users
change their password, the new password cannot match
one of their previous four passwords. In this example, the
Prevent Reuse Within <n> Changes setting should be 4 .
Prevent Reuse Within <n> Days When selected, previously used passwords can be reused.
The number in the corresponding text field is the minimum
number of days that must pass before a previously used
password can be reused.
Change Frequency Description
Require <n> Hours Between When selected, the number in the corresponding text field
Changes is the minimum number of hours that must pass before a
password change is required.
Tip: Use this setting to prevent users from changing their

password and then immediately changing it again.
Expires Every <n> Days When selected, the number in the corresponding text field
is the number of full days that must pass before the
password expires. For example, if you enter 1 , the
password expires at the end of the day after the password
is changed.
Expires on First Use When selected, newly assigned passwords expire after they
are used once (e.g., if an administrator assigns a generic or
random password to a user, the user is prompted to change
the password upon first logging on to OnBase). Users are
not prompted to change passwords on subsequent logins.
Note: The Require <n> Hours Between Changes option

is not enforced when Expires on First Use is selected.

Account Lockout Description
Lockout After <n> Failed Logins When selected, the number in the corresponding text field
is the number of invalid login attempts that can occur
before a user is locked out of OnBase.
Manual Release by Admin When selected, users locked out of OnBase because they
reached the specified number of invalid login attempts
can only be unlocked manually.
Auto-Release After <n> Minutes When selected, the number in the corresponding text field
is the number of minutes that will elapse before unlocking
users locked out of OnBase because they reached the
specified number of invalid login attempts.
Lockout After Idle <n> Days When selected, the number in the corresponding text field
is the number of days a user can go without logging into
OnBase before being locked out of OnBase.
Note: This setting is also respected by Active Directory

and LDAP authentication methods. The MANAGER and
ADMINISTRATOR User Groups are exempt from the
Lockout After Idle <n> Days setting.
8. Click OK .
Before saving the selected password policy settings, OnBase verifies that no mutually
exclusive settings are selected. If OnBase detects mutually exclusive settings, you are
prompted to change them before you will be able to save the configured password
policy.
For example, you select Prevent Reuse and Prevent Reuse Within <n> Days . These
settings are mutually exclusive. After clicking OK to save this configuration, you are
prompted to re-configure these settings before you can save the password policy. You
must deselect one of these settings before you can save the password policy.

9. The Password Policies dialog box displays the password policy that you created:
10. If necessary, use the following toolbar buttons and right-click options to edit or delete
existing password policies:
Toolbar Right-Click Option Description

Button
Edit Policy Click to edit the selected password policy.
Delete Policy Click to delete the selected password policy.
Copying Password Policies

Existing password policies, such as the two system password policies, can be copied to create
a new password policy based on the configuration settings of the original password policy.

To copy a password policy:

2. The Password Policies dialog box is displayed:
3. Right-click and select Copy Policy or select the Copy an Existing Policy button:

4. The Password Policy dialog box is displayed:
5. Enter a name for the new password policy in the Policy Name field. Edit the text in the
Description field for the new policy.
6. The new password policy is automatically configured with the same settings as the
original password policy. Edit these settings as desired, then click OK .
Organizing Password Policies

After you have created and configured all of the password policies that will be used in your
OnBase solution, you must define the default password policy for your OnBase solution. This
default password policy applies to all User Groups in your OnBase solution. If no default
password policy is assigned, the Medium Security password policy is set as the default.
After defining the default password policy, you must also define the order of precedence that
password policies are applied to users. The order precedence is used when determining which
password policy to use when a user is associated with multiple password policies. A user can
be associated with more than one password policy because they belong to more than one User
Group.

To define the default password policy and order of precedence in the Password Policies dialog
box:
1. Select the password policy that you want to be the default password policy for your
OnBase solution.
2. Click the Set System Default Password Policy button:
3. The selected password becomes the default password policy for your OnBase solution:
4. Verify that the password policies for your OnBase solution appear in the proper order of
precedence in the Precedence column:
Precedence Description
Highest The password policy is the highest precedence in your OnBase solution.
The password policy is between the highest and lowest precedence in your
OnBase solution.
Lowest The password policy is the lowest precedence in your OnBase solution.

5. To change the precedence of a password policy, select the policy and use one of the
following buttons:
Precedence Description
Click to increase the precedence of a password policy.
Click to decrease the precedence of a password policy.
6. After you have finished configuring the order of password policy precedence, click
Close to save the order and close the Password Policies dialog box.
7. See User Group Configuration for Password Policies on page 1 for information on
applying password policies to specific User Groups.
Resetting All User Passwords

In some instances, it may be necessary to reset all user passwords, forcing users to create new
passwords the next time they attempt to log in. For example, you may decide to reset all user
passwords if you change a password policy and would like the policy to be immediately
enforced. It may also be necessary to reset all user passwords if a breach in system security is
discovered or suspected.
Caution: When performing a global password reset, the password for any user accounts
configured to run OnBase as a Windows service must be changed manually.
To reset all user passwords, you must use the -ROMANZO switch.
the feature and implications of any changes to your system. Contact your service provider with
any questions regarding these features. Features enabled by the -ROMANZO switch should not
be made available to the casual user. Remove the -ROMANZO switch after completing
necessary actions.

To reset all user passwords:

1. Ensure the -ROMANZO switch is enabled.
The Password Policies dialog box is displayed.
3. Click the Global Password Reset button.

You are prompted to confirm that you want to force all users to change their passwords
upon their next login.
Note: This action does not affect the MANAGER or ADMINISTRATOR user accounts.
4. Click Yes to reset all user passwords.

Click No to cancel the action.
Upon logging in to OnBase, users are notified they must change their passwords.
Additional Setting for the Web Server

When using LDAP or Active Directory Enhanced authentication with the OnBase Web Server, the
AllowNTAuthenticationOnForwarding attribute in the web.config file of the OnBase Web server
must be set to true . If NT/LDAP authentication is configured for the OnBase Web server during
its installation, this attribute is already set to true .

When using LDAP or Active Directory Enhanced authentication with the Web Client you must
make sure anonymous access to the virtual directories for the OnBase Web and Application
Servers is disabled. This is disabled by default when the servers are installed, if you select to
use NT/LDAP Authentication during installation.
Note: Anonymous access to the Web Server and Application Server virtual directories should
be enabled when Interactive User Authentication is enabled.
The Web server must also be added to the Local intranet zone in Microsoft Internet Explorer.
Zones are configured in Internet Explorer by selecting the Security tab of the Internet Options
(available from the Tools menu). You must also Enable the following Security settings:
• Automatic prompting for file downloads
• File download
• Font download
You must also ensure that User Authentication is set to either:
• Automatic logon in Intranet zone
• Automatic logon with current user name and password
For complete details on adding and configuring sites in the Local Intranet Zone, see the
Microsoft Internet Explorer help files.
Setting Access to the Application Pools

To use Active Directory Enhanced authentication, it is recommended that access to the
application pools is set to use the Network Service account and the applications running in the
application pool are configured to use impersonation. The impersonation account should be a
member of the Account Operators group (i.e., have the Account Operator right).
If you are using Active Directory Enhanced authentication and alternate binding credentials are
specified, then the alternate binding credentials should have the Account Operator right.
Note: Depending on the network configuration, the application pools need multiple rights to get
group information for a user from all relevant domains. In most situations the Account
Operators group has sufficient rights to perform this task. Your network administrator can
determine a viable alternative to the Account Operators group if it lacks sufficient rights.
To assign a user to the application pools:

1. Click Start , then right-click My Computer and select Manage to enter the Computer
Management console.
2. Click the plus sign next to Services and Applications .
3. Click the plus sign next to Internet Information Services .
4. Click the plus sign next to Application Pools .
5. Select the Application Pool that the OnBase virtual directory you are configuring uses
( AppNet is the default virtual directory for the OnBase web server; AppServer is the
default virtual directory for the application server).
6. Right-click and select Properties .

7. Click the Identity tab.

8. Select the Configurable radio button.
9. Enter the User name and Password for the user you want this application pool to use.
10. Click OK .
11. Select File | Exit to exit Computer Management .
Repeat this process for both the OnBase web and application servers, if both servers are
installed.
Opening Multiple Web Client Sessions

If the web browser is set to reuse windows for launching shortcuts, and you have only one
window open with the OnBase Web Client, then relauching the Web Client from a shortcut
automatically disconnects you from your current session and a new connection is established
in your current window.
If you are already logged in to the OnBase Web Client and attempt to initiate another session in
a new browser window, then the Another OnBase session is currently active dialog is
displayed.
• Select Close this session and continue using the active session to close the new
session and leave the existing session open.
• Select Close the active session and continue logging in here to close the active
session and continue with the new session. If non-interactive/automatic logins are
enabled, the user is logged in automatically.

C ONFIGURING A CTIVE DIRECTORY FEDERATION S ERVICES
(AD FS)
Overview
The OnBase Web Server can be configured to use Microsoft Active Directory Federation
Services (AD FS) authentication, allowing users to authenticate in OnBase using the Web Client
or Unity Client using their Active Directory credentials.
Authentication using AD FS requires:

• The OnBase Web Server and Application Server
• An AD FS server
• User access through the OnBase Web or Unity clients
In order to enable AD FS authentication for OnBase, the configuration described in this chapter
must be completed. When correctly configured, the client authentication request is redirected
to the AD FS server, which validates the user credentials (based on the NameID value) and the
source of the redirect, and provides a Security Assertion Markup Language (SAML) token. The
SAML token is then passed to the Web Server by the client, allowing the Application Server to
process the authentication request with OnBase.
Note: The SAML token is a SAML 1.1 token.
Certificates Used and Key Locations

The following certificates are used by OnBase or AD FS to complete authentication. Make sure
you have the required certificates before attempting configuration.
• AD FS SSL: The SSL certificate used by IIS on the AD FS server to encrypt traffic. It is
required. The private key resides on the AD FS server, and the OnBase Web Server
and the client machine must trust the issuer (ROOT CA) of the certificate.
• Token Encryption: The certificate used by AD FS to encrypt the token sent to the
client. It is not required but it is recommended.
• Token Signing: The certificate used by AD FS to sign SAML tokens. It is required. The
the public key resides on the OnBase Web Server.

Configuring Active Directory Federation Services (AD FS)
• Request Signing: The certificate used by OnBase to sign the request sent to the AD
FS server. It is not required but it is recommended.
• Web Server SSL: The SSL certificate used by IIS on the OnBase Web Server to
encrypt traffic. It is required. The private key resides on the OnBase Web Server, and
the AD FS server and the client machine must trust the issuer (ROOT CA) of the
certificate.
Note: OnBase using AD FS authentication does not support CNG (Cryptographic Next
Generation) certificates.
All certificates should be in the local computer account. If the OnBase Application Server is on
a different machine from the OnBase Web Server, the certificates on both servers must match.
All private keys should be stored in the Local Computer\Personal certificate store. Private keys
in that store should have a matching public key stored in either the Local Computer\Trusted
Root Certification Authorities or Local Computer\Trusted People certificate stores. All other
public keys should be stored in the Local Computer\Trusted People certificate store.
The Application Pool Identity account or impersonation account configured for the servers
requires Read access to the certificates.
Certificate thumbprints are used to correctly identify the certificate to use for communication.
The thumbprint value can be found in the certificate manager.
Licensing
In order to use AD FS Authentication, you must be licensed for Single Sign-On for Microsoft
Active Directory Federation Services .
The following information is specific to configuring Active Directory Federation Services (AD
FS).
General Considerations — When the OnBase Web and Application Servers are upgraded, the
web.config files of the servers are replaced, which means the previously configured AD FS
instance is removed.

Before upgrading, the web.config files of the servers should be backed up. The AD FS
configuration information can be copied from the backup of the previous versions of the
web.config files into the upgraded versions. In most cases, additional reconfiguration is not
required as long as the certificates did not change.

Web application.
application.
Configuration
The following configuration must be completed in order to use AD FS Authentication with
OnBase:
• Configuring the AD FS Server on page 80
• Configuring the Application Server for AD FS on page 82
The following section describes how to remove users from an OnBase User Group when they
are removed from the corresponding domain user group:
• Integrating With Domain User Groups on page 86
If you are also configuring the OnBase Web Server to use AD FS Authentication, see:
• Configuring the Web Server for AD FS on page 83
The following modules also require additional configuration to use AD FS authentication:
• Configuring the Unity Client, MRM Unity Client, and Office Business Application for
AD FS on page 87
• Configuring Disconnected Scanning for AD FS on page 88
• Configuring Patient Window for AD FS on page 89

Web application.

application.
Configuring the AD FS Server

In order for the AD FS server to integrate with OnBase you must establish a trust between
OnBase and the AD FS server. This trust is configured on the AD FS server using the Add
Relying Party Trust Wizard . You must also define the AD FS endpoints for the integration to
function.
See:
• Adding a Relying Party Trust on page 80
• Configuring AD FS Endpoints on page 82
Note: The instructions in this section refer to third-party software and are included for
illustration purposes only. Detailed instructions on how to configure AD FS are available from
Microsoft.
Adding a Relying Party Trust

Note: The following instructions refer to third-party software and are included for illustration
purposes only. Detailed instructions on how to configure AD FS and use the Add Relying Party
Trust Wizard are available from Microsoft.
1. Access the Add Relying Party Trust Wizard on the AD FS server.

2. Under data source configuration, select the option to enter data about the relying party
manually.
3. Name the trust with a specific name that clearly identifies what resource this trust is
for.
4. When prompted to choose an AD FS profile, select AD FS 2.0 or AD FS 3.0 , depending
on your server.
5. Under certificate configuration, click Browse to add a certificate and select the Token
Encryption Certificate of the OnBase server you are establishing trust with.
6. Under URL configuration, select the option to enable support for the WS-Federation
Passive protocol.
7. Enter the URL of the OnBase Web Server as the relying party WS-Federation Passive
protocol URL. This is the fully qualified domain of the OnBase Web Server, for example
https://my.domain.com/AppNet/
Note: The URL value is case sensitive. Make sure to include the trailing slash on the URL.

8. Under identifiers configuration, add the same URL you configured as the relying party
WS-Federation Passive protocol URL.
Note: The URL value is case sensitive. Make sure to include the trailing slash on the URL.
9. Permit all users to access this relying party for the issuance authorization rules.
Note: AD FS 3.0 includes multi-factor authentication. Multi-factor authentication is supported

by OnBase and there are currently no additional configuration steps needed to integrate multi-
factor authentication with OnBase.
10. At the verification screen, verify that the Encryption tab contains the encryption
certificate and that the Endpoints tab is configured with the URL of the OnBase Web
Server.
Note: If an encryption certificate was not provided for you to use, any trusted third-party
encryption certificate can be used as long as the OnBase Web and Application Servers have the
private key of that certificate installed in the LocalMachine\Personal store.
11. After configuring the relying party you must add a claim rule.
Note: All listed claims must be configured with a claim rule in order to enable proper
authentication.
12. Select Send LDAP Attributes as Claims rule template for the rule type.
13. Give the claim rule a descriptive name.
14. Select Active Directory as the attribute store.
15. Use the following table to map the LDAP attributes to outgoing claim types:
LDAP Attribute Outgoing Claim Type
User-Principal-Name Name ID
Note: The domain is stripped from the User-Principal-

Name (UPN) value. The UPN can only be used if domain
information is already configured in OnBase by using
AD FS authentication along with AD Enhanced or LDAP
authentication.
Display-Name Name
Token-Groups – Unqualified Names Role
E-Mail-Addresses E-Mail Address

Configuring AD FS Endpoints
The following points should be noted when configuring AD FS endpoints for use with OnBase:
• OnBase only supports Windows authentication and the Transport security mode.
• OnBase supports WSTrustFeb2005 .
• The adfsEndpointAddress selection is based on the trust version, authentication
type, and security mode configured.
Configuring the Application Server for AD FS

To configure the OnBase Application Server for AD FS you must edit the Web.config file of the
Application Server. The Web.config file can be edited using the Web Application Management
Console. For complete details on using the Web Application Management Console, see the Web
Application Management Console module reference guide.
Note: The OnBase Application Server virtual directory should be configured for anonymous
authentication since the identity of the user might not be within the domain of the server.
To configure the Application Server for AD FS:

1. Create a backup copy of the Web.config file. This will allow you to easily rollback any
changes you make.
2. Launch the Web Application Management Console and ensure that the Application
Server you are configuring is loaded.
3. Select the ADFS Settings tab.
4. Select Configure for ADFS from the Tools menu. This adds the required elements to the
Web.config file and populates the default values.
5. Ensure that ADFS Enabled is selected.
6. Ensure that the value of Request Validation Mode is 2.0 .
7. Under the system.identityModel settings, update the following values to match your
environment:
• Audience URI: The value of the Relying Party Trust Identifier as configured on the AD
FS server. This value must match exactly what the AD FS server has.
• Trusted Issuer Thumbprint: The value of the thumbprint of the Token Signing
Certificate.
• Trusted Issuer Name: The value of the name of the Federation Service Identifier.
Tip: The Trusted Issuer Thumbprint and Trusted Issuer Name values can be found in the
Microsoft AD FS administration utility.
8. Under the system.identityModel.services settings, update the following values to

match your environment:
• wsFederation Issuer: The value of the issuer attribute to your AD FS server.
• wsFederation Realm: The value of the realm attribute. This must match exactly the
Relying Party identifier as configured on the AD FS server.

• Certificate X509FindType: The value of the attribute that the Certificate Find Value
is referencing. Set this value to FindByThumbprint .
• Certificate Find Value: The value of the thumbprint of the encryption certificate used
when adding the relying party trust.
Tip: The Certificate Find Value thumbprint can be found in the Microsoft AD FS administration
utility. It is the same as the previous thumbprint value used in the Trusted Issuer Thumbprint
field.
• Certificate Store Location: The value that corresponds to where the certificate can
be found. Possible values are CurrentUser and LocalMachine . The default value is
LocalMachine .
• Certificate Store Name: The value that corresponds to the store name where the
referenced certificate can be found. The default value is My . Possible values are:
• AddressBook
• AuthRoot
• CertificateAuthority
• Disallowed
• My
• Root
• TrustedPeople
• TrustedPublisher
9. Select Save from the File menu to save your changes, or press Ctrl + S on the keyboard.
Configuring the Web Server for AD FS

To configure the OnBase Web Server for AD FS you must provide an HTTPS certificate and edit
the Web.config file of the Web Server. See:
• HTTPS Certificate on page 83
• Editing the Web.config File of the Web Server on page 84
Note: The OnBase Web Server virtual directory should be configured for anonymous
HTTPS Certificate
Before the Web Server can be configured for AD FS, you must either create or import an HTTPS
certificate for the Web Server. In an internal test environment, a self-signed certificate can be
generated in the Windows Internet Information Services (IIS) Manager. In any other
environment, the more secure option of an imported HTTPS certificate generated by a
certificate authority is preferred.

Create an HTTPS binding for your Web Server and the HTTPS certificate.
Note: This process can be repeated for your Application Server, but it is not required.
Editing the Web.config File of the Web Server

To configure the OnBase Web Server for AD FS you must edit the Web.config file of the Web
Server. The Web.config file can be edited using the Web Application Management Console. For
complete details on using the Web Application Management Console, see the Web Application
Management Console module reference guide.
Note: The OnBase Web Server virtual directory should be configured for anonymous
To configure the Web Server for AD FS:

1. Create a backup copy of the Web.config file. This will allow you to easily rollback any
changes you make.
2. Launch the Web Application Management Console and ensure that the Web Server you
are configuring is loaded.
3. Select the Web Client tab.
4. Ensure the Web Client is configured for secure connections by checking that the path in
the Virtual Directory field starts with https .
Note: If the value is using an http:// address, the server must be configured for secure
connections before changing this value to https:// . The URL in the value of the Virtual
Directory field should not include the trailing slash.
5. Select the Login tab.

6. Ensure that Auto Login is selected.
7. Select the ADFS Settings tab.
8. Select Configure for ADFS from the Tools menu. This adds the required elements to the
Web.config file and populates the default values.
9. Select None from the Authentication Mode drop-down list.
10. Ensure that ADFS Enabled is selected.
11. Ensure that Cookie Handler Require SSL is deselected.
12. Under the system.identityModel settings, update the following values to match your
environment:
• Audience URI: The value of the Relying Party Trust Identifier as configured on the AD
FS server. This value must match exactly what the AD FS server has.
• Trusted Issuer Thumbprint: The value of the thumbprint of the Token Signing
Certificate.

• Trusted Issuer Name: The value of the name of the Federation Service Identifier.
Tip: The Trusted Issuer Thumbprint and Trusted Issuer Name values can be found in the
Microsoft AD FS administration utility.
13. Under the system.identityModel.services settings, update the following values to

match your environment:
• wsFederation Issuer: The value of the issuer attribute to your AD FS server.
• wsFederation Realm: The value of the realm attribute. This must match exactly the
Relying Party identifier as configured on the AD FS server.
• Certificate X509FindType: The value of the attribute that the Certificate Find Value
is referencing. Set this value to FindByThumbprint .
• Certificate Find Value: The value of the thumbprint of the encryption certificate used
when adding the relying party trust.
Tip: The Certificate Find Value thumbprint can be found in the Microsoft AD FS administration
utility. It is the same as the previous thumbprint value used in the Trusted Issuer Thumbprint
field.
• Certificate Store Location: The value that corresponds to where the certificate can
be found. Possible values are CurrentUser and LocalMachine . The default value is
LocalMachine .
• Certificate Store Name: The value that corresponds to the store name where the
referenced certificate can be found. The default value is My . Possible values are:
• AddressBook
• AuthRoot
• CertificateAuthority
• Disallowed
• My
• Root
• TrustedPeople
• TrustedPublisher
14. Select Save from the File menu to save your changes, or press Ctrl + S on the keyboard.

Integrating With Domain User Groups

To remove users from an OnBase User Group when they are removed from the corresponding
domain user group, in order to keep a one-to-one relationship between the domain and OnBase
User Groups, complete the following steps:
1. In the Configuration module, select User Groups/Rights from the Users menu. The User
Groups & Rights dialog box is displayed.
2. Select a user group from the list and click the Authentication Settings button. The
Authentication Settings dialog box is displayed.
3. Select Remove users from this group if no matching domain group found .
Note: The Remove users from this group if no matching domain group found option is not
available when OnBase is configured for Active Directory - Enhanced authentication. With
Active Directory - Enhanced authentication, this functionality is the default behavior.
4. Click OK .
With this option enabled, the OnBase User Group is checked against the corresponding domain
user group at log in. If the user logging in is a member of the OnBase User Group but is not a
member of the corresponding domain user group, the user is removed from that OnBase User
Group. Additionally, the user is removed from load-balanced Workflow queues they no longer
have access to because of their removal from OnBase User Groups, and their work is returned
to an unassigned state.
Caution: This option also removes users from OnBase User Groups if the user groups do not
exist on the domain. Make sure your OnBase User Groups have the same names as the
corresponding domain user groups. The group names do not need to have matching cases (for
example, AdminUsers is considered the same as adminusers or ADMINUSERS).

Configuring the Unity Client, MRM Unity Client, and

Office Business Application for AD FS
Caution: When using the Click-Once Installer, AD FS must be configured before signing the
deployment. Any custom changes to the client configuration file must be made before clicking
Next at the Deployment Signing dialog box. If you are running the Click-Once Installer in
Advanced Mode , you still have the option to edit files in the deployment folder at the File Edit
Notification dialog box that is displayed after the Deployment Signing dialog box.
In order to configure the Unity Client, Medical Records Unity Client, or Office Business
Application add-ins to use AD FS Authentication, you must first set up the Application Server to
use AD FS.
After the Application Server has been configured for AD FS Authentication, the following steps
must be completed to configure the Unity Client, Medical Records Unity Client, or Office
Business Application add-ins to use AD FS Authentication:
1. Open the configuration file for the Unity Client, Medical Records Unity Client, or Office
Business Application add-in.
2. In the configSections node, ensure the Hyland.Authentication section is uncommented.
<section name="Hyland.Authentication"
type="Hyland.Authentication.Configuration.AuthenticationConfiguration
Section, Hyland.Authentication" />
3. In the ServiceLocations element, update the following attributes to these values:
UseNTAuthentication="false"
UseADFS="true"
4. Uncomment the system.web and Hyland.Authentication elements at the end of the
configuration file.
5. Locate the adfsEndpointAddress element and update its value to the URL for your AD
FS Server Endpoint.
6. Locate the appliesTo element and update its value to the match the audienceUris value
in the web.config file of the Application Server.
If the Unity Client, Medical Records Unity Client, or Office Business Application add-in needs to
authenticate via an AD FS proxy server that is not joined to the domain, the following additional
steps are necessary:
1. In the Unity Client Medical Records Unity Client, or Office Business Application add-in
configuration file, locate the Hyland.Authentication element.
2. Set the forceNTLM attribute in the wsTrust child element to true .
3. Make sure the trustVersion is set to WSTrustFeb2005 .
4. Make sure the adfsEndpointAddress reflects the address of the WSTrustFeb2005
endpoint. For example, https://My-ADFS-Server/adfs/services/trust/2005/
windowstransport

5. Make sure that the AD FS server is correctly configured to use NTLM. The following
settings should have the following values:
• ExtendedProtectionTokenCheck: none
• NTLMOnlySupportedClientAtProxy: true
Tip: For details on updating AD FS server and proxy settings, see the Set-ADFSProperties page
of the AD FS Cmdlets area on the Microsoft TechNet.
Configuring Disconnected Scanning for AD FS

In order to configure Disconnected Scanning to use AD FS authentication, you must first set up
the OnBase Web and Application Servers to use AD FS.
Tip: See Configuring the Application Server for AD FS on page 82 and Configuring the Web
Server for AD FS on page 83.
To configure Disconnected Scanning to use AD FS authentication:

1. Open the disconnectedscan.exe.config file in a plain-text editor.
Note: Do not use a binary-text editor, such as Microsoft Word, to edit the Web.config file.
2. In the configSections element, uncomment the Hyland.Authentication section, if it is

not already uncommented:
type="Hyland.Authentication.Configuration.AuthenticationConfiguration
Section, Hyland.Authentication" />
3. Uncomment the system.web element, if it is not already uncommented:
<system.web>
<webServices>
<soapExtensionTypes>
<add
type="Hyland.Authentication.ADFS.CustomCanvasADFSAuthSoapExtension,
Hyland.Authentication" />
</soapExtensionTypes>
</webServices>
</system.web>

4. Uncomment the Hyland.Authentication element, if it is not already uncommented:

<Hyland.Authentication>
<adfs enabled="true" logClientEventsToEventLog="true">
<wsTrust forceNTLM="false">
<adfsEndpointAddress></adfsEndpointAddress>
<securityMode>Transport</securityMode>
<trustVersion>WSTrustFeb2005</trustVersion>
<appliesTo></appliesTo>
</wsTrust>
</adfs>
</Hyland.Authentication>
5. Set the attributes of the adfs element to the following values:
• enabled: true
• logClientEventsToEventLog: true
6. Set the forceNTLM attribute of the wsTrust element to true or false .
• true: Authentication through the Application Server is done using an AD FS proxy
server that is not directly joined to the domain.
• false: Authentication through the Application Server is done directly with an internal
AD FS server.
7. Set the value of the adfsEndpointAddress element to the address on the AD FS server
for the 2005 transport endpoint. For example:
https://adfsserver.domain.com/adfs/services/trust/2005/windowstransport
(where adfsserver.domain.com is replaced with the address specific to your AD FS
server).
8. Set the value of the securityMode element to Transport .
9. Set the value of the trustVersion element to WSTrustFeb2005 .
10. Set the value of the appliesTo element to the match the audienceUris value in the
web.config file of the OnBase Web Server. For example: https://mydomain.com/
AppNet/ (where mydomain.com is replaced with the server hosting the Web Server).
Note: The appliesTo address must end with a trailing forward-slash: /
11. Save and close the disconnectedscan.exe.config file.
Configuring Patient Window for AD FS

Before configuring the OnBase Patient Window for AD FS, you must first create a separate
Relying Party Trust on the AD FS server for the OnBase Patient Window.
To configure the OnBase Patient Window for AD FS:
1. Create a backup of the OnBase Patient Window’s Web.config file.
2. Open the live Web.config file in a text editor.

3. Within the system.web element, uncomment the following sections:

<authentication mode="None" />
<authorization>
<deny users="?" />
</authorization>
4. Within the webServices element, uncomment the soapExtensionTypes element.
5. Within the system.webServer element, uncomment the following sections:
<add name="WSFederationAuthenticationModule"
type="System.IdentityModel.Services.WSFederationAuthenticationModule,
System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" />
<add name="SessionAuthenticationModule"
type="System.IdentityModel.Services.SessionAuthenticationModule,
System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" />
6. In the appSettings element, set EnableAutoLogin to true .
7. In the Hyland.Authentication element, set Enabled to true .
8. Uncomment the system.identityModel element. Configure the following settings within
this element:
a. Set the audienceUris value to the OnBase Patient Window address.
b. Within the trustedIssuers element, set the thumbprint value to the thumbprint of the
Token Signing Certificate. Set the name value to the name of the Federation Service
Identifier. These values can be found in the Microsoft AD FS administration tool.
9. Uncomment the system.identityModel.services element. Configure the following
settings within this element:
a. Within the wsFederation element, set the issuer value to your AD FS server address,
and the realm value to your OnBase Patient Window address.
b. Within the certificateReference element, set the findValue to the thumbprint of the
encryption certificate used when adding the relying party trust.
Tip: The thumbprint value can be found in the Microsoft AD FS administration utility. It is the
same as the previous thumbprint value used in the trustedIssuers element.
Configuring Studio for AD FS

To configure OnBase Studio for AD FS:
1. Open obstudio.exe.config in a text editor.
2. Within the system.web element, uncomment the following element:
<add

3. Uncomment the Hyland.Authentication element.

<adfsEndpointAddress>
https://<ADFS_SERVER>/adfs/services/trust/2005/
windowstransport</adfsEndpointAddress>
<appliesTo>http://mydomain.com/AppNet/</appliesTo>
</wsTrust>
</adfs>
4. Configure the settings in the Hyland.Authentication element to match the settings in
the Application Server configuration. These configurations must match exactly, or AD
FS authentication will fail. The configuration settings are case sensitive.
Configuring the Unity Management Console for AD FS

To configure the Unity Management Console for AD FS:
1. Open obmc.exe.config in a text editor.
2. Uncomment the following elements:
<system.web>
<webServices>
<add
</webServices>
</system.web>
<adfsEndpointAddress>https://<ADFS_SERVER>/adfs/services/
trust/2005/windowstransport</adfsEndpointAddress>
<appliesTo>http://mydomain.com/AppNet/</appliesTo>
</wsTrust>
</adfs>

3. Configure the settings in the Hyland.Authentication element to match the settings in

the Application Server configuration.
Note: These settings must match exactly the settings in the Application Server configuration
file, or AD FS authentication will fail. The configuration settings are case sensitive.
Configuring Report Services for AD FS

If Legacy Authentication Methods uses AD FS authentication, the application configuration file
of the Legacy Authentication Methods client ( ReportServices.exe.config ) must be updated to
enable AD FS.
Caution: If this is a ClickOnce deployment, any changes to the files in the deployment folder or
the contents of the deployment folder, such as custom changes to the
ReportServices.exe.config file, must be made before clicking Next at the Deployment Signing
dialog box.
To enable AD FS authentication for the Legacy Authentication Methods client:

1. Locate the ReportServices.exe.config configuration file. This file is located in the
Destination or Deployment Folder you set during installation.
2. Open the configuration file for editing in a plain-text editor, such as Notepad. Do not edit
this file in a binary editor, such as Microsoft Word. Binary editors can introduce invalid
characters to the configuration file.
3. Locate the configSections node and uncomment the section node for Hyland.ADFS .
4. Locate the ServiceLocations node under the Hyland.Services.Client node and ensure
that the following options are set for the add node of your service location:
• UseNTAuthentication="false"
• UseADFS="true"
Note: If the add node of your service location is commented out you must uncomment it to
enable it.
5. Locate and uncomment the system.web and Hyland.ADFS nodes.

6. Locate the wsTrust node under the Hyland.ADFS node.
7. Update the adfsEndpointAddress node to reflect the URL of your AD FS server endpoint.
8. Update the appliesTo node to reflect the URL of your OnBase Application Server.
9. Save and close the configuration file.
10. If this is a ClickOnce installation, ensure that all other changes to the deployment files
have been made then sign the deployment at the Deployment Signing dialog box.

Troubleshooting
Diagnostics information is written to the LDAP/NT and Trace logs in the OnBase Diagnostics
Console, as long as the service is configured to report trace information and the Diagnostics
Console is configured to receive it.
To configure LDAP/NT logging, enable ldap-profile logging in the web.config file of the OnBase
Application Server. To enable trace logging, set the hylandTrace setting in the web.config file
of the OnBase Application Server to 4 . For complete details, see the Application Server module
reference guide.
For details on configuring the Diagnostics Console to receive trace information, see the
Diagnostics Service and Diagnostics Console module reference guide.
Additional troubleshooting items are covered in the following sections:
• Logging Client Events to the Event Log on page 93
• Verbose Logging on the AD FS Server on page 93
• Common Errors Encountered When Using AD FS on page 93
Logging Client Events to the Event Log

Troubleshooting information for the clients that use the OnBase Application Server (such as
the Unity Client, Microsoft Outlook integrations, and Report Services Client) can be written to
the Application log in the Windows Event Viewer of the workstation running the client.
To enable logging to the Event Viewer you must edit the exe.config file of the client. Locate the
adfs child element of the Hyland.Authentication element and set the value of the
logClientEventsToEventLog attribute to true .
For more information, see the section for the client you are using under Configuration on page
79.
Verbose Logging on the AD FS Server

Verbose logging can also be configured on the AD FS server using the Set-ADFSProperties
command in Windows PowerShell. For more information on configuring the AD FS server, see
the documentation provided by Microsoft on configuring computers for troubleshooting AD FS.
Common Errors Encountered When Using AD FS

The following errors may be encountered when using AD FS and are typically resolved by the
solutions presented in the following sections:
• A SignInResponse message may only redirect within the current application on page
94
• Bootstrap Token was Empty on page 94
• Client found response content type of text/html, but expected text/xml on page 94
• Failed to connect. User '' does not belong to any user groups. on page 94
• HTTP 400 Bad Request on page 95

• Object not set for an instance of an object on page 95

• OEM Authentication Failed on page 95
• SAML Assertions are not included in token on page 95
• The issuer of the security token was not recognized by the IssuerNameRegistry on
page 95
• The same client browser session has made X requests in the last Y seconds. Contact
your administrator for details. on page 95
• The type initializer for Hyland.Canvas.CanvasClientConfiguration threw an exception
on page 96
• This page cannot be displayed on page 96
• Value cannot be null on page 96
• Web Client displays a login page on page 96
A SignInResponse message may only redirect within the

current application
This error can occur when the OnBase Web Server is accessed without the final slash in the
URL. For example, if you access https://my.web.server/AppNet you may encounter this error,
but if you access https://my.web.server/AppNet/ you should not (note the final / after
AppNet ).
Bootstrap Token was Empty

This error can occur when the forceNTLM setting in the wsTrust element of the client
application is configured incorrectly. If the client application uses a proxy or WAP server,
forceNTLM should be set to true . Some client applications also require this setting to be true .
See Configuration on page 79 for details on configuring the various OnBase clients to use AD
FS.
Client found response content type of text/html, but expected

text/xml
This error is reported in the Diagnostics Console when attempting to log in to the OnBase Web
Client. It can be encountered when the when the Web Server is configured to communicate with
the Application Server using the Remoting method. When using AD FS, the communication
method must be SOAP .
Failed to connect. User '' does not belong to any user groups.
This error can occur when AD FS uses Active Directory Distribution Groups instead of Active
Directory Security Groups. In order to successfully authenticate with OnBase, users in AD FS
must be assigned to Active Directory Security Groups. More information on AD FS groups can
be found in the AD FS documentation provided by Microsoft.

HTTP 400 Bad Request

This error can occur when the user is a member of too many Active Directory groups and
attempts to log in to the OnBase Web Client. It is a known limitation of IIS when using Kerberos
authentication. For more information, see the Microsoft Support web site.
Object not set for an instance of an object

This error can occur when the claims rules associated with the Issuance Transform Rules on
the Relying Party Trust are not configured correctly. For complete information on configuring
the Relying Party Trust, see the documentation for AD FS provided by Microsoft.
OEM Authentication Failed

This error can occur when the token returned from AD FS is either empty or cannot be read. In
most cases this is because the soapExtensionTypes element in the webServices element of
the client configuration file is still commented out. To function correctly, this section must be
uncommented. See Configuration on page 79 for details on configuring the various OnBase
clients to use AD FS.
SAML Assertions are not included in token

This error can occur when the claims rules associated with the Issuance Transform Rules on
the Relying Party Trust are not configured correctly. For complete information on configuring
the Relying Party Trust, see the documentation for AD FS provided by Microsoft.
The issuer of the security token was not recognized by the

IssuerNameRegistry
This error can occur when the certificate used to sign the security token cannot be located
using the thumbprint specified in the configuation file. The thumbprint is specified in the
trustedIssuers element of the issuerNameRegistry element. Make sure that the value of the
thumbprint attribute matches exactly the thumbprint of the certificate.
Note: The configuration file is an XML file and must be saved with ASCII or ANSI encoding.
Make sure you are viewing and editing the file in an ASCII or ANSI editor, such as Notepad. If
the file contains any Unicode characters, additional or invalid characters may be introduced to
elements and attributes when rendered as ASCII or ANSI.
See Configuration on page 79 for details on configuring the various OnBase clients to use AD
FS.
The same client browser session has made X requests in the

last Y seconds. Contact your administrator for details.
This error typically occurs when the same URLs do not match exactly in different areas of AD
FS configuration. For example, the URL of the OnBase Web Server may be configured as https:/
/my.server/AppNet/ in one place and https://my.server/AppNet in another.

The type initializer for

Hyland.Canvas.CanvasClientConfiguration threw an exception
This error can be encountered in the OnBase Unity Client when attempting to log in. In most
cases the solution is to uncomment the Hyland.Authentication section element in the Unity
Client *.exe.config file. For complete details, see Configuring the Unity Client, MRM Unity Client,
and Office Business Application for AD FS on page 87.
This page cannot be displayed

This error can be caused by several misconfigurations within AD FS. For troubleshooting AD FS,
refer to the documentation provided by Microsoft through the Microsoft Support web site.
Value cannot be null

This error is reported in the Diagnostics Console when attempting to log in through the OnBase
Web Client. Make sure the virtual directory of the OnBase Web Server is configured to allow
Anonymous authentication. Also ensure that the web.config file of the Web Server is
configured correctly (see Configuring the Web Server for AD FS on page 83).
Web Client displays a login page

This error can occur when Failover to Interactive Mode is configured in the Network Security
options for OnBase when OnBase is also configured to use AD FS. OnBase does not support
Failover to Interactive Mode when using AD FS.

I NTEGRATION FOR S INGLE SIGN-ON
This chapter includes information of configuring the Integration for Single Sign-On.
Note: To configure Single Sign-On for PeopleSoft Enterprise, see Single Sign-On for PeopleSoft
Enterprise on page 145.
This chapter covers:

• Overview on page 97
• Installation on page 102
• Deploying Integration for Single Sign-On on page 105
• Additional Configuration for Single Sign-On on page 116
• SAML SSO Configuration on page 122
• CAS SSO Configuration on page 126
• Using Custom Authenticators on page 127
• Enabling OnBase Entrust on page 129
Overview
Single sign-on is third-party software that authenticates users to multiple services without
requiring the user to log in multiple times. It is most effective when users need to authenticate
to multiple services over a WAN, but also over complex LANs where users must authenticate to
multiple and disparate services.
The Integration for Single Sign-On module allows the OnBase Web Client to integrate with
most single sign-on vendors so that a user is automatically logged in to OnBase as part of a
single sign-on solution. When a user attempts to access OnBase, Integration for Single Sign-On
communicates with the configured single sign-on vendor to authenticate the user.
Note: Integration for Single Sign-On is not supported for use with the OnBase Client or Unity
Client. For other automatic login options, see Standard Authentication on page 13.
The Integration for Single Sign-On module provides a solution for integrating OnBase with
several popular single sign-on vendors without additional customization. The following table
lists these vendors and the support level for each of them.
Vendor Notes
Active Directory Authentication (NT Identity Provider (IdP) initiated only

Authentication)
Access Manager Identity Provider (IdP) initiated only

Vendor Notes
CAS Redirects authentication to the CAS browser
Microsoft MailApp Identity Provider (IdP) initiated only
OnBase Entrust Identity Provider (IdP) initiated only
PeopleSoft Enterprise Identity Provider (IdP) initiated only
SAML Identity Provider (IdP) initiated SAML 2.0 only
SAP Enterprise Portal Identity Provider (IdP) initiated only
Siteminder Identity Provider (IdP) initiated only
Integration for Single Sign-On can also integrate with custom authenticators, but custom
integrations must be deployed in a way consistent with the authentication solution. Please
contact your first line of support to create or integrate a custom single sign-on solution.
Licensing
In order to use Integration for Single Sign-On, you must be licensed for Integration for Single
Sign-On . Depending on the single sign-on scheme you are using, one of the following additional
database licenses is also required:
• Single Sign-On for CA eTrust SiteMinder
• Single Sign-On for Fiserv
• Single Sign-On for IBM Tivoli Access Manager
• Single Sign-On for Microsoft Active Directory Service
• Single Sign-On for OnBase Entrust
• Single Sign-On for SAP Enterprise Portal
• Single Sign-On for SAML
• Single Sign-On for TriCipher Armored Credential Systems
Limitations
Integration for Single Sign-On does not support concurrent OnBase logins from the same
workstation with different users. In order for another user to log in to OnBase on the same
workstation, the user that is already logged in to OnBase must log out of OnBase before
changing workstation user logins.
Synchronization between OnBase and Custom Authentication stores (such as a Single Sign-on
user repository) is not supported.

Single Sign-On does not support the Workflow task list Password Protection option. Workflow
tasks configured to require the user’s password cannot be completed if the user is logged in
using Single Sign-On.
Re-authentication is not supported with Single Sign-On autologins. Users who are required to
re-authenticate after logging in, such as when acknowledging files in Document Knowledge
Transfer, will be unable to perform those tasks if they used autologin to access OnBase.
Pre-Installation
Ensure that the third-party single sign-on client is installed on the machine from which you wish
to use a single sign-on service.
The OnBase Web Server also must be running and connected to the database you will be using.
See the Web Server module reference guide for details on installing and configured the Web
Server.
Note: The OnBase Web Server and Application Server must be configured to communicate
using SOAP. To verify the communication method, open the web.config file on the web server
in a plain-text editor, such as Notepad. The ApplicationServer element (which is contained in
the Hyland.Services.Client element) must have the ServiceClientType attribute set to SOAP
and the Url attribute must end with Service.asmx . For more information on the web.config file,
refer to the Web Server module reference guide.
The Integration for Single Sign-On can also be used with the OnBase Patient Window and
DeficiencyPop. Before configuring one of these applications to use the Integration for Single
Sign-On, ensure the application is installed and configured to use SOAP as the
ServiceClientType as described in its corresponding module reference guide.
The following information is specific to Integration for Single Sign-On.
Note: 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.
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
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.
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:

1. Locate the web.config file for the OnBase Web Server.
2. Open the web.config file in a plain-text editor, such as Notepad.
Note: 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.
3. Locate the Hyland.Authentication element.

4. 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.

Installation
Standard (EXE or MSI) Installers — There are two methods for running OnBase installers:
Interactive and silent. An interactive installation requires user interaction with dialog boxes
during the installation process. A silent installation does not require user interaction during the
installation process.
OnBase installers may consist of both an executable file (.exe ) and a Windows Installer
Package file ( .msi ). When performing an interactive installation, and both an executable file
and MSI are available, use the executable file to ensure a complete installation. The executable
validates that all prerequisites are met before proceeding with the installation. If any missing
prerequisites are identified, the installer alerts the user. Most missing prerequisites can be
installed directly from the installer before continuing the installation process.
Note: The Microsoft .NET Framework prerequisite must always be installed separately before
running either the EXE or MSI installer.
When performing a silent installation, and both an executable file and MSI are available, use the
MSI. Since the MSI package does not validate prerequisites, you must ensure that Windows
Installer 3.0 or greater is installed on each workstation and that all other prerequisites are met
before running the MSI. If any prerequisites are not met, a silent installation from the MSI will
fail without alerting the user.
For more information about configuring a silent installation, see https://docs.microsoft.com/
en-us/windows/win32/msi/command-line-options.
ClickOnce Installers — Some OnBase modules are installed for deployment using ClickOnce.
ClickOnce is a Microsoft technology that installs a deployment package to a central server.
This package can then be accessed by users to install the application on their local
workstations. The application is installed entirely under the user’s profile, ensuring that it
cannot interfere with other applications installed on the workstation.
ClickOnce deployments also have the following advantages:
• Previously installed versions of the module can be easily and automatically updated
to the latest version with little or no user interaction, as long as the deployment
server and deployment instance name are not changed.
• The module is installed on a per-user basis and does not require administrator
privileges for local installation.
• There can be multiple instances of the module deployed, allowing for different
versions of the module to be installed on a per-user basis, to match the version
requirements of the workstation it is being installed to.
For more information on Microsoft’s ClickOnce technology see https://docs.microsoft.com/en-
us/visualstudio/deployment/clickonce-security-and-deployment.
Note: ClickOnce-deployed applications are not supported by Microsoft within a Remote

Desktop environment.

OnBase modules that are deployed using ClickOnce should either take advantage of the
ClickOnce deployment method as an alternative to a Remote Desktop deployment, or the
module should be installed using a standard installer and deployed using the Remote Desktop
methodology.
Note: Not all OnBase modules that support ClickOnce have a standard installer available.
Contact your first line of support if you are unsure how to install and deploy a specific module.
User Account Control (UAC) — If Windows User Account Control (UAC) is enabled, the installer
must be run with elevated administrator privileges, even if an administrator is currently logged
on. This can be accomplished by right clicking on the installer executable and selecting Run as
Administrator from the right-click menu. MSI files cannot be run using the Run as
Administrator option. Instead, you must launch the MSI package using the command line. For
more information on installing files through the command line, refer to your Microsoft support
information or see https://docs.microsoft.com/en-us/windows/win32/msi/command-line-
options.
Silent Installation Using setup.exe — If you are running setup.exe silently from the command
line you must use the /q switch and the /CompleteCommandArgs switch, followed by the
required command-line arguments.
The q switch specifies quiet mode and is required to suppress the GUI. The
CompleteCommandArgs switch must be followed by the command-line parameters required to
configure and install the desired components.
The complete string of command-line parameters must be included in double quotes after the
CompleteCommandArgs switch. If a parameter in the string also requires double quotes, those
quotes must be escaped using \ . For example: setup.exe /q /CompleteCommandArgs
"INSTALL_PROPERTY=\"my value\" INSTALL_PROPERTY_2=\"my value 2\"" .
Note: You should check the return value of the setup.exe process. A return value of 0 (zero)
indicates success. Any other value returned may indicate that an error was encountered and
the installation failed.

Running the Installer

To launch the Integration for Single Sign-On installer, run the Hyland Single Sign On.msi file in
your Core distribution files. This file is usually located in the \install\Single Sign On\ folder.
1. The Install Wizard welcome screen is displayed.
2. Click Next . The Destination Folder dialog box is displayed.

3. Enter the top-level installation directory in the field provided, or click Change to browse
to it. The default installation location is
C:\Program Files (x86)\Hyland\Single Sign On\
Note: The assembly files required by this module are always installed to the Global Assembly
Cache (GAC), not the destination folder selected.
If Change is clicked the Change destination folder dialog box is displayed.
Enter a Folder name in the field provided or select it from the Look in drop-down select
list, then click OK .
If the Destination Folder is not changed, the default location is used.
4. Click Next . The Ready to install... dialog box is displayed.
5. Click Install to perform the installation.
6. Click Finish after the installation is completed.
Deploying Integration for Single Sign-On

There are two primary deployment models for the Integration for Single Sign-On module. The
first is a direct client/server model. In this model, the OnBase Web Server has a direct
connection to the network on which it communicates, and client machines making use of the
single sign-on functionality connect directly to it.

The other model uses an authentication server. In this model, both the Web Server and client
machines communicate with an authentication server to establish a session. The client
machine never communicates directly with the Web Server.
The same Single Sign On Config utility is used to configure both deployment models. After
running the installer, this utility is typically located at C:\Program Files\Hyland\Single Sign
On\SingleSignOnConfig.exe on the installation machine (under 64-bit systems it may be at
C:\Program Files (x86)\Hyland\Single Sign On\SingleSignOnConfig.exe ).
Note: The Single Sign On Config utility cannot be run in 32-bit mode on a 64-bit operating
system. However, the utility can still be used to configure Integration for Single Sign-On for a
32-bit process when running in 64-bit mode.
The steps in this guide are necessary only for the server-side configuration. End users do not
need to do anything beyond ensuring that the organization’s single sign-on application is
running on their machines.
Note: To complete the integration, please see the additional steps required in the
Configuration chapter of this manual.
To deploy the different models of Integration for Single Sign-On see:

• Direct Client/Server Model on page 107
• Authentication Server Model on page 109

Direct Client/Server Model

1. Launch the Single Sign On Config utility (SingleSignOnConfig.exe ).
Note: If Windows UAC is enabled, the executable must be run as an administrator.
The Single Sign On Config dialog is displayed.
2. Enter the path to the Virtual Directory . This is the virtual directory of the OnBase Web
Server. In a default installation, the virtual directory is at C:\inetpub\wwwroot\AppNet .

3. Select Web Server in the Type section. The Authenticator drop-down list is displayed.
Note: Do not select App Server or Uses App Server . These are the configuration options for
use with the Authentication Server model.
4. From the Authenticator drop-down list, select the authentication scheme that is used in
your organization. Integration for Single Sign-On must use one of the available
authentication methods.
The following items should be noted about some of the authenticators:
• The SAML authenticator requires the information in the SAML SSO Properties dialog
box to be completed. See SAML SSO Configuration on page 122.
• The CAS authenticator requires the information in the CAS Namespace dialog box to
be completed. See CAS SSO Configuration on page 126 for more information before
closing the Single Sign On Config utility.
• The PeopleSoft Enterprise authenticator requires additional configuration. See
Single Sign-On for PeopleSoft Enterprise on page 145.
• The OnBase Entrust authenticator requires additional configuration. In order to
function correctly, this authentication method must be partly configured using a
separate utility. See Enabling OnBase Entrust on page 129.
• The CUSTOM... authenticator requires Integration for Single Sign-On to be deployed
in a way consistent with the custom authentication solution. See Using Custom
Authenticators on page 127 before continuing with the configuration.

5. Click Configure to accept the configuration.

6. Click Close to close the Single Sign On Config utility.
To complete the configuration, see Additional Configuration for Single Sign-On on page 116.
Authentication Server Model

Before configuring Integration for Single Sign-On with the Authentication Server model, ensure
there is a valid ASP.NET user that the authentication server can impersonate, unless the
integrated application does not impersonate a user.
The Single Sign On Config utility generates a random public and private key pair for exchanging
custom authentication tokens with the web service. The utility generates the key pair and
encrypts and stores the key in the system Registry under
HKEY_LOCAL_MACHINE\Software\Hyland\HylandWebServices . The utility also modifies the
ACLs on the key such that only administrators and the user specified have access to read the
key.
Note: Under 64-bit systems this key may be located at

HKEY_LOCAL_MACHINE\Software\Wow6432Node\Hyland\HylandWebServices .

Web Server Configuration

The Integration for Single Sign-On installation wizard must be run on both the Web Server and
Application Server before configuring an Authentication Server model.
These steps also are used to configure the OnBase Patient Window and DeficiencyPop for the
Integration for Single Sign-On. Configure these applications using the same steps used to
configure the OnBase Web Server.
2. Enter the path to the Virtual Directory of the OnBase Web Server. In a default
installation, the virtual directory is at C:\inetpub\wwwroot\AppNet
If you are configuring the Integration for Single Sign-On for a different Web application,
such as the OnBase Patient Window, use the virtual directory for the applicable Web
application.

3. Select Web Server in the Type section. The Authenticator drop-down list is displayed.
Note: Do not select App Server at this time.
4. Select Uses App Server . The Web Server Config options are enabled.
5. From the Authenticator drop-down list, select the authentication scheme that is used in
your organization. Integration for Single Sign-On must use one of the available
authentication methods.
The following items should be noted about some of the authenticators:
• The SAML authenticator requires the information in the SAML SSO Properties dialog
box to be completed. See SAML SSO Configuration on page 122 for more information
before closing the Single Sign On Config utility.
• The CAS authenticator requires the information in the CAS Namespace dialog box to
be completed. See CAS SSO Configuration on page 126 for more information before
closing the Single Sign On Config utility.
• The PeopleSoft Enterprise authenticator requires additional configuration. See
Single Sign-On for PeopleSoft Enterprise on page 145.

• The OnBase Entrust authenticator requires additional configuration. In order to

function correctly, this authentication method must be partly configured using a
separate utility. See Enabling OnBase Entrust on page 129.
• The CUSTOM... authenticator requires Integration for Single Sign-On to be deployed
in a way consistent with the custom authentication solution. See Using Custom
Authenticators on page 127 before continuing with the configuration.
6. Enter or select an ASP.NET Identity .
This is the ASP.NET user that the authentication server impersonates and that the
service runs under. If the application is not impersonating, specify ASPNET as the user.
Note: You must specify a domain account to use as the ASP.NET Identity.
Caution: It is highly recommended that the consuming application run under its own identity.
By doing so, the private key is protected and other ASP.NET applications on the server are not
able to use the same private key to send unauthorized messages to the web service.
7. Click Configure . A public key is generated and displayed in the Public Key Token field.

8. Copy the Public Key Token to the Windows clipboard by right-clicking the Public Key
Token value and selecting Copy . This value is required to complete the App Server
configuration.
Tip: If the OnBase Application Server that is used as the authentication server is a different
machine from the Web Server, you must copy this value to a text file accessible from the
Application Server.
9. Continue to the App Server configuration steps. See App Server Configuration on page
113.
App Server Configuration

The Integration for Single Sign-On installation wizard must be run on both the OnBase Web and
Application Servers before configuring an Authentication Server model.
Note: Before configuring the Application Server, ensure that you have completed the steps for
Web Server Configuration (see Web Server Configuration on page 110). If the Application is on
a different machine from the Web Server, Integration for Single Sign-On must first be installed
on that machine (see Installation on page 102).

2. Select App Server . The Type drop-down list is enabled and the Public Key Token input
is displayed.
3. Change the Virtual Directory to point to the server that is acting as the authentication
server. This is typically the OnBase Application Server. In a default installation, the
Application Server is installed to C:\inetpub\wwwroot\AppServer .
4. Select Standard from the drop-down list unless you are using a custom authenticator.
Select CUSTOM... if you are using a custom authenticator.
Note: If you are using a CUSTOM authenticator, you must complete the steps under Using
Custom Authenticators on page 127 before continuing.
5. Click in the white area beneath the Public Key Token column heading. (null) is
displayed.
6. Make sure the Public Key Token you copied during Web Server configuration has been
copied to the clipboard. If you copied the public key to a text file on the authentication
server, you must first copy the value from the text file to place it in the clipboard.

7. Right-click on (null) and select Paste . The Public Key Token you copied to the clipboard
is added to the list.
8. Select an option under Synchronize User Groups to allow Integration for Single Sign-On
to mimic some of the features of Active Directory or LDAP authentication.
The option selected is used to synchronize OnBase users and user groups with the
authentication method selected. For example, if a user exists in an LDAP user group but
not in OnBase, and LDAP is selected, that user is automatically created in OnBase and
placed in all matching OnBase user groups, allowing for a seamless log in.
Note: If you select to synchronize user groups you must configure a default User Group. If no
default User Group is configured, users are not created or synchronized in OnBase. See
Enabling Automatic User Creation with Single Sign-On on page 117.
• Do not synchronize: Users are not created automatically in OnBase and no

synchronization takes place regarding user groups, even if an authentication method
is being used. Select this option if you intend to pass credentials for existing OnBase
users and you do not want user group synchronization to take place.
• LDAP: Users are created and/or user groups are synchronized automatically in
OnBase according to the user’s groups in LDAP. The matching user groups must
already exist in OnBase.

• Active Directory - Basic: This authentication method was removed after OnBase 18.
To continue using Active Directory to synchronize users, you must change the
configuration of OnBase to Active Directory - Enhanced or LDAP , then select the
matching option under Synchronize User Groups. See Standard Authentication on
page 13 for information on moving OnBase authentication to Active Directory
Enhanced or LDAP.
• Active Directory - Enhanced: Users are created and/or user groups are synchronized
automatically in OnBase according to the user’s groups in Active Directory. Active
Directory Enhanced is a Windows-based integrated security model that provides
control over domain group mapping. It is the recommended choice for multiple-
domain OnBase environments. Group mapping and user authentication is achieved
using the Active Directory Security ID (SID) of the group and user logging in, so name
matching is not required with Active Directory Enhanced.
Note: If you select Active Directory - Enhanced , after completing these configuration steps,
the steps in the Synchronizing User Groups Via Active Directory on page 118 topic must also be
completed.
9. Click Configure .
Note: To complete the integration, see Additional Configuration for Single Sign-On on page
116.
Additional Configuration for Single Sign-On

The following sections contain information on completing a configuration of Integration for
Single Sign-On after deployment (see Deploying Integration for Single Sign-On on page 105).
Configuration includes:
• Enabling Single Sign-On for the Web Server on page 116
• Enabling Automatic User Creation with Single Sign-On on page 117
• Synchronizing User Groups Via Active Directory on page 118
• Web.Config Settings on page 119
• Single Sign-On with Active Directory or LDAP Authentication on page 121
Enabling Single Sign-On for the Web Server

The OnBase Web Server requires a valid OnBase Application server to function correctly. See
the Application Server and Web Server module reference guides for details on installing these
servers.

In order to enable Integration for Single Sign-On with the OnBase Web Server, the Web and
Application servers must be configured to follow the Authentication Server model. Using this
model, configure the servers as illustrated in this table:
OnBase Server SSO Type Default Virtual Directory
Web Web Server C:\Inetpub\wwwroot\AppNet
Application App Server C:\Inetpub\wwwroot\AppServer
Tip: For complete details on configuring the Authentication Server model, see Authentication
Server Model on page 109.
Allowing Multiple Web Client Logins from the Same

Workstation
In some circumstances it may be necessary to allow different users to log in to OnBase at the
same time using SSO from the same workstation. In order to allow this, Anonymous Access
must be enabled on the virtual directory of the OnBase Web Server (e.g.,
C:\Inetpub\wwwroot\AppNet ).
Each user that logs in this way is given a unique Web Client session. These sessions are ended
like any other Web Client session, when the user closes the Web Client, logs out, or the session
is automatically ended due to the configured session timeout.
Enabling Automatic User Creation with Single Sign-On

OnBase users can be automatically created by the system to allow seamless access to
documents stored in OnBase. This means that users trying to access OnBase documents via a
third-party application are granted access to the document without having to provide OnBase
log in credentials.
This functionality is only available to systems that include Integration for Single Sign-On in the
overall solution. The user’s credentials are validated with the third-party application using
single sign-on. If the user is authenticated by the third-party application and does not already
exist in OnBase, an account is automatically created for that user. System-generated users are
placed in a default user group, as configured in OnBase, and the requested document is
displayed based on the permissions given to that user group.
Note: If the system is not licensed for Integration for Single Sign-On, or no default user group is
configured, new users are not generated by the system.

To configure a default User Group in OnBase:

1. Launch the OnBase Configuration module.
2. Select System Generated User Settings from the Utils menu. The SSO Default User
Group dialog is displayed.
3. Select a user group from the Default User Group drop-down list, or select
<< None >> to disable the creation of system-generated users.
4. Click Save , or click Cancel to close the dialog without saving.
Tip: See the Configuration help files or System Administration module reference guide for
details on creating User Groups in OnBase.
Synchronizing User Groups Via Active Directory

If you select Active Directory - Enhanced under Synchronize User Groups when configuring
the App Server, you must ensure that the following steps are also completed:
1. Locate the Web.config file on the OnBase web server and open it for editing in a plain-
text editor, such as Notepad. In a default installation, this file is located at
C:\Inetpub\wwwroot\AppNet\ .
Caution: Do not edit the Web.config file in a binary editor, such as Microsoft Word. Editing this
file in a binary editor can introduce additional characters that generate errors when processes
attempt to read the information contained in the file.
2. Locate the <add key="default_domainname"> node.

3. Add the domain name used for Active Directory as the value of the value attribute.
For example, the completed node may look like this:
<add key="default_domainname" value="MyDomain"></add>

4. Locate the <Hyland.Authentication> node.

5. Locate the <properties> child node of the <Hyland.Authentication> node.
Note: This node is not created until after App Server configuration is completed. If the
<properties> node is not available, make sure you have completed the initial configuration (see,
App Server Configuration on page 113).
6. Add the following node as a child of the <properties> node:

<add key="stripDomainFromUsername" value="true" />
Note: XML nodes and values are case sensitive. Make sure to add the node in the exact casing
shown above.
A completed <properties> node may look like this:

<properties>
<add key= "stripDomainFromUsername" value=" true " />
</properties>
7. Save and close the Web.config file.
Web.Config Settings
There are several options that relate to Integration for Single Sign-On that can be set in the
web.config file of the Web server, OnBase Patient Window, and DeficiencyPop. Most options
configured in the web.config file can be easily managed in the Web Application Management
Console, which provides a simple user interface for editing Web Server settings.
See the Web Application Management Console module reference guide for details on this
utility. For more general information on web.config settings, see the Web Server module
reference guide.
Enable Auto Log In



Strip the Domain from a Username

The stripDomainFromUsername key can be set to automatically strip the domain from user
names that are passed as either domain\username or domain@username . This is useful when
single sign-on authenticators use a full domain and username but OnBase only uses the user
name. Set the stripDomainFromUsername key value to true to strip the domain before
authenticating against OnBase.
If the stripDomainFromUsername key is not already in the Web.Config file of the OnBase Web
Server, it can be added manually.
Caution: Do not edit the Web.config file in a binary editor, such as Microsoft Word. Editing this
file in a binary editor can introduce additional characters that generate errors when processes
attempt to read the information contained in the file.
To add the stripDomainFromUsername key:

1. Locate the <Hyland.Authentication> node in the web.config file of the OnBase Web
Server.
2. Locate the <properties> child node of the <Hyland.Authentication> node.
Note: The <properties> node is not created until after Web Server configuration is completed.
If the <properties> node is not available, make sure you have completed the initial configuration
(see, App Server Configuration on page 113).
3. Add the following node as a child of the <properties> node:

Note: XML nodes and values are case sensitive. Make sure to add the node in the exact casing
shown above.
A completed <properties> node may look like this:

<properties>
<add key= "stripDomainFromUsername" value=" true " />
</properties>
4. Save and close the Web.config file.
Session Timeout
The EnableSessionExpiration setting should be set in the web.config file as a best practice.
What this means is that the Web Client session times out after the time specified in web.config
has passed. If this is not set, the session remains open as long as the Web browser is left open
on the user machine. When a user session times out, the user is directed to a screen indicating
this.

Redirect to Custom Page on Authentication Failure

CustomSSOAuthenticationFailurePage - If a single sign-on authentication failure occurs, the
user is redirected to the URL entered for the CustomSSOAuthenticationFailurePage element. If
this value is blank and a single sign-on authentication failure occurs, users are redirected to a
standard error page.
Force SSO Auto Log In

Single Sign-On with Active Directory or LDAP

Authentication
Integration for Single Sign-On can be used with LDAP or Active Directory Enhanced
authentication.
To use Integration for Single Sign-On, set both the EnableAutoLogin and
forceSSOAutoLoginOverDomain web.config settings to true . The settings are described below.
EnableAutoLogin


forceSSOAutoLoginOverDomain
SAML SSO Configuration

Integration for Single Sign-On can integrate with SAML authenticators. The SAML SSO
authenticator is designed to receive a SAML assertion message as an HTTP POST to the
OnBase Web Client login page.
Note: Integration for Single Sign-On currently supports Identity Provider-initiated SAML 2.0
only and does not support Relay State (it will not perform any HTTP redirects specified in the
RelayState parameter).

When SAML is selected from the Authenticator drop-down list, the SAML SSO Properties
dialog box is automatically displayed.
To configure single sign-on to use a SAML authenticator:

1. Type the POST variable name for the SAML token in the SAML Token Name field. The
SAML SSO authenticator is designed to receive a SAML assertion message as an HTTP
POST to the OnBase Web Client login page.
Note: Integration for Single Sign-On currently supports Identity Provider-initiated SAML 2.0
only and does not support Relay State (it will not perform any HTTP redirects specified in the
RelayState parameter).
2. Type the full URL address to the Username Claim Type in the field provided.
3. In the Clock Skew Used For Replay Detection In Minutes field, enter the number of
minutes that the token date/time can be off from the current date/time and still be
considered valid.
4. Select Base64 Encoded if the SAML responses are base64 encoded, then select the
format of the encoded token from the Encoding drop-down list.

5. On the Trusted Users tab, enter the subject names of all certificates that are issued by
trusted users. These values must match the subject names of the certificates.
To manually enter a new name, click twice in the Trusted Issuers Certificate Subject
Name column on a table row with an asterisk (* ) in the left column, then type the name
at the cursor.
To edit an existing name, click twice on the name to change it.
You can also enter subject names by clicking Add Trusted Issuer and selecting the
certificates to add.
The certificates available to choose from are based on the certificate store you have
configured under the Certificate Configuration tab and are displayed in the Select
Issuer Certificate dialog box.

6. Click the Certificate Configuration tab to configure the certificate validation options.
7. Select the Certificate Validation Mode from the drop-down list:

• None: The certificate issuer is not validated. This option is not recommended in a
production environment.
• PeerTrust: The certificate issuer is validated if the issuer is in the TrustedPeople
certificate store.
• ChainTrust: The certificate issuer is validated if the issuer has a valid signature
chain to a trusted root authority.
• PeerOrChainTrust: The certificate issuer is validated if using either the PeerTrust or
ChainTrust methodology validates the user.
8. Select the Certificate Revocation Mode from the drop-down list:
• NoCheck: The revocation mode of the certificate issuer is not checked.
• Online: The revocation mode of the certificate issuer is checked against an online
CRL (Certificate Revocation List).
• Offline: The revocation mode of the certificate issuer is checked against a cached
CRL (Certificate Revocation List).
9. Select the Certificate Store Location from the drop-down list:
• LocalMachine: The certificate store is located on the local machine but not under a
specific user.
• CurrentUser: The certificate store is located on the local machine under the user that
is currently logged in.
10. Select the name of the X.509 certificate store to use from the Certificate Store Name
drop-down list.

11. Click the Audience URI tab to configure the Audience URI verification.
12. Select the Audience URI Verification Mode :

• Never: The Audience URI is not checked.
• Always: The Audience URI is always checked.
• BearerKeyOnly: The Audience URI is only checked if the security token has a
BearerType key and there are no proof-of-possession keys in the security token.
13. If Always or BearerKeyOnly is selected for the Audience URI Verification Mode you
must type the Allowed Audience URI in the field provided. The is the full URL to the
OnBase Web server login page (e.g., http://YourDomain/AppNet/Login.aspx ).
14. Click OK . The SAML SSO properties are saved.
Note: To complete the full single sign-on configuration you must use the Single Sign On Config
utility. See Deploying Integration for Single Sign-On on page 105.
CAS SSO Configuration

When CAS is selected from the Authenticator drop-down list, the CAS Namespace dialog box is
displayed.

Complete the following configuration steps:

1. In the Login URL field, provide a valid URL for the login service.
2. In the Service URL field, provide a valid URL for the service you want to access.
3. In the Validation URL field, provide a valid URL for the validation service.
4. If your implementation of CAS has been updated with a custom namespace, select
Modify Namespace . A warning is displayed. Click Yes to confirm that you want to
change the default namespace, then modify the text in the Namespace field.
5. If the domain needs to be removed from the username, select Strip domain from user
name .
6. Click OK .
Using Custom Authenticators

Integration for Single Sign-On can integrate with custom authenticators. To configure single
sign-on to use a custom authenticator:
1. Select CUSTOM from the Authenticator drop-down list when performing the Web Server
configuration steps, or from the Type drop-down list if configuring the App Server (see
Deploying Integration for Single Sign-On on page 105).
The Custom Authenticator Selection dialog is displayed.
2. Enter the Authenticator Location in the field provided, or click the ... button to browse
to it. The custom authenticator is typically a DLL file created with specific references
that allow it to work with Integration for Single Sign-On.
3. If the authenticator loads correctly, the remaining fields are populated automatically,
based on information provided by the authenticator.
If the authenticator selected does not load correctly, the remaining fields are not
populated and an error is indicated beside the ... button:
4. Click Apply once the custom authenticator has loaded successfully.

5. Complete the remaining Web Server or App Server configuration steps.
Note: Depending on the authentication methods used, your custom authenticator may require
additional steps to complete the configuration, such as editing the OnBase web server
Web.config file. Contact your first line of support to determine if your authenticator requires
any additional steps.
Enabling Custom Authenticators

Custom Authentication is available when OnBase is licensed for Integration for Single Sign-On
and the OnBase Hyland.Authentication.dll .NET assembly is registered as a COM object (this
step is registered automatically by the Integration for Single Sign-On installer).
To enable the custom authenticator, see:
• Authentication Server Configuration Requirements on page 128
• Configuring a Custom Authenticator on page 128
Authentication Server Configuration Requirements

Using custom authenticators in an environment with an authentication server introduces
additional challenges. In a direct client/server environment, the custom authenticator is
running in the same process that the user is operating in. This permits the custom
authenticator to access information about the user’s operating environment (e.g., session
variables, cookies, HTTP headers). When the user operates in a different process/server than
the OnBase Application Server, you must add the custom authenticator’s SOAP Extension to the
*.config file of the Web service consumer. This is required to ensure the security and validity of
the information that is supplied to Application Server. The configured SOAP extension is
invoked at the time of a web service call.
Note: Contact your first line of support for assistance with correctly updating the values of
these elements to meet the needs of your custom Integration for Single Sign-On deployment.
Configuring a Custom Authenticator

A custom authenticator is the specific component that is invoked to retrieve the user’s user
name. Custom authenticators can be created to support customer requirements. Please
contact your first line of support to create or integrate a custom single sign-on solution.
To configure a custom authenticator, the consuming application must have a .NET config file.
If a .NET config file does not exist for the consuming application, then one must be created. For
web applications, the .NET config file must be named web.config. For client applications, the
.NET config file must be named the same name as the executable (e.g., DMDesktop.exe.config
or wscript.exe.config).
The .NET config file must be configured with a specific configSection and Hyland
Authentication elements. An example config file is included here:
<configuration>

<configSections>
type="Hyland.Authentication.Configuration.CustomAuthenticationConfigHandle
r, Hyland.Authentication, Version=2.1.0.0, Culture=neutral,
PublicKeyToken=c02e21dc39c53bb0" />
</configSections>
<Hyland.Authentication
Type="Hyland.Authentication.NtAuthenticationProvider,
Hyland.Authentication.NtAuthentication">
<properties>
</properties>
</Hyland.Authentication >
</configuration>
Note: Contact your first line of support for assistance with correctly updating the values of
these elements to meet the needs of your custom single sign-on deployment.
Enabling OnBase Entrust

OnBase Entrust is an authentication scheme used to provide single sign-on authentication
between OnBase and custom line-of-business (LOB) applications. In order to create the trust
between the LOB application and OnBase, the custom application must include certain
elements used to produce the authentication token required by Integration for Single Sign-On.
In order to successfully configure Integration for Single Sign-On using OnBase Entrust, the line-
of-business (LOB) application with which Integration for Single Sign-On will authenticate must
include the correct calls to the exposed OnBase Entrust methods.
In order to successfully configure Integration for Single Sign-On using OnBase Entrust, three
elements of the solution must be configured, once the line-of-business application is prepared
to authenticate with single sign-on:
• The line-of-business application, using OnBase Entrust Configuration ;
• the OnBase web server configuration file, using Single Sign-On Config ;
• the OnBase application server configuration file, using Single Sign-On Config .
Note: The Single Sign-On Config and OnBase Entrust Configuration utilities cannot be run in
32-bit mode on a 64-bit operating system. However, the utilities can still be used to configure
single sign-on and OnBase Entrust for a 32-bit process when running in 64-bit mode.

.NET Requirements
The OnBase Entrust Single Sign-On provider targets Microsoft .NET Framework version 3.5.
This may be different from the .NET requirements of other areas of your overall OnBase
solution.
OnBase Entrust Token Overview

The OnBase Entrust Configuration utility is used to generate and store the private key that is
used to authenticate using OnBase Entrust. The private key is encrypted using the Windows
Data Protection API and stored in a registry key protected using an Access Control List (ACL),
such that only the Windows user specified and system administrators have access to the
private key.
In order to authenticate a LOB application with Integration for Single Sign-On, the LOB
application must be able to generate a valid token, which is passed to Integration for Single
Sign-On.
The OnBase Entrust token generated contains the following information:
• User name: The OnBase user name provided by the LOB application.
• Time stamp: The time stamp when the token was generated, based on the
application server time. The time stamp is used to prevent token reuse and to ensure
that the token was generated within the last hour.
Note: OnBase Entrust uses the application server time when generating the token, but
verification of the token usually occurs on the web server. For this reason, the application
server and the web server must have their clocks synchronized to within one hour of each other
for OnBase Entrust to validate the token generated.
• Digital signature: The user name and time stamp are digitally signed using the
OnBase Entrust private key, generated by the OnBase Entrust Configuration utility.
• Public key: The public key of the OnBase Entrust public/private key pair, which is
used to verify that the digitally signed token is valid and has not been modified
during transmission.
Note: Integration for Single Sign-On only trusts the token passed if the token is signed by the
key that is configured using the Single Sign-On Configuration utility, and is provided with a SHA
512 hash of the public key.

Installing the Token Generator for Use with a LOB

Application
Locate the folder that contains the OnBase Entrust configuration files in your source
installation files (e.g., \Apps - Less than 100 Distributed\OnBaseEntrustConfig\ ). Copy all of
the files in that folder to the web server hosting the line-of-business application that is being
integrated with OnBase Entrust (e.g., C:\Inetpub\wwwroot\LOBserver\LOBapp\ ). The following
files must be copied to the location of the LOB application:
• Hyland.OnBaseEntrust.dll
• Hyland.Types.dll
• OnBaseEntrust Configuration.exe
Adding the Token Generator to a LOB Application

The OnBase Entrust token is generated using one of two methods:
• GenerateToken: Accepts an OnBase user name and generates an Entrust token
using that user name.
• GenerateTokenAfterVerifyingPassword: Accepts an OnBase user name and
password, and generates an Entrust token only after verifying the user name and
password.
To use the OnBase Entrust token generator in your LOB application:
Note: The following examples are shown in C#.
1. Add a reference to Hyland.OnBaseEntrust.dll , then add the appropriate using statement

in your code. For example:
using Hyland.OnBaseEntrust;
2. Construct a new instance of the token generator class and call either GenerateToken or
GenerateTokenAfterVerifyingPassword . For example:
TokenGenerator generator = new TokenGenerator();
TokenResult result = generator.GenerateToken();
• If you call GenerateToken , you must pass the OnBase user name, such as:
TokenResult result = generator.GenerateToken(username_string);
• If you call GenerateTokenAfterVerifyingPassword , you must pass the OnBase user
name and password, such as:
TokenResult result = generator.GenerateTokenAfterVerifyingPassword
(username_string,password_string);
3. The method called returns the TokenResult object, which contains the result of the
token generation call in three properties:
• result.Exception: Contains any exceptions thrown during the token generation
process. If no exceptions were thrown, this property returns null .

•result.Status: An enumeration that returns the status of the token generation:

• TokenGeneratorStatus.ExceptionOccurredWhenGeneratingToken: An exception
occurred when the token was being generated.
• TokenGeneratorStatus.FailedToObtainPrivateKey: Failed to obtain the private
key required to digitally sign the token.
• TokenGeneratorStatus.Success: The OnBase Entrust token was successfully
generated.
• TokenGeneratorStatus.UnableToVerifyPassword: An exception occurred when
attempting to verify the password provided.
• TokenGeneratorStatus.UsernameOrPasswordInvalid: The user name or
password provided is invalid.
• result.Token: The string representation of the token generated.
4. The token generated must be passed to the OnBase web server as an HTTP post
parameter called entrusttoken .
Token Generator Code Example

The following examples in C# try to generate a valid token. If successful, the token is displayed
to the user. If the status is anything other than success , the status is displayed.
The following is a sample code to generate an asymmetric OnBase Entrust token:
TokenResult result = generator.GenerateToken("johnsmith");
if (result.Status == TokenGeneratorStatus.Success)
{
MessageBox.Show("Generated token: " + result.Token);
}
else
{
MessageBox.Show("Failed to create token: " +
result.Status.ToString());
}
The following is a sample code to generate a symmetric OnBase Entrust token:

byte[] keyBytes = null; //Load the key from a secure location.

//This is a required operation on the key without this Entrust with
Symmetric key will not work.
ProtectedMemory.Protect(keyBytes, MemoryProtectionScope.SameProcess);

TokenResult result = generator.GenerateTokenUsingSymmetricKey("johnsmith",

keyBytes);
if (result.Status == TokenGeneratorStatus.Success)
{
MessageBox.Show("Generated token: " + result.Token);
}
else
{
MessageBox.Show("Failed to create token: " +
result.Status.ToString());
}
Configuring the Line-of-Business Application

To configure your line-of-business application for use with OnBase Entrust:
1. Launch the OnBaseEntrust Configuration.exe . This utility should be located in the same
folder as your LOB application. The OnBase Entrust Configuration dialog is displayed.
2. Select Open from the File menu. The Open dialog is displayed.

3. Navigate to and select the *.config file of the LOB application. This file is usually named
web.config , but can also be named after the application (e.g., LOBapp.config).
4. Click Open . The configuration information for the following elements is displayed in the
OnBase Entrust Configuration dialog:
• ApplicationServerURL
• DataSource

• PublicKeyHash
If these elements contain values, the values of the elements are displayed. Otherwise,
the values of the elements are empty. The values of ApplicationServerURL and
DataSource are contained in the *.config file, but the value of the PublicKeyHash is
based on the OnBase Entrust key stored in the system registry, if a key exists.
5. Select the value to edit or add and enter the following information:
• ApplicationServerURL: The full URL to the service page of the OnBase application
server (e.g., http://MachineName/AppServer/Service.asmx)
Note: In hosted environments using OnBase Entrust with the OnBase Patient Window or
DeficiencyPop, the line-of-business (LOB) application may not have access to the Service.asmx
page of the OnBase Application Server. In this case, you can configure the LOB application to
use the OnBase Patient Window or DeficiencyPop Service.asmx page for token generation.
• DataSource: The name of the data source used by the application server.
• PublicKeyHash: This value cannot be manually added or edited. Continue to the next
step to create a public key hash if one has not already been created for the current
user.

6. Select Generate Key from the Tools menu to populate the value of the PublicKeyHash .
The Generate OnBase Entrust Key dialog is displayed.
7. Enter the Windows user name or domain identity of the user who will be running the LOB
application (e.g, johnsmith or domain\johnsmith ). This information is used to protect
the registry key that stores the OnBase Entrust key. Only system administrators and this
user will have access to the OnBase Entrust registry key.
Note: If the OnBase web server is configured to accept only integrated logins, with no
anonymous access, this user must have access to the web server in order to generate OnBase
Entrust tokens. If the user running the OnBase web server is not a domain user or otherwise
cannot authenticate to the OnBase application server, then anonymous access must enabled
on the application server.
8. Click OK . The user name input is validated.

9. Click OK at the New OnBase Entrust key was generated and stored prompt. The
PublicKeyHash value in the OnBase Entrust Configuration dialog is now populated.
10. Select Save from the File menu to save the configuration.
11. Double click the value of the PublicKeyHash to select the entire value.
12. Right click the value and select Copy , or press Ctrl-C on your keyboard. This places the
value in the Windows clipboard.
13. Close the OnBase Entrust Configuration dialog.
Note: Immediately continue with configuring the OnBase web server, as the value you just
copied must be pasted in to the configuration of the web server. If you overwrite the
PublicKeyHash value in your clipboard, simply launch the OnBase Entrust Configuration utility
and open the LOB *.config file again, then recopy the PublicKeyHash value.
Configuring
After configuring the line-of-business application for use with single sign-on, Integration for
Single Sign-On must be correctly configured on the OnBase web and application servers. This
section details the steps specific to configuring Integration for Single Sign-On for use with
OnBase Entrust. Standard configuration of Integration for Single Sign-On is covered in the
Integration for Single Sign-On chapter of this module reference guide.

Configuring the Web Server

To configure the OnBase Web server, OnBase Patient Window, and DeficiencyPop for use with
OnBase Entrust:
1. Launch the Single Sign On Config utility (SingleSignOnConfig.exe ) locally on the
OnBase web server. The Single Sign On Config dialog is displayed.
2. Enter the path to the Virtual Directory of the web server. This is the directory that
contains the OnBase web.config file (e.g., c:\inetpub\wwwroot\AppNet ).

3. Select Web Server under Type . The Authenticator drop-down list is displayed.
4. Select Uses App Server . The Web Server Config options are enabled.
5. From the Authenticator drop-down list, select OnBase Entrust . The OnBase Entrust
Properties dialog is displayed.
6. Select the token type from the Select the Entrust Token Type area:
• Asymmetric: The default setting that uses a Public Key Hash. The key is stored in the
web.config of the web server.
• Symmetric: The symmetric key allows for a MAC-address-based filtering scheme.
The key is protected by DPAPI and stored in the web server registry with ACL.
Proceed to the sub-section for the token type selected.

Asymmetric Token Type

If the asymmetric token type is selected, the OnBase Entrust Properties for public key hashes
dialog is displayed:
1. Double click the white field under Public Key Hash and paste (press Ctrl-V ) the public
key hash copied from the OnBase Entrust Configuration dialog.
Note: If you have overwritten the public key hash value in your clipboard, simply launch the
OnBase Entrust Configuration utility again and open the LOB *.config file, then recopy the
PublicKeyHash value. See, Configuring the Line-of-Business Application on page 133.
2. Click OK . The Public Key Hash is saved and the OnBase Entrust Properties dialog is
closed.
3. Enter an ASP.NET Identity in the corresponding Web Server Config field.
Specify the ASP.NET user that the authentication server impersonates. This is the user
that the service runs under. If the application is not impersonating, specify ASPNET as
the user.

Token value and selecting Copy . This value is required to complete the application
server configuration.
If the application server is on a different machine from the web server, you must save
this value to a text file accessible from the application server.
6. Immediately continue with configuring the OnBase application server.
Symmetric Token Type

If the symmetric token type is selected, the OnBase Entrust Properties for symmetric keys
dialog is displayed:
1. Double click the white field under Symmetric Key and enter the Base64-encoded
symmetric key generated by the application for which single sign-on is being
configured.
2. Enter an ASP.NET Identity in the corresponding field. Specify the identity of the user
running ASP.NET or the application pool. This is the user that the service runs under. If
the application is not impersonating, specify ASPNET as the user.

3. Select Enable MAC address based filtering to include the MAC address of the machine
running the application with which single sign-on is authenticating. The Media Access
Control address field is displayed:
4. Double click the white field under Symmetric Key and enter the MAC address of the
machine that is running the application for which single sign-on is being configured.
5. Click OK . The information is saved and the OnBase Entrust Properties dialog is closed.
6. Enter an ASP.NET Identity in the corresponding Web Server Config field.
Specify the ASP.NET user that the authentication server impersonates. This is the user
that the service runs under. If the application is not impersonating, specify ASPNET as
the user.
Token value and selecting Copy . This value is required to complete the application
server configuration.
If the application server is on a different machine from the web server, you must save
this value to a text file accessible from the application server.
9. Immediately continue with configuring the OnBase application server.

Configuring the Application Server

To configure the OnBase Application Server for use with OnBase Entrust:
Note: Before configuring the application server, ensure that you have completed the steps
above, for configuration of the web server. If the application server is on a different machine
from the web server, Integration for Single Sign-On must first be installed on the application
server.
1. Launch the Single Sign On Config utility (SingleSignOnConfig.exe ), if it is not already

open. This utility must be run locally on the OnBase application server. The Single Sign
On Config dialog is displayed.
2. Change the Virtual Directory to point to the OnBase application server. This is the
directory that contains the OnBase web.config file (e.g.,
c:\inetpub\wwwroot\AppServer ).
3. Select App Server under Type . The Type drop-down list is enabled and the Public Key
Token input is displayed.
4. Select Standard from the drop-down list.
5. Click in the white area beneath the Public Key Token column heading. (null) is
displayed.

6. Right-click on (null) and select Paste . The public key token you copied during web
server configuration is added to the list.
Note: If you saved the public key to a text file, you must first copy the value from the text file to
place it in the clipboard, which allows it to be pasted here.
7. Select Do not synchronize under Synchronize User Groups . The other options are
intended for use with Active Directory and LDAP authentication to create users that do
not already exist in OnBase.
8. Click Configure

SINGLE S IGN-O N FOR PEOPLES OFT E NTERPRISE
Single Sign-On for PeopleSoft Enterprise is a single sign-on solution, specific to OnBase
integrations with PeopleSoft, that allows users to log in to OnBase automatically using
PeopleSoft credentials, when OnBase is accessed from an enabled PeopleSoft page.
Note: The steps outlined in this appendix are intended to describe only the specific
configuration steps required to complete a single sign-on integration with PeopleSoft.
Complete instructions on installing and using the OnBase Integration for Single Sign-On
solution are described in the Configuration and Installation sections of this module reference
guide.
Licensing
This OnBase Integration for Single Sign-On solution requires the following additional OnBase
database license:
For general information on upgrading your single sign-on solution, see the Integration for Single
Sign-On chapter of the Authentication module reference guide.
Upgrading PeopleTools — If you have upgraded PeopleTools to version 8.54 or greater for use
with Single Sign On, you must reconfigure the Single Sign On module to point to a web service
for authentication (the service in the Hyland.Authentication.PeopleSoft.war file).

Requirements
The following additional requirements must be met to configure and use Single Sign-On for
PeopleSoft Enterprise:
• PeopleTools version 8.48 or higher.
• The PRTL_SS_CI PeopleSoft API component interface.
• The OnBase Integration for Single Sign-On must be installed on the OnBase web
server.
Note: In order for an OnBase user to be automatically logged in to OnBase using single sign-on
when OnBase is accessed through a PeopleSoft page, that user’s OnBase user name must
match exactly that user’s PeopleSoft user ID. The user’s passwords do not have to match.
Server Locations
It is recommended that the OnBase web server and PeopleSoft server are both on the same
domain (e.g., peoplesoft.mydomain.com and webserver.mydomain.com ). With this setup, the
configuration of the integration is greatly simplified as many of the default settings can be
used. For example, in a default setup, the web browser only forwards the authentication cookie
to other servers on the same domain, while servers on different domains do not receive the
cookie.
Note: The instructions in this appendix assume single sign-on is being configured with the
OnBase web server and PeopleSoft server on the same domain.
If it is not possible to have the OnBase web server and the PeopleSoft server on the same
domain then the PeopleSoft node issuing the authentication token must be configured to issue
an authentication cookie for the domain the OnBase web server is on. Refer to PeopleBooks for
instructions on how to accomplish this.
PeopleSoft Configuration
When OnBase receives the PeopleSoft authentication token as an encrypted cookie, OnBase
needs to connect to the PeopleSoft server to validate the token and extract the user name.
It is recommended that a PeopleSoft user account is created for the sole purpose of validating
the token. This account should have access only to the PeopleSoft single sign-on component
interface ( PRTL_SS_CI ). This account should not be allowed to log in to PeopleSoft
interactively (where a user provides credentials).

The authentication token can alternatively be included in the query string if a cookie cannot be
used. To send the token in the query string, include the PS_SSO_TOKEN parameter on the query
string (e.g., /AccLogin.aspx?DBID=VIS&SCREENID=Accounts-
Payable&SEGMENT1=502&REVISION_NUM=6&PS_SSO_TOKEN=mwAAAAQDAgEBAAAAvAIA
AAAAAAAsAAAABABTaGRyAk4 ).
Note: The authentication token can alternatively be included in the query string if a cookie
cannot be used.
Note: For detailed instructions regarding the configuration of PeopleSoft, refer to the help files
provided by PeopleSoft.
Creating the PeopleSoft User Account

To create the user account for use with the OnBase Integration for Single Sign-On you must
create a new Permission List , Role , and User ID with the settings described below.
Creating the Permission List

1. Log in to PeopleSoft under an account with sufficient privileges to create a new
Permission List, Role, and User ID.
Note: When logging in to PeopleSoft, browse to the PeopleSoft page using the full URL,
including the domain name (e.g., http://srv-peoplesoft.mydomain.com/psp/hyland/
?cmd=login , not http://srv-peoplesoft/psp/hyland/?cmd=login ).
2. Select Permission Lists from Permissions & Roles under the Security menu in
PeopleTools .
3. Under the Add a New Value tab, enter a name for the new list in the Permission List
field, then click Add .
Tip: To make future maintenance easier, use a name for the Permission List that will be easily
identified as the list used for the OnBase Integration for Single Sign-On.
4. Locate and select the Component Interfaces tab.

5. Add the PRTL_SS_CI component interface to the Permission List you just created. This
is the component interface that enables single sign-on in PeopleSoft.
6. Click the Edit link for the PRTL_SS_CI component.
7. Select Full Access for each of the methods listed (Authenticate , Get , and Get_UserID ).
8. Click OK to save the settings.

Creating the Role

1. Select Roles from Permissions & Roles under the Security menu in PeopleTools .
2. Under the Add a New Value tab, enter a name for the new role in the Role Name field,
then click Add .
Tip: To make future maintenance easier, use a name for the Role that matches the name of the
Permission List created for use with the OnBase Integration for Single Sign-On.
3. Under the General tab, enter a description of the role’s purpose in the Description field.
4. Under the Permission Lists tab, add the permission list you created for use with the
OnBase Integration for Single Sign-On.
5. Click Save to save the new role.
Creating the User

1. Select User Profiles from User Profiles under the Security menu in PeopleTools .
2. Under the Add a New Value tab, enter a name for the new user in the User ID field, then
click Add .
Tip: To make future maintenance easier, use a name for the User ID that matches the name of
the Permission List and/or Role created for use with the OnBase Integration for Single Sign-On.
3. Under the General tab, enter a password for the new user in the Password field and
enter the same password in the Confirm Password field.
4. Under the ID tab, select None from the ID Type drop-down list.
5. Under the Roles tab, select the role you created for use with the OnBase Integration for
Single Sign-On.
6. Click Save to save the new user.
Configuring PeopleSoft to Create the SSO

Authentication Token
To create the authentication token for use with the OnBase Integration for Single Sign-On you
must create a PeopleSoft node that issues the token before accessing OnBase. The token is
issued in the form of an encrypted cookie, PS_TOKEN .
Note: For detailed instructions regarding the configuration of PeopleSoft, refer to the
PeopleSoft help files.
To configure a node to issue the token:

1. Log in to PeopleSoft under an account with sufficient privileges to create a new node.
Note: When logging in to PeopleSoft, browse to the PeopleSoft page using the fully qualified
domain name in the URL.
2. Select Single Signon from Security Objects under the Security menu in PeopleTools .

3. Ensure that a Local Node has already been defined. Note the Message Node Name of
the Local Node. This is the node that will be configured for use with single sign-on.
4. Select Node Definitions under the Portal menu in PeopleTools .
5. Locate and select the Local Node of the application, as you noted earlier.
6. Under the Node Definitions tab, select Password from the Authentication Option drop-
down list.
7. Click Save to save the settings.
8. Select Web Profile Configuration under the Web Profile menu in PeopleTools .
9. Under the General tab, make sure the Authentication Domain matches the domain of
your OnBase web server and PeopleSoft server (e.g., .mydomain.com ).
Single Sign-On Configuration

To complete the OnBase Integration for Single Sign-On, the OnBase web server must be
configured to accept and process the authentication tokens created by PeopleSoft.
Setup
Before running the OnBase Single Sign-On Config utility you must complete the following
tasks.
• Copy the entire PS_HOME\jre\bin\client directory from the PeopleSoft server to the
OnBase web server. This directory contains the Java runtime, which is required to
complete the integration.
• Copy the entire PS_HOME\bin\client\winx86 directory from the PeopleSoft server to
the OnBase web server. This directory contains the PeopleTools DLLs that are
required to complete the integration.
• Copy the entire PS_HOME\setup directory from the PeopleSoft server to the OnBase
web server. This directory contains the Java application that is required to complete
the integration.
• Make sure the Interop.PeopleSoft.dll file is present in the Windows GAC
( C:\WINDOWS\assembly ) of the OnBase web server. This file is located in the
Integration for Single Sign-On installation directory (in a default installation,
C:\Program Files\Hyland\Single Sign On ).
If this file is not present in the GAC, drag-and-drop the Interop.PeopleSoft.dll file
from the Integration for Single Sign-On installation directory to the GAC directory
( C:\WINDOWS\assembly ).

Web Server and Application Server Configuration

To configure OnBase to use the PeopleSoft token for OnBase authentication, launch the
OnBase Single Sign-On Config utility. In a default installation, this utility is located at
C:\Program Files\Hyland\Single Sign On\SingleSignOnConfig.exe .
1. Follow the steps outlined in Integration for Single Sign-On on page 97 to configure the
Web Server (OnBase Web Server).
2. Select PeopleSoft Enterprise from the Authenticator drop-down list. The PeopleSoft
Properties dialog is displayed.

3. Fill out the following fields as required:
Option Description
PeopleTools Enter the full path to the psapiadapter.dll file in the PeopleTools Client API
Client API Folder field, or click the ... button to browse to it. This file is located in the local
Folder copy of the PS_HOME\bin\client\winx86 folder. For example:
C:\PS_HOME_COPY\bin\client\winx86\psapiadapter.dll
Note: This option is not required when using PeopleTools version 8.5.4 or
higher.
jvm.dll Enter the full path to the jvm.dll file in the jvm.dll Location field, or click the ...
Location button to browse to it. This file is located in the local copy of the
PS_HOME\jre\bin\client folder. For example:
C:\PS_HOME_COPY\jre\bin\client\jvm.dll
higher.
psjoa.jar Enter the full path to the psjoa.jar file in the psjoa.jar Location field, or click the
Location ... button to browse to it. This file is located in the local copy of the
PS_HOME\setup folder. For example:
C:\PS_HOME_COPY\setup\psjoa.jar
higher.
PeopleSoft Enter the full path to the URL of the Web Service used to execute the PeopleSoft
Endpoint token authentication. For example:
https://ps-env-854.psdemo.local:8080/MyWebService/PeopleSoftSSO
Tip: It is highly recommended to enter a secure URL that uses https.
The web service to be used is provided by your solution provider as a .war

file: Hyland.Authentication.PeopleSoft.war .
below.

Option Description
PeopleSoft Server Name - enter the name of the PeopleSoft server.

Application Port Number - enter the port number of the PeopleSoft server.
Server
User Name - enter the PeopleSoft User ID you created in PeopleSoft for use with
the Integration for Single Sign-On.
Password - enter the password that corresponds to the user name entered.
Domain Password - enter the domain connection password required to connect
to the specified PeopleSoft server.
Note: All domains, PeopleSoft Internet Architecture, and three-tier workstations

used for a particular database must use the same domain connection password.
The domain password can be configured within PeopleSoft. The default value of
PS is used if no domain password is specified.
4. Click OK .
5. Continue with the configuration steps described in the Integration for Single Sign-On
chapter to complete configuration of the Web Server and App Server .
Note: When configuring the App Server , make sure Standard is selected from the drop-down
list under the Type settings.
Web.config Settings
To enable single sign-on, ensure that the EnableAutoLogin key in the web.config file of the
OnBase Web Server is set to true . The Web.config file is located at the root of the OnBase Web
Server ( C:\Inetpub\wwwroot\AppNet\Web.config in a default installation).
Note: For more information on the options available in the web.config file, see the Integration
for Single Sign-On or Web Server Administration module reference guides.

Legacy Authentication Methods Onbase Foundation Ep4 Module Refere PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Legacy Authentication Methods Onbase Foundation Ep4 Module Refere PDF

Hochgeladen von

Copyright:

Verfügbare Formate

Legacy Authentication Methods

© 2020 Hyland Software, Inc. and its affiliates ii

GENERAL INFORMATION AND REQUIREMENTS

© 2020 Hyland Software, Inc. and its affiliates iii

Adding Users to Additional User Groups in Active Directory Enhanced .................................... 26

© 2020 Hyland Software, Inc. and its affiliates iv

Enforcing User Password Security.................................................................................................................... 61

CONFIGURING ACTIVE DIRECTORY FEDERATION SERVICES (AD FS)

© 2020 Hyland Software, Inc. and its affiliates v

INTEGRATION FOR SINGLE SIGN-ON

© 2020 Hyland Software, Inc. and its affiliates vi

Installing the Token Generator for Use with a LOB Application....................................................................131

SINGLE SIGN-ON FOR PEOPLESOFT ENTERPRISE

© 2020 Hyland Software, Inc. and its affiliates vii

Significant value is achieved by consolidating authentication methods across an enterprise or

© 2020 Hyland Software, Inc. and its affiliates 1

Authentication Method Interactive/Automatic Login Notes

Internal Security By default, users are prompted to provide

Active Directory - Enhanced By default, users are not prompted to provide

© 2020 Hyland Software, Inc. and its affiliates 2

Authentication Method Interactive/Automatic Login Notes

LDAP By default, users are not prompted to provide

© 2020 Hyland Software, Inc. and its affiliates 3

Authentication Method Interactive/Automatic Login Notes

Active Directory Enhanced

There is no additional licensing required to use Active Directory Enhanced.

Active Directory Federation Services (AD FS)

© 2020 Hyland Software, Inc. and its affiliates 4

Hyland Identity Provider (IdP) Server

There is no additional licensing required to use LDAP.

Integration for Single Sign-On

© 2020 Hyland Software, Inc. and its affiliates 5

See Integration for Single Sign-On on page 97.

Single Sign-On for PeopleSoft Enterprise

Active Directory and LDAP Authentication

© 2020 Hyland Software, Inc. and its affiliates 6

Extended Character Sets

LDAP Directory Service

Active Directory Federation Services (AD FS)

© 2020 Hyland Software, Inc. and its affiliates 7

Integration for Single Sign-On

Single Sign-On for PeopleSoft Enterprise

© 2020 Hyland Software, Inc. and its affiliates 8

Active Directory Federation Services (AD FS)

The following items should also be noted when configuring AD FS:

Integration for Single Sign-On

© 2020 Hyland Software, Inc. and its affiliates 9

To determine the version configured for the OnBase Web Server:

3. Locate the Hyland.Authentication element.

© 2020 Hyland Software, Inc. and its affiliates 10

Single Sign-On for PeopleSoft Enterprise

© 2020 Hyland Software, Inc. and its affiliates 11

© 2020 Hyland Software, Inc. and its affiliates 12

© 2020 Hyland Software, Inc. and its affiliates 13

Active Directory - Enhanced is a Windows-based integrated security method that provides

Extended Character Sets

LDAP Directory Service

© 2020 Hyland Software, Inc. and its affiliates 14

The following information is specific to Standard Authentication.

Configuring Directory Service Authentication

© 2020 Hyland Software, Inc. and its affiliates 15

To access the Directory Service Authentication dialog, select Directory Service

Source of Security Information