Digipass Authentication
For IIS Basic
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.
Table of Contents
Table of Contents
1
Digipass Authentication for IIS Overview... 6
1.1 IIS 6 Module - Basic Authentication...6
1.1.1 IIS Module Terminology...6
1.1.2 Authentication Methods...7
1.1.3 Server Connection Management...8
1.1.3.1 Connection Profiles... 8
1.1.3.2 Connection Options... 8
1.1.3.3 Standard Server setup...9
1.1.4 Tracing...9
1.2 Basic Authentication Credentials...11
1.2.1 User ID and Password Replacement Scenarios...11
1.2.1.1 Authorization using Domain Windows User Accounts...11
1.2.1.2 Authorization using Local Windows User Accounts, Login using Domain Windows User Accounts...12
1.2.1.3 Authorization from Local Windows User Accounts, Login using Digipass User Accounts...13
1.2.2 Configuration Settings...15
1.2.3 Digipass User Attribute Settings...16
2
Installation... 18
2.1 System Requirements...18
2.1.1 Software...18
2.2 Pre-Installation Tasks...18
2.2.1 Install Authentication Server ...18
2.2.2 IIS...19
2.2.3 Information Needed...19
2.2.4 Licensing...19
2.3 Install Digipass Authentication for IIS Basic...20
2.4 Digipass Authentication for IIS Basic Wizard...25
3
Configuration... 31
3.1.6 Basic Authentication Credential Overrides...38
3.1.7 Failed Login Page...38
3.1.8 Realm...38
3.1.9 Authentication Headers...39
3.2 Configuration File...40
3.2.1 Configuration Settings...42
3.2.2 Modify Character Set Used...45
3.3 Configuring IIS to work with the IIS 6 Module...46
3.3.1 Secure Areas...46
3.3.2 Public Areas...49
3.4 Configure Authentication Server...51
3.4.1 Component Record...51
3.4.2 Configure for Windows User Accounts...51
3.4.2.1 Windows User Name Resolution...51
3.4.2.2 Case Sensitivity...52
3.4.2.3 Default Domain... 52
3.4.3 Policy...53
3.4.3.1 Windows Domain Login with Password Replacement...53
3.4.3.2 Windows Domain Login without Password Replacement...54
3.4.3.3 Local Authentication Only... 55
4
Post-Installation Tasks... 56
4.1 Login Failure Page...56
5
Troubleshooting... 57
5.1 IIS 6 Module Installation Problems...57
5.1.1 Check file placement...57
5.1.2 Check Permissions...58
5.1.2.1 Trace File Directory... 58
5.1.2.2 Configuration file...59
5.1.2.3 Add the IIS_WPG Group...59
5.1.3 Set System Environment Variable...61
5.1.4 Install the ISAPI Filter...64
5.2 Other Troubleshooting Options...66
5.2.1 No Trace File...66
5.2.2 Information from Trace File...66
5.2.3 Authentication Server...66
5.2.4 Licensing...66
5.3 Repair Installation...67
6
Uninstalling the Digipass Authentication for IIS ... 68
Table of Contents
7
Technical Support... 69
1
Digipass Authentication for IIS Overview
1.1
IIS 6 Module - Basic Authentication
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 the HTTP Basic Authentication mechanism 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 filter specifically designed for use with IIS 6 only.
Figure 1 – Digipass Authentication for IIS Overview
1.1.1
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.
Digipass Authentication for IIS Overview
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.
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.
Response Only login
Users log in via the current login page with their username and One Time Password (OTP).
Virtual Digipass login
Users logging in with a Virtual Digipass need to use a 2-step process. They attempt a login with their User ID, password and/or a keyword (as required by VACMAN Middleware). The login fails, and triggers the sending of an One Time Password to the User’s mobile via text message. The User re-attempts a login, using their password and OTP.
Challenge/Response logins are not supported for basic authentication.
1.1.3
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.3.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 Authentication Server can be re-established.
1.1.3.2 Connection Options
Terminology
Maximum Connections
The maximum number of connections that the IIS 6 Module may have open to the Authentication Server at one time.
Timeout
Digipass Authentication for IIS Overview 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.
1.1.3.3 Standard Server setup
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 Authentication Server is busy or unavailable.
1.1.4
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.
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
Digipass Authentication for IIS Overview
1.2
Basic Authentication Credentials
There are two types of authentication credential modification which may be performed by the IIS 6 Module.
Stored Password Proxy
The standard Stored Password Proxy replaces an OTP entered by the User with the Stored Static Password from the Digipass User account for back-end system authentication checks by the Authentication Server. However, if the User enters a static password in front of their OTP, the static password they enter will take precedence over Stored Static Password. In that case, the Stored Static Password will not be used at all for that login.
User Attribute Replacement
A different User ID and/or password may be set for individual Digipass User accounts. Typically, this would be used where a small number of local Windows accounts are used for authorization by a web site. The IIS 6 Module will replace the User ID and/or password entered during login with User attributes.
1.2.1
User ID and Password Replacement Scenarios
1.2.1.1 Authorization using Domain Windows User Accounts
In this scenario, Domain Windows User accounts are used for authentication and authorization with Active Directory. Typically, the Authentication Server's password replacement would be used to allow a User to log in using an OTP only, with their Windows password stored in the Authentication Server and passed back to the IIS 6 Module. Alternatively, a User may be required to enter their password and OTP at every login.
This approach requires the web server to be linked to Active Directory.
The Authentication Server checks the One Time Password. If correct, the Authentication Server sends the Windows password back to the IIS 6 Module.
The IIS 6 Module replaces the OTP entered by the User in the User's basic authentication credentials with the Windows password.
The web site authorizes access according to permissions set for Domain user accounts.
'Authentication Server Password Replacement' Configuration Settings
The 'Authentication Server password replacement' option requires the following settings in the Authentication Server:
It is recommended that Windows User Name Resolution enabled (ODBC databases only, including the embedded PostgreSQL database) on Windows platforms
Password Autolearn and Stored Password Proxy enabled Windows Back-End Authentication enabled
'No Authentication Server Password Replacement' Configuration Settings
The 'No Authentication Server password replacement' option requires the following settings in the Authentication Server:
It is recommended that Windows User Name Resolution is enabled (ODBC databases only, including the embedded PostgreSQL database) on Windows platforms
Password Autolearn and Stored Password Proxy disabled
Windows Back-End Authentication disabled for Windows platforms, or Microsoft Active Directory back-end Authentication for aXs GUARD
It will also require each User enter their password in front of their OTP during login.
1.2.1.2 Authorization using Local Windows User Accounts, Login using Domain Windows User Accounts
In this scenario, Domain Windows User accounts are used for authentication and local Windows User accounts are used for authorization. The Domain must be an Active Directory domain. Typically, Windows Back-End Authentication would be used with Dynamic User Registration enabled. Password Autolearn and Stored Password Proxy are not required.
This approach removes the need for the web server to be linked to Active Directory, while retaining authentication of Active Directory accounts. It allows authorization permissions to be set according to 'user profiles' if individual authorization is not required.
Digipass Authentication for IIS Overview
The Authentication Server checks the OTP. If correct, the Authentication Server looks up the User-Name and Password attributes for the Digipass User account and returns them to the Authentication Server.
User attributes for a Digipass User may be viewed or edited via the Authorization Profiles/Attributes button on the Digipass User property sheet for VACMAN Middleware, or on the User tab of the Webadmin application for Identikey Server or aXs GUARD.
The web site authorizes access according to permissions set for local accounts, using the User-Name and Password attributes passed back from the Authentication Server. You might create only a few local accounts - one per authorization profile required - or a local account for each User.
This requires the following settings in the Authentication Server:
The Authentication Server checks the OTP. If correct, the Authentication Server looks up the User-Name and Password attributes for the Digipass User account and returns them to the IIS 6 Module.
User attributes for a Digipass User may be viewed or edited via the Authorization Profiles/Attributes button on the Digipass User property sheet for VACMAN Middleware, or on the User tab of the Webadmin application for Identikey Server or aXs GUARD.
The web site authorizes access according to permissions set for local accounts, using the User-Name and Password attributes passed back from the Authentication Server. You might create only a few local accounts - one per authorization profile required - or a local account for each User.
This requires the following settings in the Authentication Server: User attributes set for each Digipass User account.
Note
If the Digipass User account's User ID will be the same as the local Windows account User ID, there is no need to set the User-Name attribute.
Digipass Authentication for IIS Overview
1.2.2
Configuration Settings
Image 1: User Attribute Configuration Settings
Three User attribute settings are available in the IIS 6 Module Configuration.
Replace User Name with User Attribute
This enables or disables the replacement of the User ID entered during login with a User attribute named User-Name. There are three possible results:
Setting enabled and User attribute set - the User ID set in the attributes for the relevant Digipass User account will be passed to the web site.
Setting enabled and User attribute not set - the User ID entered during login will be passed to the web site. Setting disabled - the User ID entered during login will be passed to the web site.
Replace Password with User Attribute
This enables or disables the replacement of the password entered during login with a User attribute named Password. There are three possible results:
Setting enabled and User attribute set - the password set in the attributes for the relevant Digipass User account will be passed to the web site.
Setting enabled and User attribute not set - the password entered during login will be passed to the web site. Setting disabled - the password entered during login will be passed to the web site
Note
1.2.3
Digipass User Attribute Settings
Any User attributes to be used by the IIS 6 Module will need these settings:
Attribute Group
The value in this field must be identical to the value set in the IIS 6 Module Configuration.
Name
The Name for a User attribute should be either User-Name or Password.
Usage
The Usage should be set to Basic.
Value
The Value set for an attribute will be the alternate User ID or password.
Digipass Authentication for IIS Overview
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
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 (32- or 64-bit)
The User must have administration rights on the installation machine.
Note
If the web site is not in Basic Authentication mode, this IIS Module will not function.
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 IIS Basic cannot be installed on the same machine as any other Digipass Authentication packages.
2.2.1
Install Authentication Server
An Authentication Server must be installed on the network before the IIS 6 Module is installed. See 2.1 System
Installation
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
IIS
Ensure IIS and the OWA are installed and working correctly. The OWA must be installed on the IIS server where the web server is running.
2.2.3
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).
2.2.4
Licensing
The Authentication Server will regard each incoming IP address as a different Client Component. This is the reason for selecting a single IP address in connecting to the Authentication Server if there is more than one IP address for a machine.
2.3
Install Digipass Authentication for IIS Basic
1. Start the ‘Digipass Authentication for IIS Basic’ installation process.
If you are not using the CD Autorun interface, locate and double-click on the Digipass_Auth_for_IIS_basic_320.msi file.
Installation
3. Tick the box marked 'I accept the terms in the License Agreement'.
5. Enter the destination folder for the module.
Installation
7. Click Install to install the Digipass Authentication for IIS Basic. The files will be installed to the directory you specified.
8. To finish the install click Finish.
Installation
2.4
Digipass Authentication for IIS Basic Wizard
Note
For a definition of the term Authentication Server, please see 1.1.1IIS 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 compliant or embedded database. If using the embedded PostgreSQL database, select
ODBC-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.
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.
Installation
b. Click on Next.
c. Continue with the following steps.
8. Enter your login details:
Active Directory
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.
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
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 OWA 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.
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 IIS Basic 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 Configuration Wizard was last run.
3.1.1
Enable/Disable the IIS 6 Module
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
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.
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.3 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.
3. Make required changes.
4. Click on the OK button.
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.
Configuration
3.1.2.4 Modify Connection Settings
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.
3.1.3
Turn Tracing On or Off
1. Select a Tracing option. See 1.1.4 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. Click on the Apply button.
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
3.1.4
Component Type
The Component Type is used when connecting to an Authentication Server, to assist in finding the correct Component record.
Caution
If a static password was used in the login (rather than an OTP), the session may not appear to timeout, as both browser and IIS can cache and automatically replay a password to reconnect. However if an OTP was used in the login, the session will timeout as expected, as the OTP cannot be reused.
1. Click on the Authentication tab.
2. Enter a value in the Timeout field.
3. Click on the Apply button.
3.1.6
Basic Authentication Credential Overrides
The IIS 6 Module may be configured to substitute a User Attribute for the User ID or password entered during login. These Attributes are taken from the Digipass User account.
1. Tick the Replace User Name with User Attribute checkbox to replace each User ID with a User Attribute. If unticked, each User ID will be left unmodified.
2. Tick the Replace Password with User Attribute checkbox to replace each User's password with a User Attribute.
3. Enter the Attribute Group name to use.
3.1.7
Failed Login Page
This option allows you to specify a HTML page which will be presented to a User if their login is rejected by the IIS 6 Module.
Note
The browser used for the login attempt may either display the page immediately or pop up the login dialog. If the login dialog is popped up, clicking on the Cancel button will cause the failed login page to be displayed.
1. Click on the Authentication tab.
2. Enter the file location and name in the HTML File field or browse to the correct file.
3. Click on the Apply button.
3.1.8
Realm
If the Realm property is set in IIS, its value will appear in a standard Basic Authentication logon dialog box when IIS requests User login details. When the IIS 6 Module needs to request User login details, it needs the Realm value in order to conform to IIS. As the IIS configuration cannot be read by the IIS 6 Module, the Realm value must also be configured here.
Configuration
1. Click on the Authentication tab.
2. Enter the Realm name.
3. Click on the Apply button.
3.1.9
Authentication Headers
This is an advanced option which should only be enabled on advice from Technical Support, as it may slow down authentication processing.
1. Click on the Authentication tab.
2. Tick or untick the Modify Basic Authentication Headers checkbox.
3. Click on the Apply button.
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="13"/> <Enabled type="unsigned" data="1"/> <Tracing>
<Trace-Header type="unsigned" data="31"/> <Trace-Mask type="unsigned" data="0x00000000"/>
<Trace-File type="string" data="C:\Program Files\VASCO\Digipass Authentication for IIS Basic\Log\dpiis.trace"/> </Tracing>
<Idle-Timeout type="unsigned" data="5"/> <Modify-Auth-Headers type="unsigned" data="0"/> <Component-Type type="string" data="IIS6 Module"/>
<Error-Page type="string" data="c:\windows\Help\iisHelp\common\401-4.htm"/> <Encoding type="string" data="ISO-8859-1"/>
<Realm type="string" data=""/> <Attribute-Group type="string" data=""/>
<Use-Attribute-For-User-Name type="unsigned" data="0"/> <Use-Attribute-For-Password type="unsigned" data="0"/> <AAL3>
<SEAL>
<Local-Address type="string" data="192.168.174.130"/> <Connection-List>
Configuration <Load-Balancing type="bool" data="false"/>
<Connection00>
<Name type="string" data="192.168.174.130"/> <Address type="string" data="192.168.174.130"/> <Port type="unsigned" data="20003"/>
<Server-Type type="string" data="Primary"/> <Nr-Connections type="unsigned" data="10"/> <Min-Reconnect-Interval type="unsigned" data="30"/> <Max-Reconnect-Interval type="unsigned" data="300"/> <Timeout type="unsigned" data="60"/>
</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.
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 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 IIS6 Module Default Component type to specify when connecting to an Authentication Server.
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
eg. for DATE,TIME,LEVEL = 1 + 2 + 4 = 7
A value of 0 will result in no header being added to the trace output.
Trace/Trace-Mask 0x00000000 Hexadecimal or decimal values:
Trace/Trace-File <installation directory>\ Log\dpiis.trace
The absolute path and filename of the file to which internal state tracing will be written. The file but not the path will be created by the IIS6 module if it does not exist.
If this option is blank, the IIS 6 Module will not output tracing.
Hex Decimal
0x00000000 0 No tracing
0x0010000E 1048590 Configuration and error messages only 0xFFFFFFFF 4294967295 All levels enabled.
Configuration
Option Name Default Value Notes
AAL3/SEAL/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.
AAL3/SEAL/Connection-List/Load-Balancing
False Whether load balancing is enabled for connections to Authentication Servers.
AAL3/SEAL/Connection-List/ Connection <number>/ Name
<blank> Text to display in the Servers list on the Configuration.
AAL3/SEAL/Connection-List/ Connection <number>/ Address
127.0.0.1 IP Address of the Authentication Server.
AAL3/SEAL/Connection-List/ Connection<number>/ Port
20003 Port to use in connecting to the Authentication Server for SEAL. AAL3/SEAL/Connection-List/
Connection<number>/ Server-Type
Primary Either Primary or Backup Authentication Server. This setting affects load-balancing.
AAL3/SEAL/Connection-List/ Connection <number>/ Nr-Connections
10 The maximum number of concurrent connections which the IIS 6 Module
may hold open to the Authentication Server. AAL3/SEAL/Connection-List/
Connection <number>/Min-Reconnect-Interval
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.
AAL3/SEAL/Connection-List/ Connection <number>/Max-Reconnect-Interval
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.
Option Name Default Value Notes
Error-Page %WINDIR%\Hel
p\iisHelp\ Common\401-4.html
This option allows you to specify a HTML page which will be presented to a User if their login is rejected by the IIS 6 Module.
Realm <blank> Realm value used in IIS. See 3.1.8 Realm for more information
Encoding ISO-8859-1 The character encoding to use in sending a login request to the
Exchange. This allows the use of international character sets (see 3.2.2 Modify Character Set Used)
Attribute-Group <blank> 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 Exchange server.
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. Use-Attribute-For-Password 0 If this option is enabled, the IIS 6 Module will retrieve a Password
attribute from a Digipass User account. It will replace the password entered during login with the attribute value before passing the request to the Exchange server.
0 Disabled. The password will not be replaced with the User attribute. 1 Enabled. The password will be replaced with the Password User
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 Exchange server.
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 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
3.3
Configuring IIS to work with the IIS 6 Module
3.3.1
Secure Areas
Follow these instructions to secure any areas of your website to which Users should be logged in with an OTP to access.
1. Right-click on My Computer.
2. Click on Manage.
Configuration
3. Expand the Services and Applications heading.
4. Double-click on Web Sites.
5. Find and right-click on the area to be protected.
6. Click on Properties.
The web site Properties window will be displayed.
7. Click on the Directory Security tab.
8. Click on the Edit… button in the Authentication and access control section. The Authentication Methods window will be displayed.
9. Ensure that the Anonymous Access checkbox is unticked.
10. Tick the Basic authentication checkbox.
11. Ensure that the Integrated Windows authentication checkbox is not ticked.
12. If required, enter the Default domain.
13. If required, enter a Realm name.
14. Click on the OK button.
Configuration
3.3.2
Public Areas
Follow these instructions to correctly set up any areas of your website to which Users should be have anonymous access.
1. Return to the Computer Management window.
2. Find and right-click on the area to be protected.
3. Click on Properties.
The web site Properties window will be displayed.
4. Click on the Directory Security tab.
5. Click on the Edit… button in the Authentication and access control section. The Authentication Methods window will be displayed.
10. If required, enter a Realm name.
11. Click on the OK button.
12. Click on the Apply button.
Configuration
3.4
Configure Authentication Server
3.4.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 OWA.
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.4.2
Configure for Windows User Accounts
3.4.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 –
3.4.2.2 Case Sensitivity
Windows User names are not sensitive. If the ODBC database used by the Authentication Server is case-sensitive, 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.4.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.
Configuration
3.4.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) This Policy is configured with the following settings:
Note
These settings are all available on Windows but are not all available on Identikey Server on Linux or the aXs GUARD Identifier.
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.
If you need different settings, either select a different Policy (eg. Self-Assignment or Auto-Assignment) for the IIS 6 Module 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.4.3.1 Windows Domain Login with Password Replacement
These settings are typically used where the scenario described in 1.2.1.1 Authorization using Domain Windows
User Accounts is in place.
Back-End Authentication
Stored Password Proxy: Enabled
These settings allow the Authentication Server to create an account for an unrecognized User based on a successful Active Directory authentication. The Authentication Server can then store the User’s Windows 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).
3.4.3.2 Windows Domain Login without Password Replacement
These settings are typically used where:
The web site retrieves authorization information from Active Directory Domain User accounts, and the
Password Replacement model is not being used - Password Autolearn and Stored Password Proxy are disabled (see 1.2.1.1 Authorization using Domain Windows User Accounts ).
The Authentication Server checks authentication details against Active Directory Domain User accounts only for DUR and Self-Assignment logins (see 1.2.1.2 Authorization using Local Windows User Accounts, Login using
Domain Windows User Accounts).
Back-End Authentication
Back-End Authentication: If Needed
Back-End Protocol: Windows or Active Directory
These settings allow the Authentication Server to check user login details with 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 Active Directory authentication. The Authentication Server will not store or replay a User’s Active Directory password.
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).
3.4.3.3 Local Authentication Only
These settings are typically used where:
the Authentication Server does not check authentication details against Windows accounts (see 1.2.1.3 Authorization from Local Windows User Accounts, Login using Digipass User Accounts above ).
Back-End Authentication
Back-End Authentication: None
The Authentication Server will not check user login details with Active Directory.
Digipass User Account Handling
Dynamic User Registration: Disabled Password Autolearn: Disabled Stored Password Proxy: Disabled
New Digipass User accounts must be created manually (no DUR). An Active Directory password is not stored, because back-end authentication is disabled.
Digipass Assignment Mode
4
Post-Installation Tasks
4.1
Login Failure Page
The IIS 6 Module will use the standard login failure page by default. This can be found at <Windows directory>\Help\iisHelp\common\401-4.htm.
You may wish to create a custom html page that Users will be given by the IIS 6 Module if their login fails. See
3.1.7
Troubleshooting
5
Troubleshooting
5.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.
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.
<install directory> version.txt <install directory>\Bin dpmodulecfg.xml dpiisfil.dll dpiismodcfg.exe ikaal3ldap.dll ikaal3seal.dll libeay32.dll libxml2.dll openssl.exe
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 <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.
Troubleshooting
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.
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.
If the IIS_WPG group is not listed for the configuration file, see 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.
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.
6. Click on the OK button.
7. Check that the IIS_WPG group is listed.
8. Click on the OK button.
Troubleshooting
5.1.3
Set System Environment Variable
1. Right-click on My Computer.
The System Properties window will be displayed.
3. Click on the Advanced tab.
4. Click on the Environment Variables button.
Troubleshooting
If DPIISModuleDirectory is not displayed in the System variables list, create it manually:
5.1.4
Install the ISAPI Filter
1. Right-click on My Computer.
2. Click on Manage.
The Computer Management window will be displayed.
Troubleshooting
4. Right-click on Web Sites.
5. Click on Properties.
The Web Sites Properties window will be displayed.
6. Click on the ISAPI Filters tab
7. If the Digipass Authentication Filter is not included in the list, add it manually:
a. Click on the Add… button.
b. Enter these values:
Filter Name: Digipass Authentication Filter Executable: <install directory>\bin\dpiisfil.dll
c. Click on the OK button.
The Digipass Authentication Filter should now appear in the list of ISAPI filters – however the status will not be set to until the IIS 6 Module has been successfully loaded into Internet Information Services. This will occur when
5.2
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.
5.2.1
No Trace File
If there is no trace file, or the trace file information does not help, first check that the ISAPI filter has been loaded (see 5.1.4 Install the ISAPI Filter 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
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.
5.2.4
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.
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 Digipass_Auth_for_IIS_basic_320.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 IIS Basic Wizard after the installation repair.
6
Uninstalling the Digipass Authentication for IIS
6.1
Uninstall the Digipass Authentication for IIS
1. Open the Windows Add or Remove Programs utility. Select Digipass Authentication for IIS Basic. Click on the Change/Remove button. OR
Locate and double-click on the Digipass_Auth_for_IIS_basic_320.msi file to start the MSI.
2. Click on the Next button.
3. Select the Remove radio button to select the remove function.
4. Click on the Remove radio button to confirm the remove function.
5. Click on the Finish button.
The Uninstallation Progress screen will be displayed, showing the progress of your uninstall.
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
E-mail [email protected] 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)
