DIGIPASS Authentication for Citrix Web Interface Guide 3.3

Transcription

1 DIGIPASS Authentication for Citrix Web Interface Guide 3

2 Disclaimer of Warranties and Limitations of Liabilities Disclaimer of Warranties and Limitations of Liabilities The Product is provided on an 'as is' basis, without any other warranties, or conditions, express or implied, including but not limited to warranties of merchantable quality, merchantability of fitness for a particular purpose, or those arising by law, statute, usage of trade or course of dealing. The entire risk as to the results and performance of the product is assumed by you. Neither we nor our dealers or suppliers shall have any liability to you or any other person or entity for any indirect, incidental, special or consequential damages whatsoever, including but not limited to loss of revenue or profit, lost or damaged data of other commercial or economic loss, even if we have been advised of the possibility of such damages or they are foreseeable; or for claims by a third party. Our maximum aggregate liability to you, and that of our dealers and suppliers shall not exceed the amount paid by you for the Product. The limitations in this section shall apply whether or not the alleged breach or default is a breach of a fundamental condition or term, or a fundamental breach. Some states/countries do not allow the exclusion or limitation or liability for consequential or incidental damages so the above limitation may not apply to you. Copyright 2011 VASCO Data Security Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of VASCO Data Security Inc. Trademarks VACMAN, Identikey, axs GUARD and Digipass are registered trademarks of VASCO Data Security International Inc. Microsoft and Windows are registered trademarks of Microsoft Corporation. All other trademarks are the property of their respective holders. 2

3 Table of Contents Table of Contents 1 DIGIPASS Authentication for Citrix Web Interface Overview Installation System Requirements Pre-Installation Tasks DIGIPASS Authentication for Citrix Web Interface Configuration Wizard IIS Module Configuration IIS Module Configuration Configuration File Configure Citrix Web Interface 4.5 and 4.6 to work with the Authentication Server Configure Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3 to work with the Authentication Server Configure Citrix Advanced Access Control Server 4.5 to work with the Authentication Server Configure Authentication Server Post-Installation Tasks Set up 1-Step Challenge/Response Login Tasks to set up for One-Step challenge-response for Citrix Set Up Password Change Page Display Login Failure Reason Create 2-Step Challenge/Response Template Copy Challenge Response Files Update Registry Settings for VACMAN Middleware Troubleshooting IIS Module Installation Problems Other Troubleshooting Options Repair Installation Uninstalling the IIS Module IIS Module Overview... 4 Uninstall the IIS Module Technical Support Last Updated : 14/07/11

4 DIGIPASS Authentication for Citrix Web Interface Overview 1 DIGIPASS Authentication for Citrix Web Interface Overview The main component of DIGIPASS Authentication for Citrix Web Interface is the IIS Module. 1 IIS Module Overview The IIS Module is an add-on for VACMAN Middleware, IDENTIKEY Server and axsguard Identifier. It can be configured to intercept authentication requests to a website which uses a login form and redirect them to an Authentication Server. The Authentication Server must be one of the following servers: IDENTIKEY Server 1or higher IDENTIKEY Server component VACMAN Middleware 0 Authentication Server component axsguard Identifier x or higher The IIS Module is an ISAPI extension specifically designed for use with IIS 6, although IIS 7 or IIS 7.5 can be used if the Backwards Compatibility module is installed. Figure 1 DIGIPASS Authentication for Citrix Overview 1 Authentication Methods See the Product Guide for the authentication server for detailed information on login methods and options. 4

5 DIGIPASS Authentication for Citrix Web Interface Overview Response Only login Users log in via the current login page with their username and One Time Password (OTP). 1-Step Challenge/Response login A random challenge - of a length configured for all users - is displayed on the login page. Users log in with their username and DIGPASS response to the displayed challenge. This requires modification of the current login page used by Citrix Web Interface. 2-Step Challenge/Response login After the login page, the IIS Module redirects users to a Challenge page where a random challenge of the length required by the user s DIGPASS is displayed. The user must enter a response to the challenge in order to complete the login. A Challenge page template must be used with this feature. A default template is provided. It can be used without modification or it can be customized to match your preferred look and feel. Virtual DIGIPASS login Users logging in with a Virtual DIGPASS use a similar process to the 2-step Challenge/Response login. If the user has a Primary Virtual DIGPASS assigned, or requests use of the Backup Virtual DIGPASS feature during the first step, an OTP will be sent to the user s mobile phone via text message. The user is then redirected by the IIS Module to the Challenge page to enter the OTP. This uses the same Challenge template used in the 2-step Challenge/Response login. 2 Server Connection Management The IIS Module provides flexibility in managing connections to multiple primary and/or backup Authentication Servers. This allows redundancy and load sharing over multiple Servers. 1 Connection Profiles Two connection profiles are available: Primary The Server(s) to which the IIS Module will first attempt to connect. The Primary Authentication Server(s) take the majority of the data load. Load sharing may be implemented over all Primary Authentication Servers. 5

6 DIGIPASS Authentication for Citrix Web Interface Overview Backup A Backup Server can provide redundancy and failover. It is typically a local machine which, if the Primary Authentication Server is busy or cannot be contacted, will be used until a connection to the Primary Server can be re-established. 2 Connection Options Terminology Some of the terms used in configuring server connections are explained below: Maximum Connections The maximum number of connections that the IIS Module may have open to the Authentication Server at one time. Timeout The time that the IIS Module should wait for a reply from the Authentication Server. Reconnect Interval If the IIS Module cannot connect to an Authentication Server, it will make connection attempts at increasing time intervals until it succeeds in establishing a connection. The time period between connection attempts is the Reconnect Interval. Figure 2 Standard Server Connection Configuration This setup uses one main Authentication Server to handle requests from the Web Server, with a backup Authentication Server for use when the main Server is busy or unavailable. 6

7 DIGIPASS Authentication for Citrix Web Interface Overview 3 IIS Module Terminology The following definitions describe how these terms are used in this document. They are also used in other IIS Package manuals. Authentication Server The term Authentication Server refers to the component to which the IIS Module sends authentication requests. This component is: For IDENTIKEY Server, the IDENTIKEY Server service or daemon For axsguard Identifier, the IDENTIKEY Server daemon For VACMAN Middleware 3, the DIGIPASS Authentication Service Basic Authentication A method of authentication that uses the HTTP Basic Authentication mechanism. This uses a login pop-up box provided by the Browser. Client/Component/Client Component The above terms refer to the same thing. The Client Component is the record defined in the Authentication Server's data store, to represent an installed instance of the IIS Module. Different terms are used due to differences in terminology on the server side. i.e. Client for IDENTIKEY Server and axsguard, Component for VACMAN Middleware They are used for the following main purposes: To indicate that the Authentication Server is permitted to process a request from that client To specify a Policy to be used to process the request To hold a License Key for the IIS Module Forms Authentication The method of authentication where the Web Site provides its own login page. IIS Module General term for a plug-in to IIS to allow DIGIPASS authentication to take place. The IIS Module takes two forms depending on its application: IIS Extension The IIS Extension is an ISAPI extension used for Forms Authentication. It is referred to as the IIS Module in manuals for Forms Authentication, unless the text is referring specifically to the IIS Extension. 7

8 DIGIPASS Authentication for Citrix Web Interface Overview IIS Filter The IIS Filter is an ISAPI filter used for Basic Authentication. The IIS plug-in is referred to as the IIS Module in manuals for Basic Authentication, unless the text is referring specifically to the IIS Filter. 4 Password Change The IIS Module can capture password changes made in Citrix Web Interface. This requires modification of the current Password Change page used by Citrix Web Interface. 5 Tracing The IIS Module makes use of a trace file to record information about events that occur on the system, for use in troubleshooting. This could include generic information, changing conditions, or problems and errors that have been encountered. The level of tracing that the IIS Module employs depends on its configuration settings. Caution Enabling Full Tracing should only be done for troubleshooting purposes. There are no limits set on the size of the tracing file, so if the option is left on too long on a high-load system the file may dramatically slow down or crash Windows, due to excessive I/O or filling up the hard drive. Because there are no size limitations set on the trace file, it is not recommended that you have tracing permanently enabled. If your system is set up with Tracing always enabled, ensure that the file size does not cause problems by deleting or archiving it whenever it gets too large. Basic tracing includes: Critical error/warning messages [CRITC] Major error/warning messages [MAJOR] Minor error/warning messages [MINOR] Configuration messages [CONFG] Full tracing includes: Critical error/warning messages [CRITC] Major error/warning messages [MAJOR] Minor error/warning messages [MINOR] Configuration messages [CONFG] Informational messages [INFOR] Data tracing messages [DATA] 8

