Technical Integration Guide for Entrust IdentityGuard 9.1 and Citrix Web Interface using RADIUS

Transcription

1 Technical Integration Guide for Entrust IdentityGuard 9.1 and Citrix Web Interface using RADIUS Document issue: 2.0 August 2009

2 Entrust is a registered trademark of Entrust, Inc. in the United States and certain other countries. Entrust is a registered trademark of Entrust Limited in Canada. All other company and product names are trademarks or registered trademarks of their respective owners. The material provided in this document is for information purposes only. It is not intended to be advice. You should not act or abstain from acting based upon such information without first consulting a professional. ENTRUST DOES NOT WARRANT THE QUALITY, ACCURACY OR COMPLETENESS OF THE INFORMATION CONTAINED IN THIS ARTICLE. SUCH INFORMATION IS PROVIDED "AS IS" WITHOUT ANY REPRESENTATIONS AND/OR WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, BY USAGE OF TRADE, OR OTHERWISE, AND ENTRUST SPECIFICALLY DISCLAIMS ANY AND ALL REPRESENTATIONS, AND/OR WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT, OR FITNESS FOR A SPECIFIC PURPOSE. Copyright Entrust. All rights reserved.

3 Table of Contents Introduction... 4 Integration information...4 Partner contact information...4 Supported authentication methods...4 Capabilities...5 Integration overview... 6 Integration with Entrust IdentityGuard...6 Migrating users to Entrust IdentityGuard... 9 Forced migration...9 Phased migration with a parallel Web site...9 Co-deployment or phased migration with a Radius server...10 Prerequisites Integrating Citrix Web Interface with Entrust IdentityGuard Configuring the RADIUS shared secret...12 Configuring Entrust IdentityGuard second-factor authentication using the Access Management Console...13 Configuring Entrust IdentityGuard second-factor authentication using configuration files...17 Testing the integration Troubleshooting Known Issues All rights reserved. 3

4 Introduction This technical integration guide describes how to integrate Citrix Web Interface and Entrust IdentityGuard 9.1 using RADIUS. The aim of this integration is to add Entrust IdentityGuard second-factor authentication to XenApp Web sites accessed through Citrix Web Interface. This integration works with Entrust IdentityGuard grids, tokens, temporary PINs, one-time passwords, knowledgebased questions and answers, and personal verification numbers. For more information on using Entrust IdentityGuard, see the Entrust IdentityGuard Administration Guide. Integration information Entrust product: Entrust IdentityGuard 9.1 or 9.2 Partner name: Citrix Partner product: Web Interface for Windows Partner product: Web Interface for Java Application Servers Partner product: Web Interface for Windows Partner product: Web Interface for Java Application Servers Check the Platform Support and Integration Center for the latest supported version information at: Partner contact information Web site: Support site: Supported authentication methods The Citrix Web Interface RADIUS integration supports the Entrust IdentityGuard authentication methods and authentication protocols listed in Table 1. All rights reserved. 4

5 Table 1: Authentication methods Authentication method Notes Supported protocols Grid* Two-step authentication. PAP Token* Response-only tokens (one-step and twostep authentication) and challenge-response tokens (two-step authentication). PAP Temporary PIN* For grid and token authentication. PAP One-time password* Two-step authentication. PAP Knowledge-based questions and answers Single question and answer. Two-step authentication. PAP Mutual Serial number replay for grid and token authentication. PAP * Can also include a personal verification number (PVN). A PVN is an additional authentication feature that can be added to grid, token and one-time password authentication. The Entrust IdentityGuard Radius proxy does not support the creation of new PVNs. Administrators must assign users their initial PVNs. Administrators can use the Entrust IdentityGuard Administration interface to force users to change their PVNs. It is possible for users to change their own PVNs. The option Separate Challenge for PVN Update was introduced in Entrust IdentityGuard 9.1. See Using a PVN with your second-factor authentication response for more information. Note: The Entrust IdentityGuard server supports additional authentication methods and features that are not supported in this integration due to limitations of the RADIUS protocol. The unsupported authentication methods and features include: Multiple question and answer pairs for knowledge-based authentication. Risk-based authentication based on machine authentication and IP address geo-location. Mutual authentication using user-selected images. Capabilities Support for two-factor authentication using the industry-standard RADIUS protocol was added to Citrix Web Interface in 5.0. This makes possible an out-of-the-box integration with Entrust IdentityGuard via the Entrust IdentityGuard Radius proxy. This integration applies to users accessing a XenApp Web site that is configured to use Explicit authentication with RADIUS two-factor authentication. All rights reserved. 5

6 Integration overview Entrust IdentityGuard Radius proxy is automatically installed when you install Entrust IdentityGuard. The Radius proxy allows Radius clients such as Citrix Web Interface to communicate with Entrust IdentityGuard for strong second-factor authentication. Integration with Entrust IdentityGuard When you use Entrust IdentityGuard as a Radius server for Citrix Web Interface, you configure Entrust IdentityGuard to handle only second-factor authentication as Citrix Web Interface handles first-factor authentication. The Entrust IdentityGuard Radius proxy intercepts messages between Citrix Web Interface and Entrust IdentityGuard as shown in Figure 1. Figure 1 Overview of Entrust IdentityGuard integrated with Citrix Web Interface There are two authentication options for Citrix Web Interface and Entrust IdentityGuard Radius: Two-step authentication, for all supported authentication types. The second-factor authentication challenge is presented on a second authentication page after the user has entered their first-factor credentials (user name and password). One-step authentication, for response-only tokens. The user enters the token response code on a single authentication page at the same time as they enter their first-factor credentials (user name and password). Two-step authentication with Entrust IdentityGuard The following steps outline the process for two-factor authentication with Entrust IdentityGuard when a challengeresponse authentication method is used. At Entrust IdentityGuard, the configuration setting First-Factor Authentication Method for the VPN Server representing the Citrix Web Interface is set to No First-Factor Authentication. 1. A user enters first-factor credentials (user name and password) into the browser. All rights reserved. 6

7 2. The browser sends the credentials to Citrix Web Interface, which forwards the user name to the Entrust IdentityGuard Radius proxy. 3. The Radius proxy forwards the user name to Entrust IdentityGuard. 4. Entrust IdentityGuard generates a second-factor challenge and sends it to the Radius proxy. The Radius proxy sends the challenge to Citrix Web Interface, which displays it in a two-factor authentication page sent to the browser. 5. The user enters a response to the second-factor challenge into the browser. 6. The browser sends the response to Citrix Web Interface, which forwards it to the Radius proxy. The Radius proxy forwards the response to Entrust IdentityGuard for authentication. 7. Entrust IdentityGuard either accepts or rejects the response and then sends a message to the Radius proxy. The Radius proxy forwards the message to Citrix Web Interface. If the message is a reject message, then the user failed second-factor authentication. If the message is an accept message, then the user passed second-factor authentication and Citrix Web Interface proceeds to validate the first-factor credentials. One-step authentication with Entrust IdentityGuard (response-only tokens) The following steps outline the process for two-factor authentication with Entrust IdentityGuard when a responseonly token is used. At Entrust IdentityGuard, the configuration setting First-Factor Authentication Method for the VPN Server representing the Citrix Web Interface is set to Entrust IdentityGuard Token. 1. A user enters first-factor credentials (user name and password) and second-factor credentials (token response code) into the browser. 2. The browser sends the credentials to Citrix Web Interface, which forwards the user name and token response code to the Entrust IdentityGuard Radius proxy. 3. The Radius proxy forwards the user name and token response code to Entrust IdentityGuard. 4. Entrust IdentityGuard either accepts or rejects the response and then sends a message to the Radius proxy. The Radius proxy forwards the message to Citrix Web Interface. If the message is a reject message, then the user failed second-factor authentication. If the message is an accept message, then the user passed second-factor authentication and Citrix Web Interface proceeds to validate the first-factor credentials. Using a PVN with your second-factor authentication response Refer to the Entrust IdentityGuard Administration Guide for information on using a Personal Verification Number (PVN) during authentication. When using the Radius proxy, PVNs are specified as part of the authentication response. For example, if your PVN is 1234, and the token response is , the combined Radius password is entered as: (PVN first, followed by token response). The PVN and grid or one-time password responses are combined similarly. During authentication, users can choose to change their PVN or they may be forced to change their PVN by an administrator. By default for PVN changes, Entrust IdentityGuard displays one prompt, at which the user must enter the old PVN, the challenge response, the new PVN, and confirmation of the new PVN all on one line, in the following format: old pvn + challenge response + new pvn + new pvn All rights reserved. 7

