Digipass for Citrix VM3.0: troubleshooting guide. Creation date: 11/07/2007 Last Review: 30/11/2007 Revision number: 2

Transcription

1 Digipass for Citrix VM3.0: troubleshooting guide Creation date: 11/07/2007 Last Review: 30/11/2007 Revision number: 2 Document type: Whitepaper Security status: EXTERNAL Summary This document describes how to troubleshoot a Digipass for Citrix environment on IIS6. In this document you will find detailed information about possible issues in the Vasco filter for Citrix on IIS6. Troubleshooting 1) Vasco Forms based filter for Citrix overview The purpose of the filter is to trap the username and One Time Password (OTP) (=Digipass Password), entered on the logon screen of Citrix, before the information is sent to Active Directory. The Username and OTP are sent to the Vacman Middleware (VM) server for validation of the OTP. If this validation is successful, VM will send the stored static password from its local database back to the Vasco filter. The Vasco filter will then replace the OTP with this static password on the Citrix logon screen. From there on the username and password are sent to Active Directory for verification of the necessary access rights to the Citrix published applications that are being accessed. More detailed information about the operation of the software can be found in the figures below..doc 3/12/ :05 Page 1 of 10

2 Citrix login without Digipass 1) The user enters his username and Windows password on the Citrix Login page 2) Citrix validates the username and static password against the Active Directory database 3) User is granted access to his published applications..doc 3/12/ :05 Page 2 of 10

3 Citrix login with Digipass 1) User enters his username and Digipass password (OTP) on the Citrix login page (This can be the Citrix server or a web-server publishing the Citrix page) 2) The Vasco IIS module (Vasco filter) intercepts the Username and OTP and sends them to the VM server for validation 3) After a successful verification, VM sends the Username and the VM Password back to the Vasco IIS module. 4) The Vasco IIS module (Vasco filter) replaces the OTP with the static password received from VM on the Citrix login page. 5) Citrix validates the username and static password against Active Directory 6) User is granted access to his published applications.doc 3/12/ :05 Page 3 of 10

4 2) Citrix setup: After having installed Citrix, you need to make sure that the Citrix setup is functioning correctly before the Vasco filter is installed. If this is not the case please check the following link: 3) Troubleshooting and log files Both the Vasco IIS module (filter) and the Middleware can generate log files. You need to determine which setup you are using to perform the correct troubleshooting steps and find out where exactly the necessary information (log files) can be found. Below you will find the most common setups. a) Vasco filter and Middleware server installed on the Citrix server. All log files will be on the same server in the Vasco log directories under the installation folder b) Vasco filter installed on Citrix WI server, Middleware server installed on member server in the domain. The filter log files will be on the Citrix WI server while the Middleware log files will be on the member server.doc 3/12/ :05 Page 4 of 10

5 4) Creating the log files To discover the problem in the configuration it is of course very helpful to have log files. These log files are not created by default since logging consumes a lot of disk space. These options to create log files need to be enabled in case of authentication problems and disabled afterwards, when the Citrix setup with Vasco Digipass is working correctly. Enable logging in the Vacman Middleware: Click on Start => Programs => Vasco => Authentication Server Configuration Select the Full Tracing option and click OK : To set the new configuration, the service needs to be restarted..doc 3/12/ :05 Page 5 of 10

6 After enabling this option all Middleware events are logged to a text file (dpauthserv.trace) that is in the following directory (default installation folder): C:\Program Files\Vasco\Vacman Middleware 3\Log Enable logging in the Vasco filter: Click on Start Programs Vasco Digipass Pack for Citrix Web Interface: Select the Full Tracing option and click OK :.doc 3/12/ :05 Page 6 of 10

7 To activate the new configuration, the IIS Admin service needs to be restarted (for example by using the iisreset command on a command prompt) After enabling this option all Vasco Filter events are logged to a text file. The default name and location of this log file is: C:\Program Files\Vasco\Digipass Pack for Citrix\Log 5) Step by step test scenario Middleware 3.0 with an ODBC database: 1) Enable logging on the filter and in Middleware 2) Follow the steps as described in the Digipass for Citrix Web Interface Guide in section 3.5 Configure Authentication server 3) In VM, create a new policy to experiment with, do not change the pre-defined policies created by the installation procedure. To create a new policy, copy the VM3.0 Windows Password replacement policy to test policy 4) In the test policy properties, check/change the following paramaters: On the Main Settings tab: Set the authenticator to Digipass/Password Backend Authentication: Always Protocol: Windows On the User Settings tab: Enable DUR, Autolearn, Stored Password Proxy Set the Windows Group Check to No Check.doc 3/12/ :05 Page 7 of 10