9 DIGIPASS Authentication for Citrix Web Interface Overview Debugging messages (useful for support purposes) [DEBUG] Security messages, messages that may contain security sensitive data [SECUR] Note The IIS Module will require permissions for the directory in which the tracing file is kept. See 5.2 Check Permissions for more information. 9

10 Installation 2 Installation Before installing the IIS Module, check that all system requirements and pre-installation tasks have been met. This will help ensure a smooth, trouble-free installation and integration process. 1 System Requirements 1 Server Requirements - Software An authentication server running on another machine. This should be one of the following: IDENTIKEY Server 1 or higher IDENTIKEY Server component VACMAN Middleware 0 - Authentication Server component axsguard Identifier x or higher Internet Information Services (IIS) 6.0 OR Internet Information Services (IIS) 7 or 7.5 with Backward Compatibility module installed. The following operating systems are supported: Windows Server 2003 SP2 or higher Windows Server 2003 R2 standard x64edition SP2 Windows 2008 R2 or higher Citrix Presentation Server or XenApp containing Citrix Web Interface 4.5, 4.6, 5.0.1, 5.2, 5.2 or 5.3 OR Citrix Advanced Access Control Server 4.5 The User must have administration rights on the installation machine. 2 Pre-Installation Tasks Before installing the IIS Module, there are several tasks which need to be completed. Performing these tasks (where applicable) will assist in a quick, smooth installation process. Note DIGIPASS Authentication for Citrix Web Interface cannot be installed on the same machine as any other Digipass Authentication packages. 10

11 Installation 1 Install Authentication Server An Authentication Server must be installed on the network before the IIS Module is installed. See 1 System Requirements for compatible servers and 6 Configure Authentication Server for configuration recommendations. Warning If the users are Active Directory users on a Windows platform, it is recommended that the Use Windows User Name Resolution feature on the Authentication Server is enabled. This uses Windows functions to identify User IDs as Windows User accounts, including the domain to which the account belongs. This feature is not available on Linux platforms or the axs GUARD Identifier. If the Use Windows User Name Resolution feature is disabled, it is essential that users always use the same login name. If they try to log in using a different form of their Windows account name, their login will be rejected, unless a second Digipass User account has been created. 2 IIS Ensure IIS and the Citrix Web Interface are installed and working correctly. The Citrix Web Interface must be installed on the IIS server where the web server is running. 3 Information Needed Before you begin installation of the IIS Module, ensure that you have the following information easily accessible, as you will need to enter this during the installation. IP address and port number of the Authentication Server. To check this, open the Authentication Server Configuration and check the Component location and Port fields. Source IP address on the local machine to use when connecting to the Authentication Server (if multiple IP addresses are configured for this machine, as this affects licensing see below). 4 Licensing The Authentication Server will regard each incoming IP address as a different Client Component. This is the reason for selecting a single IP address in connecting to the Authentication Server if there is more than one IP address for a machine. 11

12 Installation 3 DIGIPASS Authentication for Citrix Web Interface Configuration Wizard 12

13 Installation Note For a definition of the term Authentication Server, please see 3 IIS Module Terminology Enter the IP address for the Authentication Server in the IP Address field. Check the Port field. If the SEAL port on which the primary Authentication Server is listening is not the default provided (20003), enter the correct port number. The Wizard will attempt to connect to the Authentication Server using the IP address and port provided. If the connection fails an error window will appear informing you of the problem. Click OK to take you back to the Authentication Server Connection Details window. To get help identifying the problem, see the 5 Troubleshooting section. The Installation Wizard can register the DIGIPASS filter as a client on the Authentication Server. To make use of this facility, click the Create the Component Record Automatically option. Provide a User ID and Password to allow administrative access to the Authentication Server. 4. If you do not want to create a client on Authentication Server, click on the Do NOT create a Client component for this DIGIPASS filter option. 13

14 Installation 5. Click Next to continue. 6. Select an IP address from the IP Address drop down list, which will contain IP addresses assigned to the current machine. The IIS Module will use the selected IP address exclusively. As VASCO component licensing operates on IP address, this ensures that the IIS Module will only use up one component license slot. 7. Click Next. 14

15 Installation 8. To load a license key: Select a license key file by clicking... Select the license.dat file to load from where you saved it on your machine. Click Open to load the License Key from the file. If you do not already have a license.dat file containing a License Key for the Citrix Web Interface Component at this Location, click on the Request a License from 'vasco.com' button. This will take you to the vasco.com web site, where you can request a license key and save it to a file called license.dat. To load a license key later, simply click on Next. 15

16 IIS Module Configuration 3 IIS Module Configuration Configuration settings can be modified in two ways. The easiest method is via the IIS Module Configuration a graphical interface that allows you to make changes with a few mouse clicks. Advanced users may prefer to edit the configuration file directly. 1 IIS Module Configuration A Graphical User Interface (GUI) called, DIGIPASS Authentication for Citrix Web Interface Configuration, is available for use in configuring the IIS Module. This provides a simple, intuitive way to set up the IIS Module to work with your current system. Alternatively, open Windows Explorer and open <IIS Module install directory>\bin\dpiismodcfg.exe. If this is the first time you have opened the DIGIPASS Authentication for Citrix Web Interface Configuration and the configuration file has not been edited, the values you will see are those entered when the Wizard was last run. 16

17 IIS Module Configuration 1 Enable/Disable the IIS Module This option starts or stops the IIS Module from redirecting authentication requests to the Authentication Server. 2 Click on the Connections tab. Tick or untick the Enable DIGIPASS Authentication checkbox. Click on the Apply button. Authentication Server Details The Server list contains all Authentication Servers which may be utilized by the IIS Module. Authentication Server records can be added, deleted, or their details modified. 17

18 IIS Module Configuration 1 Add a Server Click on the Add button. The Server Details window will be displayed. Enter a name for the Authentication Server in the Display Name field. This name will be used to distinguish the Authentication Server in the Server list, but has no effect on the behaviour of the IIS Module. Enter an IP address and port (typically 20003) for the Authentication Server, in the IP Address and Port fields. 4. To use SSL when connecting to the Authentication Server, tick the Use SSL checkbox. This is only available for IDENTIKEY Server version 1 and above. 5. Select a Server Type (see 2 Server Connection Management). 6. To test the details entered above, click the Test Connection button. A message will appear indicating if it was successful. 7. Enter a timeout period (in seconds) in the Timeout field. 8. Enter the maximum number of concurrent connections to be made from the IIS Module to the Server, in the Max. Connections field. 18

19 IIS Module Configuration 2 9. Enter a minimum and maximum amount of time that the IIS Module should wait before attempting to reconnect to the Authentication Server in the Min. Reconnect Interval and Max. Reconnect Interval fields. 10. Click on the OK button. Modify Server Details Select the Server to be edited. Click on the Edit button. The Edit Server window will be displayed. 3 Make required changes. 4. Click on the OK button. Delete a Server Record Select the Server record to be deleted. Click on the Delete button. 19

20 IIS Module Configuration 4 Modify Connection Settings Connect from IP Address If a server has multiple IP addresses configured, the IIS Module needs to know which to use in connecting to the Authentication Server(s). Select the IP address from which to connect to Authentication Servers from the drop-down list in the Connect from IP Address field. Click on the Apply button. Load Sharing Load sharing allows the IIS Module to connect to multiple Authentication Servers when it has reached the maximum number of concurrent connections for the first primary Authentication Server in the Server list. Tick the Enable Load Sharing checkbox. 20

