Mixed Authentication Setup Version 8.2 January 1, 2016 For the most recent version of this document, visit our documentation website.
Table of Contents 1 Overview 3 2 IIS installed components 3 2.1 Creating an active directory authenticated site 5 2.2 Creating new application pools in IIS 6 2.3 Creating a new website in IIS 7 2.4 Configuring the site to use active directory authentication 11 3 Relativity user account active directory setup 12 3.1 Database setup 12 3.2 Internet Explorer setup 13 4 Configuring custom pages for AD authentication 14 4.1 Determining the application GUID 14 4.2 Configuring custom pages on the IIS 14 4.2.1 Configuring custom pages for the first time 14 4.2.2 Upgrading your custom page and user-friendly URL configurations 18 5 Configuring AD site bindings 21 6 Additional troubleshooting 22 6.1 401.1 error when browsing to website 22 6.2 Prompted to log in when browsing to website 22 Relativity Mixed Authentication Setup - 2
1 Overview You have the option to set up mixed authentication for Active Directory (AD) in a single Relativity instance. For mixed authentication, you create an additional website that enforces Windows AD authentication. External users are authenticated via Relativity username and password over SSL, while internal users, those already authenticated into the domain, do not need to supply Relativity login credentials. Note: This guide is most commonly used when installing the processing server. 2 IIS installed components Before setting up mixed authentication, confirm that the following IIS roles have been installed. Please note that the ordering of these roles is different in Windows Server 2012. Relativity Mixed Authentication Setup - 3
Relativity Mixed Authentication Setup - 4
2.1 Creating an active directory authenticated site To create the AD Authentication site: 1. Log in to your web server. 2. Stop the website to disable the site or IIS. 3. Navigate to C:\Program Files\kCura Corporation. This assumes Relativity was installed to the default location. 4. Create a new folder here called RelativityAD. Note that the folder can't contain a space. 5. Copy all contents from the Relativity folder to the RelativityAD folder. Relativity Mixed Authentication Setup - 5
2.2 Creating new application pools in IIS Perform the following steps to create new application pools in IIS: 1. Open IIS. 2. Right-click Application Pool and select Add Application Pool. 3. Name the application pool RelativityAD. Confirm that.net v4.0 is selected. Change the Managed pipeline mode to Integrated 4. Click OK. 5. Click Advanced Settings on the right hand side of IIS. 6. Change the identity of the Process Model by clicking. Relativity Mixed Authentication Setup - 6
7. Select Custom Account, and click Set. 8. Enter the Relativity Service Account. You just created an application pool for the Relativity (AD) Virtual Directory. Now you must do the same for the other new virtual directories. Perform the steps again to create the following: Relativity.DistributedAD Relativity.ServicesAD RelativityWebAPIAD and Relativity.RESTAD. 2.3 Creating a new website in IIS Perform the following steps to create a new website called RelativityAD within IIS: Note: You must perform these steps while logged in with a Relativity Service Account. 1. Right-click Sites and select Add Website. 2. Name the site RelativityAD. 3. Select the RelativityAD app pool. 4. Enter the physical path, which should be: C:\inetpub\wwwroot. Relativity Mixed Authentication Setup - 7
5. Change the IP address to an available internal IP address. 6. If your custom applications provide user-friendly URLs for access to custom pages, complete these steps: Relativity Mixed Authentication Setup - 8
a. Expand your RelativityAD site and then your Relativity site. b. Right-click on the App folder and select Convert to Application from the menu. c. On the Add Application dialog, click OK. Create applications for the new RelativityAD site: 1. Right-click the RelativityAD site and select Add Application. 2. Enter the Alias Relativity. 3. Enter the physical path, which should be similar to C:\Program Files\kCura Corporation\RelativityAD\EDDS. 4. Select the appropriate application pool for this new application. In this case, the application pool is RelativityAD. 5. Repeat these steps for all other applications. Make sure to select the appropriate app pool for each application. Relativity.Distributed: C:\Program Files\kCura Corporation\RelativityAD\EDDS.Distributed Relativity.Services: C:\Program Files\kCura Corporation\RelativityAD\Relativity.Services RelativityWebAPI: C:\Program Files\kCura Corporation\RelativityAD\WebAPI Relativity.REST: C:\Program Files\kCura Corporation\RelativityAD\Relativity.REST Relativity Mixed Authentication Setup - 9
HTMLArea: C:\Program Files\kCura Corporation\RelativityAD\HTMLArea\HTMLArea-6.24.04 Note: Although the.net Framework Version column shows "v2.0" and "v4.0" for.net Framework versions, these equate to ASP.NET 3.5 and ASP.NET 4.5. Due to the internals of how application pools bind to.net Framework versions, the actual version name written to configuration (and thus displayed in the tool) corresponds to the original.net Framework file version. 6. Click on the RelativityAD site (Select ). 7. Double-click Authentication. Relativity Mixed Authentication Setup - 10
8. Set Anonymous Authentication to Disabled and Windows Authentication to Enabled. Note: Under the RelativityAD site, only Relativity and RelativityWebAPI required Windows Authentication to be enabled. 9. Click on Relativity.Services under the RelativityAD site, and then double-click Authentication. 10. Set Anonymous Authentication to Enabled, and Windows Authentication to Disabled. 11. Repeat step 10 for the following applications under the RelativityAD site: Relativity.DistributedHTMLArea Relativity.Distributed Relativity.REST HTMLArea 2.4 Configuring the site to use active directory authentication Update the authentication and authorization sections in all web.config files to match the following format: <authentication mode="windows" /> <authorization><deny users="?" /></authorization> You can find web config files in the following folders: C:\Program Files\kCura Corporation\RelativityAD\EDDS C:\Program Files\kCura Corporation\RelativityAD\EDDS.Distributed Relativity Mixed Authentication Setup - 11
C:\Program Files\kCura Corporation\RelativityAD\WebAPI 3 Relativity user account active directory setup Perform one of the following user account setups procedures: 3.1 Database setup The users in Relativity must be set up with an appropriate active directory account. There are two ways of accomplishing this: 1. Log in to Relativity through the Forms Authenticated site. 2. Navigate to the System Administrators section and click the Users tab. 3. Navigate to the Authentication Data section of each user s properties and enter their domain login. For example, kcura\user01. OR 4. Adjust and execute the following statement in SQL: UPDATE EDDS.EDDSDBO.[User] SET AuthenticationData = 'domain\adaccount' WHERE EmailAddress = 'emailaddress' If you have to update several users, use the following script: /****** This script will update all users in the system to use AD authentication. The AuthenticationData field will be updated with domain\username, as the username appears in the email address. ******/ DECLARE @domain varchar(30) SET @domain = 'kcura' ---Set this value to your domain name. DECLARE DBCursor CURSOR FOR SELECT ArtifactID FROM EDDS.EDDSDBO.[User] OPEN DBCursor DECLARE @user varchar(30) FETCH next FROM DBCursor INTO @user WHILE @@FETCH_STATUS = 0 BEGIN UPDATE EDDS.EDDSDBO.[User] Relativity Mixed Authentication Setup - 12
SET AuthenticationData = @domain + '\' + (SELECT LEFT(EmailAddress,patindex ('%@%',EmailAddress)-1) FROM [User] WHERE ArtifactID = @user) WHERE ArtifactID = @user FETCH NEXT FROM DBCursor INTO @user END CLOSE DBCursor DEALLOCATE DBCursor To ensure a valid active directory account is entered, run the following command from the command prompt: C:\>whoami This should return: domain\username. After this change is made, a user with this particular active directory account can attempt to log into the system. 3.2 Internet Explorer setup To ensure that users will not be prompted on entry to Relativity, the site must run in the IE local intranet security zone. Relativity Mixed Authentication Setup - 13
4 Configuring custom pages for AD authentication Relativity automatically deploys custom pages in most environments. However, you must manually configure your environment to use custom pages through an AD authenticated site. This following information describes how to complete this configuration by copying your custom pages to the AD web site and converting your custom pages to an application on the IIS. These updates ensure that your custom pages display properly, and that your users don t receive any errors when trying to access them. 4.1 Determining the application GUID You need to know the GUID for the application to locate the folder that contains its custom pages. To determine the GUID, open Microsoft SQL Server Management Studio. Run this query on the ApplicationServer table in the EDDS. Replace YourApplicationName with the name of your application. select Name, [GUID] from EDDS.eddsdbo.LibraryApplication where Name = 'YourApplicationName' 4.2 Configuring custom pages on the IIS You must configure your custom pages for AD authentication on the IIS for them to work properly with this authentication mode. You may also need to configure user-friendly URLs if they are used to access custom pages in your environment. After you complete the initial setup, you may need to modify this configuration when you upgrade to a new version of Relativity. This section contains the following information: 4.2.1 Configuring custom pages for the first time This section includes information about configuring your custom pages on the IIS for the first time. It also describes how to configure user-friendly URLs if you are currently using them in your applications. Configure your custom pages for the first time: 1. On your web server, locate the CustomPages directory within the Relativity installation folder under the Forms site: C:\Program Files\kCura Corporation\Relativity\EDDS\CustomPages\ 2. Perform one of the following tasks: Copy all the custom pages from the Forms site - Copy the entire CustomPages directory to the EDDS folder within the AD site installation directory. Next, continue with step 5. For example, your directory may be located in this file path: Relativity Mixed Authentication Setup - 14
C:\Program Files\kCura Corporation\RelativityAD\EDDS Copy only the custom pages for a specific application from the Forms site - continue with step 3. 3. Create a folder called CustomPages in the installation directory of the AD site, if it doesn't already exist. 4. Use these steps to copy the folder containing the custom pages for your application from the Forms site to the CustomPages folder of the AD authenticated site: a. Locate the your CustomPages folder on the Form site in the following directory, where <YourApplicationGUID> is the unique identifier assigned to your application: C:\Program Files\kCura Corporation\Relativity\EDDS\CustomPages\<YourApplicationGUID> b. Paste your CustomPages folder to this directory on the AD site: C:\Program Files\kCura Corporation\RelativityAD\EDDS\CustomPages\ 5. Open the Server Manager and navigate to the IIS. 6. To promote the location of the custom pages to an application, expand your RelativityAD site and then the Custom Pages folder in the Connection pane. 7. Locate the subfolder with your application GUID. 8. Right-click on the folder and select Convert to Application from the menu. When creating the application, make sure that you use the app pool that matches your application GUID. Relativity Mixed Authentication Setup - 15
9. Click OK. 10. If you are currently logged in to Relativity, log out and close the browser. 11. Log in to Relativity with AD authentication. 12. Navigate to a custom page for your application. Configure user-friendly URLs for custom pages: 1. Open the Server Manager and navigate to the IIS. 2. Expand your RelativityAD site and then your Relativity site. Relativity Mixed Authentication Setup - 16
3. Right-click on the new Apps application and select Add Virtual Directory. 4. On the Add Virtual Directory dialog, enter the user-friendly URL assigned to your custom application through Relativity to the Alias field. Relativity Mixed Authentication Setup - 17
5. In the Physical path field, select the path to the application subfolder under the Apps folder on your machine. 6. Click OK. 7. Access your custom page with its user-friendly URL. 4.2.2 Upgrading your custom page and user-friendly URL configurations When you install a new version of Relativity, you need to upgrade the configuration of your custom pages on the IIS, as well as the user-friendly URLs if you are using them to access custom pages. Upgrade your custom page configuration: 1. On your web server, locate the CustomPages directory within the Relativity installation folder under the Forms site, and copy the custom page for a specific application that you have updated: C:\Program Files\kCura Corporation\Relativity\EDDS\CustomPages\<YourApplicationGUID> 2. Paste the custom page to the following AD directory: C:\Program Files\kCura Corporation\RelativityAD\EDDS\CustomPages\<YourApplicationGUID> Upgrade your custom page configuration for user-friendly URLs: 1. On your web server, copy the folder with the name of your user-friendly URL under the Relativity installation folder: C:\Program Files\kCura Corporation\Relativity\EDDS\Apps\<YourUserFriendlyURL> 2. Paste this folder in the following directory: C:\Program Files\kCura Corporation\RelativityAD\EDDS\Apps Relativity Mixed Authentication Setup - 18
3. Open the Server Manager and navigate to the IIS. 4. Expand your RelativityAD site and then your Relativity site. Relativity Mixed Authentication Setup - 19
5. Right-click on the App folder and select Convert to Application from the menu. 6. On the Add Application dialog, click OK. 7. Right-click on the new Apps application and select Add Virtual Directory. 8. On the Add Virtual Directory dialog, enter the user-friendly URL assigned to your custom application through Relativity in the Alias field. Relativity Mixed Authentication Setup - 20
9. In the Physical path field, select the path to the application subfolder under the Apps folder on your machine. 10. Click OK. 11. Access your custom page with its user-friendly URL. 5 Configuring AD site bindings Use these steps to verify that the bindings for your AD site are configured correctly. 1. Open the IIS Manager. 2. In IIS Manager Connections pane, expand Sites. 3. Right -click on the Default Web Site, and click Edit Bindings on the menu. 4. Confirm that Site Bindings dialog list the following binding types. Add new bindings, if necessary. 5. Expand the Default Web Site. Relativity Mixed Authentication Setup - 21
6. Right-click on the Relativity.Services site. On the right-click menu, click Manage Application, and then Advanced Settings. 7. On the Advanced Settings dialog, confirm that the Enabled Protocols field includes http, net.pipe, and net.tcp. Update this list, if necessary. 6 Additional troubleshooting The sections below contain some additional troubleshooting information which may be helpful. 6.1 401.1 error when browsing to website You receive error 401.1 when you browse a Web site that uses Integrated Authentication and is hosted on IIS 5.1 or a later version Perform the registry change on the web server(s) outlined here: http://support.microsoft.com/default.aspx?scid=kb;en-us;896861 6.2 Prompted to log in when browsing to website If you are prompted for a login when the system is configured for Active Directory authentication, this behavior may be caused by one of the following: The IIS 6.0 website is part of an IIS application pool. The application pool is running under a local account or under a domain user account. The website is configured to use Integrated Windows authentication only. Relativity Mixed Authentication Setup - 22
In the last scenario, when Integrated Windows authentication tries to use Kerberos authentication, it may not work. To use Kerberos authentication, a service must register its service principal name (SPN) under the Active Directory account through which it is running. By default, Active Directory registers the network basic input/output system (NetBIOS) computer name. Active Directory also permits the Network Service or the Local System account to use Kerberos. The following Microsoft KB article provides a resolution to this problem: http://support.microsoft.com/kb/871179 You must install suptools.msi from the support/tools folders on the Windows Server 2003 CD/DVD. Be sure to install the setspn.exe file. 1. Open a command prompt. 2. Browse to the directory where the setspn.exe is installed. 3. Run the following command: setspn.exe -a http/iis_computer's_netbios_name DomainName\User- Name. You must have an account with sufficient domain account privileges to run this command. Be sure to replace the IIS_computer's_NetBIOS_name with the netbios name of the computer. Replace the DomainName\Username with the user account that the IIS App pool is running underneath. 4. After this is complete, run the following command: setspn.exe -a http/iis_computer's_fqdn DomainName\UserName. Be sure to replace the IIS_computer's_FQDN with the fully qualified domain name for the computer. If the computer name is webserver and it is on the test.local domain the FQDN would be webserver.test.local. Be sure to replace the domainname\username with the account that is running the application pools. Relativity Mixed Authentication Setup - 23
Proprietary Rights This documentation ( Documentation ) and the software to which it relates ( Software ) belongs to kcura LLC and/or kcura s third party software vendors. kcura grants written license agreements which contain restrictions. All parties accessing the Documentation or Software must: respect proprietary rights of kcura and third parties; comply with your organization s license agreement, including but not limited to license restrictions on use, copying, modifications, reverse engineering, and derivative products; and refrain from any misuse or misappropriation of this Documentation or Software in whole or in part. The Software and Documentation is protected by the Copyright Act of 1976, as amended, and the Software code is protected by the Illinois Trade Secrets Act. Violations can involve substantial civil liabilities, exemplary damages, and criminal penalties, including fines and possible imprisonment. 2015. kcura LLC. All rights reserved. Relativity and kcura are registered trademarks of kcura LLC. Relativity Mixed Authentication Setup - 24