8 In addition to the default method for PVN changes, a new option called Separate Challenge for PVN Update was introduced in IdentityGuard 9.1. With the Separate Challenge option enabled, Entrust IdentityGuard displays three prompts, allowing the user to enter the information separately, in the following format: old pvn + challenge response new pvn new pvn All rights reserved. 8

9 Migrating users to Entrust IdentityGuard When integrating Citrix Web Interface with Entrust IdentityGuard, your Citrix users must also become Entrust IdentityGuard users to take advantage of Entrust IdentityGuard authentication. You can accomplish this migration in one of several ways: Forced migration on page 4 Phased migration with a parallel Web site on page 9 Co-deployment or phased migration with a Radius server on page 10 Each migration scenario is discussed in more detail in the following sections. Forced migration With forced migration, you have an existing XenApp Web site that provides access to protected resources and you want to use the Entrust IdentityGuard Administration interface to migrate all users to Entrust IdentityGuard at a preannounced switch-over date. Advantages Easy to implement. Effective with a small number of users. Disadvantages Administrators may experience a large number of problems on the switch-over date. No user feedback that a pilot would generate. To perform a forced migration 1. Inform your users that you plan to add second-factor authentication on a specified date. 2. Have an Entrust IdentityGuard administrator use the bulk operations mechanism of Entrust IdentityGuard to load all your users into the Entrust IdentityGuard repository. (See the Entrust IdentityGuard Administration Guide for information about bulk operations.) 3. Provide your users with their credentials for Entrust IdentityGuard authentication. 4. On the switch-over date, integrate Citrix Web Interface and Entrust IdentityGuard. Phased migration with a parallel Web site With phased migration you have an existing XenApp Web site that provides access to protected resources, and you use another XenApp Web site to authenticate users with Entrust IdentityGuard. Advantages Disadvantages Allows for a pilot and user feedback. Any users not yet migrated to the new system do not see any changes. Requires another XenApp Web site. All rights reserved. 9

10 Users can bypass the second-factor login by using the old XenApp Web site. To perform a phased migration with a parallel Web site 1. Integrate Entrust IdentityGuard with a new dedicated XenApp Web site. 2. Have an Entrust IdentityGuard administrator use the bulk operations mechanism of Entrust IdentityGuard to load all your users into the Entrust IdentityGuard repository. (See the Entrust IdentityGuard Administration Guide for information about bulk operations.) 3. Inform your users that they should now use second-factor authentication and provide them with their credentials for Entrust IdentityGuard authentication. 4. Direct your users to the new Web site URL integrated with Entrust IdentityGuard. 5. After all your users have migrated, disable the old Web site not integrated with Entrust IdentityGuard. Co-deployment or phased migration with a Radius server You have an existing XenApp Web site that provides access to protected resources using two-factor authentication to a Radius server such as RSA ACE/Server configured to be presented as a Radius server. You want to migrate users to Entrust IdentityGuard second-factor authentication, and authenticate using either the Radius server or Entrust IdentityGuard during a co-deployment period. To migrate, you use the Entrust IdentityGuard Administration interface to move users to Entrust IdentityGuard in phases. Migrated users are forced to authenticate with Entrust IdentityGuard authentication. Users that have not yet migrated continue to use the existing Radius server. After all users are migrated, you can decommission your Radius server. Advantages Disadvantages Any users not yet migrated to the new system are not inconvenienced. Any users migrated to the new system cannot bypass it and use the old system. Gradually adding users to the new system means administrators experience fewer problems. Starting with a small group of users allows for a pilot that generates user feedback. May require reconfiguration of the existing second-factor authentication server to be presented as a Radius server. More overhead to inform users in a staged manner. To perform a phased migration or co-deployment with a Radius server See the Entrust IdentityGuard 9.1 Co-deployment with RSA ACE/Server or a Radius server for instructions. All rights reserved. 10