21 IIS Module Configuration Click on the Apply button. SSL Certificate Archive By default, the IIS Module uses the Windows Certificate Archive. To use a different Certificate Archive: Select Load CA Certificates from a File. Browse to a certificate archive file. Click on Apply. Note 1 The Certificate Authority for any server certificates used by IDENTIKEY Server must be included in this certificate archive. If using the Windows Certificate Store, new certificates must be added to the Local Computer Certificate Store. This may be achieved via the Certificates (Local Computer) MMC snap-in or Active Directory's Group Policies. Use of a Service-specific Certificate Store is not supported. Note 2 Ensure that the CA certificate file has read permission granted to the IIS_WPG group. Browse to the CA certificate, and allow read access to the IIS_WPG group using the method described in 5.1 Trace File Directory 21

22 IIS Module Configuration 3 Turn Tracing On or Off Select a Tracing option. See 5 Tracing for more information. If you have selected Basic Tracing or Full Tracing, enter a path and filename for the tracing file into the File Name field. The file path entered must be the full absolute path. Click on the Apply button. 22

23 IIS Module Configuration Note If the File Name field is left blank or the file path does not exist, the IIS Module will not output tracing. If the file does exist, tracing will be appended to the file. If the path is valid but the file does not exist, it will be created. If the IIS_WPG group does not have Write permissions for the directory specified, tracing will not be successful. See 5.1 Trace File Directory for more information. 23

24 IIS Module Configuration 4 Component Type The Component Type is used when connecting to an Authentication Server, to assist in finding the correct Component record. 5 Sites Each web site to be protected by the IIS Module is displayed in the Sites list. One Site record will be entered into the configuration during installation and named Citrix Web Interface 4.x, depending on the version of Citrix Web Interface installed on the machine. Site records may be modified at any time. 24

25 IIS Module Configuration 5.1 Modify Login Page Details Click on the Authentication tab. Select the Site and click on the Edit button. The Edit Site window will be displayed. 25

26 IIS Module Configuration Click on the Login tab. 4. Modify the Base URL if required. 5. For information on modifying query string parameters for the login page, see the Add, Modify and Delete a Query String Parameter topics below. 6. Click on the Form Fields tab. 7. Ensure that the correct names for the fields on the login page corresponding to User Name, Password and Domain are entered into the relevant fields. 8. Click on the Failed Login tab. Modify the Base URL if required. 26

27 IIS Module Configuration 9. Tick the Return Failure Reason checkbox if you wish to enable the IIS 6 Module to add information about a login failure to the login page (see 4.4 Display Login Failure Reason). 10. For information on modifying query string parameters for the login page, see the Add, Modify and Delete a Query String Parameter topics below. 1 If you need to set up 2-step Challenge/Response login or Virtual Digipass login: a. 5.2 Click on the Two Step C/R tab 1 Enter the location of the Challenge/Response template. 1 Click on OK. Modify Change Password Page Details Click on the Authentication tab. Select the Site and click on the Edit button. The Edit Site window will be displayed. 27

28 IIS Module Configuration 5.3 Click on the Change Password tab. 4. Tick the Enabled checkbox to allow the IIS Module to capture password changes. 5. Modify the Base URL if required. 6. For information on modifying query string parameters for the change password page,see the Add, Modify and Delete a Query String Parameter topics below. 7. Ensure that the correct names for the fields on the login page corresponding to User Name, Password, New Password and Confirm Password are entered into the relevant fields. 8. Click on OK. Modify 1-Step Challenge/Response Login Page Details Click on the Authentication tab. Select the Site and click on the Edit button. 28

29 IIS Module Configuration The Edit Site window will be displayed. 5.4 Click on the One Step C/R tab. 4. Tick the Enabled checkbox to allow 1-step Challenge/Response logins. 5. Modify the Base URL if required. 6. For information on modifying query string parameters for the change password page,see the Add, Modify and Delete a Query String Parameter topics below. 7. Click on OK. Add a Query String Parameter The Query String Parameters list contains URL parameters required by Citrix when a login is submitted. The IIS 6 Module will only identify a request as a login if these variables are present in the query string. 29

30 IIS Module Configuration Click on the button. The Add Login Query String Parameter window will be displayed. 5.5 Enter the new parameter, exactly as it will appear in the query string eg. page=login Click on OK. 4. Repeat the process for other query string parameters Modify a Query String Parameter Select a Query String Parameter from the list. Click on the button. The Edit Login Query String Parameter window will be displayed. Make the required changes. 4. Click on OK. 30

31 IIS Module Configuration 5.6 Delete a Query String Parameter Select a query string parameter from the list. Click on the button. A confirmation window will be displayed. 5.7 Click on Yes to delete the query string parameter. Add a Session Variable for the Failed Login Page The Session Variables list contains query string parameters from the login submit request which should be included in the failed login URL, such as session identifiers. Click on the button. The Add Failed Login Session Variable window will be displayed. Enter the name of the query string parameter. Click on OK. Repeat the process for other query string parameters to be included in the failed login URL. 5.8 Edit a Session Variable Select a session variable from the list. Click on the button. The Edit Failed Login Session Variable window will be displayed. 31

32 IIS Module Configuration 5.9 Modify the name of the session variable.. 4. Click on OK. Remove a Session Variable Select a query string parameter from the session variable list. Click on the button. A confirmation window will be displayed Click on Yes to remove the session variable from the list. Delete Site Record Click on the Authentication tab. Select the site name from the Sites list. Click on the Delete button. A confirmation window will be displayed. 4. Click on OK to delete the site record. 32

33 IIS Module Configuration 2 Configuration File The IIS Module Configuration writes to an.xml file named dpmodulecfg.xml in the installation directory. It is possible to edit this file directly instead of using the IIS Module Configuration. Increment the Revision number by 1 to have your changes take effect. Note This option is recommended only for advanced users. The IIS Module Configuration GUI will prevent most common configuration mistakes, but there are no such checks made when edits are made directly to the configuration file. Incorrect changes to the configuration file may cause the IIS Module to stop working. Example configuration file - <VASCO> <Revision type="unsigned" data="2" /> <Enabled type="bool" data="true" /> <Default-Component-Type type="string" data="citrix Web Interface" /> - <Tracing> <Trace-Header type="unsigned" data="15" /> <Trace-Mask type="unsigned" data="0x " /> <Trace-File type="string" data="c:\program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface\log\dpiis.trace" /> </Tracing> - <Sites> - <Site0> <Name type="string" data="" /> - <Login> - <Match-URL> <URL type="string" data="" /> </Match-URL> - <Failed-URL> <URL type="string" data="" /> </Failed-URL> <User-Field type="string" data="user" /> <Password-Field type="string" data="password" /> <Domain-Field type="string" data="domain" /> <Challenge-Template type="string" data="c:\program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface\citrix\challenge_template.html" /> <Error-Message type="bool" data="false" /> <Submit-Encoding type="string" data="iso " /> </Login> - <ChgPasswd> <Enabled type="bool" data="false" /> <Match-URL> <URL type="string" data="" /> </Match-URL> 33

34 IIS Module Configuration <User-Field type="string" data="dp_user" /> <Domain-Field type="string" data="dp_domain" /> <Password-Field type="string" data="password" /> <NewPassword-Field type="string" data="passwordnew" /> <PasswordConf-Field type="string" data="passwordconfirm" /> <Submit-Encoding type="string" data="iso " /> </ChgPasswd> - <One-Step-CR> <Enabled type="bool" data="false" /> - <Match-URL> <URL type="string" data="" /> </Match-URL> </One-Step-CR> <Component-Type type="string" data="citrix Web Interface" /> </Site0> </Sites> - <AAL3> - <SEAL> <Local-Address type="string" data=" " /> - <Connection-List> - <Connection00> <Display-Name type="string" data="main_server" /> <Address type="string" data=" " /> <Port type="unsigned" data="20003" /> <Server-Type type="string" data="primary" /> <Nr-Connections type="unsigned" data="10" /> - <SSL> <Enabled type="bool" data="false" /> <CA-File type="string" data="" /> <Verify-Certificate type="bool" data="true" /> </SSL> </Connection00> </Connection-List>. </SEAL> </AAL3> </VASCO> Caution The configuration file is UTF8 encoded. Non-UTF8 encoded characters should not be added to the configuration file, or it will not load. 34

35 IIS Module Configuration 2 Configuration Settings The table below lists the options, their default values, and a brief explanation of each. Table 1 Configuration Options Option Name Default Value Notes Revision 1 The current revision of the configuration. This is incremented each time the configuration is changed and allows the IIS Module to automatically reload its configuration parameters. If you have manually changed configuration settings in the file, increment this setting by 1 so that your changes take effect. Enabled true Whether the IIS Module is enabled or disabled. If disabled, does not block access, but does not intercept authentication requests they pass through unmodified. Default-Component-Type Citrix Web Interface Default Component type to specify when connecting to an Authentication Server. Trace/Trace-Header 15 The tracing header fields that have been enabled. This is a bitmask constructed by adding the following values: Enable the Date field Enable the Time field Enable the Tracing level field Enable the Thread ID field Enable the File field Enable the Line field eg. for DATE,TIME,LEVEL = = 7 A value of 0 will result in no header being added to the trace output. Trace/Trace-Mask 0x Hexadecimal or decimal values: Hex 0x x E Decimal xFFFFFFFF No tracing Configuration and error messages only All levels enabled. Trace/Trace-File <installation directory>\ Log\\dpiis.trace The absolute path and filename of the file to which internal state tracing will be written. The file but not the path will be created by the filter / extension if it does not exist. If this option is blank, the IIS Module will not output tracing. Sites/Site<number>/ <blank> Text to display in the Sites list on the Configuration GUI. 35

36 IIS Module Configuration Option Name Default Value Notes Name Sites/Site<number>/ Component-Type Outlook Web Access Default Component type to specify when connecting to an Authentication Server for this site. If this parameter is not specified the default will be the component type above. Sites/Site<number>/ Login/ Match-URL/URL /owa/auth/owaauth.dll The base URL to use in submitting a login. Sites/Site<number>/ Login/Match-URL/ Param<number> <blank> Query string parameter needed in the URL. Sites/Site<number>/ Login/Failed-URL/URL /owa/auth/logon.aspx?replacecu The base URL to use after a failed login attempt. rrent=1&reason=2 Sites/Site<number>/ Login/User-Field username Name of the field that corresponds to User. Sites/Site<number>/ Login/Password-Field password Name of the field that corresponds to Password. Sites/Site<number>/ Login/Domain-Field <blank> Name of the field that corresponds to Domain. Sites/Site<number>/ Challenge\challenge_template.ht Location and file name of the template to use in creating a Login/Challenge-Template ml Challenge/Response page. Sites/Site<number>/ Login/Submit-Encoding UTF-8 The character encoding to use in submitting a login request to Exchange. This allows the use of international character sets (see ) Sites/ Site<number>/ One-Step-CR/ MatchURL/URL /owa/auth/logon.aspx The base URL to use in making a one-step challenge/response login request. Sites/ Site<number>/ <blank> One-Step-CR/ Match-URL/ Param<number> Query string parameter needed in the URL. Sites/ Site<number>/ One-Step-CR/ Enabled 0 Whether one-step challenge/response logins are enabled. AAL3/SEAL/ ConnectionList/ Connection <number>/ Address IP Address of the Authentication Server. AAL3/SEAL/Local Address Local IP address. AAL3/SEAL/ ConnectionList/ Connection<number>/ Port Port to use in connecting to the Authentication Server AAL3/SEAL/ConnectionFalse List/Connection<number> Enable or disable the use of SSL when connecting to this Authentication Server. 36

37 IIS Module Configuration Option Name Default Value Notes /SSL/Enabled AAL3/SEAL/Connection<blank> List/Connection<number> /SSL/CA-File By default, the IIS Module will use the Windows Certificate Store. If a file location and name is provided in this field, the IIS Module will use this certificate store instead. AAL3/SEAL/ConnectionTrue List/Connection<number> /SSL/Verify-Certificate If this option is set to True, the IIS Module will validate the Authentication Server's certificate against its certificate store. AAL3/SEAL/ ConnectionList/ Connection<number>/ Server-Type Primary Either Primary or Backup Authentication Server. This setting affects load-balancing. AAL3/SEAL/ ConnectionList/ Connection <number>/ Nr-Connections 10 The maximum number of concurrent connections which the IIS Module may hold open to the Authentication Server. AAL3/SEAL/ ConnectionList/ Connection <number>/minreconnect-interval 30 The minimum amount of time that the IIS Module will leave between attempts to reconnect to a higher-priority server after losing connection to it. AAL3/SEAL/ ConnectionList/ Connection <number>/maxreconnect-interval 300 The maximum amount of time that the IIS Module will leave between attempts to reconnect to a higher-priority server after losing connection to it. 37

38 IIS Module Configuration 3 Modify Character Set Used If you are using non-western European characters, the IIS Module may need to be configured to use a specific character set when submitting login requests to the the web site. The character set to be used can be modified in the IIS Module configuration file (dpmodulecfg.xml) in the <installation directory>\bin directory. Edit the Encoding setting to the desired character set code these are listed in the table below. Caution The IIS Module can only be configured to use a single character set it is not able to handle multiple character sets simultaneously. Table 2 - Character Set Codes Language ISO code Windows code Arabic ISO CP1256 Baltic ISO or ISO CP1257 Central European ISO CP1257 Chinese Simplified ISO-2022-CN GB2312 Chinese Traditional Big5 Cyrillic ISO CP1251 Greek ISO CP1253 Hebrew ISO I CP1255 Japanese ISO-2022-JP Korean ISO-2022-KR Thai ISO Turkish ISO Vietnamese Western European 3 Other code(s) CP874 CP1258 ISO CP1252 Configure Citrix Web Interface 4.5 and 4.6 to work with the Authentication Server Open the Access Management Console for Presentation Server. 38

39 IIS Module Configuration Expand the Citrix Resources node. Expand the Configuration Tools and Web Interface nodes. 4. Select the location of the Citrix Web Interface installation to modify. 5. Click on Configure authentication methods. The Configure Authentication Methods window will be displayed. 6. Tick the Explicit checkbox and click on the Properties button. 39

40 IIS Module Configuration 4 7. In the Properties window, click on the Explicit->Authentication Type entry in the tree on the left. 8. Select the Windows or NIS (UNIX) option button and the desired credential format. 9. Click on the Two-factor Authentication entry in the tree. 10. Select Disable from the Two-factor setting drop down list. 1 Complete the sections of the Properties dialog as needed. 1 Click on OK to close the Properties window, then OK again to close the Configure Authentication Methods window. Configure Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3 to work with the Authentication Server Open the Citrix Web Interface Management console. 40

41 IIS Module Configuration Click on Xenapp Web Sites Click on the required web site. 4. Click on Authentication methods. The Configure Authentication Methods window will be displayed. 5. Tick the Explicit checkbox and click on the Properties button. 41

42 IIS Module Configuration 5 6. In the Properties window, click on the Explicit->Authentication Type entry in the tree on the left. 7. Select the Windows or NIS (UNIX) option button and the desired credential format. 8. Click on the Two-factor Authentication entry in the tree. 9. Select Disable from the Two-factor setting drop down list. 10. Complete the sections of the Properties dialog as needed. 1 Click on OK to close the Properties window, then OK again to close the Configure Authentication Methods window. Configure Citrix Advanced Access Control Server 4.5 to work with the Authentication Server No further configuration is required when using Citrix Advanced Access Control Server

43 IIS Module Configuration 6 Configure Authentication Server 6.1 Component Record A Client Component record must be configured in the Authentication Server for the IIS Module. The Configuration Wizard can create the required record if a connection to the Authentication Server, and an administrator account with sufficient privileges, is available. If the Configuration Wizard does not create a Client Component record, this must be done manually. The Component Type should be set to Citrix Web Interface. The Location should be set to the same IP address as in the Connect from IP Address setting in IIS Module Configuration. Select a Policy for the Authentication Server to use when processing authentication requests from the IIS Module. See 6.3 Policy for more information. A valid license key must be obtained for the IIS Module and loaded in to the Component record. 6.2 Configure for Windows User Accounts 6.1 Windows User Name Resolution If the Authentication Server is installed on a Windows platform and is using an ODBC database (including the embedded database) as its data store, it is recommended that you enable Windows User Name Resolution. This allows the Authentication Server to use Windows functionality to resolve a User ID as entered during a login into a User ID and Domain. It is highly recommended if Dynamic User Registration will be enabled. This setting is not required where the Authentication Server is using Active Directory as its data store - name resolution will occur automatically. This setting is not available on IDENTIKEY Server on Linux, or axsguard Identifier. If the Use Windows User Name Resolution feature is disabled or unavailable, it is essential that users always use the same login name. If they try to log in using a different form of their Windows account name, their login will be rejected, unless a second DIGPASS User account has been created. This is essential for enabling the change password facility to work. 6.2 Case Sensitivity Windows User names are not case-sensitive. If the ODBC database used by the Authentication Server is casesensitive, ensure that User ID case is converted to lower case. Upper case may also be used, but will involve extra 43

44 IIS Module Configuration configuration steps. The embedded PostgreSQL database is set to convert to lower case by default. See the Encoding and Case Sensitivity topic in the Administrator Reference for more information. 6.3 Default Domain Where Users log in without entering a domain name or UPN, the Authentication Server will need to be configured to use the correct domain. There are two basic scenarios that might apply: Change Master Domain If Users will only ever be logging in to one domain via the Authentication Server, the simplest solution is to set the Master Domain name to the Fully Qualified Domain Name of the required domain. This option is not available for axsguard Identifier. Set Default Domain in Policy This strategy should be used if: You wish to keep the Master Domain strictly for administration accounts and separate from User accounts The Authentication Server may be required to handle a different default domain for different IIS 6 Modules or other clients Each Policy may be configured with a Default Domain, to be used if a User does not enter a domain on login. Typically, you will need to modify the Policy used by each IIS Module. 44

45 IIS Module Configuration 6.3 Policy The Component record created during installation of the IIS Module uses the default Password Replacement Policy for the package. It will be named: VM3 Windows Password Replacement (VACMAN Middleware) Identikey Windows Password Replacement (IDENTIKEY Server) Identikey Microsoft AD Password Replacement (axsguard Identifier) These Policies are configured with the following settings: Note These settings are all available on Windows but the VM3 Windows Password Replacement policy is not available on IDENTIKEY Server on Linux or the axsguard Identifier, so the corresponding settings are not available on those platforms Back-End Authentication is set to If Needed (used for DUR, Password Autolearn etc, not all logins). Windows is used as the back-end authenticator in the VM3 Windows Password Replacement and Identikey Windows Password Replacement Policies. Dynamic User Registration, Password Autolearn and Stored Password Proxy are enabled. Group Check Mode is set to Pass Back and DIGPASS Users is placed in the Group List. This will mean that any logins by Users not in the DIGPASS Users group will be ignored not rejected by the Authentication Server in the VM3 Windows Password Replacement and Identikey Windows Password Replacement Policies. If you will need different settings, either select a different Policy (eg. Self-Assignment or Auto-Assignment) for the IIS Module Component or copy the Password Replacement Policy to a new record, modify the new Policy as required, and use the new Policy for the IIS Module Component. 6.1 Standard Policy Configurations for Citrix Web Interface DIGPASS Users login with OTP only (Windows user accounts) The following settings are recommended for this scenario: Back-End Authentication Back-End Authentication: If Needed Back-End Protocol: Windows (IDENTIKEY Server and VACMAN Middleware) or Microsoft AD (axs GUARD Identifier) These settings allow the Authentication Server to check user login details with Windows or Active Directory in case of DUR, Password Autolearn and Self-Assignment logins through the IIS Module. 45

46 IIS Module Configuration DIGPASS User Account Handling Dynamic User Registration: Enabled Password Autolearn: Enabled Stored Password Proxy: Enabled These settings allow the Authentication Server to create an account for an unrecognized User based on a successful Windows or Active Directory authentication. The Authentication Server can then store the User s Active Directory password and replay it to the IIS Module in place of the One Time Password entered by the User on future logins. DIGPASS Assignment Mode Either Self-Assignment or Auto-Assignment would typically be used in this scenario, although manual assignment may also be used. Local Authentication The typical setting for local authentication would be DIGPASS/Password, meaning that Users usually need to use an OTP when logging in, but are not required to in some circumstances (eg. in Grace Period). DIGPASS Users login with Password and OTP (Windows user accounts) The following settings are recommended for this scenario: Back-End Authentication Back-End Authentication: If Needed Back-End Protocol: Windows (IDENTIKEY Server and VACMAN Middleware) or Microsoft AD (axsguard Identifier) These settings allow the Authentication Server to check user login details with Windows or Active Directory in case of DUR and Self-Assignment logins through the IIS Module. DIGPASS User Account Handling Dynamic User Registration: Enabled Password Autolearn: Disabled Stored Password Proxy: Disabled These settings allow the Authentication Server to create an account for an unrecognized User based on a successful Windows or Active Directory authentication. The Authentication Server will not store or replay a User s Windows or Active Directory password. 46

47 IIS Module Configuration DIGPASS Assignment Mode Either Self-Assignment or Auto-Assignment would typically be used in this scenario, although manual assignment may also be used. Local Authentication The typical setting for local authentication would be DIGPASS/Password, meaning that Users usually need to use an OTP when logging in, but are not required to in some circumstances (eg. in Grace Period). Non-Windows User accounts The following settings are recommended for this scenario: Back-End Authentication Back-End Authentication: None The Authentication Server will not use back-end authentication. DIGPASS User Account Handling Dynamic User Registration: Disabled Password Autolearn: Disabled Stored Password Proxy: Disabled As these settings are used with Windows back-end authentication, they will not be used. DIGPASS Assignment Mode As Self-Assignment and Auto-Assignment are both reliant on back-end authentication,only manual assignment will be available. Local Authentication The typical setting for local authentication would be DIGPASS, meaning that Users are required to use an OTP when logging in Step Challenge/Response If you use 1-Step Challenge/Response, you will need these Policy settings: 1-Step Challenge/Response Permitted: Yes Server Challenge Challenge Length as required Add Check Digit as required 47

48 IIS Module Configuration Challenge Check Mode: 0 For more information, see the Policies section of the IDENTIKEY Server Product Guide. 48

49 Post-Installation Tasks 4 Post-Installation Tasks 4.1 Set up 1-Step Challenge/Response Login Implementing one-step Challenge/Response login requires the login page used by Citrix Web Interface to be modified. The standard login page has been modified and the correct page for the Citrix Web Interface version has been placed in the <install directory>\citrix\<citrix version> directory. To use a login page which has been customized for your company eg. colours and graphics used follow the instructions in Modify Custom Login Page. Some file names and locations, and code used in the login page, will vary depending on the version of Citrix Web Interface in use. Follow the instructions for your current version of Citrix Web Interface. 4.2 Tasks to set up for One-Step challenge-response for Citrix The instructions for modifying the Citrix login page vary slightly between the versions of Citrix that are supported. The differences are in the location of the Citrix directory, and the name of the login page. Web root is typically c:\inetpub\wwwroot. Table 3 - Location of <citrix> directory for supported Citrix versions. Citrix Version 4.1 <citrix> Citrix Web Interface 4.5, 4.6 <web root>\citrix\accessplatform Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3 <web root>\citrix\xenapp Citrix Advanced Access Control v4.5 <web root>\citrixloginpoint\<site> Set up for Citrix Web Interface 4.5 and 4.6 Table 4 - Citrix directory and login page variations Citrix Web Interface 4.5 and 4.6 Citrix directory Login page <citrix>\citrix\accessplatform loginmainform.inc Login page Backup <citrix directory>\app_data\auth\include\loginmainform.inc to a suitable place. 49