8 5) Change the policy used on the Citrix Web Interface component to test policy 6) Manually create a user dptest in Active Directory 7) Try to login to Citrix using the user dptest and his static password 8) Normally, the Vacman Middleware user is created by the DUR process. If DUR was disabled you need to create the Middleware user manually, and configure the correct static password (identical to the Active Directory password). 9) If the authentication was successful, import a demo DPX file. A demo DPX key is created during the installation process in the subfolder DPX of the Middleware installation directory. The DPX key for the demo DPX files key is always 32 times the nr 1 ( ) 10) Assign the Demo Digipass to the user dptest. 14) Try to login to Citrix using the user dptest and his OTP 6) Checking and understanding the log files After having enabled debugging in both the Middleware and the Vasco filter a new authentication attempt needs to done to make sure that the problem is logged in the log files. It is important to examine both the filter and the Middleware trace files simultaneously. Check the entries that happened at the same time in the filter and in the Middleware and correlate the events. When going through the log files it is very important to understand the information in the log files since this is the key to solving the problem. This gives a complete overview of what happened during the authentication attempt. If no filter trace file was created; there is a configuration problem in the filter. Please check the Digipass Pack for Citrix administration manual. Follow the troubleshooting section step by step..doc 3/12/ :05 Page 8 of 10

9 7) Troubleshooting your setup step by step: Step 1: Checking if the Vasco filter log files exist Problem: No filter trace file is created. This is usually caused by the filter not being on the correct place in the IIS server so that the filter does not see any authentication requests coming in. Solution Check the troubleshooting section of the Digipass Pack for Citrix administration guide Step 2: Communication between Filter and Middleware Problem: No entries in the Middleware debug.log file, however authentication attempts are seen in the filter trace file Solution Solve the communication issue between the filter and the Middleware server. Possible issues are: - the Middleware server address specified in the filter configuration is not corresponding to the IP address of the Middleware server. - The communications port between the filter and the Middleware is blocked. The default communication port used between filter and middleware is When firewalls are used, make sure TCP port is opened between the filter and the Middleware server. Step 3: Error messages are logged Both the Citrix filter and the Middleware produce messages in the trace files. It is best to check both the Citrix filter trace and the Middleware trace for these messages. Below you find a list of the known error messages with their solution. Error code: <1> Error message: <Serial [xxxxxxxxxx] Application [xxxxxx] OTP Incorrect - [Validation Failed]> Cause: When mistyping the Server (Static) PIN code or OTP Solution: Correctly enter the PIN and OTP Error code: <201> Error message: <Serial [xxxxxxxxxx] Application [xxxxxx] OTP Incorrect - [Code Replay Attempt]> Cause: The Digipass OTP has already been used before Solution: Wait at least 36 seconds before retrying to log in. Never login more than.doc 3/12/ :05 Page 9 of 10

10 once with the same OTP since this will always fail Error code: <-202> Error message: <Serial [xxxxxxxxxx] Application [xxxxxx] OTP Incorrect - [Response Too Small]> Cause: The user did not type his complete (PIN+)OTP Solution: Make sure the user enters his full OTP (With PIN if required) Error code: <-205> Error message: <Serial [xxxxxxxxxx] Application [xxxxxx] OTP Incorrect - [Response Not Decimal]> Cause: The user tries to login using his static password after the grace period has expired Solution: Make sure users only use their Digipass OTP after the expiry of the Grace Period Windows Authentication failed: [1326] [Logon failure: unknown user name or bad password.] Cause: The user s static password does not correspond with the Middleware password while using Local and Windows authentication Solution: If Autolearn is enabled let the user login using Windows Password (+PIN) +OTP. If Autolearn is not enabled please make this change manually in the Middleware. Error code: <1007> Error message: <Digipass User account is locked> Cause: The password or OTP have been entered incorrectly too many times. By default the user lock threshold is set to 3 attempts Solution: An administrator needs to uncheck the locked checkbox on the user record Applies to: Vacman Middleware 3.0 and Digipass for Citrix Web Interface More information: Documentation: VACMAN Middleware Administration Guide.pdf Digipass Pack for Citrix Web Interface Guide IIS6.pdf.doc 3/12/ :05 Page 10 of 10