11 Prerequisites Complete the following steps before integrating Citrix Web Interface with Entrust IdentityGuard: Install and configure Citrix Web Interface and Citrix XenApp, using the documentation provided by Citrix. Create a XenApp Web site configured for Explicit authentication and verify that users are able to log in and access resources using their user name and password. Install and configure Entrust IdentityGuard and the Entrust IdentityGuard Radius proxy, using the Entrust IdentityGuard Installation Guide. Note: The Entrust IdentityGuard Radius Proxy needs to know which Radius clients will connect to it. In this integration, Citrix Web Interface is acting as a Radius client. Because VPN servers are the most common Radius clients for Entrust IdentityGuard, the Entrust documentation uses the term VPN server to refer to a Radius client. For the purposes of this integration, you should understand VPN server to mean Citrix Web Interface. As part of configuring Entrust IdentityGuard you will add a VPN server to represent Citrix Web Interface. o o Set the First-Factor Authentication Method to No First-Factor Authentication if you are using two-step authentication, or Entrust IdentityGuard Token if you are using one-step response-only token authentication. Take note of the VPN Shared Secret as you will need this information to configure the Citrix Web Interface for RADIUS authentication. All rights reserved. 11

12 Integrating Citrix Web Interface with Entrust IdentityGuard This section describes how to configure the Citrix Web Interface to use the Entrust IdentityGuard server for secondfactor authentication. Refer to the Citrix Web Interface Administrator s Guide for additional information. Topics in this section: Configuring the RADIUS shared secret on page 12 Configuring Entrust IdentityGuard second-factor authentication using the Access Management Console on page 13 Configuring Entrust IdentityGuard second-factor authentication using configuration files on page 17 Configuring the RADIUS shared secret Citrix Web Interface (the Radius client) and IdentityGuard Radius proxy (the Radius server) need to use the same shared secret for secure communications. You configured a shared secret at IdentityGuard using the VPN Shared Secret property when you added the Citrix Web Interface host as a VPN server. You must now configure the matching secret at Citrix Web Interface. Configuring the shared secret on IIS Follow these steps to configure the shared secret if you are running Citrix Web Interface on IIS. To configure the shared secret on IIS 1. Open the web.config file for your XenApp Web site. For example: C:\Inetpub\wwwroot\Citrix\XenApp\web.config 2. Find the line containing the key RADIUS_SECRET_PATH. For example: <add key="radius_secret_path" value="/radius_secret.txt" /> 3. The path is relative to the conf sub-folder of the web site. You have now determined the name and location of the shared secret file. For example: C:\Inetpub\wwwroot\Citrix\XenApp\conf\radius_secret.txt 4. Create a plain text file in this location containing the same secret that you configured at Entrust IdentityGuard. As recommended in the Citrix Web Interface Administrator s Guide, ensure that this file is protected using operating system controls so that it can only be accessed by the appropriate users or processes. Configuring the shared secret on a Java application server Follow these steps to configure the shared secret if you are running Citrix Web Interface on a Java application server (Apache Tomcat, IBM WebSphere, or Sun Java System Application Server). To configure the shared secret on a Java application server 1. Open the web.xml file for your XenApp Web site. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\XenApp\WEB- INF\web.xml All rights reserved. 12

13 2. Find the lines containing the parameter name RADIUS_SECRET_PATH. For example: <context-param> <param-name>radius_secret_path</param-name> <param-value>/radius_secret.txt</param-value> </context-param> 3. The path is relative to the WEB-INF folder of the web site. You have now determined the name and location of the shared secret file. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\XenApp\WEB- INF\radius_secret.txt 4. Create a plain text file in this location containing the same secret that you configured at Entrust IdentityGuard. As recommended in the Citrix Web Interface Administrator s Guide, ensure that this file is protected using operating system controls so that it can only be accessed by the appropriate users or processes. Configuring Entrust IdentityGuard second-factor authentication using the Access Management Console Use this method if you are running Web Interface on IIS. To configure Entrust IdentityGuard second-factor authentication using the Access Management Console 1. Launch Citrix Access Management Console. 2. In the tree view on the left, navigate to the XenApp Web site to which you are adding IdentityGuard secondfactor authentication. For example, All rights reserved. 13

