Digipass Authentication for Citrix Web Interface Guide - Vasco

y these field values (right-click and select Fields) to change text throughout the document: 

2008 

Digipass Authentication for Citrix Web Interface 

IIS 6 Module 

Internet Information Services 

IIS 

Authentication Server 

dpauthserver.xml 

Digipass Authentication for Citrix 

Exchange 

Citrix Web Interface 

Guide 

Citrix.msi 

dppack 

the web site 

IIS 6 Module 

Digipass Authentication for Citrix Web Interface 

Internet Information Services 

IIS 


dpauthserver.xml 

Digipass Authentication for Citrix 

Exchange 

Citrix Web Interface 

Guide 

Citrix.msi 

the web site 

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 

© 2008 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. 

Digipass Authentication for Citrix Web Interface Guide 2

Table of Contents 


1 Digipass Authentication for Citrix Web Interface Overview............................................................................... 6 

1.1 IIS 6 Module Overview............................................................................................................................................6 

1.1.1 Authentication Methods....................................................................................................................................6 

1.1.2 Server Connection Management.......................................................................................................................7 

1.1.2.1 Connection Profiles.................................................................................................................................................. 7 

1.1.2.2 Connection Options.................................................................................................................................................. 8 

1.1.3 IIS Module Terminology.....................................................................................................................................9 

1.1.4 Password Change...........................................................................................................................................10 

1.1.5 Tracing............................................................................................................................................................ 10 

2 Installation.................................................................................................................................................... 12 

2.1 System Requirements..........................................................................................................................................12 

2.1.1 Server Requirements - Software.....................................................................................................................12 

2.2 Pre-Installation Tasks...........................................................................................................................................12 

2.2.1 Install Authentication Server ..........................................................................................................................13 

2.2.2 IIS...................................................................................................................................................................13 

2.2.3 Information Needed........................................................................................................................................13 

2.2.4 Licensing........................................................................................................................................................13 

2.3 Install Digipass Authentication for Citrix Web Interface.........................................................................................14 

2.4 Digipass Authentication for Citrix Web Interface Wizard......................................................................................19 

3 Configuration................................................................................................................................................ 25 

3.1 IIS 6 Module Configuration...................................................................................................................................25 

3.1.1 Enable/Disable the IIS 6 Module......................................................................................................................26 

3.1.2 Authentication Server Details..........................................................................................................................26 

3.1.2.1 Add a Server..........................................................................................................................................................26 

3.1.2.2 Modify Server Details..............................................................................................................................................27 

3.1.2.3 Delete a Server Record...........................................................................................................................................28 

3.1.2.4 Modify Connection Settings.....................................................................................................................................29 

3.1.3 Turn Tracing On or Off....................................................................................................................................30 

3.1.4 Sites................................................................................................................................................................ 31 

3.1.4.1 Modify Login Page Details.......................................................................................................................................31 

3.1.4.2 Modify Change Password Page Details.................................................................................................................... 33 

3.1.4.3 Modify 1-Step Challenge/Response Login Page Details............................................................................................ 34 

3.1.4.4 Add a Query String Parameter.................................................................................................................................35 

3.1.4.5 Modify a Query String Parameter.............................................................................................................................36 

3.1.4.6 Delete a Query String Parameter............................................................................................................................. 37 

3.1.4.7 Add a Session Variable for the Failed Login Page..................................................................................................... 37 

3.1.4.8 Edit a Session Variable........................................................................................................................................... 37 

3.1.4.9 Remove a Session Variable.....................................................................................................................................38 



3.1.4.10 Delete Site Record..................................................................................................................................................38 

3.2 Configuration File.................................................................................................................................................39 

3.2.1 Configuration Settings.....................................................................................................................................41 

3.2.2 Modify Character Set Used..............................................................................................................................45 

3.3 Configure Citrix Web Interface 4.0 to work with the Authentication Server...........................................................45 

3.4 Configure Citrix Web Interface 4.5 and Citrix Web Interface 4.6 to work with the Authentication Server.............. 47 

3.5 Configure Authentication Server...........................................................................................................................50 

3.5.1 Component Record.........................................................................................................................................50 

3.5.2 Configure for Windows User Accounts............................................................................................................50 

3.5.2.1 Windows User Name Resolution..............................................................................................................................50 

3.5.2.2 Case Sensitivity......................................................................................................................................................51 

3.5.2.3 Default Domain...................................................................................................................................................... 51 

3.5.3 Policy..............................................................................................................................................................52 

3.5.3.1 Standard Policy Configurations for Citrix Web Interface.............................................................................................52 

3.5.3.2 1-Step Challenge/Response....................................................................................................................................54 

4 Post-Installation Tasks.................................................................................................................................. 56 

4.1 Set up 1-Step Challenge/Response Login.............................................................................................................56 

4.1.1 Set up for Citrix Web Interface 4.x...................................................................................................................56 

4.1.1.1 Modify Custom Login Page..................................................................................................................................... 57 

4.1.1.2 Troubleshooting..................................................................................................................................................... 59 

4.2 Set Up Password Change Page.............................................................................................................................59 

4.2.1 Replace Default Files - Citrix Web Interface 4.0..............................................................................................59 



4.2.4 Modify Custom Change Password Page..........................................................................................................60 

4.2.5 Modify Server Include File...............................................................................................................................61 

4.3 Display Login Failure Reason................................................................................................................................61 

4.3.1 Replace Default Files......................................................................................................................................62 

4.3.2 Modify Existing Files.......................................................................................................................................63 

4.4 Create 2-Step Challenge/Response Template......................................................................................................64 

4.5 Copy Challenge Response Files............................................................................................................................64 

5 Troubleshooting............................................................................................................................................ 65 

5.1 IIS 6 Module Installation Problems........................................................................................................................65 

5.1.1 Check file placement......................................................................................................................................65 

5.1.2 Check Permissions.......................................................................................................................................... 67 

5.1.2.1 Trace File Directory................................................................................................................................................ 67 

5.1.2.2 Configuration file....................................................................................................................................................67 

5.1.2.3 Add the IIS_WPG Group..........................................................................................................................................68 

5.1.3 Set System Environment Variable...................................................................................................................70 

5.1.3.1 Register IIS 6 Module Extension.............................................................................................................................. 73 



5.1.3.2 Remove IIS 6 Module Extension ............................................................................................................................. 73 

5.1.3.3 Check IIS 6 Module Extension ................................................................................................................................ 73 

5.1.4 Register as Wildcard Application Mapping......................................................................................................77 

5.2 Other Troubleshooting Options.............................................................................................................................81 

5.2.1 No Trace File................................................................................................................................................... 81 

5.2.2 Information from Trace File.............................................................................................................................81 

5.2.3 Authentication Server......................................................................................................................................81 

5.2.4 Licensing........................................................................................................................................................81 

5.3 Repair Installation.................................................................................................................................................82 

6 Uninstalling the IIS 6 Module......................................................................................................................... 83 

6.1 Uninstall the IIS 6 Module.....................................................................................................................................83 

7 Technical Support......................................................................................................................................... 84 

7.1 Support Contact Information.................................................................................................................................84 


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 6 Module. 

1.1 IIS 6 Module Overview 

The IIS 6 Module is an add-on for VACMAN Middleware, Identikey Server and aXs GUARD 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 3.x – Identikey Server component 

VACMAN Middleware 3.0 – Authentication Server component 

aXs GUARD Identifier 3.x 

The IIS 6 Module is an ISAPI extension specifically designed for use with IIS 6 only. 

Figure 1 – Digipass Authentication for Citrix Overview 

1.1.1 Authentication Methods 

See the Product Guide for the authentication server for detailed information on login methods and options. 


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 Digipass response to the displayed challenge. 

This requires modification of the current login page used by the web site. 

2-Step Challenge/Response login 

After the login page, the IIS 6 Module redirects users to a ‘Challenge page’ where a random challenge – of the 

length required by the user’s Digipass – 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 Digipass use a similar process to the 2-step Challenge/Response login. If the user 

has a Primary Virtual Digipass assigned, or requests use of the Backup Virtual Digipass 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 6 

Module to the Challenge page to enter the OTP. 

This uses the same Challenge template used in the 2-step Challenge/Response login. 

1.1.2 Server Connection Management 

The IIS 6 Module provides flexibility in managing connections to multiple primary and/or backup Authentication 

Servers. This allows redundancy and load sharing over multiple Servers. 

1.1.2.1 Connection Profiles 

Two connection profiles are available: 

Primary 

The Server(s) to which the IIS 6 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. 


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. 

1.1.2.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 6 Module may have open to the Authentication Server at one 

time. 

Timeout 

The time that the IIS 6 Module should wait for a reply from the Authentication Server. 

Reconnect Interval 

If the IIS 6 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. 


1.1.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. 

Basic Authentication 

A method of authentication that uses the HTTP Basic Authentication mechanism. This uses a login pop-up box 

provided by the Browser. 

Forms Authentication 

The method of authentication where the Web Site provides its own login page. 

IIS Module/IIS 6 Module 

General term for a plug-in to IIS to allow Digipass authentication to take place. 

The IIS 6 module is the IIS Module for IIS version 6. 

The IIS 6 module takes two forms depending on its application: 

IIS Extension 

The IIS Extension is an ISAPI extension used for Forms Authentication. The IIS plug-in is referred to as the IIS 

Module in manuals for Forms Authentication, unless the text is referring specifically to the IIS Extension. 

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. 


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 aXs Guard Identifier, the Identikey Server daemon 

For VACMAN Middleware 3, the Digipass Authentication Service 

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 aXs Guard, Component for 

VACMAN Middleware 3. 

They are used for the following main purposes: 


1.1.4 Password Change 

1.1.5 Tracing 


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 

The IIS 6 Module can capture password changes made in Citrix Web Interface. This requires modification of the 

current Password Change page used by Citrix Web Interface. 

The IIS 6 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 6 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] 


Debugging messages (useful for support purposes) [DEBUG] 


Security messages, messages that may contain security sensitive data [SECUR] 

Note 

The IIS 6 Module will require permissions for the directory in which the tracing file is kept. See 

5.1.2 Check Permissions for more information. 


2 Installation 

Installation 

Before installing the IIS 6 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. 

2.1 System Requirements 

2.1.1 Server Requirements - Software 

An authentication server running on another machine. This should be one of the following: 

Identikey Server 3.x – Identikey Server component 

VACMAN Middleware 3.0 - Authentication Server component 

aXs GUARD Identifier 3.x 

Internet Information Services (IIS) 6.0 or higher 

Windows Server 2003 SP2 or higher 

Citrix Presentation Server Web Interface 4.0 (also known as XenApp) or later 

The User must have administration rights on the installation machine. 

Note 

2.2 Pre-Installation Tasks 

Digipass Authentication for Citrix Web Interface is not supported on 64-bit operating systems. 

Before installing the IIS 6 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. 


2.2.1 Install Authentication Server 

2.2.2 IIS 

Installation 

An Authentication Server must be installed on the network before the IIS 6 Module is installed. See 2.1 System 

Requirements for compatible servers and 3.5 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. 

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. 

2.2.3 Information Needed 

2.2.4 Licensing 

Before you begin installation of the IIS 6 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). 

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. 


2.3 Install Digipass Authentication for Citrix Web Interface 

1. Start the ‘Digipass Authentication for Citrix Web Interface ’ installation process. 

If you are not using the CD Autorun interface, locate and double-click on the Citrix.msi file. 

2. Click Next. 

Installation 


The License Agreement screen will be displayed. 

3. Tick the box marked 'I accept the terms in the License Agreement'. Click Next. 

4. Enter the destination folder for the module. Click Next to accept the default or choose your preferred 

