Integrationformicrosoftactivedirectoryfederatedservicesadfswhitep.pdf

Integration for Microsoft Active Directory Federated Services (AD FS) White Paper for OnBase 14 and higher Configuration and Deployment White Paper

Technical White Paper Document Version 1.97 Last Updated: October 4, 2016

Technical Support Hyland Software, Inc. 28500 Clemens Road Westlake, Ohio 44145 Ph: (440) 788-5000 Fax: (440) 788-5100 www.onbase.com

INTELLECTUAL PROPERTY STATEMENT AND DISCLAIMER ©2016 Hyland Software, Inc. All rights reserved. The information contained in this document is subject to change without notice and does not represent a commitment on the part of Hyland Software, Inc. Please contact your first line of support to request any updates to this documentation. Hyland Software® and OnBase® are registered trademarks of Hyland Software, Inc. Application Enabler™ is an unregistered trademark of Hyland Software, Inc. All other trademarks, service marks, trade names and products of other companies are the property of their respective owners.

Table of Contents 1

About this Document .................................................................................................................... 6 1.1

Purpose .................................................................................................................................. 6

1.2

Intended Audience ................................................................................................................ 6

1.3

Background ............................................................................................................................ 6

1.4

AD FS Integration Process Flows ......................................................................................... 7 Web Client Process ......................................................................................................... 7 Unity Client Process .......................................................................................................8 Using an AD FS Proxy .................................................................................................... 9

2

Certificates ................................................................................................................................... 10 2.1

Certificates in Use................................................................................................................ 10 Web Server SSL Communication Certificate .............................................................. 10 AD FS Server SSL Communication Certificate ........................................................... 10 AD FS Proxy SSL Communication Certificate ............................................................ 10 Token Encryption Certificate ....................................................................................... 10 Token Signing Certificate ............................................................................................. 10

2.2

Certificate Usage...................................................................................................................11

2.3

Certificate Locations ........................................................................................................... 13 Private Keys................................................................................................................... 14 Public Keys .................................................................................................................... 14

2.4

Certificate Handling ............................................................................................................ 14 Managing Certificates ................................................................................................... 14 Managing Certificate Permissions ............................................................................... 15

2.5

Certificate Identification ..................................................................................................... 16 Thumbprint ................................................................................................................... 16

3

4

AD FS Configuration ................................................................................................................... 17 3.1

AD FS Server Relying Party Trust Configuration .............................................................. 17

3.2

AD FS Endpoints ................................................................................................................ 30

3.3

AD FS Proxy ......................................................................................................................... 31

Web & Application Server ..........................................................................................................32 4.1

Prerequisites ........................................................................................................................32

.NET Framework 4.5 ....................................................................................................32 Active Directory Federation Service (AD FS) .............................................................32 OnBase Installers ..........................................................................................................32 Certificate Statement ....................................................................................................32 4.2

OnBase Web Server .............................................................................................................33 Web Server IIS Changes – SSL Setup .........................................................................33 Modifying the Web Server web.config ........................................................................34 Web Server Virtual Directory Authentication Configuration ................................... 38

4.3

OnBase Application Server .................................................................................................39 Modifying the Application Server web.config.............................................................39 Application Server Virtual Directory Authentication Configuration ........................ 41 Split Web Server and Application Server Configuration ...........................................42

4.4

Pop Integrations ..................................................................................................................43

4.5

Remote Clients.....................................................................................................................44 Hyland.ADFS Configuration Section Examples from the Remote Clients ...............44 Unity Client, Outlook Integration, Report Services and MRM Unity ....................... 45 Disconnected Scanning ................................................................................................ 51

4.6

Mobile Clients ...................................................................................................................... 53 Mobile Access via an AD FS Proxy .............................................................................. 54

4.7

ClickOnce Deployment Configuration of Remote Clients ................................................ 55

4.8

OnBase Patient Viewer........................................................................................................ 61 AD FS Configuration .................................................................................................... 61 Modifying the Patient Viewer web.config ................................................................... 61

5

User Group Mapping ..................................................................................................................64 5.1

OnBase User Group Configuration ....................................................................................64 Removing a User from a User Group .......................................................................... 65

6

Troubleshooting ..........................................................................................................................66 6.1

Logging Events to the Event Log ........................................................................................66

6.2

Forcing Specific Credentials ...............................................................................................66

6.3

Tracing on the AD FS Server .............................................................................................. 67

6.4

Testing Valid AD FS Configuration .................................................................................... 67

6.5

Common Errors .................................................................................................................. 68

ID3206: A SignInResponse message may only redirect within the current application .................................................................................................................................. 68 SAML Assertions are not included in token .............................................................. 68 Object not set for an instance of an object ................................................................. 68 OEM Authentication Failed .........................................................................................69 Client found response content type of 'text/html', but expected 'text/xml'. ............69 Value cannot be null .....................................................................................................70 The type initializer for 'Hyland.Canvas.CanvasClientConfiguration' threw an exception......................................................................................................................................70 ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry. .................................................................................................................. 71 OnBase Web Client display a login page ..................................................................... 72 Failed to connect. User ‘’ does not belong to any user groups ................................... 73 MSIS7042: The same client browser session has made 'X' requests in the last 'Y' seconds. Contact your administrator for details. ...................................................................... 74 HTTP 400 Bad Request................................................................................................ 74 This page cannot be displayed ..................................................................................... 74 7

Appendix A: Generating a Self-Signed Certificate in IIS ......................................................... 75 Generating a Self-Signed Certificate ........................................................................... 75 Assigning the Certificate to the Web Site .................................................................... 76

8

Appendix B: Internet Information Services and Windows Identity Foundation ................... 79 8.1

WIF Configuration Schema ................................................................................................ 79 system.identityModel ................................................................................................... 79 system.identityModel.services .................................................................................... 80

1 About this Document 1.1 Purpose The purpose of this document is to provide step by step instructions on how to configure an Active Directory Federation Services (AD FS) integrated OnBase Solution for OnBase 14 and higher.

1.2 Intended Audience This document is intended for OnBase solution administrators working on and with the Integration for Microsoft AD FS.

1.3 Background This integration for Microsoft AD FS is designed around making the OnBase Web Server a Claims aware application. Prior to .NET 4.5, this was accomplished by installing the Windows Identity Foundation (WIF) framework as a separate installation. In .NET 4.5, the Windows Identity Foundation (WIF) was integrated into the .NET framework. The OnBase Web Server accepts a Claim Token from the AD FS server that presents information about the user. This token has multiple claims inside of it that refer to things like a user name and group memberships. This is similar to our NT or LDAP integrations, where we trust those sources completely, and rely on that user store for our information. AD FS provides several large benefits to the customer. 

Users do not need a second set of credentials



Users can authenticate from anywhere, securely and quickly



A high privilege user is no longer required for impersonation

AD FS implementations rely heavily on certificates and SSL. Unencrypted communication will be refused. There are numerous certificates used to encrypt both tokens and traffic between servers.

1.4 AD FS Integration Process Flows Web Client Process Step 5

Step 4 Step 1 OnBase Web Server

OnBase Application Server

Active Directory Federated Services Server

Foreign Active Directory

Web Client User

Step 3 Step 2

Figure 1-1 – AD FS Integration Process with the Web Client

1. User contacts OnBase Web Server and the OnBase Web Server sends a redirect back to the client which instructs the browser to contact the AD FS Server to authenticate. 2. User’s browser is redirected silently to the configured AD FS end point. 3. If the credentials are valid and the redirect request came from a trusted source (generally Active Directory), the AD FS Server provides a Security Assertion Markup Language (SAML) token back to the Client. 4. The Client provides the token to the OnBase Web Server. The OnBase Web Server decrypts the token and passes the claims to the OnBase Application Server. 5. OnBase Application Server processes the claims against existing users and groups within the OnBase database and allows the user to login if a matching group is found.

Unity Client Process Step 4

Step 3 OnBase Web Server

OnBase Application Server

Unity Client User

Step 2 Step 1 Active Directory Federated Services Server

Foreign Active Directory

Figure 1-2 – AD FS Integration with the Unity Client

1. The Unity Client silently contacts the configured AD FS end point. 2. If the credentials are valid and the redirect request came from a trusted source (generally Active Directory), the AD FS Server provides a Security Assertion Markup Language (SAML) token back to the Client. 3. The Client provides the token to the OnBase Web Server. The OnBase Web Server decrypts the token and passes the claims to the OnBase Application Server. 4. OnBase Application Server processes the claims against existing users and groups within the OnBase database and allows the user to login if a matching group is found.

Using an AD FS Proxy Foreign Active Directory

Step N+1

Step N ADFS Proxy

User Active Directory Federated Services Server

Step N+3 Step N+2

Figure 1-3 – AD FS through a Proxy

It is possible to put an AD FS proxy between the network and the AD FS server. The proxy is transparent to the user, but it is important to understand how the communication is routed in a proxied AD FS environment. 1. The client attempts to contact the AD FS endpoint. This request is caught by the AD FS proxy. 2. If the endpoint is Proxy Enabled and the AD FS Proxy knows about it, the request is forwarded to the AD FS server. 3. If the credentials are valid and the redirect request came from a trusted source (generally Active Directory), the AD FS Server provides a Security Assertion Markup Language (SAML) token back to the proxy. 4. The Proxy sends the response back to the client.

2 Certificates 2.1 Certificates in Use Web Server SSL Communication Certificate This is the SSL certificate that IIS uses on the Web Server. It is required for communication back to the OnBase Web Server.

AD FS Server SSL Communication Certificate This is the SSL certificate that IIS uses on the AD FS Server to encrypt traffic. It is required for communication back to the AD FS Server.

AD FS Proxy SSL Communication Certificate This is the SSL certificate that IIS uses on the AD FS Proxy Server to encrypt traffic. It is required when using an AD FS Proxy.

NOTE: There are special requirements when creating the AD FS Proxy SSL. Review the following article for more information: Server 2008R2: https://technet.microsoft.com/en-us/library/dd807054%28WS.10%29.aspx Server 2012R2: https://technet.microsoft.com/en-us/library/dn383647.aspx#BKMK_2_1

Token Encryption Certificate This certificate is used by AD FS to encrypt the token sent back to the client. While this certificate is recommended to be a separate certificate from the Web Servers SSL certificate, it is possible to re-use the Web Server Certificate for this purpose.

Token Signing Certificate This certificate is used by AD FS to sign SAML tokens. It is required for a proper AD FS configuration.

2.2 Certificate Usage This section will explain what certificates are used during which processes. This demonstrates the Web Client flow.

Figure 2-1 Certificate Useage Diagram

1. All traffic between the User and the OnBase Web Server will be encrypted with the OnBase Web Server’s SSL Certificate. 2. The User is then redirected to the AD FS Proxy Server a) The User must trust the AD FS Proxy Server SSL certificate, as all traffic between the AD FS Proxy and the client must be encrypted. 3. The AD FS Proxy serves as a pass-through to the AD FS Server and does not decrypt the token.

4. The proxy returns to the OnBase Web Server (Relying Party Trust) a token which was signed by the AD FS Token Signing certificate on the AD FS Server. The transmission is encrypted using the AD FS SSL certificate. 5. The client provides the token to the OnBase Web Server which then passes it to the OnBase Application Server. 6. The OnBase Application Server verifies the AD FS token by verifying the signature (if present) using the AD FS Token Signing Certificate.

2.3 Certificate Locations The following diagram lists the respective certificates and their locations on the various server roles across the AD FS architecture. It has been created to demonstrate the certificates needed in a typical AD FS configuration for use with the OnBase Web Client. If the Client Workstation is running one of the Remote Clients, this diagram assumes it is using the Web Server as a passthrough proxy to the Application Server. This configuration has a split Web Server and Application Server as well as an AD FS Proxy Server. The AD FS Proxy Server and the Web Server are in their respective DMZ while the AD FS Server and Application Server are within the respective internal networks.

Figure 2-2 – Certificate Locations for a Web Client or Remote Client AD FS configuration