14 3. Right-click the Web site and select Configure authentication methods. 4. Click Properties next to the Explicit method to open the properties dialog. All rights reserved. 14

15 5. In the tree view on the left navigate to Two-Factor Authentication. 6. In the drop-down list for Two-factor setting, select RADIUS. All rights reserved. 15

16 7. Click Add. 8. Enter the host name or IP address of your Entrust IdentityGuard server and the port number (often 1812) of the Entrust IdentityGuard Radius proxy. 9. Click OK three times. You have now configured the XenApp Web site to use Entrust IdentityGuard for second-factor authentication. The changes take effect immediately with no restart required. All rights reserved. 16

17 Configuring Entrust IdentityGuard second-factor authentication using configuration files Use this method if you are running Web Interface on a Java application server. To configure Entrust IdentityGuard second-factor authentication using configuration files 1. Open the WebInterface.conf file for your XenApp Web site. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\XenApp\WEB- INF\WebInterface.conf 2. Locate the line containing AdditionalExplicitAuthentication and set it to RADIUS. Create the line if it is not already there, or uncomment it by removing the leading # if it is there but commented out. It should look like this: AdditionalExplicitAuthentication=RADIUS 3. Locate the line containing RadiusServers and set it to your IdentityGuard server host and Radius port. Create the line if it is not already there, or uncomment it by removing the leading # if it is there but commented out. It should look like this: RadiusServers=identityguardserver.mycorp.com: Save and close the file. 5. Restart the Java application server. You have now configured the XenApp Web site to use Entrust IdentityGuard for second-factor authentication. All rights reserved. 17

18 Testing the integration After configuring Citrix Web Interface and Entrust IdentityGuard, use your browser to test the integration and ensure you configured everything correctly. To test the integration 1. Enter the URL of the XenApp Web site in a browser. The login form appears in the browser. For example: 2. Enter a valid user name, password, and domain. 3. If you are using two-step authentication (First-Factor Authentication Method for the Citrix Web Interface Radius client -- called VPN server in the Entrust IdentityGuard configuration -- is set to No First-Factor Authentication) then enter any value in the PASSCODE field. It is not used but cannot be left blank. See Known Issues below for instructions on how to hide this field. 4. If you are using one-step authentication (First-Factor Authentication Method for the Citrix Web Interface Radius client -- called VPN server in the Entrust IdentityGuard configuration -- is set to Entrust IdentityGuard Token) then enter the token code in the PASSCODE field. See Known Issues below for instructions on how to change the help text attached to this field so that it is meaningful to your users. 5. If you are using two-step authentication, the Entrust IdentityGuard challenge is displayed in the browser. For example: All rights reserved. 18

19 6. If you are using one-step authentication there is no two-factor authentication page. 7. If you enter the correct credentials, the XenApp Web site home page displays in the browser. For example: All rights reserved. 19

20 Troubleshooting If you encounter problems during the integration of Citrix Web Interface with Entrust IdentityGuard, check the log files. For information about Entrust IdentityGuard log files, see the Entrust IdentityGuard Administration Guide. For information about Citrix Web Interface log files, refer to your Citrix product documentation. All rights reserved. 20