50 Post-Installation Tasks 4.2 Copy modified login page from: a. CWI <digipass>\citrix\cwi_4.5\loginmainform.inc to <citrix directory>\app_data\auth\include\loginmainform.inc. b. CWI <digipass>\citrix\cwi_4.6\loginmainform.inc to <citrix directory>\app_data\auth\include\loginmainform.inc. Enable one-step Challenge/Response in the Configuration GUI. Modify the base URL and/or query string parameters as required. See the 5.3 Modify 1-Step Challenge/Response Login Page Details topic in the for more information. Set up for Citrix Web Interface 5.0.1, 5.2, and 5.2, 5.3 Table 4 - Citrix directory and login page variations Citrix Web Interface 5.0.1, 5.2, and Citrix directory Login page <citrix>\xenapp loginmainform.inc Login page Backup <citrix directory>\app_data\auth\include\loginmainform.inc to a suitable place. Copy modified login page from a. CWI <digipass>\citrix\cwi_5.0.1\loginmainform.inc to <citrix directory>\app_data\include\loginmainform.inc. b. CWI <digipass>\citrix\cwi_5.2\loginmainform.inc to <citrix directory>\app_data\include\loginmainform.inc. c. CWI <digipass>\citrix\cwi_5.2\loginmainform.inc to <citrix directory>\app_data\include\loginmainform.inc. d. CWI <digipass>\citrix\cwi_5.3\loginmainform.inc to <citrix directory>\app_data\include\loginmainform.inc. Enable one-step Challenge/Response in the Configuration GUI. Modify the base URL and/or query string parameters as required. See the 5.3 Modify 1-Step Challenge/Response Login Page Details topic in the for more information. 50

51 Post-Installation Tasks 4.3 Set up for Citrix Advanced Access Control v4.5 Table 4 - Citrix directory and login page variations Citrix Advanced Access Control v4.5 Citrix directory Login page <citrix>\citrixloginpoint\<site> BasePage.aspx Login page 4.3 Backup <citrix>\basepage.aspx to a suitable place. Copy modified login page from <digipass>\citrix\caac_4.5\basepage.aspx to <citrix>\basepage.aspx Enable one-step Challenge/Response in the Configuration GUI. Modify the base URL and/or query string parameters as required. See the 5.3 Modify 1-Step Challenge/Response Login Page Details topic for more information. Set Up Password Change Page The IIS Module can capture password changes within Citrix Web Interface. For version 4.x, note that only expired password changes can be captured. To enable this, the Password Change page used by Citrix Web Interface must be modified. A modified version of the standard password change page is provided with the IIS Module, and is installed to <install directory>\citrix\cwi_<citrix version>\changepassword.inc. For Citrix Web Interface 4.x an additional file login.aspxf (4.5 and 4.6) - must be modified. Some file names and locations, and code used in the change password page, will vary depending on the version of Citrix Web Interface in use. Follow the instructions for your current version of Citrix Web Interface. 4.1 Replace Default Files - Citrix Web Interface 4.5 The <citrix directory> is located in <web root>\citrix\metaframe\app_data\auth, where Web root is typically c:\inetpub\wwwroot. The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface Backup <citrix directory>\include\changepassword.inc to a suitable place and <citrix directory>\ serverscripts\login.aspxf to a suitable place. 51

52 Post-Installation Tasks 4.2 Copy changepassword.inc from <install directory>\citirix\cwi_<citrix version> to <citrix directory>\include. Copy login.aspxf from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\serverscripts. 4. Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the 5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. Replace Default Files - Citrix Web Interface 4.6 The <citrix directory> is located in <web root>\citrix\accessplatform\app_data\auth. Web root is typically located in c:\inetpub\wwwroot. 4.3 Backup <citrix directory>\include\changepassword.inc and <citrix directory>\ serverscripts\login.aspxf to a suitable place. Copy changepassword.inc from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\include. Copy login.aspxf from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\serverscripts. 4. Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. Replace Default Files - Citrix Web Interface The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface The <citrix directory> is located in <web root>\citrix\xenapp, where web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\include\changepassword.inc and <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java to a suitable place. Copy <install directory>\citrix\cwi_5.0.1\changepassword.inc to <citrix directory>\app_data\include\changepassword.inc Copy <install directory>\citrix\cwi_5.0.1\sessionutils.java to <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. 52

53 Post-Installation Tasks 4.4 Replace Default Files - Citrix Web Interface 5.2 The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface The <citrix directory> is located in <web root>\citrix\xenapp, where web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\include\changepassword.inc and <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java to a suitable place. Copy <install directory>\citrix\cwi_5.2\changepassword.inc to <citrix directory>\app_data\include\changepassword.inc Copy <install directory>\citrix\cwi_5.2\sessionutils.java to <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. 4.5 Replace Default Files - Citrix Web Interface 5.2 The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface The <citrix directory> is located in <web root>\citrix\xenapp, where web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\include\changepassword.inc and <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java to a suitable place. Copy <install directory>\citrix\cwi_5.2\changepassword.inc to <citrix directory>\app_data\include\changepassword.inc Copy <install directory>\citrix\cwi_5.2\sessionutils.java to <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. 4.6 Replace Default Files - Citrix Web Interface 5.3 The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface The <citrix directory> is located in <web root>\citrix\xenapp, where web root is typically located in c:\inetpub\wwwroot. 53

54 Post-Installation Tasks Backup <citrix directory>\app_data\include\changepassword.inc and <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java to a suitable place. Copy <install directory>\citrix\cwi_5.3\changepassword.inc to <citrix directory>\app_data\include\changepassword.inc Copy <install directory>\citrix\cwi_5.3\sessionutils.java to <citrix directory>\app_code\pagesjava\com\citrix\wi\pageutils\sessionutils.java Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. 4.7 Citrix Advanced Access Control 4.5 The <install directory> directory is typically the install directory of the DIGIPASS Authentication for Citrix Web Interface, e.g. C:\Program Files\VASCO\DIGIPASS Authentication for Citrix Web Interface The <citrix directory> is located in <web root>\citrixloginpoint\<site>, where web root is typically located in c:\inetpub\wwwroot. Backup backup <citrix directory>\changepassword.ascx to a suitable place. Copy <install directory>\citrix\caac_4.5\changepassword.ascx to <citrix directory> Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if required. See the5.2 Modify Change Password Page Details topic in the IIS Module Configuration GUI section for more information. 4.8 Modify Custom Change Password Page If you have a current Change Password page in use which differs from the standard Citrix page, you may need to modify it rather than replacing it with the Change Password page provided with the IIS Module. A piece of code must be inserted into the page to include a hidden field used by the IIS Module. The code required can be found below or taken directly from the Change Password page added to the <install directory>\citrix\cwi_<citrix version> directory during installation. Citrix Web Interface 4.x <!-- Digipass Authentication for Citrix Web Interface modifications : START --> <!-- The following hidden field is required to learn password changes. --> <input type='hidden' name='dp_user' value='<%=session["dp_user"]%>'> <!-- Digipass Authentication for Citrix Web Interface modifications : END --> 54