NOTE: AD FS Server SSL* - The AD FS Proxy Server must have a certificate with the same subject name as the AD FS Server SSL certificate in the corporate network. For this reason it is typically recommended to use the same server authentication certificate configured on the AD FS Server on the AD FS Proxy. https://technet.microsoft.com/en-us/library/dd807054.aspx https://msdn.microsoft.com/en-us/library/azure/dn151311.aspx

Private Keys All private keys belong in the Local Computer\Personal certificate store. The Application Pool Identity account or impersonation account configured in the web.config will need READ access to these certificates. Private keys should have a matching public key in either Local Computer\Trusted Root Certification Authorities or Local Computer\Trusted People certificate stores.

Public Keys All public keys referenced by in the above diagram should be placed in the Local Computer\Trusted People certificate store and should belong in the local computer account.

2.4 Certificate Handling Certificates can be manipulated by using the Microsoft Management Console (MMC). You can import, remove, and drag and drop certificates from this dialog.

Managing Certificates When managing certificates on the server, make sure that they are added to the appropriate certificate store under the appropriate account. 1. Open Certificate Manager in the Microsoft Management Console (MMC) by clicking the Start button, typing mmc.exe into the Search box, and then pressing ENTER a) If you are prompted for an administrator password or confirmation, type the password or provide confirmation. 2. Once the Microsoft Management Console (MMC) is open, add the Certificates snap-in by clicking File | Add/Remove Snap-ins and selecting the Certificates add-in 3. When prompted select the Computer account radio button and click Next 4. Select Local Computer under the Select Computer screen 5. Click Finish

6. Click Ok to exit out of the Add or Remove Snap-ins screen

Managing Certificate Permissions When configuring a split OnBase Web Server and Application Server, it is important to make sure that the Application Pool Identity account or impersonation account configured in the web.config will need Read access to the certificates private keys. In this case the Web Servers SSL certificates private key as well as the Token Encryption certificates private key must be on the Application Server. When this occurs, the permissions to read this certificate may need to be granted to the configured account. This can be managed from the Certificate Console on the Application Server. 1. 2. 3. 4. 5.

Open the Certificates Manager within the Microsoft Management Console (MMC) Right click on the certificate to manage Select All Tasks Select Manage Private Keys… Add the user account and grant the Read permission

Figure 2-3 Private Key Permission Management

2.5 Certificate Identification The AD FS integration uses certificate thumbprints to appropriately identify which certificate to use for communication.

Thumbprint To find the thumbprint of a certificate, find the certificate using the Certificate Manager in the Microsoft Management Console (MMC). Under the Details tab of the certificate, the thumbprint is listed under the Thumbprint field. Once the field has been selected, copy the value for later use.

Figure 2-4 Certificate Thumbprint

NOTE: When copying value from the text box area, be aware that extraneous non-visible Unicode characters might be select. See section ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry.

3 AD FS Configuration This section explains the how to configure AD FS to create a trust relationship between AD FS and a specific OnBase service. This is necessary because without a trust relationship, AD FS and the OnBase service should not respect or trust information and requests between the two endpoints.

3.1 AD FS Server Relying Party Trust Configuration 1. Open the AD FS Management console. Select Relying Party Trusts

Figure 3-1 Adding a Relying Party Trust in AD FS Management Console

2. Select Add Relying Party Trust…

Figure 3-2 Adding a Relying Party Trust

3. Press Start. Select the Enter data about the relying party manually radio button.

Figure 3-3 – Adding a Relying Party Trust: Select Data Source

4. Press Next. Specify a display name for this trust. This name should be specific to the trust, but can be anything. Press Next.

Figure 3-4 – Adding a Relying Party Trust: Specify Display Name

5. Select AD FS 2.0 profile on the Choose Profile screen

Figure 3-5 – Adding a Relying Party Trust: Choose Profile

NOTE: If using AD FS 3.0 (Server 2012 R2), select the top option of AD FS profile.

6. Browse and select the Token Encryption Certificate of your OnBase Server on the Configure Certificate screen

Figure 3-6 – Adding a Relying Party Trust: Configure Certificate

7. Select Enable support for the WS-Federation Passive protocol radio button and enter the fully qualified domain name of your OnBase server in the URL box. In this example it is https://OnBaseWebServer.domain.com/AppNet/

Figure 3-7 – Adding a Relying Party Trust: Configure URL

NOTE: Make sure to add the trailing / in the URL for the Relying Party URL.

8. Enter the URL of the OnBase Web Server in the Configure Identifiers screen and click Next.

Figure 3-8 – Adding a Relying Party Trust: Configure Identifiers

NOTE: Make sure to add the trailing “/” in the URL for the trust identifier URL.

9. Select Permit all users to access this relying party on the Issuance Authorization Rules screen

Figure 3-9 – Adding a Relying Party Trust: Choose Issuance Authorization Rules

10. Verify that the Encryption tab contains the Web Server SSL Certificate. The Endpoints tab contains the value of the OnBase Web Server URI. This value should contain a trailing ‘/’ – for example, “https://server/appnet/”.

Figure 3-10 – Adding a Relying Party Trust: Ready to Add Trust

11. Hit Next, and Close.

Figure 3-11 – Adding a Relying Party Trust: Finish

12. In the Edit Claim Rules dialog that opens, click Add Rule… to create a new rule.

Figure 3-12 – Edit Claim Rules: Add Rule

13. Select Send LDAP Attributes as Claims

Figure 3-13 – Edit Claim Rules: Choose Rule Type

14. Give the rule a display name. Select Active Directory as the attribute store. Fill out the Mapping as shown below.

Figure 3-14 – Edit Claim Rules: Configure Claim Rule

NOTE: All listed claims must be configured for proper authentication.

LDAP Attribute

Outgoing Claim Type

User-Principal-Name

Name ID

Display-Name

Name

Token-Groups – Unqualified Names

Role

E-Mail-Addresses

E-Mail Address

Table 1 – LDAP Attribute Mapping

NOTE: The Token-Groups – Unqualified Names only returns Security Groups user assignment. 15. Press Apply, then click OK. The AD FS Server is now configured.

3.2 AD FS Endpoints OnBase only supports Windows Authentication and Transport Security Mode. OnBase supports both WS-Trust versions; WSTrust13 and WSTrustFeb2005 are valid values for TrustVersion. The ADFSEndpointAddress selected is based on the Trust Version, Authentication Type and Security Mode which comes from the AD FS server configuration

Figure 3-15 – AD FS Endpoints

For direct communication to the AD FS Server, WSTrust13 is the preferred method as it is the finalized specification of WS-Trust. The WS-Trust February 2005 (ie WSTrustFeb2005) is a draft version of WS-Trust which Microsoft started using when implementing AD FS.

3.3 AD FS Proxy AD FS allows for a proxy service to stand as an intermediary between a client and an AD FS service. Generally, this is just another instance of an AD FS service acting as a proxy, forwarding requests and responses between clients and proxy-enabled endpoints. Enabling proxying for specific AD FS endpoints is outside the scope of this whitepaper. Likewise, an in-depth explanation of Security Support Provider Interfaces (SSPI) and Security Support Providers (SSP) are out of scope. These are components that help perform security related operations, and are used by AD FS to communicate credentials of the user requesting a token from AD FS. If the AD FS Proxy is joined to the same domain as the destination AD FS service, a security support provider does not need to be specified. However, if the AD FS Proxy is not on the same domain as the destination service (ie the AD FS Proxy Server exists in the DMZ), the NTLM security support provider must be specified. To do this, set the ForceNTLM attribute on the “WSTrust” element in the “Hyland.ADFS” configuration section to true.

NOTE: An AD FS Proxy can only use WSTrust2005 as WSTrust2013 won’t pass through the proxy.

4 Web & Application Server 4.1 Prerequisites .NET Framework 4.5 OnBase 14 and higher requires the .NET Framework 4.5.1 or 4.5.2.

Active Directory Federation Service (AD FS) This document assumes that a working AD FS Server has been configured and is functioning properly based on Microsoft’s best practices.

OnBase Installers The AD FS solution discussed in this white paper requires a core build of 14 or higher. For lower versions of OnBase, please refer to the AD FS Installation Guide White Paper for OnBase 12 and 13. This document will assume the core has been installed and is functioning correctly with OnBase authentication.

Certificate Statement AD FS relies heavily on proper certificate chains. There will be numerous references to selfsigned certificates that have been manually added to the certificate stores on various servers. This is not a best practice, nor is it a recommended solution that should be implemented in a live environment. In production environments, only certificates that can be traced back to a valid certificate authority should be used.

4.2 OnBase Web Server NOTE: This guide assumes that you have a functional web server that you can log into with OnBase authentication using SSL. This webserver must also be able to communicate with the ADFS server via the name that will be on its certificate. If a certificate is not available, follow the steps in Appendix A to setup IIS with a Self-Signed Certificate.

Web Server IIS Changes – SSL Setup SSL can be set up by either generating a self-signed certificate or importing a certificate created by a certificate authority. The first option is acceptable in an internal test environment but highly discouraged in any other environment (See Appendix A for more information on Generating a Self-Signed Certificate).

4.2.1.1 Importing a Certificate In environments outside of an internal test environment, it is recommended to have a certificate authority generate a certificate which is imported into IIS. This is preferred because the certificate authority is generally a trusted source of certificates which can be relied on instead of “some machine that generated this certificate”, which is what happens when a certificate is generate by IIS. Certificates that contain a private key have a password associated to them to help prevent bad actors from importing them and impersonating the legitimate certificate holder. 1. 2. 3. 4.

Select the server in IIS Manager Double click on Server Certificates Click the Import… action in the Actions panel on the right. Browse to the certificate and enter the password for the certificate. If you wish to allow the private portion of the certificate to be exported later, check the Allow this certificate to be exported checkbox. Click OK.

4.2.1.2 Creating a HTTPS binding 1. 2. 3. 4. 5. 6.

Select the your website (likely default website) Click Bindings Click Add… Select HTTPS for the Type and select the SSL certificate and click OK. Click Close. Under your AppNet application, select SSL Settings.

7. Check the Require SSL Box. NOTE: This process can be repeated on the Application Server portion, but is not required.

Modifying the Web Server web.config The Web Server, when hosting Web Clients and not acting as a pass-through service location must enable WIF and facilitate negotiation with the AD FS server. 1. Make a backup of the OnBase Web Server’s web.config. 2. Uncomment the configSections for system.identityModel and system.identityModel.services. (see Appendix B: WIF Configuration Schema) 3. Confirm that the authentication mode is set to None. <system.web> ... ...

4. In the system.web section, confirm that authorization is set to deny unknown users with <deny users = “?” /> <deny users="?" />

5. Add a new soapExtensionTypes node to the webServices node <webServices> <protocols>

<soapExtensionTypes>

5. In the system.webServer/modules section, you will find the WSFederationAuthenticationModule and SessionAuthenticationModule modules commented out:

Uncomment the WSFederationAuthenticationModule and SessionAuthenticationModule keys.

6. Confirm that the Application Server is set to use SOAP and AllowNTAuthenticationOnForwarding is set to FALSE. <ApplicationServer Url="http://AppServerURL/Service.asmx" ServiceClientType="SOAP" />

7. Uncomment the modules to enable the WSFAM and SAM modules if they were not already uncommented. ... <section name="Hyland.ADFS" type="Hyland.ADFS.ADFSConfiguration, Hyland.ADFS" /> <section name="system.identityModel" type="System.IdentityModel.Configuration... <section name="system.identityModel.services" type="System.IdentityModel.Services... ...

8. Check that the dmsVirtualRoot is using https. NOTE: Unlike previous sections, this value should not contain a trailing slash, as it will interfere with Pop integrations.



9. Alter the EnableAutoLogin element to True.

10. Enable AD FS in the node.

...

11. Update the <system.identityModel> node referencing system.identityModel. ...

<system.identityModel> <securityTokenHandlers> <securityTokenHandlerConfiguration> <trustedIssuers>

12. Update the <system.identityModel.services> node referencing system.identityModel.services.

