VASCO Digipass Authentication for Citrix Web Interface User guide
Advertisement
Advertisement
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
Authentication Server dpauthserver.xml
Digipass Authentication for Citrix
Exchange
Citrix Web Interface
Digipass Authentication for
Citrix Web Interface Guide
Guide
Citrix.msi
the web site
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
Table of Contents
Digipass Authentication for Citrix Web Interface Guide 3
Table of Contents
Digipass Authentication for Citrix Web Interface Guide 4
Table of Contents
Digipass Authentication for Citrix Web Interface Guide 5
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.
1.1.1
Figure 1 – Digipass Authentication for Citrix Overview
Authentication Methods
See the Product Guide for the authentication server for detailed information on login methods and options.
Digipass Authentication for Citrix Web Interface Guide 6
Digipass Authentication for Citrix Web Interface Overview
1.1.2
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.
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.
Digipass Authentication for Citrix Web Interface Guide 7
Digipass Authentication for Citrix Web Interface Overview
1.1.2.2
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.
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.
Digipass Authentication for Citrix Web Interface Guide 8
1.1.3
Digipass Authentication for Citrix Web Interface Overview
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 I IS
Module in manuals for Forms Authentication , unless the text is referring specifically to the I IS 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.
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 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:
Digipass Authentication for Citrix Web Interface Guide 9
1.1.4
1.1.5
Digipass Authentication for Citrix Web Interface Overview
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
Password Change
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.
Tracing
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]
Digipass Authentication for Citrix Web Interface Guide 10
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 6 Module will require permissions for the directory in which the tracing file is kept. See
for more information.
Digipass Authentication for Citrix Web Interface Guide 11
Installation
2 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
Digipass Authentication for Citrix Web Interface is not supported on 64-bit operating systems.
2.2
Pre-Installation Tasks
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.
Digipass Authentication for Citrix Web Interface Guide 12
2.2.1
Installation
Install Authentication Server
An Authentication Server must be installed on the network before the IIS 6 Module is installed. See
for compatible servers and 3.5
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.2.2
2.2.3
2.2.4
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.
Information Needed
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).
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.
Digipass Authentication for Citrix Web Interface Guide 13
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.
Installation
2.
Click Next.
Digipass Authentication for Citrix Web Interface Guide 14
The
License Agreement screen will be displayed.
Installation
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.
Digipass Authentication for Citrix Web Interface Guide 15
Installation
5.
Click Install to install the Digipass Authentication for Citrix Web Interface .
The files will be installed to the directory you specified.
Digipass Authentication for Citrix Web Interface Guide 16
Installation
6.
To finish the install click
Finish
Digipass Authentication for Citrix Web Interface Guide 17
Installation
On exit, the installer launches the Digipass Authentication for Citrix Web Interface Wizard.
Digipass Authentication for Citrix Web Interface Guide 18
2.4
Digipass Authentication for Citrix Web Interface Wizard
Installation
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.
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 .
4.
Click
Next
.
The Wizard will attempt to connect to the Authentication Server using the IP address and port provided.
Digipass Authentication for Citrix Web Interface Guide 19
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.
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.
6.
Click Next .
Digipass Authentication for Citrix Web Interface Guide 20
Installation
7.
Select one of the two option buttons.
Create Component record manually
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
b.
Click on
Next.
c.
Continue with the following steps.
8.
Enter your login details:
Active Directory
Digipass Authentication for Citrix Web Interface Guide 21
Installation a.
Enter the User ID and password for the Domain Administrator.
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.
Digipass Authentication for Citrix Web Interface Guide 22
ODBC-Compliant Database
Installation 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
b.
Click on Next.
Digipass Authentication for Citrix Web Interface Guide 23
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.
Digipass Authentication for Citrix Web Interface Guide 24
Configuration
3 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 < IIS 6 Module install directory>\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.
Digipass Authentication for Citrix Web Interface Guide 25
3.1.1
Enable/Disable the IIS 6 Module
Configuration
3.1.2
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.
Authentication Server Details
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.
3.1.2.1
Add a Server
1.
Click on the Add button.
The New Server window will be displayed.
Digipass Authentication for Citrix Web Interface Guide 26
Configuration
3.1.2.2
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
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.
Modify Server Details
1.
Select the Server to be edited.
2.
Click on the Edit button.
The Edit Server window will be displayed.
Digipass Authentication for Citrix Web Interface Guide 27
Configuration
3.1.2.3
3.
Make required changes.
4.
Click on the OK button.
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.
Digipass Authentication for Citrix Web Interface Guide 28
Configuration
3.1.2.4
Modify Connection Settings
Reconnect Interval
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.
2.
Click on the Apply button.
Digipass Authentication for Citrix Web Interface Guide 29
3.1.3
Configuration
Load Sharing
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.
2.
Click on the Apply button.
Turn Tracing On or Off
1.
Select a Tracing option. See 1.1.5
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.
Click on the Apply button.
Digipass Authentication for Citrix Web Interface Guide 30
Configuration
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
Trace File Directory for more information.
3.1.4
Sites
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.
Digipass Authentication for Citrix Web Interface Guide 31
2.
Select the Site and click on the Edit button.
The Edit Site window will be displayed.
Configuration
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.
Digipass Authentication for Citrix Web Interface Guide 32
Configuration
Modify the Base URL if required.
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
3.1.4.2
12.
Enter the location of the Challenge/Response template.
13.
Click on OK.
Modify Change Password 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.
Digipass Authentication for Citrix Web Interface Guide 33
Configuration
3.1.4.3
3.
Click on the Change Password tab.
4.
Tick the Enabled checkbox to allow the IIS 6 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,Password, New
Password and Confirm Password are entered into the relevant fields.
8.
Click on OK .
Modify 1-Step Challenge/Response Login Page Details
1.
Click on the Authentication tab.
2.
Select the Site and click on the Edit button.
Digipass Authentication for Citrix Web Interface Guide 34
The Edit Site window will be displayed.
3.
Click on the One Step C/R tab.
Configuration
3.1.4.4
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.
1.
Click on the + button.
Digipass Authentication for Citrix Web Interface Guide 35
The Add Login Query String Parameter window will be displayed.
Configuration
3.1.4.5
2.
Enter the new parameter, exactly as it will appear in the query string – eg. page=login
3.
Click on OK.
4.
Repeat the process for other query string parameters
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.
4.
Click on OK.
Digipass Authentication for Citrix Web Interface Guide 36
Configuration
3.1.4.6
3.1.4.7
Delete a Query String Parameter
1.
Select a query string parameter from the list.
2.
Click on the button.
A confirmation window will be displayed.
3.
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.
1.
Click on the + button.
The Add Failed Login Session Variable window will be displayed.
3.1.4.8
2.
Enter the name of the query string parameter.
3.
Click on OK.
Repeat the process for other query string parameters to be included in the failed login URL.
Edit a Session Variable
1.
Select a session variable from the list.
2.
Click on the button.
The Edit Failed Login Session Variable window will be displayed.
Digipass Authentication for Citrix Web Interface Guide 37
3.1.4.9
3.
Modify the name of the query string parameter.
4.
Click on OK.
Remove a Session Variable
1.
Select a query string parameter from the session variable list.
2.
Click on the button.
A confirmation window will be displayed.
3.
Click on Yes to remove the query string parameter from the list.
3.1.4.10
Delete Site Record
1.
Click on the
Authentication tab.
2.
Select the site name from the Sites list.
3.
Click on the Delete button.
A confirmation window will be displayed.
4.
Click on OK to delete the site record.
Configuration
Digipass Authentication for Citrix Web Interface Guide 38
Configuration
3.2
Configuration File
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
<VASCO>
<Revision type="unsigned" data="2"/>
<Enabled type="unsigned" data="1"/>
<Default-Component-Type type="string" data="Citrix Web Interface"/>
<Tracing>
<Trace-Header type="unsigned" data="15"/>
<Trace-Mask type="unsigned" data="0x00000000"/>
<Trace-File type="string" data="C:\Program Files\VASCO\Digipass Authentication for
Citrix Web Interface\Log\ dpextcfg.trace"/>
</Tracing>
<Sites>
<Site0>
<Component-Type type="string" data="Citrix Web Interface"/>
<Name type="string" data="Citrix Web Interface 4.x"/>
<Login>
<Match-URL>
<URL type="string" data="/Citrix/MetaFrame/auth/login.aspx"/>
</Match-URL>
<Failed-URL>
<URLtype="string"data="/Citrix/MetaFrame/auth/login.aspx?NFuse_MessageType=Error&
NFuse_MessageKey=InvalidCredentials&NFuse_LogEventID="/>
</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\ change_password\challenge_template.html"/>
<Submit-Encoding type="string" data="UTF-8"/>
</Login>
<ChgPasswd>
<Enabled type="bool" data="false"/>
<Match-URL>
<URL type="string" data="/Citrix/MetaFrame/auth/changepassword.aspx"/>
Digipass Authentication for Citrix Web Interface Guide 39
Configuration
</Match-URL>
<User-Field type="string" data="dp_user"/>
<Password-Field type="string" data="password"/>
<NewPassword-Field type="string" data="passwordNew"/>
<PasswordConf-Field type="string" data="passwordConfirm"/>
<Submit-Encoding type="string" data="UTF-8"/>
</ChgPasswd>
<One-Step-CR>
<Enabled type="bool" data="false"/>
<Match-URL>
<URL type="string" data="/Citrix/MetaFrame/auth/login.aspx"/>
</Match-URL>
</One-Step-CR>
</Site0>
</Sites>
<AAL3>
<SEAL>
<Local-Address type="string" data="10.2.10.140"/>
<Connection-List>
<Connection00>
<Address type="string" data="10.2.10.120"/>
<Port type="unsigned" data="20003"/>
<Server-Type type="string" data="primary"/>
<Nr-Connections type="unsigned" data="10"/>
</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.
Digipass Authentication for Citrix Web Interface Guide 40
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
Revision
Enabled
Default-Component-Type
Local-Address
Trace/Trace-Header
1
1
Citrix Web Interface
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.
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 to specify when connecting to an
Authentication Server.
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.
31 The tracing header fields that have been enabled. This is a bitmask constructed by adding the following values:
1
2
4
Enable the Date field
Enable the Time field
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
Trace/Trace-File
Digipass Authentication for Citrix Web Interface Guide
<installation directory>\ eg. for DATE,TIME,LEVEL = 1 + 2 + 4 = 7
A value of 0 will result in no header being added to the trace output.
Hexadecimal or decimal values:
Hex
0x00000000
Decimal
0 No tracing
0x0010000E 1048590
0xFFFFFFFF 4294967295
Configuration and error messages only
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
41
Configuration
Option Name Default Value Notes
Local-Address
Log\dpextcfg.trace
127.0.0.1
Connection-List/Load-
Balancing
Connection-List/ Connection
<number>/ Name
False
<blank>
Connection-List/ Connection
<number>/ Address
Connection-List/
Connection<number>/ Port
Connection-List/
Connection<number>/
Server-Type
IP Address entered during installation.
20003 (default) or
Port number entered during installation.
Primary
Connection-List/ Connection
<number>/
Nr-Connections
10
Connection-List/ Connection
<number>/Min-Reconnect-
Interval
30
IIS6 module if it does not exist.
If this option is blank, the IIS 6 Module will not output tracing.
The local IP address to be used when connecting to Authentication
Servers.
Whether load balancing is enabled for connections to Authentication
Servers.
Text to display in the Servers list on the Configuration.
IP Address of the Authentication Server.
Port to use in connecting to the Authentication Server
Either
Primary or Backup Authentication Server. This setting affects load-balancing.
The maximum number of concurrent connections which the IIS 6
Module may hold open to the Authentication Server.
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.
Connection-List/ Connection
<number>/Max-Reconnect-
Interval
Attribute-Group
300
<blank>
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.
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<number>/ Name Citrix Web Interface 4.x Text to display in the Sites list on the Configuration GUI.
Sites/Site<number>/
Component-Type
Sites/Site<number>/
Login/Match-URL/URL
Citrix Web Interface
/citrix/metaframe/auth
/login.aspx
(CWI 4.0 - 4.5)
Component type to specify when connecting to an Authentication
Server for this Site.
The base URL to use in submitting a login
Digipass Authentication for Citrix Web Interface Guide 42
Configuration
Option Name Default Value
OR
/citrix/AccessPlatform/a uth /login.aspx
(CWI 4.6)
Notes
Sites/Site<number>/
Login/Match-URL/
Param<number>
Sites/Site<number>/
Login/Failed-URL/URL
Sites/Site<number>/
Login/User-Field
Sites/Site<number>/
Login/Password-Field
Sites/Site<number>/
Login/Domain-Field
<blank> password domain
Query string parameter needed in the URL.
/citrix/metaframe/auth
/login.aspx?Nfuse_Mes
sageType=Error&
Nfuse_MessageKey=In validCredentials&N fuse_LogEventID=
(CWI 4.0 - 4.5)
OR
/citrix/AccessPlatform/a 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.
Name of the field that corresponds to Password.
Name of the field that corresponds to Domain
Sites/Site<number>/
Login/Challenge-Template
Sites/Site<number>/
Login/Error-Message
<install directory>\ change_password\chall enge_template.html false
Location and file name of the template to use in creating a
Challenge/Response page
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.
The base URL used in changing a User’s password. Sites/Site<number>/
ChgPasswd/Match-URL/URL
/citrix/metaframe/auth
/changepassword.aspx
(CWI 4.0 - 4.5)
OR
/citrix/AccessPlatform/ auth
Digipass Authentication for Citrix Web Interface Guide 43
Configuration
Option Name Default Value
/changepassword.aspx
(CWI 4.6)
Notes
Sites/Site<number>/
ChgPasswd/ Match-
URL/Param<number>
Sites/Site<number>/
ChgPasswd/Enabled
Sites/Site<number>/
ChgPasswd/ User-Field
<blank>
0 dp_user
Sites/Site<number>/
ChgPasswd/ Password-Field password
Sites/Site<number>/
ChgPasswd/ NewPassword-
Field passwordNew
Sites/Site<number>/
ChgPasswd/ PasswordConf-
Field
Sites/Site<number>/ One-
Step-CR/Match-URL/URL passwordConfirm
/citrix/metaframe/auth/l ogin.aspx
(CWI 4.0 - 4.5)
OR
/citrix/AccessPlatform/a uth/login.aspx
(CWI 4.6)
Query string parameter needed in the URL.
Whether the IIS 6 Module will capture password changes.
Name of the field that corresponds to User.
Name of the field that corresponds to Password.
Name of the field that corresponds to New Password.
Name of the field that corresponds to Confirm New Password.
The base URL to use in making a one-step challenge/response login request.
Query string parameter needed in the URL. Sites/ Site<number>/ One-
Step-CR/ Match-URL/
Param<number>
Sites/ Site<number>/ One-
Step-CR/ Enabled
<blank>
0 Whether one-step challenge/response logins are enabled.
Digipass Authentication for Citrix Web Interface Guide 44
Configuration
3.2.2
Modify Character Set Used
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
<installation directory>\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
Arabic
Baltic
Central European
Chinese Simplified
Chinese Traditional
Cyrillic
Greek
Hebrew
Japanese
Korean
Thai
Turkish
Vietnamese
Western European
ISO code Windows code
ISO-8859-6 CP1256
ISO-8859-4 or ISO-8859-13 CP1257
ISO-8859-2 CP1257
ISO-2022-CN
ISO-8859-2
ISO-8859-7
ISO-8859-8-I
ISO-2022-JP
ISO-2022-KR
ISO-8859-11
ISO-8859-9
ISO-8859-1
CP1251
CP1253
CP1255
CP874
CP1258
CP1252
GB2312
Big5
Other code(s)
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.
Digipass Authentication for Citrix Web Interface Guide 45
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.
Configuration
6.
The Configure Authentication Methods Wizard window will be displayed.
Digipass Authentication for Citrix Web Interface Guide 46
7.
Tick the Explicit checkbox.
8.
Select Disable from the Enforce 2-factor authentication drop down list.
9.
C lick on Next.
Configuration
3.4
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.
Configure Citrix Web Interface 4.5 and Citrix Web Interface 4.6 to work with the
Authentication Server
1.
Open the Access Management Console for Presentation Server.
Digipass Authentication for Citrix Web Interface Guide 47
Configuration
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.
Digipass Authentication for Citrix Web Interface Guide 48
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.
Digipass Authentication for Citrix Web Interface Guide 49
Configuration
3.5
Configure Authentication Server
3.5.1
Component Record
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
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
Digipass Authentication for Citrix Web Interface Guide 50
Configuration
3.5.2.2
rejected, unless a second Digipass User account has been created. This is essential for enabling the change password facility to work.
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 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.
3.5.2.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 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.
Digipass Authentication for Citrix Web Interface Guide 51
Configuration
3.5.3
Policy
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:
3.5.3.1
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.
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 Authentication for Citrix Web Interface Guide 52
Configuration
Digipass 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 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)
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 and Self-Assignment logins through the IIS 6 Module.
Digipass 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.
Digipass Authentication for Citrix Web Interface Guide 53
Configuration
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).
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.
Digipass 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.
Digipass 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 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
Digipass Authentication for Citrix Web Interface Guide 54
Challenge Check Mode:
0
For more information, see the Policies section of the Product Guide.
Configuration
Digipass Authentication for Citrix Web Interface Guide 55
Post-Installation Tasks
4 Post-Installation Tasks
4.1
4.1.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>\change_password\CWI_<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.
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 <citrix> directory is located in <web root>\Citrix\MetaFrame\
(4.0 - 4.5) and <web root>\Citrix\AccessPlatform\ (4.6) in the table below.
Web root is typically c:\inetpub\wwwroot.
Table 3 - Citrix directory and login page variations
Citrix directory
Login page
Citrix Web Interface 4.0
<citrix>\auth loginMainForm.inc
Citrix Web Interface 4.5 and 4.6
<citrix>\app_data\auth loginMainForm.inc
Login page
1.
Backup <citrix directory>\include\<login page> to a suitable place.
2.
Copy modified login page from <install directory>\change_password\CWI_<Citrix version>\<login page> to
<citrix directory>\include\<login page>
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.
Digipass Authentication for Citrix Web Interface Guide 56
Post-Installation Tasks
4.1.1.1
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 <install directory>\change_password\CWI_<Citrix version>\flash.class
to <citrix directory>.
2.
Remove commenting (the greyed-out lines in the example below) for the applet code in the login page <citrix directory>\include\<login page> .
To edit the file, right-click on it and select Edit from the menu.
CWI 4.x
<!-- 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>
-->
3.
Save the file and close.
4.
Using the IIS Management Console, check that permissions for the <citrix directory>\flash.class file allow read access.
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
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.
Digipass Authentication for Citrix Web Interface Guide 57
Post-Installation Tasks
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>\change_password\CWI_<Citrix version>\ directory during installation.
CWI 4.x
<!-- 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>
</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 %>
Digipass Authentication for Citrix Web Interface Guide 58
Post-Installation Tasks
4.1.1.2
</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.2
4.2.1
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 <install directory>\change_password\CWI_<citrix version>\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.
Replace Default Files - Citrix Web Interface 4.0
The <citrix directory> is located in <web root>\Citrix\MetaFrame\auth .
Web root is typically located in c:\inetpub\wwwroot .
1.
Backup <citrix directory>\include\changepassword.inc
and <citrix directory>\ serverscripts\login.cs
to a suitable place.
2.
Copy changepassword.inc from <install directory>\change_password\CWI_<citrix version> to <citrix directory>\include .
Digipass Authentication for Citrix Web Interface Guide 59
Post-Installation Tasks
4.2.2
4.2.3
4.2.4
3.
Copy login.cs from <install directory>\change_password\v<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 Modify Change Password Page Details topic in the IIS 6 Module Configuration GUI section for more information.
Replace Default Files - Citrix Web Interface 4.5
The <citrix directory> is located in <web root>\Citrix\MetaFrame\app_data\auth .
Web root is typically c:\inetpub\wwwroot .
1.
Backup <citrix directory>\include\changepassword.inc and <citrix directory>\ serverscripts\login.aspxf to a suitable place.
2.
Copy changepassword.inc from <install directory>\change_password\CWI_<citrix version> to <citrix directory>\include .
3.
Copy login.aspxf from <install directory>\change_password\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 Modify Change Password Page Details topic in the IIS 6 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 .
1.
Backup <citrix directory>\include\changepassword.inc
and <citrix directory>\ serverscripts\login.aspxf to a suitable place.
2.
Copy changepassword.inc from <install directory>\change_password\CWI_<citrix version> to <citrix directory>\include .
3.
Copy login.aspxf from <install directory>\change_password\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 Modify Change Password Page Details topic in the IIS 6 Module Configuration GUI section for more information.
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.
Digipass Authentication for Citrix Web Interface Guide 60
Post-Installation Tasks
4.2.5
4.3
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 <install directory>\change_password\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 -->
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:
if (credentials != null && !bIsError()) {
Code
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
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.
Digipass Authentication for Citrix Web Interface Guide 61
4.3.1
Post-Installation Tasks
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 <citrix directory> is located in <web root>\Citrix\MetaFrame\auth .
Web root is typically located in c:\inetpub\wwwroot .
1.
Backup <citrix directory>\include\messagecenter.inc
and <citrix directory>\ clientscripts\login.js
to a suitable place.
2.
Copy messagecenter.inc
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\include .
3.
Copy login.js
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\clientscripts .
4.
Enable
Return Failure Reason (see Modify Login Page Details).
Citrix Web Interface 4.5
The <citrix directory> is located in <web root>\Citrix\MetaFrame .
Web root is typically located in c:\inetpub\wwwroot .
1.
Backup <citrix directory>\app_data\auth\include\messagecenter.inc
and <citrix directory>\auth\clientscripts\login.js
to a suitable place.
2.
Copy messagecenter.inc
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\app_data\auth\include .
3.
Copy login.js
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\auth\clientscripts .
4.
Enable Return Failure Reason (see 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 .
1.
Backup <citrix directory>\app_data\auth\include\messagecenter.inc
and <citrix directory>\auth\clientscripts\login .js to a suitable place.
2.
Copy messagecenter.inc
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\app_data\auth\include .
3.
Copy login.js
from <install directory>\fail_reason\v-<citrix version> to <citrix directory>\auth\clientscripts .
4.
Enable Return Failure Reason (see Modify Login Page Details).
Digipass Authentication for Citrix Web Interface Guide 62
4.3.2
Post-Installation Tasks
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
<%
// 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
Digipass Authentication for Citrix Web Interface Guide 63
4.4
4.5
Post-Installation Tasks
Create 2-Step Challenge/Response Template
The example challenge-template.html is found in the <install directory>\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
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 <install directory>\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 ).
Digipass Authentication for Citrix Web Interface Guide 64
Troubleshooting
5 Troubleshooting
5.1
5.1.1
IIS 6 Module Installation Problems
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.
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.
<install directory>
version.txt
<install directory>\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
Digipass Authentication for Citrix Web Interface Guide 65
citrixwiz.exe
<install directory>\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
<install directory>\change_password\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>\change_password\CWI_4_6
changepassword.inc
default.htm
login.aspxf
login.js
loginMainForm.inc
Messagecenter.inc
Digipass Authentication for Citrix Web Interface Guide
Troubleshooting
66
5.1.2
README_challenge.inc
README_chpwd.inc
README_failreason.inc
<install directory>\fail_reason
messagecenter.inc
login.js
Check Permissions
Troubleshooting
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 <install directory>\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 ( <install directory>\log by default ).
2.
Right-click on the relevant directory.
3.
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 Add the IIS_WPG Group.
5.1.2.2
Configuration file
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.
Digipass Authentication for Citrix Web Interface Guide 67
Troubleshooting
5.1.2.3
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
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.
1.
Click on the Add… button.
The Select Users, Computers, or Groups window will be displayed.
2.
Click on the Advanced… button.
Digipass Authentication for Citrix Web Interface Guide 68
3.
Enter search criteria (see example below) and click on the Find Now button.
Troubleshooting
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.
Digipass Authentication for Citrix Web Interface Guide 69
5.1.3
Set System Environment Variable
1.
Right-click on My Computer.
2.
Click on Properties .
Troubleshooting
Digipass Authentication for Citrix Web Interface Guide 70
3.
The System Properties window will be displayed.
Troubleshooting
Click on the Advanced tab.
4.
Click on the Environment Variables button.
The Environment Variables window will be displayed.
Digipass Authentication for Citrix Web Interface Guide 71
Troubleshooting
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: <IIS 6 Module installation path>
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.
Digipass Authentication for Citrix Web Interface Guide 72
Troubleshooting
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 <install-dir>\bin directory at install time.
1.
Open up a DOS command prompt and navigate to the <install-dir>\bin directory
5.1.3.2
5.1.3.3
2.
Enter cscript add-ext.vbs
and press enter.
3.
Your new IIS 6 Module Extension will be registered by the script.
Remove IIS 6 Module Extension
Run the following script to remove the IIS 6 Module Extension. The script is installed in the <install-dir>\bin directory at install time.
1.
Open up a DOS command prompt and navigate to the <install-dir>\bin directory
2.
Enter cscript rem-ext.vbs
and press enter.
3.
Your IIS 6 Module Extension will now be removed.
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.
Digipass Authentication for Citrix Web Interface Guide 73
Troubleshooting
The
Computer Management window will be displayed
3.
Expand the Services and Applications heading.
Digipass Authentication for Citrix Web Interface Guide 74
4.
Expand the Internet Information Services heading
Troubleshooting
Digipass Authentication for Citrix Web Interface Guide 75
5.
Click on Web Services Extensions.
The Web Service Extensions window will be displayed.
Troubleshooting
Digipass Authentication for Citrix Web Interface Guide 76
5.1.4
Register as Wildcard Application Mapping
Troubleshooting
1.
Right-click on
My Computer
2.
Click on
Manage.
The Computer Management window will be displayed.
For Citrix 4.0 – 4.5
Digipass Authentication for Citrix Web Interface Guide 77
Troubleshooting
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.
Digipass Authentication for Citrix Web Interface Guide 78
Troubleshooting
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:
Digipass Authentication for Citrix Web Interface Guide 79
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).
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.
Digipass Authentication for Citrix Web Interface Guide 80
Troubleshooting
5.2
5.2.1
5.2.2
5.2.3
5.2.4
Other Troubleshooting Options
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.
No Trace File
If there is no trace file, or the trace file information does not help, first check that the ISAPI extension has been registered (see
Register IIS 6 Module Extension
for instructions) and the wildcard application mapping is set (see
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.
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.
Authentication Server
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.
Licensing
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.
Digipass Authentication for Citrix Web Interface Guide 81
Troubleshooting
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.
Digipass Authentication for Citrix Web Interface Guide 82
Uninstalling the IIS 6 Module
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.
The Uninstallation Progress screen will be displayed, showing the progress of your uninstall.
7.
After uninstallation, the system must be restarted.
Digipass Authentication for Citrix Web Interface Guide 83
Technical Support
7 Technical Support
If you encounter problems with a VASCO product please do the following:
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
Website
http://www.vasco.com/support/contacts.html
Phone
Australia
Belgium
+61 2 8061 3700 (Sydney)
+32 2 609 9770 (Brussels)
Singapore
USA
+65 6 232 2727
+1 508 366 3400 (Boston)
Digipass Authentication for Citrix Web Interface Guide 84
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement