Tenrox. Single Sign-On (SSO) Setup Guide. January, Tenrox. All rights reserved.

Transcription

1 Tenrox Single Sign-On (SSO) Setup Guide January, Tenrox. All rights reserved.

2 About this Guide This guide provides a high-level technical overview of the Tenrox Single Sign-On (SSO) architecture, as well as describes the procedure for setting up the SSO software on a 64-bit Operating System (OS). This guide is used to set up the SSO for the following Tenrox releases: Tenrox 2011 R1 Tenrox 2011 R2 Tenrox 2011 R3 Tenrox Technical Support The Tenrox support specialists are trained to use, configure, and troubleshoot Tenrox in your specific enterprise environment. If you have any questions, you can reach us by: Calling (450) Sending an to support@tenrox.com Tenrox Software License Agreement The Tenrox Software license agreement was reviewed and accepted during the installation procedure of this software in your environment. Copyright 2012 Tenrox. All rights reserved. You may not photocopy or share this document with any other party without express written permission from Tenrox. For additional information, please contact Tenrox at: Corporate site: Sales sales@tenrox.com Support support@tenrox.com Or click Help > Contents and Index from within Tenrox. Issue 1

3 Tenrox Single Sign-On Setup Guide This guide provides an overview of the Tenrox Single Sign-On (SSO) architecture, as well as the instructions for installing and setting up the Tenrox Single Sign-On (SSO) software on a Windows Server 2008 (R2). For more information, see the following: Single Sign-On (SSO) Overview Setting Up the SSO Add-On 2012 Tenrox. All rights reserved. 3

4 Tenrox Single Sign-On Setup Guide Single Sign-On (SSO) Overview Tenrox provides a comprehensive solution that supports the following: Identity Provider (IdP): master authentication authority that asserts information about the user accessing the Tenrox solution; for example, the user, John Doe with the address of john.doe@acompany.com is authenticated into the system using any password mechanism or directory authentication service. Note: The Tenrox solution includes a Web site (TLogin) that is installed on the customer site to provide the authentication token. Service Provider (SP): slave process that relies on information supplied by the Identity Provider; a trust relationship is established between the IdP and SP and it is up to the SP to decide whether to trust the assertions provided SSO Architecture The Tenrox Single Sign-On (SSO) architecture is based on two main components: Identity Provider (IdP) defined in the Tenrox TLogin Web site running in the client network infrastructure Service Provider (SP) defined by the Tenrox application Web site (TEnterprise) Note: The communication between the IdP and SP uses a secure and encrypted Secure Sockets Layer (SSL)- based communication channel. 4

5 Single Sign-On (SSO) Overview Server Authentication Process The server authentication process in the Tenrox application consists of the following steps when using the SSO provider: 1. User attempts to reach a hosted Tenrox application (SP), TEnterprise or Web services. 2. Tenrox (SP) generates a Security Assertion Markup Language (SAML) authentication request. The SAML request is encoded and embedded into the URL for the TLogin (IdP) Web site. 3. Tenrox (SP) sends a redirect to the user's browser. The redirect URL includes the encoded SAML authentication request that should be submitted to the TLogin (IdP) Web site. 4. TLogin (IdP) decodes the SAML request and extracts the URL. TLogin (IdP) then authenticates the user by either requesting for valid login credentials or checking for valid session cookies. 5. TLogin (IdP) generates a SAML response that contains the authenticated user's name. In accordance with the SAML 2.0 specification, this response is digitally signed with the partner's public and private keys. 6. TLogin (IdP) encodes the SAML response and returns that information to the user's browser. TLogin (IdP) provides a mechanism so that the browser can forward that information to Tenrox (SP). 7. Tenrox (SP) verifies the SAML response using the public key. If the response is successfully verified, the user is redirected to the requested URL Tenrox. All rights reserved. 5