...

<system.identityModel.services> <wsFederation issuer="https://ADFS.ADFSdomain.net/adfs/ls/" realm="https://hostname.domain.net/AppNet/" /> <serviceCertificate>

Web Server Virtual Directory Authentication Configuration The Web Server virtual directory should be configured for Anonymous authentication since the identity of the user might not be within the domain and therefore wouldn’t be validated.

Figure 4-1 – Web Server Authentication Settings

4.3 OnBase Application Server The Application Server is a passive receiver of SAML tokens. Since all it needs to do is verify and understand the token, we do not need to enable the WSFAM and SAM modules.

Modifying the Application Server web.config 1. Make a backup copy of the OnBase Application Server web.config. 2. Uncomment the section node in the configSections block with the name system.identityModel and system.identityModel.Services if not already uncommented. <section name="system.identityModel" type="System.IdentityModel.Configuration.SystemIdentityModelSection, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" /> <section name="system.identityModel.services" type="System.IdentityModel.Services.Configuration.SystemIdentityModelServicesSection, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />

3. Alter the httpRuntime element by adding a requestValidationMode attribute. The attribute value must be “2.0”.

4. Enable AD FS by setting the Enabled attribute of the Hyland.ADFS element to True.



5. Update the <system.identityModel> node referencing system.identityModel. NOTE: These following two sections can be Copied and Pasted from the system.identityModel and system.identityModel.services setting from the Web Servers web.config. Make sure not to overwrite the Hyland.ADFS key as it is different in the Application Server web.config than it is in the Web Server web.config.

...



<system.identityModel> <securityTokenHandlers> <securityTokenHandlerConfiguration> <trustedIssuers>

6. Update the <system.identityModel.services> node referencing system.identityModel.services.

...



<system.identityModel.services> <wsFederation issuer="https://ADFS.ADFSdomain.net/adfs/ls/" realm="https://hostname.domain.net/AppNet/" /> <serviceCertificate>



Application Server Virtual Directory Authentication Configuration The Application Server virtual directory should be configured for Anonymous authentication since the identity of the user might not be within the domain and therefore wouldn’t be validated.

Figure 4-2 – Application Server Authentication Settings

Split Web Server and Application Server Configuration In the case of a split OnBase Web/Application Server, the certificates on the Application Server needs to match the Web Server. This includes having the private half of the Web Server’s SSL certificate if it was used for Token Encryption as part of the setup for the Relying Party Trust Encryption in AD FS.

Figure 4-3 – Adding a Relying Party Trust: Configure Certificate

1. Verify that the Web Servers Private Key Certificate has been imported to the Personal Store on the Application Server (See Certificate Locations). 2. Verify that the Web Servers Public Key Certificate has been imported to the appropriate Certificate Store on the Application Server (See Certificate Locations). 3. Verify the Impersonation or Application Pool Identity account has permission to READ the Private Key (See Managing Certificate Permissions)

4.4 Pop Integrations To allow Docpop and similar functionality to use the AD FS integration, first configure the Web Server and Application Server web.config files as to enable AD FS integration for the Web Client. Next, set the enableAutoLogin value to true.

... ... <enableAutoLogin value="true" /> ...

4.5 Remote Clients The following section documents the configuration for the various remote clients. Remote Clients include the Unity Client, Outlook Integration, Report Services and MRM Unity.

Hyland.ADFS Configuration Section Examples from the Remote Clients 4.5.1.1 Example of Default WSTrust13 Configuration ... <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/13/windows transport <SecurityMode>Transport WSTrust13 <AppliesTo>https://hostname.domain.com/AppNet/

4.5.1.2 Example of WSTrustFeb2005 Connecting to a Domain Joined AD FS Proxy ... <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/2005/windo wstransport <SecurityMode>Transport WSTrustFeb2005 <AppliesTo>https://hostname.domain.com/AppNet/

4.5.1.3 Example of WSTrustFeb2005 Connecting to a non-Domain Joined AD FS Proxy ... <WSTrust ForceNTLM="True"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/2005/windo wstransport <SecurityMode>Transport WSTrustFeb2005 <AppliesTo>https://hostname.domain.com/AppNet/



Unity Client, Outlook Integration, Report Services and MRM Unity 1. Open the client configuration file (ie obUnity.exe.config) in the respective install directory 2. Find the configSections element and uncomment the AD FS section as shown below. ...

3. Find the ServiceLocations section. Configure the AD FS service location to use UseADFS with the attribute value set to true and UseNTAuthentication attribute set to false. The resulting section should be as shown below. <ServiceLocations>

4. Uncomment the system.web and Hyland.ADFS elements at the end of the configuration file by removing the highlighted characters: ... <webServices> <soapExtensionTypes> <WSTrust ForceNTLM="false"> https:///adfs/services/trust/13/windowstransport <SecurityMode>Transport WSTrust13 <AppliesTo>http://mydomain.com/AppNet/ -->

5. Update the ADFSEndpointAddress to the correct address of the AD FS Server. 6. Ensure that the Hyland.ADFS element is set to Enabled.

7. Update the AppliesTo to match audienceUris in AppServer web.config.

... <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/13/windows transport <SecurityMode>Transport WSTrust13 <AppliesTo>https://hostname.domain.com/AppNet/

8. Ensure that the endpoint being used is enabled in the AD FS server (See ADFS Endpoint).

4.5.2.1 Unity Client, Outlook Integration, Report Services and MRM Unity via an AD FS Proxy If the application 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 application configuration file, locate the Hyland.ADFS element. 2. Set the ForceNTLM attribute to true. 3. Update the ADFSEndpointAddress to use the ./trust/2005/windowstransport endpoint

4. Update the TrustVersion to WSTrustFeb2005 ... <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/2005/windo wstransport <SecurityMode>Transport WSTrustFeb2005 <AppliesTo>https://hostname.domain.com/AppNet/

4.5.2.2 Web Server Service Locations The following steps are only necessary if the Unity Based Clients will be connecting to the OnBase Web Server’s service location. If the Unity Client uses the OnBase Application Server as the service location, it is not necessary. 1. Add the following location elements to the OnBase Web Server’s web.config. ... <system.web> <system.web> <system.web>