destination and click Next. 

Installation 


5. Click Install to install the Digipass Authentication for Citrix Web Interface . 

The files will be installed to the directory you specified. 

Installation 


6. To finish the install click Finish 

Installation 


On exit, the installer launches the Digipass Authentication for Citrix Web Interface Wizard. 

Installation 


2.4 Digipass Authentication for Citrix Web Interface Wizard 

Note 

For a definition of the term Authentication Server, please see 1.1.3 IIS Module Terminology 

1. Enter the IP address for the Authentication Server in the IP Address field. 

Installation 

2. 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. 

3. Select the type of data store that the primary Authentication Server is using. Select either Active Directory or 

ODBC-compliant or embedded database. If using the embedded PostgreSQL database, select ODBCcompliant 

or embedded database. 


The Wizard will attempt to connect to the Authentication Server using the IP address and port provided. 


Installation 

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. 

5. Select an IP address from the IP Address drop down list, which will contain IP addresses assigned to the 

current machine. The IIS 6 Module will use the selected IP address exclusively. As VASCO component 

licensing operates on IP address, this ensures that the IIS 6 Module will only use up one component license 

slot. 



7. Select one of the two option buttons. 

Create Component record manually 

Installation 

The Wizard will not attempt to create a Component record for the IIS 6 Module or load a license for the 

record. You will need to do this manually instead. This option where a Component record already exists for 

the IIS 6 Module, with a valid license key loaded. 

a. Select Do not create the Component record and do not load the license automatically 

b. Click on Next. 

c. Jump to Step 10. 

Create Component record automatically 

The Wizard will create a Component record in the Authentication Server data store for the IIS 6 Module. You 

may also load a license for the created record. If the Component record already exists for the IIS 6 Module at 

the current IP address, a new Component record will not be created. The license key will be loaded into the 

existing Component record. 

a. Select Do create the Component record automatically 


c. Continue with the following steps. 

8. Enter your login details: 

Active Directory 


a. Enter the User ID and password for the Domain Administrator. 

Installation 

If you are logged into the current machine as Domain Administrator in the correct Domain, you may 

leave these fields blank. 

b. Enter the Fully Qualified Domain Name of the Domain in which the Authentication Server configuration 

data is kept. Typically this will be Digipass Configuration Domain. This is a mandatory field. 

c. Enter a preferred server if you wish the Wizard to connect to a specific Domain Controller. The text 

entered should be the first part of the Fully Qualified Domain Name for the Domain Controller. 

d. Click on Next. 


ODBC-Compliant Database 

a. Enter the User ID and password for an Administrator account on the Authentication Server. This 

account will need permissions to: 

view, create and update Components 


view Policies 

Installation 


Installation 

9. 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 Key from www.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. 

10. The Summary screen will allow you to review your configuration settings before they are applied. 

Check the configuration settings carefully and click Back to go back and change a setting if it is incorrect. 

Click Proceed to apply the configuration settings when they are correct. 

11. If the Authentication Server uses Active Directory as its data store, you may need to restart the 

Authentication Server before it will recognise the new Component record and acknowledge requests 

from the IIS 6 Module. 


3 Configuration 

Configuration 

Configuration settings can be modified in two ways. The easiest method is via the IIS 6 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. 

3.1 IIS 6 Module Configuration 

A Graphical User Interface (GUI) is available for use in configuring the IIS 6 Module. This provides a simple, 

intuitive way to set up the IIS 6 Module to work with your current system. 

To open the IIS 6 Module Configuration, click on the Start Button and select Programs VASCO Digipass 

Authentication for Citrix Web Interface IIS Module Configuration 

Alternatively, open Windows Explorer and open \Bin\dpiismodcfg.exe. 

If this is the first time you have opened the IIS 6 Module Configuration and the configuration file has not been 

edited, the values you will see are those entered when the Wizard was last run. 


3.1.1 Enable/Disable the IIS 6 Module 

Configuration 

This option starts or stops the IIS 6 Module from redirecting authentication requests to the Authentication Server. 

1. Click on the General tab. 

2. Tick or untick the Enable Digipass Authentication checkbox. 

3. Click on the Apply button. 

3.1.2 Authentication Server Details 

3.1.2.1 Add a Server 

The Server list contains all Authentication Servers which may be utilized by the IIS 6 Module. Authentication Server 

records can be added, deleted, or their details modified. 

1. Click on the Add button. 

The New Server window will be displayed. 


Configuration 

2. 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 6 Module. 

3. Enter an IP address and port (typically 20003) for the Authentication Server, in the IP Address and Port 

fields. 

4. Select a Server Type (see 1.1.2 

Server Connection Management). 

5. Enter a timeout period (in seconds) in the Timeout field. 

6. Enter the maximum number of concurrent connections to be made from the IIS 6 Module to the Server, in the 

Max. Connections field. 

7. Enter a minimum and maximum amount of time that the IIS 6 Module should wait before attempting to 

reconnect to the Authentication Server in the Min. Reconnect Interval and Max. Reconnect Interval fields. 

8. Click on the OK button. 

3.1.2.2 Modify Server Details 

1. Select the Server to be edited. 

2. Click on the Edit button. 

The Edit Server window will be displayed. 


3. Make required changes. 


3.1.2.3 Delete a Server Record 

1. Select the Server record to be deleted. 

2. Click on the Delete button. 

A confirmation window will be displayed. 

3. Click on OK to delete the Server record. 

Configuration 


3.1.2.4 Modify Connection Settings 

Reconnect Interval 

Configuration 

If the IIS 6 Module loses contact with the primary Authentication Server(s), it will switch its connection over to a 

backup Authentication Server. It will try to reconnect with the primary server(s) at increasing intervals until 

connection with the primary server(s) is re-established. 

The Minimum Reconnect Interval and Maximum Reconnect Intervalsets the minimum and maximum amounts of 

time that the IIS 6 Module will leave between attempts to reconnect to the primary Authentication Server(s). 

Connect from IP Address 

If a server has multiple IP addresses configured, the IIS 6 Module needs to know which to use in connecting to the 

Authentication Server(s). 

1. Enter the IP address from which to connect to Authentication Servers in the Connect from IP Address field. 

This may be left blank if there is only one IP address for the machine. 



Load Sharing 

Configuration 

Load sharing allows the IIS 6 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. 

1. Tick the Enable Load Sharing checkbox. 


3.1.3 Turn Tracing On or Off 

1. Select a Tracing option. See 1.1.5 Tracing for more information. 

2. 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. 



3.1.4 Sites 

Note 

If the File Name field is left blank or the file path does not exist, the IIS 6 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.2.1 Trace File Directory for more information. 

Configuration 

Each web site to be protected by the IIS 6 Module is displayed in the Sites list. C 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. 

3.1.4.1 Modify Login Page Details 

1. Click on the Authentication tab. 


2. Select the Site and click on the Edit button. 

The Edit Site window will be displayed. 

3. 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, 

Password and Domain are entered into the relevant fields. 

8. Click on the Failed Login tab. 

Configuration 


Modify the Base URL if required. 

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 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. 

11. If you need to set up 2-step Challenge/Response login or Virtual Digipass login: 

a. Click on the Two Step C/R tab 

12. Enter the location of the Challenge/Response template. 

13. Click on OK. 

3.1.4.2 Modify Change Password Page Details 





3. Click on the Change Password tab. 

4. Tick the Enabled checkbox to allow the IIS 6 Module to capture password changes. 


Configuration 

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,Password, New 

Password and Confirm Password are entered into the relevant fields. 


3.1.4.3 Modify 1-Step Challenge/Response Login Page Details 





3. Click on the One Step C/R tab. 

4. Tick the Enabled checkbox to allow 1-step Challenge/Response logins. 


Configuration 

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. 


3.1.4.4 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. 

1. Click on the + button. 


The Add Login Query String Parameter window will be displayed. 

2. Enter the new parameter, exactly as it will appear in the query string – eg. page=login 


4. Repeat the process for other query string parameters 

3.1.4.5 Modify a Query String Parameter 

1. Select a Query String Parameter from the list. 

2. Click on the button. 

The Edit Login Query String Parameter window will be displayed. 

3. Make the required changes. 


Configuration 


3.1.4.6 Delete a Query String Parameter 

1. Select a query string parameter from the list. 



3. Click on Yes to delete the query string parameter. 

3.1.4.7 Add a Session Variable for the Failed Login Page 

Configuration 

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. 

1. Click on the + button. 

The Add Failed Login Session Variable window will be displayed. 

2. Enter the name of the query string parameter. 


Repeat the process for other query string parameters to be included in the failed login URL. 

3.1.4.8 Edit a Session Variable 

1. Select a session variable from the list. 


The Edit Failed Login Session Variable window will be displayed. 


3. Modify the name of the query string parameter. 


3.1.4.9 Remove a Session Variable 

3.1.4.10 Delete Site Record 

1. Select a query string parameter from the session variable list. 



3. Click on Yes to remove the query string parameter from the list. 


2. Select the site name from the Sites list. 

3. Click on the Delete button. 


4. Click on OK to delete the site record. 

Configuration 


3.2 Configuration File 

Configuration 

The IIS 6 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 6 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 6 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 6 Module to stop working. 

Example configuration file 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Caution 

The configuration file is UTF8 encoded. Non-UTF8 encoded characters should not be added to 

the configuration file, or it will not load. 

Configuration 


3.2.1 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 

Configuration 

Revision 1 The current revision of the configuration. This is incremented each 

time the configuration is changed and allows the IIS 6 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 1 Whether the IIS 6 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. 

Local-Address IP address 

automatically detected 

by the install program. 

If more than one IP 

address was detected, 

this value will be the IP 

address selected during 

installation. 

The local IP address to be used when connecting to Authentication 

Servers. 

Trace/Trace-Header 31 The tracing header fields that have been enabled. This is a bitmask 

constructed by adding the following values: 

1 Enable the Date field 

2 Enable the Time field 

4 Enable the Tracing level field 

8 Enable the Thread ID field 

16 Enable the File field 

32 Enable the Line field 

Trace/Trace-Mask 0x00000000 Hexadecimal or decimal values: 

Trace/Trace-File \ 

eg. for DATE,TIME,LEVEL = 1 + 2 + 4 = 7 

A value of 0 will result in no header being added to the trace output. 

Hex Decimal 

0x00000000 0 No tracing 

0x0010000E 1048590 Configuration and error messages only 

0xFFFFFFFF 4294967295 All levels enabled. 

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 



Configuration 

Log\dpextcfg.trace IIS6 module if it does not exist. 

If this option is blank, the IIS 6 Module will not output tracing. 

Local-Address 127.0.0.1 The local IP address to be used when connecting to Authentication 

Servers. 

Connection-List/Load- 

Balancing 

Connection-List/ Connection 

/ Name 


/ Address 

Connection-List/ 

Connection/ Port 

Connection-List/ 

Connection/ 

Server-Type 


/ 

Nr-Connections 


/Min-Reconnect- 

Interval 


/Max-Reconnect- 

Interval 

False Whether load balancing is enabled for connections to Authentication 

Servers. 

Text to display in the Servers list on the Configuration. 

IP Address entered 

during installation. 

20003 (default) or 

Port number entered 

during installation. 

IP Address of the Authentication Server. 

Port to use in connecting to the Authentication Server 

Primary Either Primary or Backup Authentication Server. This setting affects 

load-balancing. 

10 The maximum number of concurrent connections which the IIS 6 

Module may hold open to the Authentication Server. 

30 The minimum amount of time in seconds that the IIS 6 Module will 

leave between attempts to reconnect to a higher-priority server after 

losing connection to it. 

300 The maximum amount of time in seconds that the IIS 6 Module will 

leave between attempts to reconnect to a higher-priority server after 

losing connection to it. 

Attribute-Group The Attribute Group name to use in retrieving credentials from a 

Digipass User account. 

Use-Attribute-For-User- 

Name 

0 If this option is enabled, the IIS 6 Module will retrieve a User-Name 

attribute from a Digipass User account. It will replace the User ID 

entered during login with the attribute value before passing the 

request to the the web site. 

0 Disabled. The User ID will not be replaced with the User attribute. 

1 Enabled. The User ID will be replaced with the User-Name 

attribute. 

Sites/Site/ Name Citrix Web Interface 4.x Text to display in the Sites list on the Configuration GUI. 

Sites/Site/ 

Component-Type 

Sites/Site/ 

Login/Match-URL/URL 

Citrix Web Interface Component type to specify when connecting to an Authentication 

Server for this Site. 

/citrix/metaframe/auth 

/login.aspx 

(CWI 4.0 - 4.5) 

The base URL to use in submitting a login 



Sites/Site/ 

Login/Match-URL/ 

Param 

Sites/Site/ 

Login/Failed-URL/URL 

Sites/Site/ 

Login/User-Field 

Sites/Site/ 

Login/Password-Field 

Sites/Site/ 

Login/Domain-Field 

Sites/Site/ 

Login/Challenge-Template 

Sites/Site/ 

Login/Error-Message 

Sites/Site/ 

ChgPasswd/Match-URL/URL 

OR 

/citrix/AccessPlatform/a 

uth /login.aspx 

(CWI 4.6) 

Query string parameter needed in the URL. 


/login.aspx?Nfuse_Mes 

sageType=Error& 

Nfuse_MessageKey=In 

validCredentials&N 

fuse_LogEventID= 

(CWI 4.0 - 4.5) 

OR 


uth 

/login.aspx?Nfuse_Mes 

sageType=Error& 

Nfuse_MessageKey=In 

validCredentials&N 

fuse_LogEventID= 

(CWI 4.6) 

The base URL to use after a failed login attempt 

user Name of the field that corresponds to User. 

password Name of the field that corresponds to Password. 

domain Name of the field that corresponds to Domain 

\ 

change_password\chall 

enge_template.html 

Location and file name of the template to use in creating a 

Challenge/Response page 

Configuration 

false Specifies whether the IIS Module should pass a reason for a login 

failure to Citrix. Corresponds to Return Failure Reason checkbox in 

the Configuration GUI. 


/changepassword.aspx 

(CWI 4.0 - 4.5) 

OR 

/citrix/AccessPlatform/ 

auth 

The base URL used in changing a User’s password. 



Sites/Site/ 

ChgPasswd/ Match- 

URL/Param 

Sites/Site/ 

ChgPasswd/Enabled 

Sites/Site/ 

ChgPasswd/ User-Field 

Sites/Site/ 

ChgPasswd/ Password-Field 

Sites/Site/ 

ChgPasswd/ NewPassword- 

Field 

Sites/Site/ 

ChgPasswd/ PasswordConf- 

Field 

Sites/Site/ One- 

Step-CR/Match-URL/URL 

Sites/ Site/ One- 

Step-CR/ Match-URL/ 

Param 

Sites/ Site/ One- 

Step-CR/ Enabled 

/changepassword.aspx 

(CWI 4.6) 


0 Whether the IIS 6 Module will capture password changes. 

dp_user Name of the field that corresponds to User. 

password Name of the field that corresponds to Password. 

passwordNew Name of the field that corresponds to New Password. 

Configuration 

passwordConfirm Name of the field that corresponds to Confirm New Password. 

/citrix/metaframe/auth/l 

ogin.aspx 

(CWI 4.0 - 4.5) 

OR 


uth/login.aspx 

(CWI 4.6) 

The base URL to use in making a one-step challenge/response login 

request. 


0 Whether one-step challenge/response logins are enabled. 


3.2.2 Modify Character Set Used 

Configuration 

If you are using non-Western European characters, the IIS 6 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 6 Module configuration file (dpmodulecfg.xml) in the 

\bin directory. Edit the Encoding setting to the desired character set code – these are listed 

in the table below. 

Caution 

The IIS 6 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 Other code(s) 

Arabic ISO-8859-6 CP1256 

Baltic ISO-8859-4 or ISO-8859-13 CP1257 

Central European ISO-8859-2 CP1257 

Chinese Simplified ISO-2022-CN GB2312 

Chinese Traditional Big5 

Cyrillic ISO-8859-2 CP1251 

Greek ISO-8859-7 CP1253 

Hebrew ISO-8859-8-I CP1255 

Japanese ISO-2022-JP 

Korean ISO-2022-KR 

Thai ISO-8859-11 CP874 

Turkish ISO-8859-9 

Vietnamese CP1258 

Western European ISO-8859-1 CP1252 

3.3 Configure Citrix Web Interface 4.0 to work with the Authentication Server 

1. Open the Access Suite Console for Presentation Server. 

2. Expand the Suite Components node. 


3. 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. 

6. The Configure Authentication Methods Wizard window will be displayed. 

Configuration 


7. Tick the Explicit checkbox. 

8. Select Disable from the Enforce 2-factor authentication drop down list. 

9. C lick on Next. 

10. Select the Windows or NIS (UNIX) option button. 

11. Click on Next. 

12. Complete the next two Wizard steps as needed. 

13. Click on Finish. 

Configuration 

3.4 Configure Citrix Web Interface 4.5 and Citrix Web Interface 4.6 to work with the 


1. Open the Access Management Console for Presentation Server. 


2. Expand the Citrix Resources node. 

3. 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. 

Configuration 


Configuration 

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. 

11. Complete the sections of the Properties dialog as needed. 

12. Click on OK to close the Properties window, then OK again to close the Configure Authentication 

Methods window. 


3.5 Configure Authentication Server 

3.5.1 Component Record 

Configuration 

A Client Component record must be configured in the Authentication Server for the IIS 6 Module. The wizard can 

create the required record if: 

The Authentication Server is using an ODBC database (including the embedded PostgreSQL database) as its 

data store, or 

The Authentication Server is using Active Directory and the wizard can successfully connect to Active Directory 

from the web server. 

To create the Client Component record manually: 

1. Create a Client Component record for the IIS 6 Module. 

a. The Component Type should be set to Citrix Web Interface. 

b. The Location should be set to the same IP address as in the Connect from IP Address setting in IIS 6 

Module Configuration. 

c. Select a Policy for the Authentication Server to use when processing authentication requests from the 

IIS 6 Module. See 3.5.3 Policy for more information. 

2. A valid license key must be obtained for the IIS 6 Module and loaded in to the Component record. 

3.5.2 Configure for Windows User Accounts 

3.5.2.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 aXs GUARD 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 


3.5.2.2 Case Sensitivity 

3.5.2.3 Default Domain 

Configuration 

rejected, unless a second Digipass User account has been created. This is essential for enabling the change 

password facility to work. 

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 

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. 

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 aXs GUARD 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 6 Module. 


3.5.3 Policy 

Configuration 

The Component record created during installation of the IIS 6 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 (aXs GUARD 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 aXs GUARD 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 Digipass Users is placed in the Group List. This will mean that any 

logins by Users not in the Digipass 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 6 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 6 Module Component. 

3.5.3.1 Standard Policy Configurations for Citrix Web Interface 

Digipass 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 6 Module. 


Digipass User Account Handling 

Dynamic User Registration: Enabled 

Password Autolearn: Enabled 

Stored Password Proxy: Enabled 

Configuration 

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 6 Module in place of the One Time Password entered by the User on 

future logins. 

Digipass 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 Digipass/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). 

Digipass Users login with Password and OTP (Windows user accounts) 



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 and Self-Assignment logins through the IIS 6 Module. 


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. 



Configuration 

Either Self-Assignment or Auto-Assignment would typically be used in this scenario, although manual assignment 

may also be used. 


The typical setting for local authentication would be Digipass/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 



Back-End Authentication: None 

The Authentication Server will not use back-end authentication. 


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. 


As Self-Assignment and Auto-Assignment are both reliant on back-end authentication,only manual assignment will 

be available. 


The typical setting for local authentication would be Digipass, meaning that Users are required to use an OTP when 

logging in 

3.5.3.2 1-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 


Challenge Check Mode: 0 

For more information, see the Policies section of the Product Guide. 

Configuration 


4 Post-Installation Tasks 

4.1 Set up 1-Step Challenge/Response Login 

Post-Installation Tasks 

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 \change_password\CWI_ 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.1.1 Set up for Citrix Web Interface 4.x 

The instructions for modifying the Citrix Web Interface login page vary slightly between Citrix Web Interface 

versions 4.0 and 4.5 and 4.6. The differences are in the location of the Citrix directory, and the name of the login 

page. 

The standard settings for each are listed below. The directory is located in \Citrix\MetaFrame\ 

(4.0 - 4.5) and \Citrix\AccessPlatform\ (4.6) in the table below. 

Web root is typically c:\inetpub\wwwroot. 

Table 3 - Citrix directory and login page variations 

Citrix Web Interface 4.0 Citrix Web Interface 4.5 and 4.6 

Citrix directory \auth \app_data\auth 

Login page loginMainForm.inc loginMainForm.inc 

Login page 

1. Backup \include\ to a suitable place. 

2. Copy modified login page from \change_password\CWI_\ to 

\include\ 

3. Enable one-step Challenge/Response in the Configuration GUI. Modify the base URL and/or query string 

parameters as required. 

See the Modify 1-Step Challenge/Response Login Page Details topic in the IIS 6 Module 

Configuration GUI section for more information. 


Challenge Flash Applet 


This applet is only required if your company is using Digipass which have an optical challenge reader, and you wish 

to utilize this functionality. 

1. Copy \change_password\CWI_\flash.class to . 

2. Remove commenting (the greyed-out lines in the example below) for the applet code in the login page \include\. 

To edit the file, right-click on it and select Edit from the menu. 

CWI 4.x 

 

 

3. Save the file and close. 

4. Using the IIS Management Console, check that permissions for the \flash.class file allow 

read access. 

4.1.1.1 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 6 Module. 

When the IIS 6 Module detects a request for the login page, it adds three headers to the request before passing it 

on. The headers added are: 

Table 4 - Headers added to login request string 

Header Explanation 

VASCO-Challenge Contains the string challenge to be displayed to the user. ie "1234" 

VASCO-State Contains data that needs to be passed as the field "DPExtState" on the login request. 

VASCO-FlashCode 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 \change_password\CWI_\ directory during installation. 

CWI 4.x 

 

 

 

 

 

 

 

 

 

 

 

 

Challenge: 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

--> 

4.1.1.2 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.2 Set Up Password Change Page 


The IIS 6 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 6 Module, and is installed to \change_password\CWI_\changepassword.inc. For Citrix Web Interface 4.x an additional 

file – login.cs (4.0) or 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.2.1 Replace Default Files - Citrix Web Interface 4.0 

The is located in \Citrix\MetaFrame\auth. 

Web root is typically located in c:\inetpub\wwwroot. 

1. Backup \include\changepassword.inc and \ serverscripts\login.cs to a 

suitable place. 

2. Copy changepassword.inc from \change_password\CWI_ to \include. 


3. Copy login.cs from \change_password\v to \serverscripts. 


4. Enable Change Password in the Configuration GUI. Modify the base URL and/or query string parameters if 

required. See the Modify Change Password Page Details topic in the IIS 6 Module Configuration GUI 

section for more information. 


The is located in \Citrix\MetaFrame\app_data\auth. 