21 Known Issues Problem: Entrust IdentityGuard users may get locked out unexpectedly when using one-step authentication. Cause: When Citrix Web Interface retransmits an authentication request due to a timeout, Entrust IdentityGuard Radius proxy treats the duplicate request as an attempt to reuse a one-time token password instead of ignoring the duplicate request. If the maximum number of attempts is exceeded the user is locked out. (147142) Solution: If you are using one-step authentication, increase the default setting for RadiusRequestTimeout in the Citrix WebInterface.conf file from 30 to 50. This greatly reduces the chances of Citrix Web Interface sending enough duplicate requests to lead to erroneous user lockout. Problem: The help text attached to the PASSCODE field on the login page for one-step authentication contains references to RSA SecurID and Secure Computing SafeWord which may confuse users that have Entrust IdentityGuard response-only tokens. Cause: The default help text assumes that RSA SecurID or SecureComputing SafeWord tokens are the only options for two-factor authentication. Solution: Modify the default help text if you are using one-step Entrust IdentityGuard authentication. 1. Open C:\Program Files\Citrix\Web Interface\5.1.1\languages\ help_strings.properties in a text editor. The path to this file may vary on your system. 2. Search for Help_Passcode and enter the desired help text. For example, use the following lines instead of the existing text: <dt>entrust IdentityGuard authentication</dt>\ <dd>enter your token code (the number displayed on your Entrust IdentityGuard token) in the <strong>passcode</strong> box. If your system administrator has given you a PVN, enter your PVN followed by the passcode. For example, if the passcode displayed on your token is '123456' and your PVN is '7777', enter <strong> </strong> in the <strong>passcode</strong> box. To change your PVN, enter your old PVN followed by the passcode followed by the new PVN twice.</dd>\ 3. Save and close the file. The changes take effect immediately with no restart required. Problem: The PASSCODE field on the initial login page is not needed for two-step authentication, however it cannot be left blank and a dummy value must be entered. This may confuse users. Cause: The initial login page assumes that a PASSCODE is required for two-factor authentication. Solution: Modify the initial login page to hide the PASSCODE field if you are using two-step IdentityGuard authentication. 1. Open C:\Inetpub\wwwroot\Citrix\XenApp\app_code\PagesJava\com\citrix\wi\pages\auth\Login.java in a text editor. The path to this file may vary on your system. All rights reserved. 21

22 2. If you are using Novell Directory Services (NDS), open C:\Inetpub\wwwroot\Citrix\XenApp\app_code\PagesCs\pages\auth\LoginASP.cs as well. 3. Locate the following line in Login.java: viewcontrol.setshowpasscode(twofactorauth.gettwofactorauthmethod(wiconfig)!= null); 4. Comment out the line and insert extra lines as shown so that it looks like this: // Entrust IdentityGuard hide passcode field viewcontrol.setshowpasscode(false); //viewcontrol.setshowpasscode(twofactorauth.gettwofactorauthmethod(wiconfig)!= null); 5. Depending on whether you are using Windows or Novell Directory Services (NDS), follow the appropriate procedures below. Windows: a) Locate the following line: parameters.put(twofactorauth.val_passcode, passcode); b) Insert the following lines above it: // Entrust IdentityGuard -- allow empty passcode if (passcode.length() == 0) passcode = "dummy"; c) Save and close Login.java. NDS: a) Save and close Login.java. b) Locate the following line in LoginASP.cs: parameters.put(twofactorauth.val_passcode, passcode); c) Insert the following lines above it: // Entrust IdentityGuard -- allow empty passcode if (passcode.length == 0) passcode = "dummy"; d) Save and close LoginASP.cs. The changes take effect immediately with no restart required. The next time the login page is used there is a onetime delay while the changed file is recompiled. Problem: Users experience an unexpected delay of up to 60 seconds when they enter the wrong value in response to an IdentityGuard challenge when using two-step authentication. The following error message is displayed in the browser: An authentication error has occurred. Contact your system administrator. Cause: Citrix Web Interface sends the response to the Entrust IdentityGuard challenge from a different source port than the original access-request, which is unusual but allowed by the Radius protocol. Entrust IdentityGuard sends the second access-challenge message back to the original port, so Citrix Web Interface never gets it and times out. (148716) All rights reserved. 22

23 Solution: Fixed in Entrust IdentityGuard 9.1 patch Problem: Consider the case where IdentityGuard is co-deployed with RSA ACE/Server or another Radius server (a displaced server), and users are being migrated from the displaced server to IdentityGuard. Users that have not yet been migrated to IdentityGuard will experience an unexpected delay of up to 60 seconds during log in through the displaced server whenever they are required to re-enter a new PIN and passcode for confirmation. The following error message is displayed in the browser: An authentication error has occurred. Contact your system administrator. The PIN confirmation page is not shown, which means if the user mistypes their chosen PIN they will only discover this the next time they try to log in, and they will have to contact their administrator to reset their token. Cause: Citrix Web Interface sends the response to the Entrust IdentityGuard challenge from a different source port than the original access-request, which is unusual but allowed by the Radius protocol. Entrust IdentityGuard sends the next access-challenge message back to the original port, so Citrix Web Interface never gets it and times out after retransmitting the original access-request several times. (148716) Solution: Fixed in Entrust IdentityGuard 9.1 patch All rights reserved. 23