6 Tenrox Single Sign-On Setup Guide Tenrox Authentication Providers The TLogin supports multiple pluggable authentication providers; by default, the following authentication providers are supported: TenroxSDKAuthProvider WindowsAuthProvider ActiveDirectoryAuthProvider RemoteActiveDirectoryAuthProvider Note: The authentication provider used is defined in the configuration of the TLogin (IdP), allowing a common access point to authorization regardless of the authentication type. TenroxSDKAuthProvider The TenroxSDKAuthProvider is a basic Tenrox authentication method where both the user name and password are stored and managed by the Tenrox application. With this authentication method, a logon page is always displayed and users are prompted to enter their correct credentials that are stored in Tenrox. There is no synchronization connection between the user in Tenrox and the domain user in the organization. WindowsAuthProvider The WindowsAuthProvider method is used when users are logged onto a domain while accessing the Tenrox application. The Internet Information Services (IIS) server has anonymous access removed and Windows Authentication switched on. With this authentication method, the Tenrox application retrieves the domain user name from the request and uses it to process the user in the Tenrox application. As a result, a logon page is not displayed and users are not prompted for their user names or passwords. Note: In the case users are not currently logged onto the domain, then they are prompted for their user names and passwords. ActiveDirectoryAuthProvider The ActiveDirectoryAuthProvider method uses SAML 2.0 to securely connect the two networks together. It is certificate-based and secure with the responsibility of entering the credentials and verifying their transfer from Tenrox to the clients network. The client hosts the authentication service with the TLogin Web site and provides Tenrox with an assertion that Tenrox uses to perform its own validation for the users logging on. The assertion contains user information, allowing Tenrox to process the request and open the requested page. RemoteActiveDirectoryAuthProvider The RemoteActiveDirectoryAuthProvider method allows Tenrox to validate a user against a remote active directory. This is performed through an installed Web service on the client Web service with the credentials being passed from the Tenrox logon to the Web service on the client network over SSL. The Web service queries the active directory with the supplied credentials and returns a pass or fail to the Tenrox application. No information is communicated back to Tenrox regarding an invalid user name, invalid password or any internal domain-specific information; as a result, there is no risk of exposure to any domain or user data and no hints to breach network security. The illustration represents the interaction between the Tenrox application and the remote Web service. 6

7 Single Sign-On (SSO) Overview 2012 Tenrox. All rights reserved. 7

8 Tenrox Single Sign-On Setup Guide Setting Up the SSO Add-On This section describes the installation and setup of the SSO software. System Requirements Before installing the Tenrox SSO software, ensure that the following is installed or configured on your machine: Operating System (OS): Microsoft Windows 2008 Server R2 (64-bit OS) Minimum machine requirements: Memory: 2 GB RAM Disk space: 1 GB HD Web Server: IIS (Internet Information Services) version 7.5 with the following options: Common HTTP Features (All save WebDav) Application Development (ASP.NET, ISAPI Extensions, ISAPI Filters) Health and Diagnosis (HTTP Logging, Logging Tools, Request Monitor) Security (Basic Authentication, Windows Authentication) Management Tools (IIS Management Console) SSL: valid certificate from a valid certificate authority to allow SSL for the site Note: The SSL certificate is also installed on the Web site. Windows HTTP Services Certificate Configuration Tool (WinHttpCertCfg.exe) Note: The Windows HTTP Services Certificate Configuration Tool can be downloaded from c748e422833f&displaylang=en. Local user account when using Windows authentication: create an account on your local Web server to allow Tenrox support personnel to access the application and help resolve problems 8

9 Setting Up the SSO Add-On Installing the SSO Software The SingleSignOn.exe file is used to install the SSO software on the server. The SSO software creates the TLogin folders and the virtual directory in the IIS. Note: Tenrox provides the SingleSignOn.exe file and the password for installing the SSO software. To install the Single Sign-On software: 1. Use Windows Explorer to locate the SingleSignOnEnglish.exe file Note: The SSO software is typically provided either on CD/DVD or through the Tenrox File Transfer Protocol (FTP) site; for more information, contact your system administrator or Tenrox representative. 2. Double the SingleSignOnEnglish.exe file to extract main application files. 3. Click Next to continue when the Single Sign-On setup wizard is displayed. 4. Enter the password and then click Next to continue. Note: Tenrox provides the required password for running the installation process Tenrox. All rights reserved. 9

10 Tenrox Single Sign-On Setup Guide 5. Specify the default folder or click Browse to select another folder for the software installation, and then click Next to continue. Note: Tenrox recommends using the default folder, C:\Program Files\Tenrox\Single Sign-On Extension\ to avoid problems when saving files. 6. Click Install to create the virtual directory TLogin on the server. Note: If the virtual directory TLogin already exists on the server, the user prompted to either click Yes to skip the creation of this virtual directory and continue with the installation or No to create a new virtual directory. 7. Click Finish to exit the software setup wizard after the software is successfully installed. 10

11 Setting Up the SSO Add-On Importing and Setting Up the Permissions for the Certificate Tenrox provides the certificate that is installed using the host35_w3svc1_cert.pfx file. After the certificate is installed, it is imported and its permissions are set up. Note: Before setting up the certificate, ensure that the server is part of the domain and can access the Internet using Hypertext Transfer Protocol Secure (HTTPS). To import and set up the permissions for the certificate: 1. Install the certificate in the Local Computer\Personal\Certificates folder. 1a. From the File menu, click Add/Remove Snap-in. 1b. From the Standalone tab, click Add. 1c. Select Certificates from the Available Standalone Snap-ins list and then click Add. 1d. Select the Computer account option from the Certificate snap-in dialog box and then click Next. 1e. Select the Local computer option to specify the computer that this console is running on and then click Finish. 1f. Click Close and then click OK. 2. From the console tree, right-click the logical store where you want to import the new certificate and then click All Tasks>Import. Note: The default location for certificates is on the Console Root in the Certificates (Local Computer)/ Personal/Certificates folder Tenrox. All rights reserved. 11

12 Tenrox Single Sign-On Setup Guide 3. Click Browse to locate the host35_w3svc1_cert.pfx file and then click Next to continue. Note: To locate the host35_w3svc1_cert.pfx file provided by Tenrox, specify the *.pfx extension as the file type. 4. Enter tenrox as the password for the private key and then click Next to continue. 5. Select the Place all certificates in the following store option and then click Browse to select the certificate store. Note: The default location for certificates is on the Console Root in the Certificates (Local Computer)/ Personal/Certificates folder. 6. Click Next to continue. 12

13 Setting Up the SSO Add-On 7. From Certificate Manager, right-click the Tenrox certificate Test.tenroxhosting.com and then click Manage Private Keys from the shortcut menu. 8. Click the Add button and then type IIS AppPool\DefaultAppPool to add the application pool to the certificate key. 9. Copy and paste the following URL in the browser address box to access the Windows HTTP Services Certificate Configuration Tool (WinHttpCertCfg.exe) page: c748e422833f&displaylang=en 10. Download the winhttpcertcfg.msi file (Windows Installer Package) and then run the file to install the tool and documentation on the server. 11. Launch Command Prompt and enter the following commands to set the correct Access Control List (ACL) entries on the certificate that was previously installed: C:\Program Files\Windows Resource Kits\Tools>winhttpcertcfg -g -c LOCAL_MACHINE\My -s Test.tenroxhosting.com -a "NETWORK SERVICE" C:\Program Files\Windows Resource Kits\Tools>winhttpcertcfg -g -c LOCAL_MACHINE\My -s Test.tenroxhosting.com -a <Internet_Guest_Account(IUSR_...)> 2012 Tenrox. All rights reserved. 13

14 Tenrox Single Sign-On Setup Guide Configuring the Hosted Environment After the ACL entries for the certificate are set, the virtual directory (portal) and the required permissions on the certificate that the SSO application uses are configured. To configure the hosted environment 1. Provide the URL of your Web server to the Tenrox On-Demand team to have them set up the configuration file. Note: Tenrox will provide the configuration file LoginConfig.xml. 2. Copy the configuration file LoginConfig.xml to C:\Program Files\Tenrox\Single Sign-On Extension\TLogin\config. 3. Generate the metadata file required by the Tenrox server by clicking the link MetadataIssuer.ashx if the file is opened from the Web server; otherwise, enter the URL TLogin/MetadataIssuer.ashx in the Web browser. 4. Send the generated metadata file to the Tenrox On-Demand team to have them configure the hosted environment for use with the SSO add-on. Note: After Tenrox configures the hosted environment for use with the SSO add-on, they will send you the metadata file (client.metadata). The application is unavailable until the SSO configuration is complete. 5. Copy the client.metadata file sent by Tenrox to C:\Program Files\Tenrox\Single Sign-On Extension\TLogin\spMetadata. 6. Enter the URL in the Web browser to access the Tenrox Login for your organization. Note: The SSO add-on should now be working and can be tested. 14