Web root is typically c:\inetpub\wwwroot. 

1. Backup \include\changepassword.inc and \ serverscripts\login.aspxf 

to a suitable place. 


3. Copy login.aspxf from \change_password\CWI_ to \serverscripts. 


required. See the Modify Change Password Page Details topic in the IIS 6 Module Configuration GUI 

section for more information. 


The is located in \Citrix\AccessPlatform\app_data\auth. 


1. Backup \include\changepassword.inc and \ serverscripts\login.aspxf 

to a suitable place. 


3. Copy login.aspxf from \change_password\CWI_ to \serverscripts. 


required. See the Modify Change Password Page Details topic in the IIS 6 Module Configuration GUI section 

for more information. 

4.2.4 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 6 Module. 



A piece of code must be inserted into the page to include a hidden field used by the IIS 6 Module . The code 

required can be found below or taken directly from the Change Password page added to the \change_password\CWI_ directory during installation. 

Citrix Web Interface 4.x 

 

 

 

 

4.2.5 Modify Server Include File 

The login.cs (4.0) or 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 6 Module. This is required for Citrix Web Interface 4.x only. 

The code should be inserted in the loginAuthenticateExplicit function, underneath the following text: 

Code 

if (credentials != null && !bIsError()) { 

System.Collections.Hashtable parameters = new System.Collections.Hashtable(); 

parameters["AccessToken"] = credentials; 

parameters["ExplicitAuth"] = expAuth; 

// 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.3 Display Login Failure Reason 

The IIS 6 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 6 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. 


4.3.1 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.0 

The is located in \Citrix\MetaFrame\auth. 


1. Backup \include\messagecenter.inc and \ clientscripts\login.js to a 

suitable place. 

2. Copy messagecenter.inc from \fail_reason\v- to \include. 

3. Copy login.js from \fail_reason\v- to \clientscripts. 

4. Enable Return Failure Reason (see Modify Login Page Details). 


The is located in \Citrix\MetaFrame. 


1. Backup \app_data\auth\include\messagecenter.inc and \auth\clientscripts\login.js to a suitable place. 

2. Copy messagecenter.inc from \fail_reason\v- to \app_data\auth\include. 

3. Copy login.js from \fail_reason\v- to \auth\clientscripts. 



The is located in \Citrix\AccessPlatform. 


1. Backup \app_data\auth\include\messagecenter.inc and \auth\clientscripts\login.js to a suitable place. 

2. Copy messagecenter.inc from \fail_reason\v- to \app_data\auth\include. 

3. Copy login.js from \fail_reason\v- to \auth\clientscripts. 



4.3.2 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. 

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 

 

 

 

dp_failcode = dp_getQueryVariable("failcode"); 

if (dp_failcode != "") { 

document.write("Digipass Error: "); 

document.write(dp_failcode); 

document.write(" "); 

document.writeln(dp_getQueryVariable("failmessage")); 

} 

 

 

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

4.4 Create 2-Step Challenge/Response Template 


The example challenge-template.html is found in the \change_password 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 6 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: 

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.5 Copy Challenge Response Files 

The flash.class file is required if the challenge flash applet will be used for Challenge/Response logins. The applet 

will only be useful if the Digipass used by your company have an optical challenge reader. 

The flash.class file must be copied from \change_password to the citrix\metaframe\site or 

citrix\auth (for 4.0) or citrix\app_data\auth (for 4.5 and 4.6) directory under the web server root (typically 

c:\inetpub\wwwroot). 


5 Troubleshooting 

5.1 IIS 6 Module Installation Problems 

Troubleshooting 

The installation program for the IIS 6 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 6 Module for the first time, following these 

steps may help you track down the problem and fix it manually. 

5.1.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 6 Module will not function correctly. 

 

version.txt 

\Bin 

ikaal3seal30.dll 

ikaal3ldap.dll 

libeay32.dll 

libxml2.dll 

openssl.exe 

stlport.5.1.dll 

vxmsw28u_vc_custom.dll 

ssleay32.dll 

dpmodulecfg.xml 

dpiisext.dll 

dpiismodtcfg.exe 

add_ext.vbs 

rem_ext.vbs 


citrixwiz.exe 

\change_password\CWI_4_0 

changepassword.inc 

default.htm 

login.js 

loginMainForm.inc 

Messagecenter.inc 

README_challenge.inc 

README_chpwd.inc 

README_failreason.inc 

session.cs 



default.htm 

login.aspxf 

login.js 








default.htm 

login.aspxf 

login.js 








\fail_reason 

messagecenter.inc 

login.js 

5.1.2 Check Permissions 

5.1.2.1 Trace File Directory 


Permissions need to be set to allow the IIS 6 Module to access and write to the trace file. By default, the trace file 

is stored in \log. Follow these steps for the folder the trace file will be written to. 

1. Open Windows Explorer and browse to the directory that the trace file will be written to (\log by default). 

2. Right-click on the relevant directory. 

3. Select Properties. 

5.1.2.2 Configuration file 

The 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 Add the IIS_WPG Group. 

1. Open Windows Explorer and browse to the installation directory. 

2. Right-click on the dpmodulecfg.xml file. 

3. Select Properties. 

The dpmodulecfg.xml Properties window will be displayed. 


4. 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.1.2.3 Add the IIS_WPG Group for 

instructions on adding the account manually. 

5.1.2.3 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. 

1. Click on the Add… button. 

The Select Users, Computers, or Groups window will be displayed. 

2. Click on the Advanced… button. 


3. 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. 


7. Check that the IIS_WPG group is listed. 


9. The account should now be listed in the Security group and user list. 


5.1.3 Set System Environment Variable 

1. Right-click on My Computer. 

2. Click on Properties. 



3. The System Properties window will be displayed. 

Click on the Advanced tab. 

4. Click on the Environment Variables button. 

The Environment Variables window will be displayed. 



If DPIISModuleDirectory is not displayed in the System variables list, create it manually: 

5. Click on the New button. 

6. Enter the following values: 

Variable Name: DPIISModuleDirectory 

Variable Value: 

7. Click on the OK button 

8. Click on the OK button again. 

The new System variable should now appear in the System variables list. 



5.1.3.1 Register IIS 6 Module Extension 


You must run a script to add the new IIS 6 Module Extension. The script is installed in the \bin 

directory at install time. 

1. Open up a DOS command prompt and navigate to the \bin directory 

2. Enter cscript add-ext.vbs and press enter. 

3. Your new IIS 6 Module Extension will be registered by the script. 

5.1.3.2 Remove IIS 6 Module Extension 

Run the following script to remove the IIS 6 Module Extension. The script is installed in the \bin 

directory at install time. 

1. Open up a DOS command prompt and navigate to the \bin directory 

2. Enter cscript rem-ext.vbs and press enter. 

3. Your IIS 6 Module Extension will now be removed. 

5.1.3.3 Check IIS 6 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. 

1. Right-click on My Computer 

2. Click on Manage. 


The Computer Management window will be displayed 

3. Expand the Services and Applications heading. 



4. Expand the Internet Information Services heading 



5. Click on Web Services Extensions. 

The Web Service Extensions window will be displayed. 



5.1.4 Register as Wildcard Application Mapping 

1. Right-click on My Computer 

2. Click on Manage. 

The Computer Management window will be displayed. 

For Citrix 4.0 – 4.5 



For Citrix 4.6 


3. Expand Services and Applications -> Internet Information Services (IIS) Manager -> Web Sites -> 

Default Web Site -> Citrix -> MetaFrame for Citrix Web Interface 3.0 – 4.5, 

or 

Services and Applications -> Internet Information Services (IIS) Manager -> Web Sites -> 

Default Web Site -> Citrix -> AccessPlatform for Citrix Web Interface 4.6 

4. Right-click on MetaFrame (Citrix Web Interface 4.0 – 4.5) or AccessPlatform (Citrix Web Interface 4.6). 

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: 



Click on the Insert… button. 


8. Browse to \bin\dpiisext.dll (surround with double quotes if there are spaces in the file 

path). 

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. 


5.2 Other Troubleshooting Options 

5.2.1 No Trace File 


If you are still having problems after checking that all installation and configuration settings for the IIS 6 Module are 

correct, follow these steps to check for other possible problems. 

If there is no trace file, or the trace file information does not help, first check that the ISAPI extension has been 

registered (see 5.1.3.1 Register IIS 6 Module Extension for instructions) and the wildcard application mapping is 

set (see 5.1.4 Register as Wildcard Application Mapping for instructions). Next, check the Windows Events for 

any warnings or errors generated by a failure to load the IIS 6 Module into IIS. 

5.2.2 Information from Trace File 

1. Set the IIS 6 Module to tracing. 

2. Restart IIS. 

3. Attempt a login. 

4. Check the trace file for information on the start-up conditions of the IIS 6 Module and of the login attempt. 

5.2.3 Authentication Server 

5.2.4 Licensing 

If the IIS 6 Module appears to load and update but you are unable to achieve a successful login, check the 

Authentication Server. Open the Audit Viewer to: 

check available audit messages in the audit files or database. 

configure a live audit connection from the Authentication Server and retry a login. 

See the Authentication Server's Administrator Reference for more information. 

Check that the IIS 6 Module has a valid client Component in the Authentication Server data store, which has a valid 

license loaded. See the Licensing section of the Authentication Server's Administrator Reference for more 

information on licensing options. 


5.3 Repair Installation 

The installation of the IIS 6 Module may need to be repaired if files have been corrupted, deleted or lost. 

1. Locate and double-click on Citrix.msi file. 

2. Click on the Next button. 

3. Select the Repair option button to enter the repair function. 

4. Click on the Repair option button to confirm the repair. 

5. Click on the Finish button. 

Note 


The configuration file (dpmodulecfg.xml) will not be copied over if it exists in the standard 

directory. To repair this file, delete or move it and run the installation repair. 

If you have deleted or moved the configuration file, changed the IP address for the machine or received a new 

license for the IIS 6 Module, you will need to run the Digipass Authentication for Citrix Web Interface Wizard after 

the installation repair. 


6 Uninstalling the IIS 6 Module 

6.1 Uninstall the IIS 6 Module 

1. Open the Windows Add or Remove Programs utility. 

Select Digipass Authentication for Citrix Web Interface 

2. Click on the Change/Remove button. 

OR 

Locate and double-click on the Citrix.msi file to start the MSI. 

3. Click on the Next button. 

4. Select the Remove option button to select the remove function. 

5. Click on the Remove option button to confirm the remove function. 

6. Click on the Finish button. 

Uninstalling the IIS 6 Module 

The Uninstallation Progress screen will be displayed, showing the progress of your uninstall. 

7. After uninstallation, the system must be restarted. 


7 Technical Support 

If you encounter problems with a VASCO product please do the following: 

Technical Support 

1. Read the Troubleshooting topic in the Administrator Reference or the Troubleshooting section of this guide 

for help in discovering the source of your problem. 

2. Check if your problem is resolved in the Knowledge Base located at the following URL: 

http://www.vasco.com/support. 

3. If you do not find the information you need in the Knowledge Base, please contact the company that sold you 

the VASCO product. 

Only after doing these steps, if your problem is not yet solved, please contact VASCO support: 

7.1 Support Contact Information 

E-mail 

support@vasco.com 

Website 

http://www.vasco.com/support/contacts.html 

Phone 

Australia +61 2 8061 3700 (Sydney) 

Belgium +32 2 609 9770 (Brussels) 

Singapore +65 6 232 2727 

USA +1 508 366 3400 (Boston)

Digipass Authentication for Citrix Web Interface Guide - Vasco

Create successful ePaper yourself

Delete template?

Save as template?