<system.web> <system.web> <system.web> <system.web> ...

Disconnected Scanning As of OnBase 14, the Hyland.ADFS.dll is not included with the Disconnected Scanning installer. This file can be found in the Application Servers bin folder. 1. Update the disconnectedscan.exe.config to contain the following: a. Find the configSections node and update it be as shown below ... <section name="Hyland.ADFS" type="Hyland.ADFS.ADFSConfiguration, Hyland.ADFS "/>

b. Uncomment and configured the following section:

<system.web> <webServices> <soapExtensionTypes> <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/13/windowst ransport WSTrust13 <SecurityMode>Transport <AppliesTo>https:///AppNet/

c. Update the ADFSEndpointAddress to the correct address of the AD FS server and ensure that AD FS is set to Enabled. NOTE: Disconnected Scanning only supports Windows Authentication and Transport Security mode (See ADFS EndPoints). OnBase supports both WS-Trust versions including WSTrust13 and WSTrustFeb2005 as valid values for TrustVersion. Also note that the ADFSEndpointAddress selected is based on the trust version, authentication type and security mode and it comes from the ADFS server configuration.

2. Launch the Disconnected Scanning client from a shortcut configured with the following command line switches: -AL -ADFS -Server NOTE: ADFS only works with the -Server switch as it is not possible to configure Local mode with ADFS since authentication to the ADFS server is required.

4.5.3.1 Debugging Tips for Disconnected Scanning Enabling the NT/LDAP tab and setting hylandTracing to 4 in the Application Servers web.config will help debugging the authentication process. Add the LogClientEventsToEventLog attribute to the Hyland.ADFS element and set it to true. This will write the diagnostics messages to the windows event log on the machine running the disconnected scanning.

... <WSTrust> ...

4.6 Mobile Clients With OnBase 14.0.0.61 and higher it is possible to allow users to access OnBase from the Android or iOS Clients using their AD FS credentials.

NOTE: This configuration requires the Application Server to communicate directly with the AD FS Server or AD FS Proxy Server.

1. Add the following <WSTrust> block to the Application Server’s web.config under the block heading.

... <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/13/windows transport <SecurityMode>Transport WSTrust13 <AppliesTo>https://hostname.domain.com/AppNet/

NOTE: Make sure to remove the closing / in the (in red) header node and add the ending block entry after the close of the block.

2. Update the AppliesTo to match audienceUris in AppServer web.config. 3. Ensure that the endpoint being used is enabled in the AD FS server (See ADFS Endpoint).

Mobile Access via an AD FS Proxy If the application 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 Application Server’s web.config, locate the Hyland.ADFS element. 2. Set the ForceNTLM attribute to true. 3. Update the ADFSEndpointAddress to use the ./trust/2005/windowstransport endpoint 4. Update the TrustVersion to WSTrustFeb2005 <WSTrust ForceNTLM="false"> https://ADFSServer.ADFSdomain.com/adfs/services/trust/2005/windo wstransport <SecurityMode>Transport WSTrustFeb2005 <AppliesTo>https://hostname.domain.com/AppNet/

4.7 ClickOnce Deployment Configuration of Remote Clients The following method can be used for Click Once deployments of the Unity Client, Outlook Integration and Report Services.

NOTE: Before performing the ClickOnce configuration for the Unity Client/Outlook AddIn/Report Services, perform the configuration for a non-ClickOnce version and ensure everything works as expected.

NOTE: The screen shots below are for Unity Client deployed using the Web Deployment strategy but the process is very similar for the other clients. For more information on ClickOnce review the Core Enterprise Installer MRG. Only the screens with AD FS configuration information are included.

1. To configure the Unity Client/Outlook Integration/Report Services with ClickOnce, launch the deployment creation wizard and follow the prompts. 2. Select Advanced Mode

Figure 4-4 Deployment Wizard screen

3. Select the deployment strategy.

Figure 4-5 Deployment Wizard: Unity Client deployment screen

4. In this case, since this is being deployed via a Web Server, select the Web Site from the Web Site dropdown as well as the protocol. HTTPS is recommended. If creating the deployment from a shared folder, the options will be different.

Figure 4-6 Deployment Wizard: Virtual Directory Configuration screen

5. Create a new Service Location. Enter the Service Path and Datasource. In most cases with AD FS this will point to the OnBase Web Server. NOTE: The Use NT / LDAP Authentication check box is not checked.

Figure 4-7 Deployment Wizard: Service Locations screen

6. When the File Edit Notification is shown click on Open Deployment Folder… button.

Figure 4-8 Deployment Wizard: File Edit Notification screen

7. In the opened folder, navigate to the obunity.exe.config file and follow the steps as outlined in the Unity Client/Outlook Integration/Report Services for ADFS section to update the configuration file AD FS. 8. Once all the config changed have been made and the configuration file has been saved, click OK on the File Edit Notication screen.

9. The ClickOnce version is now ready to be deployed. The link displayed in the Summary window will be used to deploy the application.

Figure 4-9 Deployment Wizard: Summary screen

4.8 OnBase Patient Viewer The Patient Viewer (also called Medical Pop) is based on the web client, and such, the service to serve it up is based on the web server.

AD FS Configuration Because the Patient Viewer is a separate service from the Web Server, you will need to create a separate Relying Party Trust on the AD FS server. Follow the steps detailed in Section 3.1 AD FS Server Relying Party Trust Configuration, but:  

Use a different identifier WS-Federation Endpoint that points to the Patient Viewer service (i.e., instead of https://server/AppNet/, use https://server/PatientViewer/).

Modifying the Patient Viewer web.config a. Make a backup of the existing web.config. b. Verify that the configuration sections for Hyland.ADFS, system.identityModel and system.identityModel.services are in the file. c. In the system.web section, you will find the following comment: <deny users="?" /> -->

Uncomment the authentication and authorization sections: <deny users="?" />

d. In the system.web/webServices section you will find the following comment:

-->

Uncomment the soapExtentionTypes section:

<soapExtensionTypes>

e. In the system.webServer/modules section, you will find the WSFederationAuthenticationModule and SessionAuthenticationModule modules commented out:



Uncomment the WSFederationAuthenticationModule and SessionAuthenticationModule keys.



f.

In the appSettings section, set the EnableAutoLogin key to true:



g. Set the Enabled attribute on the Hyland.ADFS node to true:



h. Uncomment and configure the system.identityModel and system.IdentityModel.services sections. Take care to use the correct identifier as the audience URI and Realm settings.

5 User Group Mapping 5.1 OnBase User Group Configuration Within the AD FS integration, user groups are configured in the same way that they were with Windows NT (Active Directory – Basic) or LDAP Authentication. This means that in order for user group mapping to occur, a user group needs to be created within OnBase Config | User | User Groups with the same name as the user group in Active Directory. In the below screenshot, the user group name GRP – Tech Support is the same name in Active Directory. The Active Directory group must be a Security Group. Distribution Groups are not supported.

Figure 5-1 OnBase User Groups & Rights

Figure 5-2 Active Directory Users and Computers

NOTE: For more information on the naming convention review the Network Security MRG or the Network Security White Paper both available on the Hyland Community.

Removing a User from a User Group By default, users are added to user groups in OnBase if matching Active Directory user groups are found, however, users are only removed from the OnBase users group if the OnBase user group has the appropriate Authentication Setting enabled. The Remove users from this group if no matching domain group found setting is configured per OnBase user group under Authentication Settings.

If not enabled (unchecked) on an OnBase user group, if Active Directory does not return a matching user group, the user will be left within the OnBase user group and assigned the respective permissions. If the option is enabled (checked) on an OnBase user group, if Active Directory does not return a matching user group then OnBase will remove the user from the OnBase user group if the user was previously assigned. NOTE: This feature is only available in OnBase 16 and higher.

6 Troubleshooting AD FS will write error messages to the LDAP/NT and Trace tabs in the Diagnostics Console. To enable the tab, enable the LDAP profile in the Application Server’s web.config tab and set the hylandTrace setting to 4.

6.1 Logging Events to the Event Log For debugging the Unity Client/Outlook integration/Report Services add the LogClientEventsToEventLog attribute and set it to true on the Hyland.ADFS element in the respective applications config file (ie obUnity.exe.config). This will write the diagnostics messages to the Windows Event log on the machine running the Unity Client. ...

6.2 Forcing Specific Credentials Forcing a specific username and password can be done, but should only be done for troubleshooting purposes. To do so, add ADFSUsername and ADFSPassword nodes to the WSTrust section.

<WSTrust ForceNTLM="false"> ... <SecurityMode>Transport WSTrust13 <AppliesTo>https://hostname.domain.com/AppNet/ TestUser TestPassword123

6.3 Tracing on the AD FS Server To configure verbose logging, you can only use the Set-ADFSProperties cmdlet as provided as part of the Windows PowerShell cmdlets for AD FS 2.0. Set-ADFSProperties -LogLevel [Verbose,Errors,Warnings,Information]

More information about enabling Tracing within AD FS can be found using the below link(s): http://technet.microsoft.com/en-us/library/adfs2-troubleshooting-configuringcomputers(WS.10).aspx http://jorgequestforknowledge.wordpress.com/2014/02/05/enabling-debug-tracing-inadfs-v2-1-and-v3-0/

6.4 Testing Valid AD FS Configuration To test a request by a user to sign-in via AD FS, the following page presents a selection UI for the user to select an RP application to sign in to. This page only works for RP applications that use the SAML protocol.

https://ADFSServer.domain.net/adfs/ls/IdpInitiatedSignOn.aspx

6.5 Common Errors ID3206: A SignInResponse message may only redirect within the current application This can happen when you navigate to AppNet without the trailing slash. Instead of opening the web client by using https://webServer/AppNet, try https://webServer/AppNet/.

SAML Assertions are not included in token Verify that there are claim rules associated to the Issuance Transform Rules on the Relying Party Trust. This can be checked by right-clicking on the Relying Party Trust and choosing Edit Claims Rules… This was the resolution to the initial error reported for SI: #639679.

Object not set for an instance of an object Verify that all claim rules associated to the Issuance Transform Rules on the Relying Party Trust are configured. This can be checked by right-clicking on the Relying Party Trust and choosing Edit Claims Rules… This was the resolution to the initial error reported for SCR: #214437.

OEM Authentication Failed This error is caused because the token returned from AD FS is either empty or could not be read. If it is the case that it could not be read it is most likely caused because the following block is either missing or hasn’t been uncommented. In the system.web/webServices section you will find the following comment:

-->

Uncomment the soapExtentionTypes section:

<soapExtensionTypes>

Client found response content type of 'text/html', but expected 'text/xml'. The following error message is displayed in the Diagnostics Console when attempting to login via the Web Client: Client found response content type of 'text/html', but expected 'text/xml'. The request failed with an empty response. Check the Web Server web.config to make sure that the ApplicationServer key is configured to communicate over SOAP instead of the Remoting method. Also, check to make sure that you can connect to the Service page.

Value cannot be null The following error is displayed in the Diagnostics Console when attempting to login via the Web Client: Value cannot be null. Parameter name: username Make sure that the Web Server virtual directory is configured for Anonymous authentication Enabled. Also, check to make sure that the authentication and authorization keys are appropriately configured:

<deny users="?" />

The type initializer for 'Hyland.Canvas.CanvasClientConfiguration' threw an exception This error is displayed in the Unity Client when attempting to login. The type initializer for 'Hyland.Canvas.CanvasClientConfiguration' threw an exception Check to make sure that the following section has been uncommented in the obUnity.exe.config file: ... <section name="Hyland.ADFS" type="Hyland.ADFS.ADFSConfiguration, Hyland.ADFS "/>

ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry. This error can occur if the certificate that signs the security token cannot be found using one of the thumbprints specified in the issuerNameRegistry/TrustedIssuers section. If you copied the thumbprint from the Certificate MMC and pasted it into the web.config, it is possible that you copied over some Unicode bytes. You may not see the extra bytes.

Figure 6-1 – Extra Unicode characters may not be visible

In an advanced note editor (ie Notepad++, Notepad2, etc) you can view the file using ANSI encoding (in Notepad++ this is done by choosing Encoding -> Convert to ANSI). After doing this, you may see extra characters.

Figure 6-2 – Extra Unicode characters are visible if the file is viewed using a non-Unicode encoding

Either attempt to type out the thumbprint manually, or using an advanced note editor, convert the file to ASCII and remove the extra Unicode characters. If you attempt to past the thumbprint after copying from MMC, make sure to delete even the double quotes, since the extra Unicode bytes may be between the double quotes and the first character of the thumbprint.

OnBase Web Client display a login page The OnBase system does not support the use of the Failover to Interactive Mode Network Security options when configured for AD FS. This was the resolution to the initial error reported for SCR: #214433.

Figure 6-3 OnBase Web Client with Network Security Configured

Failed to connect. User ‘’ does not belong to any user groups OnBase does not support the mapping of Active Directory Distribution Groups back to OnBase. The reason is that Distribution Groups are not returned in the Token Groups attributed (TokenGroups – Unqualified Names). These groups are used for email applications, not security. This means user assignment in Active Directory must be to Security Groups and further the Security Groups would then be mapped to OnBase.

Figure 6-4 OnBase Web Client logging into OnBase

Read more about Active Directory Group Types in the following link: https://technet.microsoft.com/en-us/library/cc781446%28v=ws.10%29.aspx

MSIS7042: The same client browser session has made 'X' requests in the last 'Y' seconds. Contact your administrator for details. Most likely, one of the URLs doesn't match. For instance, the Web Server URL might end in /AppNet and somewhere else it might be configured as /AppNet/ with a trailing slash. Make sure to leave the trailing slash off of dmsVirtualRoot in the Web Servers web.config as it will cause redirect issues, but make sure the trailing slash is everywhere else.

HTTP 400 Bad Request When a user attempts to login to the OnBase Web Client, they are redirected to a page displaying the following: HTTP 400 Bad Request The webpage cannot be found. Viewing the response page in an application like Fiddler would show the following message: Bad Request - Request Too Long HTTP Error 400. The size of the request headers is too long. This is caused when a user is a member of many Active Directory groups and is a limitation within IIS when using Kerberos authentication. https://support.microsoft.com/en-us/kb/2020943

This page cannot be displayed Microsoft has a number of additional troubleshooting steps which can be used when running into issues with an AD FS configuration. The below Knowledge Base article describes them in greater depth. https://support.microsoft.com/en-us/kb/3044971

7 Appendix A: Generating a Self-Signed Certificate in IIS Generating a Self-Signed Certificate NOTE: The following example shows the AppServer and Web Server located on the same server. This is not a required setup for AD FS. For simplicity, this guide will contain instructions on how to use self-signed certificates. This type of certificate should not be used in a production environment, but simplifies the testing and setup.

1. Select the Server in IIS Manager

2. Select Server Certificates

3. Select Create Self Signed Certificate…

4. Pick a user friendly name that helps identify the certificate

5. Press Okay.

Assigning the Certificate to the Web Site 1. Select the your website (likely default website)

2. Click Bindings

3. Click Add…

4. Select HTTPS for the Type and select the SSL certificate you just generated and press OK.

5. Press Close.

6. Under your AppNet application, select SSL Settings.

7. Check the Require SSL Box. The

NOTE: This process can be repeated on the Application Server portion, but is not required.

8 Appendix B: Internet Information Services and Windows Identity Foundation Internet Information Services (IIS) interacts with Windows Identity Foundation (WIF) through the Session Authentication Module (SAM) and the Federated Authentication Module (WSFAM). The WSFAM handles negotiation with AD FS, and SAM processes the session cookies. WSFAM and SAM are documented in detail here.

8.1 WIF Configuration Schema The WIF configuration schema is documented here.

system.identityModel 8.1.1.1 Template <system.identityModel> <securityTokenHandlers> <securityTokenHandlerConfiguration> <trustedIssuers>

8.1.1.1.1 audienceUris The audienceUris values are what are used to tell the AD FS server who is making a request. This is necessary to specify, since AD FS requires the creation of “Relying Party Trusts” to establish trust between a relying party and AD FS. In this case, the “Relying Party” is a particular OnBase service, and is identified by AD FS by a value in the audienceUris section.

8.1.1.1.2 trustedIssuers trustedIssuers is used to identify the AD FS server with which a trust relationship has been established. They are identified by the thumbprint of the Token Signing Certificate configured in the AD FS Management utility. The thumbprint should be entered without spaces. Reference the Certificate Identification section for more information. The name of the trustedIssuer is the Federation Service Identifier value found in the AD FS Management utility.

8.1.1.1.3 certificateValidation http://msdn.microsoft.com/en-us/library/hh568649(v=vs.110).aspx The certificateValidationMode determines how to validate certificates used by the issuer. “None” is appropriate when using self-signed certificates. Other valid values we can expect are: Validation Mode

Description

ChainTrust

The certificate is valid if the chain builds to a certification authority in the trusted root store.

None

No validation of the certificate is done.

PeerOrChainTrust

The certificate is valid if it is in the trusted people store, or if the chain builds to a certification authority in the trusted root store.

PeerTrust

The certificate is valid if it is in the trusted people store.

system.identityModel.services 8.1.2.1 Template <system.identityModel.services> <wsFederation issuer="https://issuer/" realm="https://yourRealm/" requireHttps="true" /> <serviceCertificate>



8.1.2.2 wsFederation http://msdn.microsoft.com/en-us/library/hh568665(v=vs.110).aspx

The wsFederation node provides configuration for the WSFederationAuthenticationModule. The two required attributes are shown above. The issuer attribute specifies the token issuer and corresponds to the end point on the AD FS to connect to (ie the AD FS Server/Proxy). The realm attribute identifies the relying party (ie the OnBase Web Server). This must match the Relying Party identifier as configured in AD FS. Reference the Certificate Identification section for more information on how to determine the thumbprint of the certificate.