55 Post-Installation Tasks 4.9 Modify Server Include File For Citrix Web Interface 4.x only, login.aspxf (4.5 and 4.6) file for a site may have been modified from the default Citrix file by other programs. If so, it is recommended that you modify it with the required extra code rather than replacing it with the file included with the IIS Module. The code should be inserted in the loginauthenticateexplicit function, underneath the following text: if (credentials!= null &&!biserror()) { System.Collections.Hashtable parameters = new System.Collections.Hashtable(); parameters["accesstoken"] = credentials; parameters["explicitauth"] = expauth; Code // Digipass Authentication for Citrix Web Interface modifications : START // The following session variable is required to learn password changes. Session["dp_user"] = (string)credentials.getuseridentity(); // Digipass Authentication for Citrix Web Interface modifications : END 4.4 Display Login Failure Reason The IIS Module may be configured to pass information to Citrix when it fails an authentication request. This information may be used to provide Users with an explanation of why their login failed, and steps that they may be able to take to rectify the problem. The IIS Module will pass the error or status code and message text for the Authentication Server to Citrix, which depending on settings in the messagecenter.inc and login.js files - may then display the message verbatim or interpret the code to provide the User with a clear explanation or set of instructions. Note Citrix Advanced Access Control 4.5 cannot be formatted in this manner. To handle login failures you must configure the Ctrix disallowed page for authentication failure Replace Default Files A simple option is to replace the default Citrix Web Interface files with those provided with the Digipass Pack. This will allow Citrix Web Interface to display an Authentication Server error or status code and message on the User s screen underneath the Citrix-generated login failure information. Citrix Web Interface 4.5 The <citrix directory> is located in <web root>\citrix\metaframe. 55

56 Post-Installation Tasks Web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\auth\include\messagecenter.inc and <citrix directory>\auth\clientscripts\login.js to a suitable place. Copy messagecenter.inc from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\app_data\auth\include. Copy login.js from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\auth\clientscripts. 4. Enable Return Failure Reason (see 5.1 Modify Login Page Details). Citrix Web Interface 4.6 The <citrix directory> is located in <web root>\citrix\accessplatform. Web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\auth\include\messagecenter.inc and <citrix directory>\auth\clientscripts\login.js to a suitable place. Copy messagecenter.inc from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\app_data\auth\include. Copy login.js from <install directory>\citrix\cwi_<citrix version> to <citrix directory>\auth\clientscripts. 4. Enable Return Failure Reason (see 5.1 Modify Login Page Details). Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3 The <citrix directory> is located in <web root>\citrix\xenapp Web root is typically located in c:\inetpub\wwwroot. Backup <citrix directory>\app_data\include\feedback.inc to a suitable place. Copy: For CWI <install directory>\citrix\cwi_5.0.1\feedback.inc to <citrix directory>\app_data\include\feedback.inc For CWI 5.2 <install directory>\citrix\cwi_5.2\feedback.inc to<citrix directory>\app_data\include\feedback.inc For CWI 5.2 <install directory>\citrix\cwi_5.2\feedback.inc to <citrix>\app_data\include\feedback.inc For CWI 5.3 <install directory>\citrix\cwi_5.3\feedback.inc to <citrix>\app_data\include\feedback.inc Enable Return Failure Reason (see 5.1 Modify Login Page Details). Modify Existing Files The basic modification provided by VASCO consists of: A javascript function inserted into the login.js file which retrieves the code or message text for an error or status message returned by the Authentication Server. 56

57 Post-Installation Tasks Javascript code inserted into the messagecenter.inc file which calls the javascript function to get information about the current error or status message. These may be customised as required to provide interpretation of messages which Users may find confusing, extra information and/or troubleshooting tips. Messagecenter.inc Code <% // Digipass Pack for Citrix Web Interface modifications : START %> <br> <script type="text/javascript"> dp_failcode = dp_getqueryvariable("failcode"); if (dp_failcode!= "") { document.write("digipass Error: "); document.write(dp_failcode); document.write(" "); document.writeln(dp_getqueryvariable("failmessage")); } </script> <% // Digipass Pack for Citrix Web Interface modifications : END %> Login.js Function // Digipass Pack for Citrix Web Interface modifications : START function dp_getqueryvariable(variable) { var query = window.location.search.substring(1); var vars = query.split("&"); for (var i=0;i<vars.length;i++) { var pair = vars[i].split("="); if (pair[0] == variable) { return unescape(pair[1]); } } return ""; } // Digipass Pack for Citrix Web Interface modifications : END 4.5 Create 2-Step Challenge/Response Template The example challenge-template.html is found in the <install directory>\citrix directory. You may create your own based on this template, or use the example template as is. The template must contain a number of key words which the IIS Module will replace with the appropriate html code. (Note: These fields may appear more than once in the file, and each instance will be replaced) These fields are: 57

58 Post-Installation Tasks DPEXT_FORM_METHOD - This will be replaced with the correct form method DPEXT_FORM_ACTION - This must be the action specified for the form DPEXT_PASSWORD_FIELD_NAME - This must be the name for field into which the response will be written DPEXT_CHALLENGE_TEXT - This string will be replaced with the Challenge issued. DPEXT_HIDDEN_FIELDS - This will be replaced with any fields submitted from login page DPEXT_CHALLENGE_FLASH - This optional field will include the Digipass challenge flash applet html 4.6 Copy Challenge Response Files Backup the loginmainform.inc file from the appropriate directory: For CWI 4.5 and 4.6 <citrix directory>\citrix\metaframe\app_data\auth\include For CWI 5.0.1, 5.2, 5.2, 5.3 <citrix directory>\citrix\xenapp\app_data\include\loginmainform.inc For CAAC 4.5 to the Citrix web directory authentication root, typically C:\Inetpub\wwwroot\CitrixLoginPoint\<site> Copy <install directory>\citrix\cwi_<citrix version>\loginmainform.inc to the appropriate directory from the list above. EnabletOne-Step Challenge-Response using the DIGIPASS Authentication for Citrix Web Interface Configuration. See 5.3 Modify 1-Step Challenge/Response Login Page Details. Challenge Flash Applet This applet is only required if your company is using DIGPASS which have an optical challenge reader, and you wish to utilize this functionality. Copy <install directory>\citrix\flash.class to: a. <citrix directory>\auth for Citrix Web Interface b. <citrix directory> for CAAC Refer to the section of 4.3 Set Up Password Change Page relevant to your version of Citrix for definitions of <install directory> and <citrix directory>. Check file permissions: a. From the IIS management console, ensure the permissions on the flash.class file allows read access. Enable the applet in the Challenge-Response code: a. For One Step Challenge-Response, un-comment applet code in <citrix directory>\include\loginmainform.inc (as copied over in step 1). 58

59 Post-Installation Tasks b. <!-- This part adds the FLASH challenge. --> <!-- commented out by default <tr> <td> <table border="0" cellspacing="0" cellpadding="3"> <tr> <td align='left' valign='top' nowrap> </td> </tr> <tr> <td valign='top'> <%= VascoFlash %> </td> </tr> </table> </td> </tr> --> 4. For Two Step Challenge-Response, un-comment applet code in the challenge template, e.g. <digipass>\citrix\challenge_template.html <body onload='javascript:document.formdpext_password_field_name.focus()'> <div class="loginwindow"> <div class="loginwindowtitle"><h1>digipass Challenge/Response Logon</h1></div> <form name=form1 action=dpext_form_action method=dpext_form_method> <table> <tr><td></td> <td> <!-- This part adds the 'flash applet' optical challenge: DPEXT_CHALLENGE_FLASH flash applet ends here --> </td></tr> <tr><td class="leftcol">challenge:</td> <td>dpext_challenge_text</td></tr> <tr><td class="leftcol">response:</td> <td><input name="dpext_password_field_name" type="password"></td> DPEXT_HIDDEN_FIELDS </tr> </table> <div class="divcenter"><button type="submit" name="submitbutton" value="submit">submit</button></div> </form> </div> </body> 5. Save the file and close. 6. Using the IIS Management Console, check that permissions for the <citrix directory>\flash.class file allow read access. 59

60 Post-Installation Tasks Modify Custom Login Page If you have a current login page in use which differs from the standard Citrix login page, you may need to modify it rather than replacing it with the login page provided with the IIS Module. When the IIS Module detects a request for the login page, it adds three headers to the request before passing it on. The headers added are: Table 5 - Headers added to login request string Header VASCO-Challenge VASCO-State VASCO-FlashCode Explanation Contains the string challenge to be displayed to the user. ie "1234" Contains data that needs to be passed as the field "DPExtState" on the login request. Contains the html code needed to include the challenge flash applet in the login page. This requires the applet be copied to the appropriate location in the website. A piece of code must be inserted into the login page to include 1-step Challenge/Response functionality. The code required can be found below or taken directly from the login page added to the <install directory>\citrix\cwi_<citrix version>\ directory during installation. <!-- Digipass Authentication for Citrix Web Interface modifications : START --> <!-- The following code is for 1-step challenge/response. If you --> <!-- want the flash applet as well as the text challenge, un--> <!-- comment out the section marked FLASH. --> <% string VascoChallenge = Request.ServerVariables["HTTP_VASCO_CHALLENGE"]; string VascoFlash = Request.ServerVariables["HTTP_VASCO_FLASHCODE"]; string VascoState = Request.ServerVariables["HTTP_VASCO_STATE"]; if (VascoState!= null) { %> <!-- This part adds the text challenge. --> <tr> <td> <table border="0" cellspacing="0" cellpadding="3"> <tr> <td align='left' valign='top' nowrap> <label id='lblvascochallenge' class='xsnorm' for='fldvascochallenge' title="digipass Challenge"> Challenge: </label> </td> </tr> <tr> <td valign='top'> <input type='text' name='fldvascochallenge' id='fldvascochallenge' class='loginentries' value='<%= VascoChallenge %>' maxlength='<%=login_entry_max_length%>' readonly='true'> </td> 60

61 Post-Installation Tasks </tr> </table> </td> </tr> <!-- This part adds the FLASH challenge. --> <!-- commented out by default <tr> <td> <table border="0" cellspacing="0" cellpadding="3"> <tr> <td align='left' valign='top' nowrap> </td> </tr> <tr> <td valign='top'> <%= VascoFlash %> </td> </tr> </table> </td> </tr> --> <!-- This part is needed always. --> <input name='dpextstate' type='hidden' value='<%= VascoState %>'> <% } %> <!-- Digipass Authentication for Citrix Web Interface modifications : END --> Troubleshooting If the challenge flash applet is not functioning, ensure that: The applet file (flash.class) is in the correct directory The applet code has been referred to correctly in the login page code. Read permissions have been applied to the flash.class file 4.7 Update Registry Settings for VACMAN Middleware 0 If you will be using the IIS Module with VACMAN Middleware 0 and wish to utilize User Attributes, a registry entry must be added. This will allow the Administration MMC Interface to display the User Profiles/Attributes window. Location: HKEY_LOCAL_MACHINE -> SOFTWARE -> VASCO Data Security -> MMC Admin Interface directory Name: UserAttributeEnabled Type: DWORD 61

62 Post-Installation Tasks Value: 1 62

63 Troubleshooting 5 Troubleshooting 5.1 IIS Module Installation Problems The installation program for the IIS Module will usually complete the following tasks automatically. However, if it fails in these tasks for some reason, an error message will be displayed during installation. These steps can then be followed to complete the installation manually. If you are having trouble running the Authentication Server and the IIS Module for the first time, following these steps may help you track down the problem and fix it manually. 5.1 Check file placement The following files must be placed in the directory they are listed under. If they have been moved to another directory, or incorrectly copied, the IIS Module will not function correctly. <install directory> version.txt <install directory>\bin libxmldll libeay3dll ikaal3seal.dll dpmodulecfg.xml dpiismodcfg.exe dpiisext.dll citrixwiz.exe add-ext.vbs wxmsw28u_vc_custom.dll vdsseal.dll vdsradius.dll vdsprocess.dll vdsnetwork.dll 63

64 Troubleshooting vdsldap.dll vdsflash.dll vdsdatamodel.dll vdsdata.dll vdscrypto.dll vdscore.dll vdsconfig.dll stlport.5.dll ssleay3dll rem-ext.vbs openssl.exe <install directory>\citrix\cwi_4_5 changepassword.inc default.htm login.aspxf login.js loginmainform.inc Messagecenter.inc README_challenge.inc README_chpwd.inc README_failreason.inc <install directory>\citrix\cwi_4_6 changepassword.inc default.htm login.aspxf login.js loginmainform.inc Messagecenter.inc 64

65 Troubleshooting README_challenge.inc README_chpwd.inc README_failreason.inc <install directory>\citrix\cwi_5.0.1 changepassword.inc feedback.htm loginmainform.inc README_challenge.inc README_chpwd.inc README_failreason.inc SessionUtils.java <install directory>\citrix\cwi_5.2 changepassword.inc feedback.htm loginmainform.inc README_challenge.inc README_chpwd.inc README_failreason.inc SessionUtils.java <install directory>\citrix\cwi_5.2 changepassword.inc feedback.htm loginmainform.inc README_challenge.inc README_chpwd.inc README_failreason.inc SessionUtils.java 65

66 Troubleshooting <install directory>\citrix\cwi_5.3 changepassword.inc feedback.htm loginmainform.inc README_challenge.inc README_chpwd.inc README_failreason.inc SessionUtils.java <install directory>\log citrixwiz.trace 5.2 Check Permissions 5.1 Trace File Directory Permissions need to be set to allow the IIS Module to access and write to the trace file. By default, the trace file is stored in <install directory>\log. Follow these steps for the folder the trace file will be written to. Open Windows Explorer and browse to the directory that the trace file will be written to (<install directory>\log by default). Right-click on the relevant directory. Select Properties. The <directory name> Properties window will be displayed. 4. Click on the Security tab. 5. Ensure that the IIS_WPG group has Write permissions ticked. 6. If changes need to be made to the permissions, make changes and click on the Apply button. If the IIS_WPG group is not listed, see 5.3 Add the IIS_WPG Group 5.2 Configuration file Open Windows Explorer and browse to the installation directory. Right-click on the dpmodulecfg.xml file. Select Properties. The dpmodulecfg.xml Properties window will be displayed. 66

67 Troubleshooting Click on the Security tab. 5. Ensure that the IIS_WPG group has the Read permission ticked. 6. If changes were made to the permissions, click on the Apply button. 7. If the IIS_WPG group is not listed for the configuration file, see 5.3 Add the IIS_WPG Group for instructions on adding the account manually. Add the IIS_WPG Group If the IIS_WPG group is not listed for the trace file directory or configuration file, you will need to add it. Click on the Add button. The Select Users, Computers, or Groups window will be displayed. Click on the Advanced button. 67

68 Troubleshooting 5.4 Enter search criteria (see example below) and click on the Find Now button. 4. If no search criteria are entered, a list of all users and groups in the selected location will be returned. 5. Select the IIS_WPG group. 6. Click on the OK button. 7. Check that the IIS_WPG group is listed. 8. Click on the OK button. 9. The account should now be listed in the Security group and user list. Register IIS Module Extension You must run a script to add the new IIS Module Extension. The script is installed in the <install-dir>\bin directory at install time. Open up a DOS command prompt and navigate to the <install-dir>\bin directory 68

69 Troubleshooting 5.5 Enter cscript add-ext.vbs and press enter. Your new IIS Module Extension will be registered by the script. Remove IIS Module Extension Run the following script to remove the IIS Module Extension. The script is installed in the <install-dir>\bin directory at install time. 5.6 Open up a DOS command prompt and navigate to the <install-dir>\bin directory Enter cscript rem-ext.vbs and press enter. Your IIS Module Extension will now be removed. Check IIS Module Extension You can use the following method to check that your new Web Service extension exists, but you will not be able to see if the Wildcard Application Mapping exists. Right-click on My Computer Click on Manage. 69

70 Troubleshooting The Computer Management window will be displayed Expand the Services and Applications heading. 70

71 Troubleshooting 4. Expand the Internet Information Services heading 71

72 Troubleshooting 5. Click on Web Services Extensions. The Web Service Extensions window will be displayed. 5.3 Register as Wildcard Application Mapping Right-click on My Computer Click on Manage. The Computer Management window will be displayed. 72

73 Troubleshooting For Citrix 4.5,

74 Troubleshooting For Citrix Web Interface 5.0.1, 5.2, 5.2,

75 Troubleshooting For Citrix Advanced Access Control 4.5 Expand Services and Applications -> Internet Information Services (IIS) Manager -> Web Sites -> Default Web Site -> Citrix -> AccessPlatform for Citrix Web Interface 4.5,

76 Troubleshooting or Services and Applications -> Internet Information Services (IIS) Manager -> Web Sites -> Default Web Site -> Citrix -> XenApp for Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3 or Services and Applications -> Internet Information Services (IIS) Manager -> Web Sites -> Citrix Logon Point for Citrix Advanced Access Control Right-click on: AccessPlatform (Citrix Web Interface 4.5, 4.6) or XenApp (Citrix Web Interface 5.0.1, 5.2, 5.2, 5.3) or CitrixLogonPoint (Citrix Advanced Access Control 4.5) 5. Click on Properties. 6. Click on the Virtual Directory tab. 7. Click on the Configuration button. The Application Configuration window will be displayed. If the dpiisext.dll is not included in the list, add it manually: 76

77 Troubleshooting Click on the Insert button. 8. Browse to <install directory>\bin\dpiisext.dll (surround with double quotes if there are spaces in the file path). 77

78 Troubleshooting Click on the OK button. The extension should now appear in the Wildcard application maps list. 9. If the extension is not at the top of the Wildcard application maps list: a. Select the dpiisext.dll extension. b. Click on the Move Up button until the extension is at the top of the list. c. Click on the OK button to exit the Application Configuration window. 78