Identikey Server Administrator Reference - Vasco
Identikey Server Administrator Reference - Vasco
Identikey Server Administrator Reference - Vasco
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
<strong>Identikey</strong> <strong>Server</strong><br />
<strong>Administrator</strong> <strong>Reference</strong><br />
3.1
Disclaimer of Warranties and Limitations of Liabilities<br />
Disclaimer of Warranties and Limitations of Liabilities<br />
The Product is provided on an 'as is' basis, without any other warranties, or conditions, express or implied,<br />
including but not limited to warranties of merchantable quality, merchantability of fitness for a particular purpose,<br />
or those arising by law, statute, usage of trade or course of dealing. The entire risk as to the results and<br />
performance of the product is assumed by you. Neither we nor our dealers or suppliers shall have any liability to<br />
you or any other person or entity for any indirect, incidental, special or consequential damages whatsoever,<br />
including but not limited to loss of revenue or profit, lost or damaged data of other commercial or economic loss,<br />
even if we have been advised of the possibility of such damages or they are foreseeable; or for claims by a third<br />
party. Our maximum aggregate liability to you, and that of our dealers and suppliers shall not exceed the amount<br />
paid by you for the Product. The limitations in this section shall apply whether or not the alleged breach or default<br />
is a breach of a fundamental condition or term, or a fundamental breach. Some states/countries do not allow the<br />
exclusion or limitation or liability for consequential or incidental damages so the above limitation may not apply to<br />
you.<br />
Copyright<br />
Copyright © 2009 VASCO Data Security, Inc., VASCO Data Security International GmbH. All rights reserved.<br />
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any<br />
means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of<br />
VASCO Data Security Inc.<br />
RADIUS Documentation Disclaimer<br />
The RADIUS documentation featured in this manual is focused on supplying required information pertaining to the<br />
RADIUS server and its operation in the <strong>Identikey</strong> <strong>Server</strong> environment. It is recommended that further information be<br />
gathered from your NAS/RAS vendor for information on the use of RADIUS.<br />
Trademarks<br />
VASCO®, Vacman®, IDENTIKEY®, aXs GUARD, DIGIPASS®, and ® are registered or unregistered<br />
trademarks of VASCO Data Security, Inc. and/or VASCO Data Security International GmbH in the U.S. and other<br />
countries.<br />
Document Version: 1.3
Table of Contents<br />
Table of Contents<br />
1 Introduction.................................................................................................................................................. 16<br />
1.1 Available Guides................................................................................................................................................ 16<br />
2 Active Directory Schema............................................................................................................................... 17<br />
2.1 Schema Extensions........................................................................................................................................... 17<br />
2.1.1 Added Object Classes................................................................................................................................... 17<br />
2.1.2 Added Attributes........................................................................................................................................... 18<br />
2.1.3 Added Permission Property Sets................................................................................................................... 22<br />
2.2 Active Directory Auditing.................................................................................................................................... 23<br />
2.2.1 Auditing Inside the Active Directory Users and Computers Extension.............................................................23<br />
2.3 Custom Search Options..................................................................................................................................... 24<br />
2.3.1 Saved Queries.............................................................................................................................................. 24<br />
2.3.2 Using the Custom Search for Digipass.......................................................................................................... 26<br />
2.3.3 Using the Custom Search for Users...............................................................................................................27<br />
2.4 Active Directory Replication Issues..................................................................................................................... 30<br />
2.4.1 Old Data Used After Attribute Modified.......................................................................................................... 30<br />
2.4.1.1 Single <strong>Identikey</strong> <strong>Server</strong> using more than one Domain Controller................................................................................ 30<br />
2.4.1.2 <strong>Administrator</strong> and <strong>Identikey</strong> <strong>Server</strong> using different Domain Controllers.......................................................................31<br />
2.4.1.3 Multiple <strong>Identikey</strong> <strong>Server</strong>s Using Different Domain Controllers................................................................................... 31<br />
2.4.1.4 Two <strong>Administrator</strong>s Modifying the Same Attribute.....................................................................................................32<br />
2.4.2 Old Data Used Overwrites New Data............................................................................................................. 32<br />
2.4.3 Factors Affecting Replication Issues..............................................................................................................32<br />
2.4.4 Solutions and Mitigations............................................................................................................................. 33<br />
2.4.4.1 Digipass Cache......................................................................................................................................................33<br />
2.5 DPADadmin Utility.............................................................................................................................................. 35<br />
2.5.1 Extend Active Directory Schema................................................................................................................... 35<br />
2.5.2 Check Schema Extensions............................................................................................................................ 37<br />
2.5.2.1 Check the Database Structure.................................................................................................................................37<br />
2.5.2.2 Command Line Syntax............................................................................................................................................37<br />
2.5.3 Set Up Digipass Containers in Domain.......................................................................................................... 38<br />
2.5.3.1 Prerequisite Information..........................................................................................................................................38<br />
2.5.3.2 Set Up Digipass Containers.....................................................................................................................................38<br />
2.5.3.3 Command Syntax...................................................................................................................................................38<br />
2.5.4 Assign Digipass Permissions to a Group....................................................................................................... 39<br />
2.5.4.1 Pre-requisites........................................................................................................................................................ 39<br />
2.5.4.2 Command Syntax...................................................................................................................................................39<br />
2.5.5 Delete all Digipass-Related Data from Active Directory................................................................................. 40<br />
2.5.5.1 Run Delete Script on a Domain............................................................................................................................... 41<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 3
Table of Contents<br />
3 ODBC Database............................................................................................................................................ 42<br />
3.1 Database Support.............................................................................................................................................. 42<br />
3.1.1 Unicode Support........................................................................................................................................... 43<br />
3.2 Embedded Database.......................................................................................................................................... 43<br />
3.2.1 Service Account........................................................................................................................................... 43<br />
3.2.2 Database Administration Account................................................................................................................. 44<br />
3.2.3 Database Administration...............................................................................................................................44<br />
3.2.3.2 Changing the Digipass User's Password.................................................................................................................. 44<br />
3.2.4 Connection Limitations................................................................................................................................. 45<br />
3.3 Database Schema.............................................................................................................................................. 46<br />
3.3.1 vdsControl Table.......................................................................................................................................... 46<br />
3.3.2 vdsUser Table.............................................................................................................................................. 47<br />
3.3.3 vdsUserAttr Table......................................................................................................................................... 48<br />
3.3.4 vdsDigipass Table........................................................................................................................................ 48<br />
3.3.5 vdsDPApplication Table................................................................................................................................ 49<br />
3.3.6 vdsDPSoftParams Table............................................................................................................................... 49<br />
3.3.7 vdsPolicy Table............................................................................................................................................ 50<br />
3.3.8 vdsComponent Table.................................................................................................................................... 51<br />
3.3.9 vdsBackEnd Table........................................................................................................................................ 52<br />
3.3.10 vdsDomain Table.......................................................................................................................................... 53<br />
3.3.11 vdsOrgUnit Table.......................................................................................................................................... 53<br />
3.3.12 vdsReport Table........................................................................................................................................... 54<br />
3.3.13 vdsReportFormat Table................................................................................................................................ 54<br />
3.3.14 vdsConfiguration Table................................................................................................................................. 55<br />
3.3.15 vdsOfflineAuthData Table............................................................................................................................. 55<br />
3.4 Encoding and Case-Sensitivity........................................................................................................................... 56<br />
3.5 Domains and Organizational Units...................................................................................................................... 56<br />
3.5.1 Domains....................................................................................................................................................... 57<br />
3.5.1.1 Master Domain...................................................................................................................................................... 57<br />
3.5.1.2 Identifying the Domain for a Login Attempt...............................................................................................................58<br />
3.5.2 Organizational Units..................................................................................................................................... 59<br />
3.6 Database User Accounts.................................................................................................................................... 60<br />
3.6.1 Permissions on the Tables............................................................................................................................ 60<br />
3.6.2 Access to Another Schema........................................................................................................................... 60<br />
3.6.2.1 Modify vdsControl Table......................................................................................................................................... 61<br />
3.7 Database Connection Handling.......................................................................................................................... 62<br />
3.7.1 Multiple Data Sources.................................................................................................................................. 62<br />
3.7.2 Max. Connections......................................................................................................................................... 62<br />
3.7.3 Connection Wait Time...................................................................................................................................62<br />
3.7.4 Idle Timeout................................................................................................................................................. 63<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 4
Table of Contents<br />
3.7.5 Enable Load Sharing..................................................................................................................................... 63<br />
3.7.6 Reconnect Intervals...................................................................................................................................... 63<br />
3.8 DPDBADMIN...................................................................................................................................................... 64<br />
3.8.1 Modify Database Schema............................................................................................................................. 64<br />
3.8.2 Check Database Modifications...................................................................................................................... 66<br />
3.8.2.1 Prerequisite Information..........................................................................................................................................66<br />
3.8.2.2 Check the Database Structure.................................................................................................................................67<br />
3.8.2.3 Command Line Syntax............................................................................................................................................67<br />
3.8.3 Remove Database Modifications................................................................................................................... 68<br />
3.8.3.1 Prerequisite Information..........................................................................................................................................68<br />
3.8.3.2 Modify Database Structure......................................................................................................................................68<br />
3.8.3.3 Command Line Syntax............................................................................................................................................68<br />
4 Sensitive Data Encryption............................................................................................................................. 70<br />
4.1.1 Encrypted Data............................................................................................................................................. 70<br />
4.1.2 Which Encryption Algorithms can be used?.................................................................................................. 70<br />
4.1.3 Exporting Encryption Settings....................................................................................................................... 71<br />
4.1.4 Digipass TCL Command-Line Administration................................................................................................ 71<br />
5 Set Up Active Directory Permissions.............................................................................................................. 72<br />
5.1 Permissions Needed by the <strong>Identikey</strong> <strong>Server</strong>...................................................................................................... 72<br />
5.1.1 Giving Permissions to the <strong>Identikey</strong> <strong>Server</strong>....................................................................................................72<br />
5.2 Permissions Needed by <strong>Administrator</strong>s.............................................................................................................. 73<br />
5.2.1 Domain <strong>Administrator</strong>s................................................................................................................................. 73<br />
5.2.2 Delegated <strong>Administrator</strong>s............................................................................................................................. 73<br />
5.2.3 Reduced-Rights <strong>Administrator</strong>s.................................................................................................................... 73<br />
5.2.4 System <strong>Administrator</strong>s................................................................................................................................. 74<br />
5.3 Assign Administration Permissions to a User ..................................................................................................... 75<br />
5.4 Multiple Domains............................................................................................................................................... 77<br />
5.4.1 Scenario 1 – Each <strong>Identikey</strong> <strong>Server</strong> Handles One Domain............................................................................. 77<br />
5.4.2 Scenario 2 – One <strong>Identikey</strong> <strong>Server</strong> Handles All Domains............................................................................... 78<br />
5.4.3 Scenario 3 - Combination............................................................................................................................. 78<br />
6 Backup and Recovery................................................................................................................................... 79<br />
6.1 What Must be Backed Up................................................................................................................................... 79<br />
6.1.1 Configuration Files........................................................................................................................................80<br />
6.1.2 SSL Certificates............................................................................................................................................ 80<br />
6.1.3 Audit Log Data.............................................................................................................................................. 80<br />
6.1.3.1 Write to Text File....................................................................................................................................................80<br />
6.1.3.2 Write to ODBC Database.........................................................................................................................................80<br />
6.1.3.3 Write to Windows Event Log................................................................................................................................... 81<br />
6.1.4 Write to Syslog............................................................................................................................................. 81<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 5
Table of Contents<br />
6.1.5 DPX files...................................................................................................................................................... 81<br />
6.1.6 Data Store.................................................................................................................................................... 82<br />
6.1.6.1 Data Source Settings..............................................................................................................................................82<br />
6.1.6.2 Backup Strategies.................................................................................................................................................. 82<br />
6.1.6.3 Backup of PostgreSQL Embedded Database............................................................................................................ 83<br />
6.2 Recovery........................................................................................................................................................... 84<br />
6.2.1 Active Directory............................................................................................................................................ 84<br />
6.2.2 ODBC Database............................................................................................................................................ 85<br />
6.2.2.1 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Database Undamaged.......................................................................................................85<br />
6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong> Undamaged.......................................................................................................86<br />
6.2.2.3 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Restore Database............................................................................................................. 89<br />
6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong>............................................................................................................. 92<br />
6.2.2.5 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Copy Database................................................................................................................. 94<br />
7 Field Listings................................................................................................................................................ 96<br />
7.1 User Properties.................................................................................................................................................. 96<br />
7.2 User Attributes................................................................................................................................................... 98<br />
7.3 Digipass Properties.......................................................................................................................................... 100<br />
7.4 Digipass Application Tab.................................................................................................................................. 102<br />
7.5 Policy Properties.............................................................................................................................................. 103<br />
7.6 Client Properties.............................................................................................................................................. 113<br />
7.7 Back-End <strong>Server</strong> Properties............................................................................................................................. 115<br />
7.8 Reports Properties........................................................................................................................................... 116<br />
7.9 <strong>Identikey</strong> <strong>Server</strong> Properties.............................................................................................................................. 118<br />
7.10 Data Changes Requiring a Restart of <strong>Identikey</strong> <strong>Server</strong>...................................................................................... 119<br />
7.10.1 Changes to the Data Store.......................................................................................................................... 119<br />
7.10.1.1 Automatic Re-Loading of Cached Data.................................................................................................................. 119<br />
7.10.1.2 Cached Data List..................................................................................................................................................119<br />
7.10.2 Changes to Configuration Settings.............................................................................................................. 120<br />
8 Licensing.................................................................................................................................................... 121<br />
8.1 How is Licensing Handled?.............................................................................................................................. 121<br />
8.2 Licensing Parameters...................................................................................................................................... 121<br />
8.2.1 Sample License File................................................................................................................................... 122<br />
8.3 View License Information................................................................................................................................. 122<br />
8.4 Obtain and Load a License Key........................................................................................................................ 123<br />
8.5 Re-Licensing................................................................................................................................................... 124<br />
9 Web Sites................................................................................................................................................... 125<br />
9.1 Customizing the Web Sites.............................................................................................................................. 125<br />
9.2 CGI Program.................................................................................................................................................... 125<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 6
Table of Contents<br />
9.2.1 Configuration Settings................................................................................................................................ 126<br />
9.3 Form Fields..................................................................................................................................................... 127<br />
9.3.1 Registration – Main Pages.......................................................................................................................... 127<br />
9.3.1.1 Registration – Challenge Page.............................................................................................................................. 128<br />
9.3.1.2 PIN Change......................................................................................................................................................... 129<br />
9.3.1.3 Login Test – Main Page........................................................................................................................................130<br />
9.3.1.4 Login Test – Challenge Page................................................................................................................................ 131<br />
9.3.2 OTP Request Site........................................................................................................................................132<br />
9.3.2.1 Request Page...................................................................................................................................................... 132<br />
9.4 Query String Variables..................................................................................................................................... 133<br />
9.4.1 Failure/Error Handling................................................................................................................................. 133<br />
9.4.2 Query String Variable List........................................................................................................................... 134<br />
9.4.3 Return Code Listing.................................................................................................................................... 135<br />
9.4.3.1 API Return Codes.................................................................................................................................................135<br />
9.4.3.2 CGI Errors............................................................................................................................................................135<br />
9.4.3.3 Internal Errors...................................................................................................................................................... 136<br />
10 Login Options............................................................................................................................................. 138<br />
10.1 Login Permutations.......................................................................................................................................... 138<br />
10.1.1 Login Methods........................................................................................................................................... 138<br />
10.1.2 Login Actions............................................................................................................................................. 138<br />
10.1.3 Login Variables........................................................................................................................................... 138<br />
10.1.4 Password Format....................................................................................................................................... 139<br />
10.1.5 Policy Settings............................................................................................................................................ 139<br />
10.1.6 Response Only – Cleartext Combined Password Format..............................................................................140<br />
10.1.7 Response Only – CHAP/MS-CHAP/MS-CHAP2............................................................................................. 142<br />
10.1.8 2-Step Challenge/Response – Cleartext Combined Password Format..........................................................142<br />
10.1.9 Virtual Digipass.......................................................................................................................................... 144<br />
11 <strong>Identikey</strong> <strong>Server</strong> Configuration Settings....................................................................................................... 145<br />
11.1 <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard.............................................................................................................. 145<br />
11.2 Redeploy Administration Web Interface............................................................................................................ 145<br />
11.3 <strong>Identikey</strong> <strong>Server</strong> Configuration......................................................................................................................... 147<br />
11.3.1 Starting the Configuration GUI.....................................................................................................................147<br />
11.3.2 General Section.......................................................................................................................................... 147<br />
11.3.2.1 <strong>Server</strong> Location....................................................................................................................................................148<br />
11.3.2.2 Administration Session Settings............................................................................................................................ 148<br />
11.3.2.3 Tracing................................................................................................................................................................148<br />
11.3.3 Communicators Section..............................................................................................................................148<br />
11.3.3.1 SOAP.................................................................................................................................................................. 148<br />
11.3.3.2 RADIUS............................................................................................................................................................... 149<br />
11.3.3.3 SEAL................................................................................................................................................................... 149<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 7
Table of Contents<br />
11.3.4 Scenarios Section....................................................................................................................................... 150<br />
11.3.4.1 Authentication Scenario........................................................................................................................................150<br />
11.3.4.2 Signature Validation Scenario................................................................................................................................150<br />
11.3.4.3 Provisioning Scenario........................................................................................................................................... 150<br />
11.3.4.4 Administration Scenario........................................................................................................................................151<br />
11.3.4.5 Reporting Scenario...............................................................................................................................................151<br />
11.3.4.6 Audit Scenario..................................................................................................................................................... 151<br />
11.3.4.7 Replication Scenario.............................................................................................................................................151<br />
11.3.4.8 Configuration Scenario......................................................................................................................................... 152<br />
11.3.5 Engines Section.......................................................................................................................................... 152<br />
11.3.6 Storage Section.......................................................................................................................................... 152<br />
11.3.6.1 ODBC Data Sources............................................................................................................................................. 152<br />
11.3.6.2 LDAP Data Sources..............................................................................................................................................154<br />
11.3.6.3 Encryption........................................................................................................................................................... 154<br />
11.3.6.4 Advanced Configuration Settings...........................................................................................................................155<br />
11.3.7 Auditing..................................................................................................................................................... 158<br />
11.3.8 Replication Section..................................................................................................................................... 159<br />
11.3.8.1 Enable Replication................................................................................................................................................160<br />
11.3.8.2 Source <strong>Server</strong>...................................................................................................................................................... 160<br />
11.3.8.3 Destination <strong>Server</strong>................................................................................................................................................160<br />
11.3.8.4 Queue................................................................................................................................................................. 160<br />
11.3.9 Configuration File....................................................................................................................................... 161<br />
11.3.9.1 Windows - Example Configuration File...................................................................................................................161<br />
11.3.9.2 Linux Example Configuration File...........................................................................................................................168<br />
11.4 Command Line Options.................................................................................................................................... 176<br />
11.4.1 Windows Service Control Manager............................................................................................................. 176<br />
11.4.2 Linux Runtime Configuration....................................................................................................................... 176<br />
11.4.3 Running <strong>Identikey</strong> <strong>Server</strong> with Command Line Options............................................................................... 176<br />
11.4.3.1 Command Line Option flags..................................................................................................................................176<br />
11.4.3.2 Windows............................................................................................................................................................. 177<br />
11.4.3.3 Linux...................................................................................................................................................................177<br />
11.5 <strong>Identikey</strong> <strong>Server</strong> Web Administration Configuration.......................................................................................... 177<br />
11.5.1 List............................................................................................................................................................. 177<br />
11.5.1.1 Location.............................................................................................................................................................. 177<br />
11.5.1.2 <strong>Identikey</strong> <strong>Server</strong> Name........................................................................................................................................178<br />
11.5.2 Add <strong>Identikey</strong> <strong>Server</strong> ................................................................................................................................ 178<br />
11.5.3 <strong>Server</strong> Status............................................................................................................................................. 178<br />
11.5.3.1 Replication ..........................................................................................................................................................178<br />
11.5.3.2 Admin Session.....................................................................................................................................................178<br />
11.5.4 <strong>Server</strong> Configuration................................................................................................................................... 178<br />
11.6 Web Administration Setup Tool........................................................................................................................ 180<br />
11.6.1 Overview.................................................................................................................................................... 180<br />
11.6.2 Running the Application.............................................................................................................................. 180<br />
11.6.3 Available Commands.................................................................................................................................. 181<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 8
Table of Contents<br />
11.6.4 Command Usage Examples........................................................................................................................ 182<br />
11.6.4.1 Adding an <strong>Identikey</strong> <strong>Server</strong> and SSL Certificate...................................................................................................... 182<br />
11.6.4.2 Adding an <strong>Identikey</strong> <strong>Server</strong>................................................................................................................................... 183<br />
11.6.4.3 Adding an SSL Certificate..................................................................................................................................... 183<br />
11.7 Message Delivery Component Configuration.................................................................................................... 185<br />
11.7.1 Required Information.................................................................................................................................. 185<br />
11.7.2 MDC Configuration GUI............................................................................................................................... 185<br />
11.7.2.1 Modify Gateway Account Login Details.................................................................................................................. 185<br />
11.7.2.2 Configure Internet Connection Details....................................................................................................................186<br />
11.7.2.3 Configure Tracing.................................................................................................................................................186<br />
11.7.2.4 Import HTTP Gateway settings.............................................................................................................................. 187<br />
11.7.2.5 Edit Advanced Settings.........................................................................................................................................187<br />
11.7.2.6 Export HTTP Gateway settings...............................................................................................................................188<br />
11.7.2.7 Gateway Result Pages.......................................................................................................................................... 188<br />
11.7.3 MDC Configuration File............................................................................................................................... 192<br />
11.7.4 Configuration Settings................................................................................................................................ 194<br />
11.8 Digipass TCL Command Line Utility.................................................................................................................. 197<br />
11.8.1 Sample Configuration File........................................................................................................................... 197<br />
12 <strong>Identikey</strong> <strong>Server</strong> Advanced Setup................................................................................................................ 199<br />
12.1 Create Organizational Structure....................................................................................................................... 199<br />
12.1.1 Domains..................................................................................................................................................... 199<br />
12.1.1.2 Create a New Domain...........................................................................................................................................199<br />
12.1.2 Organizational Units................................................................................................................................... 200<br />
12.1.2.1 Create an Organizational Unit................................................................................................................................200<br />
12.1.3 <strong>Administrator</strong>s............................................................................................................................................ 200<br />
12.1.3.1 Create a Delegated <strong>Administrator</strong>..........................................................................................................................200<br />
12.1.3.2 Create a Global <strong>Administrator</strong>............................................................................................................................... 201<br />
12.2 How To Set Up Virtual Digipass........................................................................................................................ 202<br />
12.2.1 Pre-requisites............................................................................................................................................. 202<br />
12.2.2 Import Virtual Digipass records................................................................................................................... 202<br />
12.2.3 Set Up SMS Gateway.................................................................................................................................. 202<br />
12.2.4 Set Up Message Delivery Component......................................................................................................... 202<br />
12.2.5 Configure <strong>Identikey</strong> <strong>Server</strong> .........................................................................................................................203<br />
12.2.6 Edit <strong>Identikey</strong> <strong>Server</strong> Policy.........................................................................................................................203<br />
12.2.6.1 Primary Virtual Digipass........................................................................................................................................203<br />
12.2.6.2 Backup Virtual Digipass........................................................................................................................................ 204<br />
12.2.7 Test Virtual Digipass................................................................................................................................... 205<br />
12.3 Connect the Administration Web Interface to a New <strong>Identikey</strong> <strong>Server</strong>............................................................... 206<br />
12.3.1 Windows.................................................................................................................................................... 206<br />
12.3.2 Linux.......................................................................................................................................................... 206<br />
12.4 Create Custom Report Definition...................................................................................................................... 207<br />
12.4.1 Query Filters............................................................................................................................................... 208<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 9
Table of Contents<br />
12.5 Install a Commercial SSL Certificate.................................................................................................................212<br />
12.5.1 Windows.................................................................................................................................................... 212<br />
12.5.2 Linux.......................................................................................................................................................... 213<br />
12.6 How to Set Up a Stand-Alone <strong>Identikey</strong> <strong>Server</strong> in RADIUS Environment.............................................................214<br />
12.6.1 Information required................................................................................................................................... 214<br />
12.6.2 Instructions................................................................................................................................................ 214<br />
12.7 How to Set Up <strong>Identikey</strong> <strong>Server</strong> as RADIUS Proxy Target...................................................................................215<br />
12.7.1 Information required................................................................................................................................... 215<br />
12.7.2 Instructions................................................................................................................................................ 215<br />
12.8 How to Set Up <strong>Identikey</strong> <strong>Server</strong> as Intermediate <strong>Server</strong>.................................................................................... 217<br />
12.8.2 Information required................................................................................................................................... 218<br />
12.8.3 Instructions................................................................................................................................................ 218<br />
12.9 Add a New Domain to <strong>Identikey</strong> <strong>Server</strong>............................................................................................................ 220<br />
12.9.1 Solution 1: Install an Extra <strong>Identikey</strong> <strong>Server</strong> in the New Domain.................................................................. 220<br />
12.9.2 Solution 2: Configure New Domain for Existing <strong>Identikey</strong> <strong>Server</strong>..................................................................220<br />
13 Reporting................................................................................................................................................... 221<br />
13.1 Reporting Overview......................................................................................................................................... 221<br />
13.1.1 What fields can be included in reports?...................................................................................................... 221<br />
13.1.2 How can these fields be grouped?.............................................................................................................. 221<br />
13.1.3 How to define a Query................................................................................................................................ 221<br />
13.1.3.1 Fields Available to Report Query Definition............................................................................................................. 222<br />
13.1.4 Report Permissions.................................................................................................................................... 225<br />
13.2 Types of Report .............................................................................................................................................. 225<br />
13.2.1 Standard Reports....................................................................................................................................... 226<br />
13.2.2 Custom Reports.......................................................................................................................................... 227<br />
13.2.3 Formatting Templates................................................................................................................................ 227<br />
13.3 Archiving Strategy........................................................................................................................................... 227<br />
14 Auditing...................................................................................................................................................... 228<br />
14.1 Text File.......................................................................................................................................................... 228<br />
14.1.1 Text File Name Variables............................................................................................................................ 228<br />
14.1.2 Configure Auditing to Text File.................................................................................................................... 229<br />
14.2 Windows Event Log......................................................................................................................................... 230<br />
14.3 ODBC Audit Message Database........................................................................................................................231<br />
14.3.1 Set up ODBC Database............................................................................................................................... 231<br />
14.3.1.1 Create database...................................................................................................................................................231<br />
14.3.1.2 Create database schema...................................................................................................................................... 231<br />
14.3.1.3 Create Database Account(s)..................................................................................................................................232<br />
14.3.1.4 Create DSN on <strong>Identikey</strong> <strong>Server</strong> machine...............................................................................................................233<br />
14.3.1.5 Create DSN on Audit Viewer machine....................................................................................................................233<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 10
Table of Contents<br />
14.3.2 Configure <strong>Identikey</strong> <strong>Server</strong>..........................................................................................................................233<br />
14.3.3 Configure Audit Viewer............................................................................................................................... 234<br />
14.4 Linux Syslog.................................................................................................................................................... 234<br />
14.4.1 Configure the System Log.......................................................................................................................... 235<br />
14.4.2 Modify Configuration File............................................................................................................................ 235<br />
14.4.3 Configure <strong>Identikey</strong> <strong>Server</strong> to Write Audit Messages to the Syslog...............................................................236<br />
14.5 Live Connection - <strong>Identikey</strong> <strong>Server</strong> to Audit Viewer........................................................................................... 237<br />
14.5.1 Configure <strong>Identikey</strong> <strong>Server</strong>..........................................................................................................................237<br />
14.5.2 Configure Audit Viewer............................................................................................................................... 237<br />
15 Tracing....................................................................................................................................................... 238<br />
15.1 Trace Message Types...................................................................................................................................... 238<br />
15.2 Trace Message Levels..................................................................................................................................... 239<br />
15.3 Trace Message Contents..................................................................................................................................239<br />
16 Digipass TCL Command-Line Administration............................................................................................... 240<br />
16.1 Introduction..................................................................................................................................................... 240<br />
16.1.2 Knowledge Requirements........................................................................................................................... 241<br />
16.1.3 Data Store Connection................................................................................................................................ 241<br />
16.1.4 Configuration File....................................................................................................................................... 241<br />
16.2 Using DPADMINCMD – Basics.......................................................................................................................... 242<br />
16.2.1 Using an Interactive TCL Command Prompt................................................................................................ 242<br />
16.2.2 Running a Script......................................................................................................................................... 243<br />
16.2.3 Help........................................................................................................................................................... 244<br />
16.2.4 Command Parameters................................................................................................................................ 244<br />
16.2.5 Result Output............................................................................................................................................. 244<br />
16.2.6 Error Handling............................................................................................................................................ 245<br />
16.2.7 International Characters............................................................................................................................. 245<br />
16.2.8 Syntax Notes.............................................................................................................................................. 245<br />
16.2.9 Sample Scripts........................................................................................................................................... 246<br />
17 Replication................................................................................................................................................. 248<br />
17.1 Concepts......................................................................................................................................................... 248<br />
17.1.1 Replication Queue...................................................................................................................................... 249<br />
17.1.2 Record-level Replication............................................................................................................................. 249<br />
17.1.3 Replication Process.................................................................................................................................... 250<br />
17.1.4 Connection Handling.................................................................................................................................. 252<br />
17.1.4.1 Component Record.............................................................................................................................................. 252<br />
17.1.5 Monitoring Replication................................................................................................................................ 252<br />
17.1.5.1 Auditing...............................................................................................................................................................252<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 11
Table of Contents<br />
17.1.5.2 Administration Web Interface................................................................................................................................ 252<br />
17.1.6 Forwarding Replication Entries................................................................................................................... 253<br />
17.2 Configuring Replication ................................................................................................................................... 254<br />
17.2.1 Active Directory.......................................................................................................................................... 254<br />
17.2.2 ODBC Database.......................................................................................................................................... 255<br />
17.2.2.1 Configure Replication to a Second <strong>Identikey</strong> <strong>Server</strong>................................................................................................ 255<br />
17.2.2.2 Configure Replication to a Third or Subsequent <strong>Identikey</strong> <strong>Server</strong> .............................................................................257<br />
17.2.2.3 Add Redundant Replication...................................................................................................................................259<br />
18 Troubleshooting.......................................................................................................................................... 260<br />
18.1 Troubleshooting Tools...................................................................................................................................... 260<br />
18.1.1 View Audit Information............................................................................................................................... 260<br />
18.1.1.1 Windows Event Viewer......................................................................................................................................... 260<br />
18.1.1.2 Syslog................................................................................................................................................................. 260<br />
18.1.1.3 Text file .............................................................................................................................................................. 260<br />
18.1.1.4 ODBC Database................................................................................................................................................... 261<br />
18.1.2 Tracing....................................................................................................................................................... 261<br />
18.2 How To Troubleshoot....................................................................................................................................... 262<br />
18.2.1 Connection Problems.................................................................................................................................. 262<br />
18.2.2 Installation Check....................................................................................................................................... 262<br />
18.2.2.1 Windows Registry Entries......................................................................................................................................262<br />
18.2.2.2 Check Permissions...............................................................................................................................................263<br />
18.2.2.3 Default Policy and Component Created..................................................................................................................263<br />
18.2.3 Administration Web Interface Connection....................................................................................................264<br />
18.2.4 Message Delivery Component.................................................................................................................... 264<br />
18.2.4.1 Enable Tracing.....................................................................................................................................................264<br />
18.2.5 Open Port Numbers on Firewall.................................................................................................................. 264<br />
18.2.5.1 Incoming Ports.....................................................................................................................................................265<br />
18.2.5.2 Outgoing Ports.....................................................................................................................................................265<br />
18.2.6 SOAP/SSL Certificates................................................................................................................................ 265<br />
19 Audit Messages.......................................................................................................................................... 266<br />
19.1 Audit Message Listing...................................................................................................................................... 266<br />
20 Error and Status Codes............................................................................................................................... 279<br />
20.1 Error Code Listing............................................................................................................................................ 279<br />
20.2 Status Code Listing.......................................................................................................................................... 285<br />
21 Technical Support....................................................................................................................................... 292<br />
21.1 Support Contact Information............................................................................................................................ 292<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 12
Index of Tables<br />
Table of Contents<br />
Table 1: Custom Active Directory Object Classes...................................................................................................................................... 17<br />
Table 2: Custom Active Directory Object Attributes................................................................................................................................... 18<br />
Table 3: Custom Active Directory Permission Property Sets...................................................................................................................... 22<br />
Table 4: Saved Queries in Active Directory Users and Computers............................................................................................................. 25<br />
Table 5: Custom Active Directory Search criteria - Digipass......................................................................................................................26<br />
Table 6: Custom Active Directory Search criteria - Users.......................................................................................................................... 28<br />
Table 7: DPADadmin addschema Command Line Options.........................................................................................................................37<br />
Table 8: DPADadmin checkschema Command Line Options..................................................................................................................... 37<br />
Table 9: DPADadmin setupdomain Command Line Options.......................................................................................................................39<br />
Table 10: DPADadmin setupaccess Command Line Options..................................................................................................................... 39<br />
Table 11: ODBC Database Tables............................................................................................................................................................. 46<br />
Table 12: vdsControl Table.......................................................................................................................................................................46<br />
Table 13: vdsUser Table........................................................................................................................................................................... 47<br />
Table 14: vdsUserAttr Table......................................................................................................................................................................48<br />
Table 15: vdsDigipass Table.....................................................................................................................................................................48<br />
Table 16: vdsDPApplication Table.............................................................................................................................................................49<br />
Table 17: vdsDPSoftParams Table............................................................................................................................................................49<br />
Table 18: vdsPolicy Table.........................................................................................................................................................................50<br />
Table 19: vdsComponent Table................................................................................................................................................................ 51<br />
Table 20: vdsBackEnd Table.....................................................................................................................................................................52<br />
Table 21: vdsDomain Table...................................................................................................................................................................... 53<br />
Table 22: vdsOrgUnit Table...................................................................................................................................................................... 53<br />
Table 23: vdsReport Table........................................................................................................................................................................54<br />
Table 24: vdsReportFormat Table.............................................................................................................................................................54<br />
Table 25: vdsConfiguration Table............................................................................................................................................................. 55<br />
Table 26: vdsOfflineAuthData Table..........................................................................................................................................................55<br />
Table 27: Table Permissions Required......................................................................................................................................................60<br />
Table 28: Table Names in vdsControl........................................................................................................................................................61<br />
Table 29: DPDBADMIN addschema Command Line Options......................................................................................................................65<br />
Table 30: DPDBADMIN checkschema Command Line Options.................................................................................................................. 67<br />
Table 31: DPDBADMIN dropschema Command Line Options.................................................................................................................... 68<br />
Table 32: Encrypted Data Attributes - ODBC Database.............................................................................................................................70<br />
Table 33: Encrypted Data Attributes - Active Directory.............................................................................................................................70<br />
Table 34: User Fields................................................................................................................................................................................96<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 13
Table of Contents<br />
Table 35: User Attribute Fields..................................................................................................................................................................98<br />
Table 36: Digipass Fields........................................................................................................................................................................100<br />
Table 37: Digipass Application Fields......................................................................................................................................................102<br />
Table 38: Policy Fields............................................................................................................................................................................103<br />
Table 39: Client Fields............................................................................................................................................................................113<br />
Table 40: Back-End <strong>Server</strong> Fields...........................................................................................................................................................115<br />
Table 41: Report fields........................................................................................................................................................................... 116<br />
Table 42: <strong>Identikey</strong> <strong>Server</strong> Fields............................................................................................................................................................118<br />
Table 43: License Parameters for <strong>Identikey</strong> <strong>Server</strong>................................................................................................................................. 121<br />
Table 44: Configuration Settings for CGI Program................................................................................................................................... 126<br />
Table 45: Form Fields for Main Registration Page...................................................................................................................................127<br />
Table 46: Form Fields for Registration Challenge Page........................................................................................................................... 128<br />
Table 47: Form Fields for <strong>Server</strong> PIN Change Page................................................................................................................................. 129<br />
Table 48: Form Fields for Main Login Test Page..................................................................................................................................... 130<br />
Table 49: Form Fields for Login Test Challenge Page..............................................................................................................................131<br />
Table 50: Form Fields for OTP Request Page.......................................................................................................................................... 132<br />
Table 51: Query String Variable List........................................................................................................................................................134<br />
Table 52: API Return Codes.................................................................................................................................................................... 135<br />
Table 53: CGI Error Return Codes........................................................................................................................................................... 135<br />
Table 54: Internal Error Codes................................................................................................................................................................ 136<br />
Table 55: Login Permutations - Response Only Cleartext Combined (1)...................................................................................................140<br />
Table 56: Login Permutations - Response Only Cleartext Combined (2)...................................................................................................141<br />
Table 57: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP2...........................................................................................142<br />
Table 58: Login Permutations – 2-Step Challenge/Response Cleartext Combined...................................................................................143<br />
Table 59: Login Permutations – Virtual Digipass.....................................................................................................................................144<br />
Table 60: MDC Audit Message Variables.................................................................................................................................................190<br />
Table 61: Message Delivery Component Configuration Settings..............................................................................................................194<br />
Table 62: Audit Text File Name/Path Variables........................................................................................................................................228<br />
Table 63: Required Audit Database Tables..............................................................................................................................................231<br />
Table 64: vdsAuditMessage Required Fields...........................................................................................................................................232<br />
Table 65: vdsAuditMsgField Required Fields...........................................................................................................................................232<br />
Table 66: Required Account Permissions................................................................................................................................................233<br />
Table 67: Audit Message Types and Syslog Priority................................................................................................................................ 234<br />
Table 68: Tracing Message Types.......................................................................................................................................................... 238<br />
Table 69: Tracing Message Levels..........................................................................................................................................................239<br />
Table 70: Tracing Message Contents......................................................................................................................................................239<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 14
Table of Contents<br />
Table 71: DPADMINCMD Help Commands.............................................................................................................................................. 244<br />
Table 72: Registry Entries.......................................................................................................................................................................262<br />
Table 73: Permissions Required............................................................................................................................................................. 263<br />
Table 74: List of Incoming Ports Used by the <strong>Identikey</strong> <strong>Server</strong>................................................................................................................ 265<br />
Table 75: List of Outgoing Ports Used by the <strong>Identikey</strong> <strong>Server</strong>.................................................................................................................265<br />
Table 76: Audit Messages List................................................................................................................................................................266<br />
Table 77: Error Code List........................................................................................................................................................................279<br />
Table 78: Status Code List......................................................................................................................................................................285<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 15
1 Introduction<br />
1.1 Available Guides<br />
The following <strong>Identikey</strong> <strong>Server</strong> guides are available:<br />
Product Guide<br />
Introduction<br />
The Product Guide will introduce you to the features and concepts of <strong>Identikey</strong> <strong>Server</strong> and the various options you<br />
have for using it.<br />
Getting Started Guide<br />
The Getting Started Guide will lead you through a standard setup and testing of key <strong>Identikey</strong> <strong>Server</strong> features.<br />
Windows Installation Guide<br />
Use this guide when planning and working through an installation of <strong>Identikey</strong> <strong>Server</strong> in a Windows environment.<br />
Linux Installation Guide<br />
Use this guide when planning and working through an installation of <strong>Identikey</strong> <strong>Server</strong> in a Linux environment.<br />
<strong>Administrator</strong> <strong>Reference</strong><br />
In-depth information required for administration of <strong>Identikey</strong> <strong>Server</strong>. This includes references such as data attribute<br />
lists, backup and recovery and utility commands.<br />
Performance and Deployment Guide<br />
Contains information on common deployment models and performance statistics.<br />
Help Files<br />
Context-sensitive help accompanies the Administration Web Interface and Digipass Extension for Active Directory<br />
Users and Computers.<br />
<strong>Identikey</strong> <strong>Server</strong> SDK Programmers Guide<br />
In-depth information required to develop using the SDK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 16
2 Active Directory Schema<br />
2.1 Schema Extensions<br />
Active Directory Schema<br />
The following tables document the changes required by <strong>Identikey</strong> <strong>Server</strong> to the Active Directory (AD) schema when<br />
AD is used as the data store.<br />
2.1.1 Added Object Classes<br />
Table 1: Custom Active Directory Object Classes<br />
Attribute Type Location Explanation<br />
vasco-UserExt Aux. Class User record Extra VASCO attributes are added to an Active Directory<br />
User record via an 'auxiliary class' vasco-UserExt on the<br />
User class.<br />
vasco-DPToken Class Unassigned – Optional<br />
vasco-<br />
DPApplication<br />
Assigned – with User record<br />
The vasco-DPToken class is used to store Digipass<br />
attributes. It is also a container, in which vasco-<br />
DPApplication records for that Digipass are stored.<br />
Upon assignment to a User, the Digipass record is stored<br />
in the same location as the User.<br />
Class Within Digipass record This class is used to store Digipass Application<br />
attributes, such as <strong>Server</strong> PIN and expected OTP length.<br />
vasco-Policy Class Digipass Configuration<br />
Container<br />
vasco-Component Class Digipass Configuration<br />
Container<br />
vasco-<br />
BackEnd<strong>Server</strong><br />
Class Digipass Configuration<br />
Container<br />
vasco-Report Class Digipass Configuration<br />
Container<br />
vasco-<br />
ReportFormat<br />
vasco-<br />
Configuration<br />
Class Digipass Configuration<br />
Container<br />
Class Digipass Configuration<br />
Container<br />
vdsOfflineAuthData Class Digipass Configuration<br />
Container<br />
Policy attributes. Attributes will commonly be shared via<br />
inheritance.<br />
Component attributes include the License Key for<br />
<strong>Identikey</strong> <strong>Server</strong> Components.<br />
Information required for connection to back-end servers.<br />
Support reporting functionality. Use this class to control<br />
the report scope.<br />
Support reporting functionality. This class contains the<br />
report format definition information.<br />
Configuration settings for the <strong>Identikey</strong> <strong>Server</strong>.<br />
Offline authentication data. This is included for future<br />
releases of <strong>Identikey</strong> <strong>Server</strong>.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 17
2.1.2 Added Attributes<br />
Table 2: Custom Active Directory Object Attributes<br />
Name Class<br />
vasco-SerialNumber vasco-DPToken<br />
vasco-TokenType vasco-DPToken<br />
vasco-ApplicationNames vasco-DPToken<br />
vasco-ApplicationTypes vasco-DPToken<br />
vasco-Link<strong>Vasco</strong>DigipassToUserExt vasco-DPToken<br />
vasco-TokenAssignedDate vasco-DPToken<br />
vasco-GracePeriod vasco-DPToken<br />
vasco-EnableBVDP vasco-DPToken<br />
vasco-BVDPExpiryDate vasco-DPToken<br />
vasco-BVDPUsesLeft vasco-DPToken<br />
vasco-DirectAssignOnly vasco-DPToken<br />
vasco-AdditionalAttribute vasco-DPToken<br />
vasco-ActivationLocations vasco-DPToken<br />
vasco-ActivationCount vasco-DPToken<br />
vasco-LastActivationTime vasco-DPToken<br />
vasco-DPSoftStaticVector vasco-DPToken<br />
vasco-DPDescription vasco-DPToken<br />
vasco-SerialNumber vasco-DPApplication<br />
vasco-ApplicationName vasco-DPApplication<br />
vasco-ApplicationNumber vasco-DPApplication<br />
vasco-ApplicationType vasco-DPApplication<br />
vasco-DPBlob vasco-DPApplication<br />
vasco-Active vasco-DPApplication<br />
vasco-LinkUserExtTo<strong>Vasco</strong>Digipass vasco-UserExt<br />
vasco-LinkUserExtToUser vasco-UserExt<br />
vasco-StaticPassword vasco-UserExt<br />
vasco-LocalAuth vasco-UserExt<br />
vasco-BackEnd<strong>Server</strong>Auth vasco-UserExt<br />
vasco-Disable vasco-UserExt<br />
vasco-Profile vasco-UserExt<br />
vasco-AdminPrivileges vasco-UserExt<br />
Active Directory Schema<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 18
Name Class<br />
vasco-ObjectScope vasco-UserExt<br />
vasco-OfflineAuthEnabledOverride vasco-UserExt<br />
vasco-OfflineData vasco-UserExt<br />
vasco-CreateTime <strong>Vasco</strong>-UserExt<br />
vasco-ModifyTime <strong>Vasco</strong>-UserExt<br />
vasco-ID vasco-BackEnd<strong>Server</strong><br />
vasco-Protocol vasco-BackEnd<strong>Server</strong><br />
vasco-Domain vasco-BackEnd<strong>Server</strong><br />
vasco-Priority vasco-BackEnd<strong>Server</strong><br />
vasco-Retries vasco-BackEnd<strong>Server</strong><br />
vasco-AcctIPAddress vasco-BackEnd<strong>Server</strong><br />
vasco-AcctPort vasco-BackEnd<strong>Server</strong><br />
vasco-AdditionalAttribute vasco-BackEnd<strong>Server</strong><br />
vasco-AuthIPAddress vasco-BackEnd<strong>Server</strong><br />
vasco-SharedSecret vasco-BackEnd<strong>Server</strong><br />
vasco-Timeout vasco-BackEnd<strong>Server</strong><br />
Version-Number vasco-BackEnd<strong>Server</strong><br />
vasco-ID vasco-Component<br />
vasco-Location vasco-Component<br />
vasco-LinkComponentToPolicy vasco-Component<br />
vasco-Protocol vasco-Component<br />
vasco-ComponentType vasco-Component<br />
vasco-PublicKey vasco-Component<br />
vasco-AdditionalAttribute vasco-Component<br />
vasco-SharedSecret vasco-Component<br />
vasco-TCPPort vasco-Component<br />
Version-Number vasco-Component<br />
vasco-AdditionalAttribute vasco-Policy<br />
vasco-AllowedApplType vasco-Policy<br />
vasco-AllowedDPTypes vasco-Policy<br />
vasco-ApplicationNames vasco-Policy<br />
vasco-AssignmentMode vasco-Policy<br />
vasco-AssignSearchUpOUPath vasco-Policy<br />
vasco-Autolearn vasco-Policy<br />
vasco-BackEndAuth vasco-Policy<br />
Active Directory Schema<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 19
Name Class<br />
vasco-BackupVDPRequestKeyword vasco-Policy<br />
vasco-BackupVDPRequestMethod vasco-Policy<br />
vasco-BVDPMaximumDays vasco-Policy<br />
vasco-BVDPMaximumUses vasco-Policy<br />
vasco-ChallengeRequestKeyword vasco-Policy<br />
vasco-ChallengeRequestMethod vasco-Policy<br />
vasco-CheckChallenge vasco-Policy<br />
vasco-ChgWinPwdEnabled vasco-Policy<br />
vasco-ChgWinPwdLength vasco-Policy<br />
vasco-ChkInactDays vasco-Policy<br />
vasco-ClientGroupList vasco-Policy<br />
vasco-ClientGroupMode vasco-Policy<br />
vasco-DCR vasco-Policy<br />
vasco-Description vasco-Policy<br />
vasco-Domain vasco-Policy<br />
vasco-DUR vasco-Policy<br />
vasco-EnableBVDP vasco-Policy<br />
vasco-EventWindow vasco-Policy<br />
vasco-GracePeriod vasco-Policy<br />
vasco-GroupCheckMode vasco-Policy<br />
vasco-GroupList vasco-Policy<br />
vasco-ID vasco-Policy<br />
vasco-IThreshold vasco-Policy<br />
vasco-ITimeWindow vasco-Policy<br />
vasco-LinkPolicyToChildPolicy vasco-Policy<br />
vasco-LinkPolicyToComponent vasco-Policy<br />
vasco-LinkPolicyToParentPolicy vasco-Policy<br />
vasco-LocalAuth vasco-Policy<br />
vasco-OfflineAuthEnabled vasco-Policy<br />
vasco-OfflineTimeIntervals vasco-Policy<br />
vasco-OfflineMaxEvents vasco-Policy<br />
vasco-OneStepChalCheckDigit vasco-Policy<br />
vasco-OneStepChalLength vasco-Policy<br />
vasco-OneStepChalResp vasco-Policy<br />
vasco-OnLineSG vasco-Policy<br />
Active Directory Schema<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 20
Name Class<br />
vasco-PINChangeAllowed vasco-Policy<br />
vasco-PrimaryVDPRequestKeyword vasco-Policy<br />
vasco-PrimaryVDPRequestMethod vasco-Policy<br />
vasco-Protocol vasco-Policy<br />
vasco-SelfAssignSeparator vasco-Policy<br />
vasco-SThreshold vasco-Policy<br />
vasco-STimeWindow vasco-Policy<br />
vasco-StoredPasswordProxy vasco-Policy<br />
vasco-SyncWindow vasco-Policy<br />
vasco-2OTPSyncEnabled vasco-Policy<br />
Version-Number vasco-Policy<br />
vasco-ID vasco-Report<br />
vasco-ReportName vasco-Report<br />
vasco-Description vasco-Report<br />
vasco-DataSource vasco-Report<br />
vasco-GroupLevel vasco-Report<br />
vasco-ReportType vasco-Report<br />
vasco-RunPerms vasco-Report<br />
vasco-ChangePerms vasco-Report<br />
vasco-TimeFreq vasco-Report<br />
vasco-QueryDef vasco-Report<br />
vasco-UserID vasco-Report<br />
Version-Number vasco-Report<br />
vasco-ID vasco-ReportFormat<br />
vasco-FormatName vasco-ReportFormat<br />
vasco-FormatDef vasco-ReportFormat<br />
Version-Number vasco-ReportFormat<br />
vasco-Name vasco-Configuration<br />
vasco-Value vasco-Configuration<br />
Version-Number vasco-Configuration<br />
Active Directory Schema<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 21
2.1.3 Added Permission Property Sets<br />
Property sets have been created for typical groups of permissions required for administration tasks.<br />
Table 3: Custom Active Directory Permission Property Sets<br />
Property Set Applicable Object Actions Allowed<br />
Active Directory Schema<br />
Digipass Assignment Link Digipass Assign and unassign Digipass for Digipass User<br />
accounts.<br />
Digipass Application Data Digipass Application Digipass record functions.<br />
Digipass User Account Information User Modify Digipass User information.<br />
Digipass User Account to User Link User Link and unlink Digipass Users. This is also required<br />
when assigning Digipass to linked Digipass User<br />
records.<br />
Digipass User Account Stored Password User Read and modify the stored password for a Digipass<br />
User.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 22
2.2 Active Directory Auditing<br />
Active Directory Schema<br />
Active Directory auditing may be configured to record access and modifications to custom objects used by the<br />
<strong>Identikey</strong> <strong>Server</strong>. If you currently have default auditing enabled, it might already include actions on custom objects.<br />
See these Microsoft articles for information on turning on and configuring auditing:<br />
Windows 2003 - http://support.microsoft.com/?kbid=814595<br />
Windows Vista & 2008 – http://technet.microsoft.com/en-us/library/cc731607.aspx<br />
What Should I Audit?<br />
This will depend on what you need to audit. For example, if you wanted to record all Digipass assignments in the<br />
domain, you might set up auditing in the Domain Root for Everyone, with the Digipass Assignment Link property<br />
set.<br />
Please note that this type of auditing is specific to Active Directory. Any audit information generated by this<br />
method cannot be imported into the <strong>Identikey</strong> <strong>Server</strong> auditing system, and cannot be used to generate <strong>Identikey</strong><br />
<strong>Server</strong> reports.<br />
See the 2.1 Schema Extensions topic for more information on custom objects and permission property sets created<br />
for the <strong>Identikey</strong> <strong>Server</strong>.<br />
2.2.1 Auditing Inside the Active Directory Users and Computers Extension<br />
If you wish to produce audit files that can be imported into <strong>Identikey</strong> <strong>Server</strong> and can be used to generate <strong>Identikey</strong><br />
<strong>Server</strong> reports, you can set up auditing from inside the Active Directory Users and Computers Extension (ADUCE).<br />
All message types are audited - Error, Warning, Information, Success, Failure.<br />
To enable Auditing in the ADUCE:<br />
1. On the Digipass Extension Auditing window click on the Auditing option button.<br />
2. Browse to the location you want the audit file to be written to. The name of the file will be in the format<br />
ikey_aduce.audit, where is the current year and is the current month.<br />
3. Click OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 23
2.3 Custom Search Options<br />
Active Directory Schema<br />
The Digipass Extension adds functionality to the Active Directory Users and Computers snap-in which allows<br />
searching for specific Digipass and Digipass User records throughout a domain, or within the limits of a delegated<br />
administrator's permissions. This functionality is especially useful where unassigned Digipass have been allocated<br />
to various Organizational Units.<br />
Note<br />
2.3.1 Saved Queries<br />
To see the digipass-pool, digipass-reserve, and digipass configuration containers under the<br />
domain in the Active Directory Users and Computers snap-in the Advanced Features setting<br />
needs to be enabled. Go to View => Advanced Features and click on Advanced Features to<br />
toggle the setting on.<br />
On Windows <strong>Server</strong> 2003, Windows 2008, and Windows XP, the Microsoft Management Console (MMC)<br />
framework supports Saved Queries.<br />
On Windows <strong>Server</strong> 2003 and Windows XP, a number of Saved Queries are installed automatically into the saved<br />
MMC console file that is opened using the Start -> Programs -> VASCO -> <strong>Identikey</strong> <strong>Server</strong> -> Active Directory<br />
Users and Computers shortcut.<br />
In addition, several Query Definition Files are installed in the \Queries folder. These can be<br />
imported into your existing Active Directory Users and Computers console by right-clicking on the Saved Queries<br />
folder and selecting Import Query Definition....<br />
The Saved Queries provided by the installation are designed to provide several common queries that may be<br />
useful, as listed below. They can be edited, copied or deleted as required. If you have made a mistake modifying<br />
one and wish to start again, you can reload the query by deleting it and importing it from the Query Definition File.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 24
Table 4: Saved Queries in Active Directory Users and Computers<br />
Active Directory Schema<br />
Query Name Description Query Definition File<br />
Users with Digipass All Users in the Domain who have one or more<br />
Digipass assigned directly.<br />
Users without Digipass All Users in the Domain who have no Digipass<br />
assigned, directly or via a Linked User.<br />
Users with a DP User Account All Users in the Domain who have a Digipass User<br />
Account.<br />
Users without a DP User<br />
Account<br />
All Users in the Domain who do not have a Digipass<br />
User Account.<br />
users-with-dp.xml<br />
users-without-dp.xml<br />
users-with-dp-user-account.xml<br />
Assigned Digipass All Digipass in the Domain that are assigned. assigned-dp.xml<br />
Unassigned Digipass All Digipass in the Domain that are currently<br />
unassigned, excluding any Reserved Digipass.<br />
Locked DP User Accounts All Users in the Domain whose Digipass User<br />
Account is Locked.<br />
users-without-dp-user-account.xml<br />
unassigned-dp.xml<br />
locked-dp-user-accounts.xml<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 25
2.3.2 Using the Custom Search for Digipass<br />
To perform a search for Digipass:<br />
1. Right-click on the Organizational Unit in which to search, or the domain root.<br />
2. Click on Find...<br />
3. Select the Digipass object type from the Find: drop down list.<br />
Active Directory Schema<br />
4. Use the Digipass tab to specify the search criteria. Almost all the Digipass search criteria can be set using<br />
the form on this tab.<br />
5. If you are searching on any criteria that do not appear on the Digipass tab, use the Advanced tab:<br />
a. Click on the Advanced tab.<br />
b. Click on Field and select the required attribute from the list.<br />
c. Enter the search Condition and Value, then click Add.<br />
d. Repeat with additional Fields.<br />
6. Click Find Now to execute the search. Multiple criteria are applied using the logical AND – all criteria must<br />
be met for a Digipass to be found.<br />
The available criteria are listed in the following table:<br />
Table 5: Custom Active Directory Search criteria - Digipass<br />
Tab Field Name Usage<br />
Digipass Serial Number Exact Serial Number (as seen in Digipass properties);<br />
Serial Number with wildcard*;<br />
First Serial Number in range, when used with To field.<br />
(Serial Number) To Last Serial Number in range.<br />
Digipass Type Digipass Type, eg. DP300. Wildcard* allowed.<br />
Application Name Application Name, eg. GO3DEFAULT. Wildcard* allowed.<br />
This will find Digipass that have an Active application of the specified<br />
name**.<br />
Application Type Application Type: Response Only, Challenge/Response.<br />
This will find Digipass that have an Active application of the specified<br />
type**.<br />
Digipass Assignment Assignment status: Assigned, Unassigned.<br />
Reserved Reserved status: Reserved, Not Reserved.<br />
Description Free text.<br />
Use this field to find Digipass records with the same text string within their<br />
Description field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 26
Tab Field Name Usage<br />
Active Directory Schema<br />
Advanced Application Name Conditions: Starts with, Ends with, Is (Exactly), Is Not.<br />
Values: Application Name (complete or partial)<br />
This will find Digipass that have an Active application of the specified<br />
Application Name criteria**.<br />
Application Type Conditions: Is (Exactly), Is Not.<br />
Values: RO (Response Only), CR (Challenge/Response), SG (Signature).<br />
This will find Digipass that have an Active application of the specified<br />
Application Type criteria**.<br />
Backup Virtual Digipass<br />
Enabled<br />
Conditions: Less than or equal to, Greater than or equal to, Is (Exactly), Is<br />
Not, Not Present.<br />
Values: 0 (Default), 1 (No), 2 (Yes - Permitted), 3 (Yes - Required), 4 (Yes –<br />
Time Limited).<br />
Note that Digipass with 'Default' for this setting may either have 0 for this<br />
attribute or may not have the attribute present.<br />
Digipass Type Conditions: Starts with, Ends with, Is (Exactly), Is Not.<br />
Values: Digipass Type (complete or partial)<br />
Reserved Conditions: Is (Exactly), Is Not.<br />
Values: 0 (No), 1 (Yes).<br />
This attribute is always present.<br />
Serial Number Conditions: Starts with, Ends with, Is (Exactly), Is Not.<br />
Values: Serial Number, as seen in Digipass properties (complete or partial)<br />
User Assignment Link Conditions: Present, Not Present.<br />
Values: N/A.<br />
If this attribute is present, the Digipass is assigned; if not present, the<br />
Digipass is unassigned.<br />
* Search criteria on Digipass Application attributes ignore Inactive Digipass Applications.<br />
** For a wildcard, the * character is used.<br />
Example<br />
A search for Digipass records run with only the following text entered into the Serial Number field, would return these results:<br />
0097 No records returned<br />
0097* All Digipass with serial number starting with 0097<br />
0097987654 Digipass with serial number 0097987654 only<br />
*76 All Digipass with serial number ending in 76<br />
2.3.3 Using the Custom Search for Users<br />
To perform a search for Users:<br />
1. Right-click on the Organizational Unit in which to search, or the domain root.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 27
2. Click on Find...<br />
3. Select the Users, Contacts, and Groups object type from the Find: drop down list.<br />
4. If you have search criteria that are not related to Digipass, specify them as usual.<br />
5. To specify Digipass related search criteria, use the Advanced tab:<br />
a. Click on the Advanced tab.<br />
b. Click on Field, select the User submenu and select the required attribute from the list.<br />
c. Enter the search Condition and Value, then click Add.<br />
d. Repeat with additional Fields.<br />
Active Directory Schema<br />
6. Click Find Now to execute the search. Multiple criteria are applied using the logical AND – all criteria must<br />
be met for a User to be found.<br />
The available criteria are listed in the following table:<br />
Table 6: Custom Active Directory Search criteria - Users<br />
Field Name Usage<br />
Digipass Assignment Link Conditions: Present, Not Present.<br />
Values: N/A.<br />
If this attribute is present, a Digipass is assigned to the User; if not<br />
present, no Digipass is assigned.<br />
Digipass Back-End Authentication Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),<br />
Is Not, Not Present.<br />
Values: 0 (Default), 1 (None), 2 (If Needed), 3 (Always).<br />
Note that Users with 'Default' for this setting may either have 0 for this<br />
attribute or may not have the attribute present.<br />
Digipass Local Authentication Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),<br />
Is Not, Not Present.<br />
Values: 0 (Default), 1 (None), 2 (Digipass/Password), 3 (Digipass Only).<br />
Note that Users with 'Default' for this setting may either have 0 for this<br />
attribute or may not have the attribute present.<br />
Digipass User Account Create Time Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),<br />
Is Not, Present, Not Present.<br />
Values: Number of seconds since 1 st Jan 1970 00:00:00 that the<br />
Digipass User account was created.<br />
If this attribute is present, the User has a Digipass User account; if not<br />
present, the User does not.<br />
Digipass User Account Disabled Conditions: Is (Exactly), Is Not, Not Present.<br />
Values: 0 (No), 1 (Yes).<br />
If this attribute is not present, the account is not disabled*.<br />
Digipass User Account Lock Count Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),<br />
Is Not, Not Present.<br />
Values: current count of failed logins since last successful login.<br />
If this attribute is not present, it is treated as 0.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 28
Field Name Usage<br />
Active Directory Schema<br />
Digipass User Account Locked Conditions: Is (Exactly), Is Not, Not Present.<br />
Values: 0 (No), 1 (Yes).<br />
If this attribute is not present, the account is not locked*.<br />
Digipass User Account Modify Time Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),<br />
Is Not, Present, Not Present.<br />
Values: Number of seconds since 1 st Jan 1970 00:00:00 that the<br />
Digipass User account was last modified.<br />
Digipass User Account Password This field does not have practical value as a search field, but is listed<br />
by Active Directory anyway.<br />
Digipass User Attributes This field is not currently used.<br />
Digipass User to User Link Conditions: Present, Not Present.<br />
Values: N/A.<br />
If this attribute is present, The Digipass User account is linked to<br />
another Digipass User account; if not present, there is no link.<br />
* If you specify Is Not 1, the results will include Users who do not have the attribute set, in addition to those who<br />
have the attribute set to 0.<br />
Example<br />
A search for Digipass User accounts where the Local Authentication setting has a value other than Default would use the following<br />
criteria:<br />
Digipass Local Authentication Greater than or equal to 1<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 29
2.4 Active Directory Replication Issues<br />
Active Directory Schema<br />
Active Directory replication is not instantaneous. Intra-site replication is usually quite fast but changes on one<br />
Domain Controller may still take several minutes to be replicated to other Domain Controllers. Inter-site replication<br />
may be quite slow – an hour or more between replications is common.<br />
Replication occurs when more than one Domain Controller exists in a domain.<br />
2.4.1 Old Data Used After Attribute Modified<br />
The time period between replications becomes a problem where information is changed on one Domain Controller<br />
(for example, a Digipass User's <strong>Server</strong> PIN is reset), but old information is used on another Domain Controller<br />
before the changed information has been replicated to it.<br />
There are a few scenarios where this may occur. These are listed below:<br />
2.4.1.1 Single <strong>Identikey</strong> <strong>Server</strong> using more than one Domain Controller<br />
A single <strong>Identikey</strong> <strong>Server</strong> may make a change to a record, have to switch to another Domain Controller, and read<br />
the same record – where the change has not yet been applied.<br />
Example<br />
A User logs in with an OTP, and the <strong>Identikey</strong> <strong>Server</strong> connects to DC-01 to retrieve and update the Digipass data. The connection to<br />
the DC-01 fails soon after login, before replication has occurred. The User needs to log in again, and the <strong>Identikey</strong> <strong>Server</strong> connects<br />
to DC-02 this time. The User can log in using the same OTP as the last login – the login should fail (OTP replay) but instead<br />
succeeds, because DC-02 does not yet know that the OTP has been previously used.<br />
Time DC-01 DC-02<br />
8:32 Replication occurs<br />
8:34 User logs in with OTP 10457920.<br />
The <strong>Identikey</strong> <strong>Server</strong> records the use of the OTP in the<br />
Digipass record.<br />
8:35 Connection to DC-01 is broken, and the <strong>Identikey</strong><br />
<strong>Server</strong> switches to DC-02.<br />
8:35 User retries login using same OTP<br />
10457920. The login succeeds where it<br />
should have failed (OTP replay).<br />
The <strong>Identikey</strong> <strong>Server</strong> records the use of the<br />
OTP in the Digipass record.<br />
8:37 Replication occurs<br />
Digipass record changes are replicated between DC-01 and DC-02.<br />
The example timeline above shows the sequence of events.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 30
2.4.1.2 <strong>Administrator</strong> and <strong>Identikey</strong> <strong>Server</strong> using different Domain Controllers<br />
Active Directory Schema<br />
The administrator may not be connected to the same Domain Controller (via the Administration Interfaces) as the<br />
<strong>Identikey</strong> <strong>Server</strong>.<br />
Example<br />
An administrator changes a User's <strong>Server</strong> PIN through the Active Directory Users and Computers extension, which is connected to<br />
DC-01. The <strong>Identikey</strong> <strong>Server</strong> connects to DC-03. The User attempts a login using the new PIN, which fails because DC-03 is not yet<br />
aware of the change of <strong>Server</strong> PIN.<br />
Time DC-01 DC-03<br />
9:02 Replication occurs<br />
9:03 <strong>Administrator</strong> changes a User's <strong>Server</strong> PIN<br />
from 1234 to 9876.<br />
9:04 User attempts to log in using new PIN (9876) and the<br />
login fails.<br />
9:05 Replication occurs<br />
Digipass record changes are replicated between DC-01 and DC-03.<br />
The example timeline above shows the sequence of events.<br />
2.4.1.3 Multiple <strong>Identikey</strong> <strong>Server</strong>s Using Different Domain Controllers<br />
Multiple <strong>Identikey</strong> <strong>Server</strong>s may connect to different Domain Controllers in a domain or site.<br />
Example<br />
A User changes their own PIN during a login through one <strong>Identikey</strong> <strong>Server</strong> which connects to DC-01. The server on which the<br />
<strong>Identikey</strong> <strong>Server</strong> is installed becomes unavailable, and the User attempts another login via the <strong>Identikey</strong> <strong>Server</strong> on a backup server,<br />
which connects to DC-02. The login fails because DC-02 is not yet aware of the change of <strong>Server</strong> PIN.<br />
Time DC-01 DC-02<br />
11:54 Replication occurs<br />
11:55 User changes their <strong>Server</strong> PIN from 1234<br />
to 9876 during login.<br />
The <strong>Identikey</strong> <strong>Server</strong> records the PIN<br />
change in the Digipass record.<br />
11:57 User attempts to log in using new PIN (9876) and the<br />
login fails.<br />
11:59 Replication occurs<br />
Digipass record changes are replicated between DC-01 and DC-02.<br />
The example timeline above shows the sequence of events.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 31
Active Directory Schema<br />
2.4.1.4 Two <strong>Administrator</strong>s Modifying the Same Attribute<br />
Two administrators attempt to modify the same attribute on a single User account or Digipass record within the<br />
same replication interval. The later modification will overwrite the earlier when replication occurs.<br />
2.4.2 Old Data Used Overwrites New Data<br />
The problems above are exacerbated when the old information used on the second Domain Controller is updated<br />
based on the old information. As the updated record on the second Domain Controller now has a later modification<br />
date, the end result is that the changed information on the first Domain Controller is overwritten incorrectly.<br />
Example<br />
An administrator connects to DC-01 and sets a User's PIN from '1234' to '9876'. The User logs in through the <strong>Identikey</strong> <strong>Server</strong>,<br />
which connects to DC-02. The User enters the new <strong>Server</strong> PIN and his One Time Password. However, the PIN set on DC-01 has not<br />
yet been replicated to DC-02, so because the PIN entered does not match the old PIN still recorded in the Digipass record on DC-<br />
02, the login fails.<br />
Because the Policy setting of Identification Threshold is in use, his login failure is written back to the Digipass record. When<br />
replication occurs, the Digipass record on DC-02 has the latest modification date – and is copied to DC-01, wiping out the original<br />
PIN setting made by the administrator. Both DC-01 and DC-02 now consider '1234' to be the correct <strong>Server</strong> PIN for the Digipass.<br />
Time DC-01 DC-02<br />
10:45 Replication<br />
10:46 <strong>Administrator</strong> changes User's PIN from<br />
9876 to 1234.<br />
10:48 User login (with new PIN of 1234) fails.<br />
<strong>Identikey</strong> <strong>Server</strong> writes failure information to Digipass<br />
record.<br />
10:50 Replication<br />
Active Directory finds last instance of the Digipass blob having been modified.<br />
Active Directory overwrites DC-01 Digipass record with DC-02 Digipass record.<br />
The example timeline above shows how the problem can occur.<br />
The problem shown in the example above may also occur in a Force PIN Change set by an administrator.<br />
2.4.3 Factors Affecting Replication Issues<br />
A number of factors determine the likelihood and severity of the Active Directory issues described:<br />
Redundancy and load-balancing settings for the <strong>Identikey</strong> <strong>Server</strong><br />
There are a number of <strong>Identikey</strong> <strong>Server</strong> configuration settings which may affect replication issues:<br />
Preferred <strong>Server</strong><br />
The <strong>Identikey</strong> <strong>Server</strong> will attempt to connect to the named Domain Controller, rather than simply polling the<br />
domain for an available Domain Controller.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 32
Active Directory Schema<br />
Preferred <strong>Server</strong> Only<br />
The <strong>Identikey</strong> <strong>Server</strong> may be restricted to connecting only to the Domain Controller named in the above setting.<br />
If this is enabled, the <strong>Identikey</strong> <strong>Server</strong> will not switch to any other Domain Controller, so it will never retrieve<br />
data older than its own.<br />
Max. Bind Lifetime<br />
The maximum bind lifetime controls how long the <strong>Identikey</strong> <strong>Server</strong> will stay connected to a Domain Controller<br />
before polling the domain for a Domain Controller connection.<br />
Replication Interval<br />
On Windows <strong>Server</strong> 2003 and Windows 2008, the intra-site replication interval is not configurable, but is set to<br />
approximately 15 seconds, as replication is much more efficient.<br />
Inter-site replication is fully configurable on Windows <strong>Server</strong> 2003 and Windows 2008.<br />
The longer the replication interval, the more likelihood of these problems occurring.<br />
Number of Domain Controllers in the Site<br />
Each Domain Controller regularly requires replication with all other local Domain Controllers. As this is done<br />
sequentially, it will affect the amount of time between replications.<br />
2.4.4 Solutions and Mitigations<br />
2.4.4.1 Digipass Cache<br />
The Digipass cache collects Digipass records as they are modified, and keeps them in memory for a certain length<br />
of time. A newer entry from the cache is always used in preference to an older record from Active Directory. The<br />
cache age should be a little longer than the typical replication interval. The default is 10 minutes (600 seconds).<br />
This option will help in problems caused by a single <strong>Identikey</strong> <strong>Server</strong> accessing more than one Domain Controller in<br />
a domain – see 2.4.1.1 Single <strong>Identikey</strong> <strong>Server</strong> using more than one Domain Controller.<br />
It will also assist in<br />
problems caused by having multiple Authentication <strong>Server</strong>s accessing more than one Domain Controller in a<br />
domain, if <strong>Identikey</strong> <strong>Server</strong> replication is enabled between the servers. However, it will not affect the scenario of an<br />
Administration Interface being connected to a different Domain Controller to the <strong>Identikey</strong> <strong>Server</strong>.<br />
If you calculate that your typical replication interval will be more than ten minutes, the cache age may be increased<br />
by modifying the Blob-Cache Max-Age setting in the configuration file (\bin\identikeyconfig.xml):<br />
<br />
<br />
<br />
<br />
<br />
<br />
A large cache may slow down processing slightly for the <strong>Identikey</strong> <strong>Server</strong>, so monitor performance to check the<br />
impact caused after modifying the cache age.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 33
Active Directory Schema<br />
Warning<br />
If the <strong>Identikey</strong> <strong>Server</strong> is installed on a Member <strong>Server</strong>, this server must be closely timesynchronized<br />
with the Domain Controller(s). If the server is not time-synchronized, the Policy<br />
may select an older record when comparing records in the Digipass cache with those on the<br />
Domain Controller.<br />
If the <strong>Identikey</strong> <strong>Server</strong> is installed on a Domain Controller, time-synchronization is assumed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 34
2.5 DPADadmin Utility<br />
2.5.1 Extend Active Directory Schema<br />
Active Directory Schema<br />
The addschema command is used to create all the Active Directory Schema extensions, if they are not already<br />
there. Each element will be checked individually to see if it is already there and if not, will be added.<br />
This command is intended to be run manually by a domain administrator before the main <strong>Identikey</strong> <strong>Server</strong><br />
installation is run, as recommended by Microsoft.<br />
It may be necessary to go through an approval process in your company before running this command, as it<br />
involves changes to Active Directory Schema. You may also need to have another administrator run the command<br />
for you, possibly in another part of your network. This depends on your company’s structure and rules for Active<br />
Directory control.<br />
Prerequisite Information<br />
Schema Master Machine<br />
This command may technically be run on any Windows XP, 2003, Vista or 2008 machine. However it needs to<br />
contact the Domain Controller which has the Schema Master role. There can be only one Domain Controller in the<br />
Forest with that role. It may be simplest to run the command directly on the Schema Master, to avoid any potential<br />
connectivity or permission issues.<br />
Warning<br />
Warning: If you are passing the credentials to the command in the parameters, and you are not<br />
running the command on the Schema Master, check that you do not have any shares on the<br />
Schema Master open. This will cause the command to fail.<br />
Domain <strong>Administrator</strong> Account<br />
In order to successfully update the Schema, you must know the username and password of a Domain<br />
<strong>Administrator</strong> account that is able to log into the Schema Master. You must either run the command while logged<br />
in as that user, or pass the credentials to the command in the parameters. The Domain <strong>Administrator</strong> must have<br />
permission to extend the Schema – they must be a member of the Schema Admins group in the Forest-Root-<br />
Domain (the first Domain created in the Forest).<br />
Schema Changes Allowed<br />
By default, Active Directory does not permit Schema extensions to be made. There is a registry setting that must<br />
be changed to allow extensions. If this is not already set, DPADadmin will ask you whether it should change the<br />
setting itself or not. If you click on Yes, it will change the setting itself, make the extensions then change it back<br />
again.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 35
Active Directory Schema<br />
If you would prefer to change the setting manually, log into the Schema Master and change the value of the<br />
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NTDS\ Parameters\Schema Update Allowed<br />
registry key to 1, adding it as a value of type DWORD if it does not already exist. Alternatively, if the Schema<br />
Manager MMC snap-in is installed on the machine, this can be used to enable or disable Schema extensions.<br />
If you have disabled the Schema extensions after removing a previous installation in the Forest, reactivate them<br />
before using this command. This can be done using the Schema Manager MMC snap-in used to deactivate them.<br />
Extend the Schema on the Schema Master<br />
1. Log into the Schema Master as a member of the Schema <strong>Administrator</strong>s group.<br />
2. Copy dpadadmin.exe onto the Schema Master<br />
3. Open a command prompt in the location to which it was copied.<br />
4. Type:<br />
dpadadmin addschema<br />
5. If DPADadmin detects that Schema extensions are not currently permitted, it will prompt you whether to<br />
enable them or not. Enter y to enable them, or n to cancel.<br />
The progress and success/failure of the command will be displayed in the command prompt window. If there was<br />
a failure, it can be run again after the problem has been rectified.<br />
Extend the Schema on the <strong>Identikey</strong> <strong>Server</strong><br />
1. Open a command prompt and navigate to the installation’s bin directory by typing:<br />
2. Type:<br />
cd \bin<br />
dpadadmin addschema –master schema_master –u user_name –p password<br />
3. See Command Line Syntax for more details regarding the required parameters.<br />
4. If DPADadmin detects that Schema extensions are not allowed, it will prompt you to enable them. Enter y to<br />
enable them, or n to cancel.<br />
The progress and success/failure of the command will be displayed in the command prompt window. If there was<br />
a failure, it can be run again after the problem has been rectified.<br />
Active Directory Replication Interval<br />
If Active Directory is running replication between multiple domain controllers, allow time for the schema changes to<br />
be replicated across the system. The DPADadmin checkschema command may be used to check this – see 2.5.2<br />
Check Schema Extensions for more information.<br />
Command Line Syntax<br />
dpadadmin addschema [–master schema_master] [–u user_name [–p password]]<br />
[-q]<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 36
Table 7: DPADadmin addschema Command Line Options<br />
Option Description<br />
Active Directory Schema<br />
-master Fully qualified name of the Domain Controller with the Schema Master role. This option may<br />
be omitted if the command is run directly on the Schema Master.<br />
-u User name of a Domain <strong>Administrator</strong> in the Schema <strong>Administrator</strong>s group. This option may be<br />
omitted if you are logged into the machine as that Domain <strong>Administrator</strong> when you run the<br />
command.<br />
-p Password of the Domain <strong>Administrator</strong>. This option may be omitted if you are logged in as that<br />
Domain <strong>Administrator</strong> or if they have a blank password.<br />
-q Quiet mode, will not output commentary text.<br />
DPADadmin addschema Command Sample<br />
2.5.2 Check Schema Extensions<br />
dpadadmin addschema –master dc1.vasco.com –u schema_admin –p sa_password<br />
The checkschema command can be used to check that the Active Directory schema has been extended to include<br />
VASCO objects and attributes.<br />
2.5.2.1 Check the Database Structure<br />
1. Open a command prompt and go to the installation’s bin directory by typing:<br />
2. Type<br />
a. Open a command prompt and navigate to the installation’s bin directory by typing:<br />
cd \bin<br />
dpadadmin checkschema –u user_name –p password<br />
3. See below for more details regarding the parameters.<br />
The progress and success/failure of the command will be displayed in the command prompt window.<br />
2.5.2.2 Command Line Syntax<br />
dpadadmin checkschema [–u user_name [–p password]] [-m] [-d] [-q] [-v] [-l<br />
file_name]<br />
Table 8: DPADadmin checkschema Command Line Options<br />
Option Description<br />
-u User name of a Domain <strong>Administrator</strong> in the Schema <strong>Administrator</strong>s group. This option may be<br />
omitted if you are logged into the machine as that Domain <strong>Administrator</strong> when you run the<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 37
Option Description<br />
command.<br />
Active Directory Schema<br />
-p Password of the Domain <strong>Administrator</strong>. This option may be omitted if you are logged in as that<br />
Domain <strong>Administrator</strong> or if they have a blank password.<br />
-m Fully qualified name of the Domain Controller with the Schema Master role. This option may<br />
be omitted if the command is run directly on the Schema Master.<br />
-d Specify the domain in which the schema check should be run.<br />
-q Quiet mode, will not output commentary text.<br />
-v Verbose mode.<br />
-l Log output to file file_name.<br />
DPADadmin checkschema Command Sample<br />
dpadadmin checkschema –u schema_admin –p sa_password<br />
2.5.3 Set Up Digipass Containers in Domain<br />
This command sets up the Digipass-Pool and Digipass-Reserve containers in the specified domain. It can<br />
optionally set up the Digipass-Configuration container also.<br />
2.5.3.1 Prerequisite Information<br />
Domain <strong>Administrator</strong><br />
You must be logged into the machine as a Domain Admin in the target domain.<br />
2.5.3.2 Set Up Digipass Containers<br />
1. Log into the machine as a Domain <strong>Administrator</strong> in that Domain.<br />
2. Copy dpadadmin.exe onto the machine and open a command prompt in the location to which it was copied.<br />
3. Type:<br />
dpadadmin setupdomain<br />
The progress and success/failure of the command will be displayed in the command prompt window.<br />
2.5.3.3 Command Syntax<br />
dpadadmin setupdomain [-config] [-domain ] [-q]<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 38
Table 9: DPADadmin setupdomain Command Line Options<br />
Option Description<br />
Active Directory Schema<br />
-config OPTIONAL. Specifies that this is the Digipass Configuration Domain, so the Digipass-Configuration<br />
container must be created.<br />
-domain OPTIONAL. Specifies the FQDN of the domain to set up. If omitted, the domain to which the current<br />
machine belongs will be used.<br />
-q OPTIONAL. Specifies that quiet mode should be used.<br />
DPADadmin setupdomain Command Sample<br />
dpadadmin setupdomain -config -q<br />
2.5.4 Assign Digipass Permissions to a Group<br />
This command assigns Digipass-specific permissions to a Windows group, applicable at the domain root and<br />
downwards. The permissions assigned are:<br />
2.5.4.1 Pre-requisites<br />
Full read access to everything in the domain<br />
Full control over vasco-DPToken objects<br />
Full control over vasco-DPApplication objects<br />
Full write access to vasco-UserExt auxiliary objects<br />
You must be logged into the machine as a Domain Admin in the target domain.<br />
2.5.4.2 Command Syntax<br />
dpadadmin.exe setupaccess -group [-domain ] [-q] [-c]<br />
Table 10: DPADadmin setupaccess Command Line Options<br />
Option Description<br />
-group MANDATORY. Specify the name of the group to assign the permissions. Double-quotes<br />
are required if there are any spaces.<br />
-domain OPTIONAL. Specify the fully-qualified domain name for the domain to which the group or<br />
user belongs. If omitted, the domain to which the current machine belongs will be used.<br />
-q OPTIONAL. Specify that quiet mode should be used.<br />
-c OPTIONAL. Add the local computer to the group named.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 39
DPADadmin setupaccess Command Sample<br />
dpadadmin.exe setupaccess -group “RAS and IAS <strong>Server</strong>s” -q<br />
2.5.5 Delete all Digipass-Related Data from Active Directory<br />
Active Directory Schema<br />
Digipass-specific information is not removed from Active Directory when <strong>Identikey</strong> <strong>Server</strong> is uninstalled from a<br />
computer.<br />
A custom VB script is available which will strip all information related to the <strong>Identikey</strong> <strong>Server</strong> from a domain. The<br />
data removed includes:<br />
Digipass-Configuration container if present<br />
VASCO Records in container:<br />
Policy<br />
Component<br />
Backend<strong>Server</strong><br />
Report<br />
Reportformat<br />
Configuration<br />
Offline authentication data<br />
Digipass-Pool container if present<br />
Digipass records in container<br />
Digipass-Reserve container if present<br />
Digipass records in container<br />
All Digipass in the domain, including all Digipass Applications.<br />
All Digipass User Accounts<br />
Each Digipass User account is deleted by searching for Active Directory Users with the vasco-CreateTime attribute<br />
set (indicating that a Digipass User account has been created for that User). All vasco-UserExt attributes on the<br />
Active Directory User are reset.<br />
Note<br />
The script must be run in each domain from which data is to be removed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 40
2.5.5.1 Run Delete Script on a Domain<br />
Active Directory Schema<br />
1. Get dpDeleteAll.vbs file from the CD – \Windows\Utilities\DpDeleteAll directory. Copy to the computer where<br />
you will run the command.<br />
2. Open cmd prompt, logged in as domain admin in the domain required.<br />
3. Enter the following:<br />
cscript dpDeleteAll.vbs [] [-v]<br />
4. If the machine does not belong to the target domain, specify the domain name<br />
5. If you want record-by-record progress display, specify -v (verbose mode).<br />
Example<br />
cscript dpDeleteAll.vbs dm3.vasco.com -v<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 41
3 ODBC Database<br />
3.1 Database Support<br />
Note<br />
ODBC Database<br />
An embedded database option is available in the Windows Basic installation program. This will<br />
install PostgreSQL 8.2 for you on the server.<br />
However, <strong>Identikey</strong> <strong>Server</strong> supports other ODBC-compliant databases, should you prefer to use<br />
your own database.<br />
<strong>Identikey</strong> <strong>Server</strong> makes use of a limited set of database features, in order to support as many RDBMS (Relational<br />
Database Management Systems) as possible:<br />
Tables (relations) with the following datatypes:<br />
INTEGER (32-bit)<br />
VARCHAR (up to 1024 characters; on Microsoft SQL <strong>Server</strong> this is NVARCHAR for Unicode support)<br />
LONGVARCHAR or TEXT (depending on the database type) is used for columns over 1024 characters if<br />
required by the database<br />
TIMESTAMP (for some databases, this is DATETIME or DATE – this is not an automatically generated<br />
timestamp, but just a date/time field)<br />
Primary Key constraints<br />
Foreign Key constraints, using the default action (restrict) and cascade delete<br />
ANSI Standard SQL DML (Data Manipulation Language) – select, insert, update, delete, without any vendorspecific<br />
syntax<br />
Transactions with simple COMMIT and ROLLBACK (no 'save points' or equivalents)<br />
In order for a database to be supported, there must be an ODBC level 3 driver that supports:<br />
Multi-threaded access using multiple concurrent connections<br />
'Wide char' (Unicode) parameters for input and output<br />
The following databases have been specifically tested:<br />
Oracle 10g and Oracle 11g<br />
Microsoft SQL <strong>Server</strong> 2005 Full Enterprise Edition or Express<br />
IBM DB2 8.1 (on 32-bit platforms) and 9.1 (on 64-bit platforms)<br />
Sybase Adaptive <strong>Server</strong> Anywhere 10.0<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 42
PostgreSQL 8.2.5<br />
3.1.1 Unicode Support<br />
ODBC Database<br />
At a minimum, the database ODBC driver must allow the 'wide char' parameters to be used, as mentioned above.<br />
However, the underlying database does not necessarily need to be configured with Unicode support. The database<br />
only needs to be able to handle the characters that are actually used.<br />
If you do want full Unicode support in the database, refer to the database vendor's instructions. Normally, a<br />
database has to be created with Unicode storage from the start. Depending upon the database type, some of the<br />
columns in the database need to be increased in size, to handle multi-byte UTF-8 encoded data. The database<br />
documentation should indicate whether VARCHAR columns are defined by number of characters or number of<br />
bytes.<br />
3.2 Embedded Database<br />
The embedded database option supplied with <strong>Identikey</strong> <strong>Server</strong> for Windows uses PostgreSQL 8.2. The database<br />
server is installed as a Service and a single database created. This database has full Unicode support.<br />
The full PostgreSQL install package is used, so the database administation tools and documentation are available.<br />
The package is installed under the <strong>Identikey</strong> <strong>Server</strong> installation directory.<br />
3.2.1 Service Account<br />
Windows<br />
A local Windows account called dppostgres is created on the installation machine. This account is given privileges<br />
to log on as a service and locally. If installed on a domain controller, this account will be a domain account. The<br />
privileges to log on locally may be removed manually after installation if preferred, without preventing PostgreSQL<br />
from running.<br />
Note<br />
The dppostgres account is not automatically deleted upon uninstallation of PostgreSQL.<br />
The default password for dppostgres is p!ss&0rd. This can be changed using the standard Windows or Active<br />
Directory user management interface. If you do this, make sure that the Windows Service Control Manager is<br />
configured with the new password. The PostgreSQL service is PostgreSQL Database <strong>Server</strong> 8.2.<br />
If you have changed the password when you uninstall and reinstall the product, either delete the dppostgres<br />
account or change its password back to the default password shown above before re-installing. Otherwise, reinstallation<br />
of PostgreSQL will fail.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 43
Linux<br />
ODBC Database<br />
During Linux Simple Installation a postgres daemon user account is created, which is assigned the correct<br />
permissions to run the PostgreSQL server. The PostgreSQL server is registered as a Linux daemon which runs<br />
under the postgres account.<br />
3.2.2 Database Administration Account<br />
A single database administrator account called digipass is created when the embedded database is installed, with<br />
password digipassword. It has full administration and access rights to the database.<br />
This account is used by the <strong>Identikey</strong> <strong>Server</strong> to connect to the database. If you use an SQL or database<br />
administration tool to connect to the database, you can also use this account.<br />
If you want to change the password, you can do this using the pgAdmin III utility. See 3.2.3 Database<br />
Administration below.<br />
3.2.3 Database Administration<br />
Windows<br />
The full set of PostgreSQL administration tools are installed with the embedded database. For a full description,<br />
refer to the PostgreSQL documentation that is installed with the product.<br />
The main tool to use is pgAdmin III, which is a graphical administration interface. This can be launched by clicking<br />
on the Start Button and selecting Programs -> PostgreSQL 8.2 -> pgAdmin III.<br />
To connect to the database, right-click on the <strong>Server</strong>s -> PostgreSQL Database <strong>Server</strong> 8.2 node in the tree pane<br />
and select the Connect option. You will be prompted for the password for the digipass user – the default after<br />
installation is digipassword.<br />
After logging in, you can perform a range of database administration tasks. See the online help for more details on<br />
what can be done with the utility.<br />
The 6 Backup and Recovery section includes instructions on the pg_dump, pg_restore and vacuumdb utilities.<br />
Linux<br />
For Linux the PostgreSQL command line utilities are installed. For a full description of the command line utilities<br />
refer to the PostgreSQL documentation installed with the product.<br />
3.2.3.2 Changing the Digipass User's Password<br />
After logging in as described above, expand the Login Roles node in the tree pane. Right-click on the digipass<br />
node underneath and select Properties. Enter the new password, confirm it and click OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 44
1. Run pgAdmin III and connect as described above.<br />
2. Expand the Login Roles node in the tree pane.<br />
3. Right-click on the digipass node underneath and select Properties.<br />
4. Enter the new Password and confirm it in Password (again).<br />
5. Click on OK.<br />
ODBC Database<br />
6. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility: click on the Start Button and select Programs -> VASCO -><br />
<strong>Identikey</strong> <strong>Server</strong> -> <strong>Identikey</strong> <strong>Server</strong> Configuration.<br />
7. Click on the Storage section.<br />
8. Click on the <strong>Identikey</strong> <strong>Server</strong> row in the ODBC Data Sources list and click the Edit... button.<br />
9. Modify the Password field with the new password and click Test Connection. <strong>Identikey</strong> <strong>Server</strong><br />
Configuration will test that it can connect to the database using the new password and inform you of the<br />
result.<br />
10. If connection failed, make sure you have entered the password correctly and try again. If it still fails, cancel<br />
out of <strong>Identikey</strong> <strong>Server</strong> Configuration and try repeating the whole procedure from step 1.<br />
11. Click OK.<br />
12. Click OK to exit <strong>Identikey</strong> <strong>Server</strong> Configuration. When prompted to restart the Service, click Yes.<br />
3.2.4 Connection Limitations<br />
The embedded database install leaves PostgreSQL with the default configuration, that connections to the database<br />
may only be made on the same machine. If you need to connect from another machine to the database, you need<br />
to update the configuration.<br />
In order to allow connection from another machine, you need to modify a PostgreSQL configuration file. Edit the<br />
configuration file with a text editor. This file can be found at:<br />
\PostgreSQL\data\pg_hba.conf (Windows)<br />
/opt/vasco/identikey/usr/local/pgsql/data/pg_hba.conf (Linux)<br />
At the bottom of this file, there is a list of rules for authenticating connections to the database, which by default will<br />
be:<br />
# TYPE DATABASE USER CIDR-ADDRESS METHOD<br />
# IPv4 local connections:<br />
host all all 127.0.0.1/32 md5<br />
# IPv6 local connections:<br />
#host all all ::1/128 md5<br />
Refer to the PostgreSQL documentation for more details. As an example, to permit access from IP address<br />
10.10.1.50 by the digipass user to the postgres database, add the following line directly below # Ipv4 local<br />
connections:<br />
host postgres digipass 10.10.1.50/32 md5<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 45
3.3 Database Schema<br />
ODBC Database<br />
Digipass-related data is stored in a number of tables that are created using the DPDBADMIN command line utility:<br />
Table 11: ODBC Database Tables<br />
Table Name Notes<br />
vdsControl This table is used to control various details about the database schema and<br />
connection.<br />
vdsUser Contains Digipass User Account details.<br />
vdsUserAttr Authorization profiles/attributes (not used for all scenarios).<br />
vdsDigipass Information about individual Digipass, including the Digipass User to which they<br />
are assigned.<br />
vdsDPApplication Data for Applications belonging to each Digipass, such as <strong>Server</strong> PIN and<br />
expected OTP length.<br />
vdsDPSoftParams Data required for Software Digipass Provisioning (the 'Static Vector' used to<br />
generate Activation Codes).<br />
vdsPolicy Policy attributes. Attributes will commonly be shared via inheritance.<br />
vdsComponent Component attributes include the License Key for <strong>Identikey</strong> <strong>Server</strong>s.<br />
vdsBackEnd Back-End <strong>Server</strong> attributes. This includes RADIUS and LDAP server information.<br />
vdsDomain Domain list.<br />
vdsOrgUnit Organizational Unit structure.<br />
vdsReport Report definitions.<br />
vdsReportFormat Formatting templates for reports.<br />
vdsConfiguration Configuration settings for the <strong>Identikey</strong> <strong>Server</strong>.<br />
vdsOfflineAuthData Offline authentication data. This is included for future releases of <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
3.3.1 vdsControl Table<br />
Table 12: vdsControl Table<br />
Name Type Required?<br />
vdsName varchar(64) Yes<br />
vdsValue varchar(512)<br />
vdsFlags integer<br />
Primary Key: (vdsName)<br />
Foreign Keys: None<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 46
3.3.2 vdsUser Table<br />
Table 13: vdsUser Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsUserId varchar(255) Yes<br />
vdsOrgUnit varchar(255)<br />
vdsUserName varchar(64)<br />
vdsDescription varchar(1024)<br />
vdsPhone varchar(64)<br />
vdsMobile varchar(64)<br />
vdsEmail varchar(64)<br />
vdsStaticPwd varchar(690)*<br />
vdsLinkUserDomain varchar(255)<br />
vdsLinkUserId varchar(255)<br />
vdsLocalAuth integer<br />
vdsBackEndAuth integer<br />
vdsLockCount integer<br />
vdsLocked integer<br />
vdsDisabled integer<br />
vdsProfiles** varchar(255)<br />
vdsAdminPrivileges varchar(255)*<br />
vdsOfflineAuthEnabled integer<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
* This column contains binary data stored in base64-encoded format.<br />
** This column is obsolete (replaced by the separate vdsUserAttr table).<br />
Primary Key: (vdsDomain, vdsUserId)<br />
Foreign Keys:<br />
(vdsDomain) references vdsDomain<br />
(vdsDomain, vdsOrgUnit) references vdsOrgUnit<br />
(vdsLinkUserDomain, vdsLinkUserId) references vdsUser<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 47
3.3.3 vdsUserAttr Table<br />
Table 14: vdsUserAttr Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsUserId varchar(255) Yes<br />
vdsAttrGroup varchar(64) Yes<br />
vdsSeqNo integer Yes<br />
vdsName varchar(64) Yes<br />
vdsUsageQual varchar(64)<br />
vdsValue varchar(255)<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
Primary Key: (vdsDomain, vdsUserId, vdsAttrGroup, vdsSeqNo)<br />
Foreign Keys:<br />
3.3.4 vdsDigipass Table<br />
(vdsDomain, vdsUserId) references vdsUser (ON DELETE CASCADE)<br />
Table 15: vdsDigipass Table<br />
Name Type Required?<br />
vdsSerialNo varchar(32) Yes<br />
vdsDomain varchar(255) Yes<br />
vdsOrgUnit varchar(255)<br />
vdsDPType varchar(32)<br />
vdsUserId varchar(255)<br />
vdsAssignDate timestamp<br />
vdsGPExpires timestamp<br />
vdsBVDPEnabled integer<br />
vdsBVDPExpires timestamp<br />
vdsBVDPUsesLeft integer<br />
vdsDirectAssign integer<br />
vdsDPSoftParamsID varchar(64)<br />
vdsActivLocs varchar(1024)<br />
vdsActivCount integer<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 48
Name Type Required?<br />
vdsLastActivTime timestamp<br />
vdsDPDescription varchar(255)<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
Primary Key: (vdsSerialNo)<br />
Foreign Keys:<br />
(vdsDomain) references vdsDomain<br />
(vdsDomain, vdsOrgUnit) references vdsOrgUnit<br />
(vdsDomain, vdsUserId) references vdsUser<br />
(vdsDPSoftParamsID) references vdsDPSoftParams<br />
3.3.5 vdsDPApplication Table<br />
Table 16: vdsDPApplication Table<br />
Name Type Required?<br />
vdsSerialNo varchar(32) Yes<br />
vdsApplName varchar(32) Yes<br />
vdsApplNo integer<br />
vdsApplType integer<br />
vdsActive integer<br />
vdsBlob varchar(255)<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
Primary Key: (vdsSerialNo, vdsApplName)<br />
Foreign Keys:<br />
(vdsSerialNo) references vdsDigipass<br />
3.3.6 vdsDPSoftParams Table<br />
Table 17: vdsDPSoftParams Table<br />
Name Type Required?<br />
vdsDPSoftParamsID varchar(64) Yes<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 49
Name Type Required?<br />
vdsStaticVector varchar(1024) Yes<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
Primary Key: (vdsDPSoftParamsID)<br />
Foreign Keys: None<br />
3.3.7 vdsPolicy Table<br />
Table 18: vdsPolicy Table<br />
Name Type Required?<br />
vdsPolicyId varchar(60) Yes<br />
vdsDescription varchar(255)<br />
vdsParentPolicyId varchar(60)<br />
vdsDUR integer<br />
vdsAutoLearn integer<br />
vdsSPwdProxy integer<br />
vdsAssignMode integer<br />
vdsSearchUpOU integer<br />
vdsApplNames varchar(255)<br />
vdsApplType integer<br />
vdsDPTypes varchar(255)<br />
vdsGracePeriod integer<br />
vdsLocalAuth integer<br />
vdsBackEndAuth integer<br />
vdsBackEndProtocol varchar(32)<br />
vdsDefDomain varchar(255)<br />
vdsGroupList varchar(1024)<br />
vdsGroupMode integer<br />
vdsOSCR integer<br />
vdsOSCLength integer<br />
vdsOSCChkDgt integer<br />
vdsBVDPEnabled integer<br />
vdsBVDPMaxDays integer<br />
vdsBVDPMaxUses integer<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 50
Name Type Required?<br />
vdsChgPinAllowed integer<br />
vdsSelfAssignSep varchar(8)<br />
vdsCRMethod integer<br />
vdsCRKeyword varchar(16)<br />
vdsPVDPRqstMeth integer<br />
vdsPVDPKeyword varchar(16)<br />
vdsBVDPRqstMeth integer<br />
vdsBVDPKeyword varchar(16)<br />
vdsITimeWindow integer<br />
vdsSTimeWindow integer<br />
vdsEventWindow integer<br />
vdsSyncWindow integer<br />
vdsIThreshold integer<br />
vdsSThreshold integer<br />
vdsCheckChal integer<br />
vdsOnlineSG integer<br />
vdsChkInactDays integer<br />
vdsOTPSyncEnabled integer<br />
vdsDCR integer<br />
vdsChgWinPwdEnabled integer<br />
vdsChangeWinPwdLength integer<br />
vdsClientGroupMode integer<br />
vdsCreateTime timestamp Yes<br />
vdsModifyTime timestamp Yes<br />
vdsLockThreshold integer<br />
Primary Key: (vdsPolicyId)<br />
Foreign Keys:<br />
(vdsParentPolicyId) references vdsPolicy<br />
3.3.8 vdsComponent Table<br />
Table 19: vdsComponent Table<br />
Name Type Required?<br />
vdsComponentType varchar(60) Yes<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 51
Name Type Required?<br />
vdsLocation varchar(255) Yes<br />
vdsPolicyId varchar(80) Yes<br />
vdsProtocolId varchar(32)<br />
vdsTCPPort integer<br />
vdsSharedSecret varchar(690)*<br />
vdsLicenseKey varchar(1024)<br />
vdsPubKey varchar(1024)<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
* This column contains binary data stored in base64-encoded format.<br />
Primary Key: (vdsComponentType, vdsLocation)<br />
Foreign Keys:<br />
(vdsPolicyId) references vdsPolicy<br />
3.3.9 vdsBackEnd Table<br />
Table 20: vdsBackEnd Table<br />
Name Type Required?<br />
vds<strong>Server</strong>Id varchar(80) Yes<br />
vdsProtocolId varchar(32)<br />
vdsDomain varchar(255)<br />
vdsPriority integer<br />
vdsAuthAddr varchar(128)<br />
vdsAuthPort integer<br />
vdsRadAcctAddr varchar(128)<br />
vdsRadAcctPort integer<br />
vdsRetries integer<br />
vdsTimeout integer<br />
vdsRadSharedSecret varchar(690)*<br />
vdsDirBaseDN varchar(512)<br />
vdsSecPrincplDN varchar(512)<br />
vdsSecPrincplPwd varchar(32)<br />
vdsDirAuth varchar(32)<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 52
Name Type Required?<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
* This column contains binary data stored in base64-encoded format.<br />
Primary Key: (vds<strong>Server</strong>Id)<br />
Foreign Keys: None<br />
3.3.10 vdsDomain Table<br />
Table 21: vdsDomain Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsDescription varchar(1024)<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
Primary Key: (vdsDomain)<br />
Foreign Keys: None<br />
3.3.11 vdsOrgUnit Table<br />
Table 22: vdsOrgUnit Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsOrgUnit varchar(255) Yes<br />
vdsDescription varchar(1024)<br />
vdsParentOrgUnit varchar(255)<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
Primary Key: (vdsDomain, vdsOrgUnit)<br />
Foreign Keys:<br />
(vdsDomain) references vdsDomain<br />
(vdsDomain, vdsParentOrgUnit) references vdsOrgUnit<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 53
3.3.12 vdsReport Table<br />
Table 23: vdsReport Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsReportID varchar(64) Yes<br />
vdsReportName varchar(64) Yes<br />
vdsReportDesc varchar(255) Yes<br />
vdsDataSource integer Yes<br />
vdsGroupLevel integer Yes<br />
vdsReportType integer Yes<br />
vdsRunPerms integer Yes<br />
vdsChangePerms integer Yes<br />
vdsTimeFreq integer Yes<br />
vdsQueryDef varchar(1024) Yes<br />
vdsUserID varchar(255)<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
Primary Key: (vdsDomain, vdsReportID)<br />
Foreign Keys:<br />
(vdsDomain) references vdsDomain<br />
(vdsDomain, vdsUserID) references vdsUser<br />
3.3.13 vdsReportFormat Table<br />
Table 24: vdsReportFormat Table<br />
Name Type Required?<br />
vdsDomain varchar(255) Yes<br />
vdsReportID varchar(64) Yes<br />
vdsFmtName varchar(64) Yes<br />
vdsFmtDef varchar(32768)* Yes<br />
vdsCreateTime Timestamp Yes<br />
vdsModifyTime Timestamp Yes<br />
* This column contains binary data stored in base64-encoded format.<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 54
Primary Key: (vdsDomain, vdsReportID, vdsFmtName)<br />
Foreign Keys:<br />
(vdsDomain, vdsReportID) references vdsReport<br />
3.3.14 vdsConfiguration Table<br />
Table 25: vdsConfiguration Table<br />
Name Type Required?<br />
vdsName varchar(512) yes<br />
vdsValue varchar(512)<br />
vdsCreateTime timestamp yes<br />
vdsModifyTime timestamp yes<br />
Primary Key: vdsName<br />
Foreign Keys: None<br />
3.3.15 vdsOfflineAuthData Table<br />
Table 26: vdsOfflineAuthData Table<br />
Name Type Required?<br />
vdsComponentType varchar(60) yes<br />
vdsLocation varchar(255) yes<br />
vdsDomain varchar(255) yes<br />
vdsUserId varchar(255) yes<br />
vdsEventWindow integer<br />
vdsEventCounter integer<br />
vdsStartTime timestamp<br />
vdsEndTime timestamp<br />
vdsReGenRequired integer<br />
vdsCreateTime timestamp yes<br />
vdsModifyTime timestamp yes<br />
Primary Key: vdsComponentType, vdsLocation, vdsDomain, vdsUserid<br />
Foreign Keys: vdsComponentType, vdsLocation, vdsDomain, vdsUserid<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 55
3.4 Encoding and Case-Sensitivity<br />
ODBC Database<br />
When you create the database, depending on the database type, you may have the chance to select a collation<br />
sequence. The collation sequence determines both the sort order and the case-sensitivity of the database. If you<br />
do not have the chance to select the collation sequence, it is advisable to find out how it is already defined.<br />
The encoding used by the database is important when considering support for non-English languages. You must<br />
ensure that the database will be able to store the data in whatever languages may be used in your system.<br />
Case-sensitivity is of particular importance when looking up a Digipass User account. It determines whether the<br />
user must get the correct case for their UserId when logging in. For example, if your database collation sequence is<br />
case-sensitive, user “JSmith” would have to log in as exactly “JSmith”, not “jsmith”. If you want a case-insensitive<br />
User ID and domain lookup, and your database does not behave this way by default, you have two choices:<br />
Choose a case-insensitive collation sequence for the database.<br />
Use a configuration option in <strong>Identikey</strong> <strong>Server</strong> to convert User ID and Domain names to all upper or all lower<br />
case.<br />
Caution<br />
The configuration setting for case-sensitivity can be set up in the <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
Wizard before data is entered into the database. This setting can be changed later using the<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration utility. However, since the new setting value may invalidate<br />
existing Digipass User accounts and Domain records, additional work may be required.<br />
For example, if you have a User ID in upper or mixed case and you change the setting to convert<br />
to lower case, the Digipass User account with this User ID will need to be deleted and recreated.<br />
This setting is especially important for the Master Domain. If you plan to configure the <strong>Identikey</strong><br />
<strong>Server</strong> to convert User IDs and Domains to upper case, change the name of the Master Domain<br />
before changing the case setting. See 3.5.1.1 Master Domain for more information.<br />
The embedded database created by the installation program uses UTF-8 encoding. In addition, as this results in<br />
case-sensitive collation, the option to convert User IDs and domain names to lower case is set by default.<br />
3.5 Domains and Organizational Units<br />
The concepts of Domain and Organizational Unit are present in <strong>Identikey</strong> <strong>Server</strong> for the purpose of grouping<br />
users. They closely match the concepts of the same names in Active Directory/LDAP, but they are not identical.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 56
3.5.1 Domains<br />
ODBC Database<br />
Domains are essentially separate sub-databases of Digipass User accounts and Digipass. All Digipass User<br />
accounts and Digipass must belong to a Domain. The Domain is used as a naming scope for the UserId – it is<br />
allowed to have two different Digipass User accounts with the same UserId, so long as they are in different<br />
Domains.<br />
3.5.1.1 Master Domain<br />
When <strong>Identikey</strong> <strong>Server</strong> is installed, a single Domain will be created in the database, the Master Domain. By<br />
default, all new Digipass User accounts and Digipass will be created in that Domain.<br />
A Domain must be chosen for a Digipass User account when it is created, as the Domain makes up part of the<br />
identification (primary key) for the account. A Digipass User account may not be moved to a different Domain. It<br />
must be deleted and recreated in the required Domain.<br />
Digipass, however, may be moved to the required Domain after import. The 'primary key' of the Digipass record<br />
consists only of its Serial Number, which cannot be duplicated in different Domains.<br />
A Digipass that is assigned to a Digipass User account must belong to the same Domain as the account.<br />
Therefore, you need to ensure that the correct numbers of Digipass are allocated to the different Domains.<br />
<strong>Administrator</strong>s belonging to the Master Domain may be assigned administration privileges for all Domains in the<br />
database, or just their own Domain. <strong>Administrator</strong>s belonging to any other Domain will have the assigned<br />
administration privileges for that Domain only.<br />
If you do not need to use the concept of Domains in your system, then you can leave all Digipass User accounts<br />
and Digipass in the Master Domain.<br />
You can designate a different Domain as the Master Domain using the <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard. You<br />
can change it later using the <strong>Identikey</strong> <strong>Server</strong> Configuration utility, Storage section, Advanced Settings tab.<br />
Modify the Master Domain<br />
You might need to modify the domain used as the Master Domain if:<br />
You want new Digipass User accounts and Digipass records to be created in a different domain by default<br />
You want to change the name of the Master Domain<br />
The case used in the name of the Master Domain will not be compatible with <strong>Identikey</strong> <strong>Server</strong> configuration<br />
settings<br />
For instructions on changing the domain used as the Master Domain, see Master Domain in 11.3.6.4 Advanced<br />
Configuration Settings.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 57
3.5.1.2 Identifying the Domain for a Login Attempt<br />
ODBC Database<br />
As the Domain is part of the naming scope for a Digipass User account, the Domain must be identified when a<br />
user attempts to log in.<br />
Image 1: Domain Identification Logic<br />
When Windows Back-End Authentication is used, the Domain of a Digipass User account must match the Domain<br />
of their corresponding Windows (Active Directory) user account. In this situation, the Use Windows User Name<br />
Resolution feature would typically be used, in case the same user logs in with different Windows user name<br />
formats (DOMAIN\userid, userid@domain.com, userid). You can enable this feature using the <strong>Identikey</strong> <strong>Server</strong><br />
Configuration interface, Configure Advanced Settings screen.<br />
Without Windows name resolution, a simple rule is applied to identify the Domain of a user who is logging in: if the<br />
UserId is in the form userid@domain, and there is a Domain with the given domain name, that Domain will be<br />
used. In that case, the UserId will have the @domain part removed. Otherwise, the whole UserId will remain as<br />
userid@domain and no Domain will be identified.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 58
ODBC Database<br />
If a Domain cannot be identified via name resolution, the applicable Policy will be checked. If a Default Domain is<br />
specified in the Policy, it will be used for the login. If no Default Domain is specified in the Policy, the Master<br />
Domain will be used. The Master Domain is a configuration setting.<br />
3.5.2 Organizational Units<br />
Within a Domain, Organizational Units can be used to group Digipass User accounts and Digipass. They are<br />
primarily used in <strong>Identikey</strong> <strong>Server</strong> to allocate unassigned Digipass to groups of users such as offices or<br />
departments and to provide delegated administration by user group.<br />
Organizational Units can be created as a hierarchy, in a similar way to Active Directory/LDAP. It is not permitted to<br />
create a circular chain in the hierarchy.<br />
Digipass User accounts and Digipass do not have to belong to an Organizational Unit. If you do not need to use the<br />
Organizational Unit feature, you can ignore it.<br />
Organizational Units are not used as a naming scope in the same way as Domains. It is permitted to move Digipass<br />
User accounts and Digipass between Organizational Units whenever required. However, a Digipass that is assigned<br />
to a Digipass User Account must belong to the same Organizational Unit, as well as the same Domain. Upon<br />
assignment, or upon moving the Digipass User Account, the Digipass is moved automatically. It is not permitted to<br />
move an assigned Digipass – instead, you must move the Digipass User Account, which may have other Digipass<br />
assigned also.<br />
Organizational Units have no effect on the authentication process, with the exception of Auto- and Self-Assignment<br />
– the Digipass to be assigned must be in the same Organizational Unit as the Digipass User Account. However, if<br />
you enable the 'Search up Organizational Unit Hierarchy' Policy setting, the Digipass may be located higher up the<br />
Organizational Unit structure, provided it is still in the same Domain.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 59
3.6 Database User Accounts<br />
ODBC Database<br />
It is important to consider which database user accounts will be utilized when installing, running and administering<br />
<strong>Identikey</strong> <strong>Server</strong>. There are a few main roles that need to be considered:<br />
Schema creator. A database user account is needed to create the tables used by <strong>Identikey</strong> <strong>Server</strong>. Typically<br />
this would be either a fully privileged DBA account, or the account that will own the schema.<br />
Schema owner. This may be the same as the schema creator. If not, the schema creator can transfer<br />
ownership of the new tables after they have been created.<br />
<strong>Identikey</strong> <strong>Server</strong> account. This may be the same as the schema creator or owner, but you may prefer to use<br />
an account with less privileges.<br />
A few elements need to be taken into account when setting up these database user accounts.<br />
3.6.1 Permissions on the Tables<br />
The following permissions are required by the <strong>Identikey</strong> <strong>Server</strong> account:<br />
Table 27: Table Permissions Required<br />
Table Permissions Required<br />
vdsControl SELECT, INSERT*, UPDATE *<br />
All other tables SELECT, INSERT, UPDATE, DELETE<br />
3.6.2 Access to Another Schema<br />
Depending on the database type, there may be a problem with the <strong>Identikey</strong> <strong>Server</strong> database user account<br />
accessing the tables from another schema/user account. <strong>Identikey</strong> <strong>Server</strong> will access the tables according to the<br />
table names that are defined in the vdsControl table.<br />
If the tables are not accessible to the <strong>Identikey</strong> <strong>Server</strong> account without qualifying the table name (eg.<br />
schema.table), there are a few ways to solve the problem:<br />
Set the default schema or database. Some databases allow you to specify which schema or database a<br />
database user account will use by default when they log in. This may be a setting in the database itself or the<br />
ODBC data source<br />
Create views. You can create a view in the <strong>Identikey</strong> <strong>Server</strong> account's own schema for each table, that<br />
provides access to the table. The view names should match the table names. However, be careful that your<br />
database type permits the necessary INSERT, UPDATE and DELETE operations on the views (see the table<br />
above). Some database types provide only limited support for those operations or disallow them all.<br />
* The <strong>Identikey</strong> <strong>Server</strong> does not need INSERT and UPDATE permission on the vdsControl table itself. However, when the<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Wizard and the <strong>Identikey</strong> <strong>Server</strong> Configuration utility are used to configure Storage Advanced<br />
Settings, the same database user account is used as the <strong>Identikey</strong> <strong>Server</strong>, and at this time the INSERT and UPDATE<br />
permissions are needed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 60
ODBC Database<br />
Modify the vdsControl table. Provided that all applicable database user accounts need the schema qualifier in<br />
front of the table names, you can safely modify the vdsControl table entries to add the schema qualifier (see<br />
below). If you have just one <strong>Identikey</strong> <strong>Server</strong> account, this will be safe.<br />
Another possible solution is to create a vdsControl table in each applicable database user account's schema, that<br />
contains the necessary schema qualifier. However this is not recommended, as it is complex to set up and there<br />
are other settings in the vdsControl table other than the table names. It would be easy to end up with different<br />
settings in each table.<br />
3.6.2.1 Modify vdsControl Table<br />
There are two parts to this solution. Firstly, to make sure that the vdsControl table itself can be accessed; secondly,<br />
to update the remaining table names using the vdsControl table.<br />
The <strong>Identikey</strong> <strong>Server</strong> component uses a configuration setting in its configuration file identikeyconfig.xml to identify<br />
the vdsControl table name:<br />
VASCO->Storage->ODBC->Data-Sources->Data-Sourcesnn->Control-Table<br />
where nn is 01 for the first data source, 02 for the next, and so on. Each data source must be configured<br />
separately.<br />
Modification of the vdsControl table entries that define the table names must be performed using your database's<br />
SQL utility. The following entries in vdsControl are used to define the table names:<br />
Table 28: Table Names in vdsControl<br />
Table vdsName<br />
vdsUser user_table<br />
vdsUserAttr user_attr_table<br />
vdsDigipass dp_table<br />
vdsDPApplication dpappl_table<br />
vdsDPSoftParams dpsoft_params_table<br />
vdsPolicy policy_table<br />
vdsComponent comp_table<br />
vdsBackEnd backend_table<br />
vdsDomain domain_table<br />
vdsOrgUnit org_table<br />
vdsReport report_table<br />
vdsReportFormat report_format_table<br />
vdsConfiguration configuration_table<br />
VdsOfflineAuthData offlineauthdata_table<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 61
3.7 Database Connection Handling<br />
ODBC Database<br />
The <strong>Identikey</strong> <strong>Server</strong> can be configured with a few settings that control the connection to the database. These<br />
settings can be found in the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
3.7.1 Multiple Data Sources<br />
It is possible to make more than one database available to the <strong>Identikey</strong> <strong>Server</strong> by creating additional databases<br />
and corresponding ODBC data sources. The additional database(s) can be used for redundancy and/or simple load<br />
sharing.<br />
If this is done, it is critical that the second and subsequent databases are synchronized with the first database. You<br />
will have to use the methods available to your database type, according to the database vendor's instructions.<br />
Typical methods include mirroring, shadow databases and instantaneous replication.<br />
Simply by configuring a second data source, if all connections to the main data source fail and cannot be<br />
reopened, the <strong>Identikey</strong> <strong>Server</strong> will open connections to the second data source. Similarly, a third data source can<br />
be used when the first and second are both unavailable.<br />
3.7.2 Max. Connections<br />
There is a configurable limit on the number of connections to the data source that the <strong>Identikey</strong> <strong>Server</strong> will have<br />
open at one time. This will prevent too many connections being opened to the database in case of peak load.<br />
However, each request uses a connection for its duration, so the number of connections effectively limits the<br />
number of requests that can be concurrently executed. It may improve performance to increase this setting, when<br />
there are a lot of concurrent requests – provided that the database is able to handle the increased load.<br />
The effect of this setting depends on the characteristics of your ODBC driver and database. Some ODBC drivers<br />
may not open a separate connection to the database for each connection that is made to it; they may set up a<br />
'pool' of connections to the database or they may even just maintain a single connection.<br />
3.7.3 Connection Wait Time<br />
When the <strong>Identikey</strong> <strong>Server</strong> already has the maximum number of connections open and a new request arrives, it will<br />
wait a configurable amount of time for a connection to become available (unless the Enable Load Sharing option is<br />
used, see below). You may want to reduce this waiting time, to reduce the impact of an overload of requests.<br />
Alternatively you may want to increase the waiting time, to make it less likely that a request will be rejected due to<br />
a temporary 'spike' of requests.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 62
3.7.4 Idle Timeout<br />
ODBC Database<br />
After a period of peak load, there may be a large number of connections open to the database. The Idle Timeout<br />
setting can be used to configure how quickly the connections are closed after being idle for a period of time. It may<br />
reduce the load on the database to close these connections quickly. Alternatively, if the load is very irregular but is<br />
often high, you may prefer to keep idle connections open for longer.<br />
3.7.5 Enable Load Sharing<br />
A simple form of load sharing can be implemented if you make a second database available to the <strong>Identikey</strong><br />
<strong>Server</strong>. In fact, any number of databases can be added to the list of data sources, and the load can be shared<br />
across all of them.<br />
If you have more than one database available and the Enable Load Sharing option is used, the <strong>Identikey</strong> <strong>Server</strong> will<br />
open connections to the second database when it would exceed the maximum number of connections it is allowed<br />
to have to the first database. Similarly, it will open connections to the third database when it has reached the<br />
maximum for the second, and so on. In general, connections to the first database will be used when available, in<br />
preference to connections to any other database.<br />
3.7.6 Reconnect Intervals<br />
After the first data source has become unavailable, the <strong>Identikey</strong> <strong>Server</strong> will attempt at intervals to reconnect, even<br />
if it has successfully failed over to a second data source. It will always use the first data source in preference to the<br />
others.<br />
The Min. Reconnect Interval and Max. Reconnect Interval settings control the minimum and maximum intervals<br />
between retries respectively. The interval will start at the minimum and increase in steps until the maximum is<br />
reached. After that, the interval will stay at the maximum.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 63
3.8 DPDBADMIN<br />
3.8.1 Modify Database Schema<br />
ODBC Database<br />
The addschema command is used to create all required tables in an existing database, if they are not already<br />
there. Each table will be checked individually to see if it is already there and if not, will be added.<br />
This command is intended to be run manually by an administrator before <strong>Identikey</strong> <strong>Server</strong> is installed.<br />
It may be necessary to go through an approval process in your company before running this command. You may<br />
also need to have a database administrator run the command for you. This depends on your company’s structure<br />
and rules for control of the database.<br />
This command may also be used to create the tables required for auditing to an ODBC database.<br />
Prerequisite Information<br />
Database <strong>Administrator</strong> Account<br />
In order to successfully modify the database structure, you will need the username and password of a database<br />
administrator account that is able to make changes to the database schema – for example, creating tables. You<br />
must pass these credentials to the command in the parameters.<br />
Database Name<br />
You will need the ODBC Data Source Name of the database (as registered with Windows or Linux as an ODBC Data<br />
Source).<br />
Master Domain Name<br />
You can specify the name of the Master Domain (see 3.5.1.1 Master Domain)<br />
when you add the database schema.<br />
However if you do not do it at that time, the Configuration Wizard can change it.<br />
UserID/Domain Name Conversion<br />
The Case Conversion option for UserIDs and Domain names may be specified (see 3.4 Encoding and Case-<br />
Sensitivity for more information) during the database schema modification. Alternatively, the setting may be<br />
modified using the Configuration Wizard. This should, however, be finalised before User data is entered into the<br />
data store.<br />
Modify the Database Structure<br />
1. Follow the instructions for the installation that you have:<br />
2. Type:<br />
a. For Windows, open a command prompt and navigate to the installation’s bin directory by typing:<br />
cd \bin<br />
dpdbadmin addschema –u user_name –p password -d dsn<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 64
3. See below for more details regarding the required parameters.<br />
ODBC Database<br />
The progress and success/failure of the command will be displayed in the command prompt window. If there was<br />
a failure, it can be run again after the problem has been rectified.<br />
Command Line Syntax<br />
dpdbadmin addschema -d dsn [–u user_name] [–p password] [-domain<br />
domain_name] [-case case_conversion] [-vdsuser alternatename] [-vdsuserattr<br />
alternatename] [-vdsdomain alternatename] [-vdscontrol alternatename]<br />
[-vdsdigipass alternatename] [-vdsdpapplication alternatename] [-vdspolicy<br />
alternatename] [vdsbackend alternatename] [-vdscomponent alternatename]<br />
[-vdsorgunit alternatename] [-vdsdpsoftparams alternatename] [-vdsreport<br />
alternatename] [-vdsreportformat alternatename] [-audit] [-noserver]<br />
[-nouser] [-utf8factor factor] [-q] [-v] [-l file_name]<br />
Table 29: DPDBADMIN addschema Command Line Options<br />
Option Description<br />
-d ODBC Data Source Name (DSN)<br />
-u User name of a database administrator (if required).<br />
-p Password of the database administrator. This option may be omitted if they have a blank password.<br />
-domain Specify the Master Domain to be used. If not specified, it will be “master”. The Domain will be<br />
created if it does not already exist.<br />
-case Specify to convert User IDs and domain names to either upper or lower case. The value must be<br />
either “upper” or “lower”.<br />
vdsuser Alternative name for the Digipass User table to be created.<br />
vdsuserattr Alternative name for the Digipass User Attribute table to be created.<br />
vdsdomain Alternative name for the Domain table to be created.<br />
vdscontrol Alternative name for the Control table to be created.<br />
vdsdigipass Alternative name for the Digipass table to be created.<br />
vdsdpapplication Alternative name for the Digipass Application table to be created.<br />
vdspolicy Alternative name for the Policy table to be created.<br />
vdsbackend Alternative name for the Back-end <strong>Server</strong> table to be created.<br />
vdscomponent Alternative name for the Component table to be created.<br />
vdsorgunit Alternative name for the Organizational Unit table to be created.<br />
vdsdpsoftparams Alternative name for the DPSoft Parameters table to be created.<br />
vdsreport Alternative name for the Report Definition table to be created.<br />
vdsreportformat Alternative name for the Report Format table to be created.<br />
vdsconfiguration Alternative name for the Configuration table to be created.<br />
vdsofflineauthdata Alternative name for the Offline Authentication Data table to be created.<br />
-audit Create the Audit tables.<br />
-noserver Do not create the main tables used by the <strong>Identikey</strong> <strong>Server</strong>. This should only be used with the -audit<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 65
Option Description<br />
option, when you only want to create the auditing tables.<br />
-nouser Do not create Digipass User table. This option is not currently supported.<br />
ODBC Database<br />
-utf8factor On certain databases (such as Oracle and DB2), column sizes are specified in bytes, not characters,<br />
by default. When UTF-8 encoding is used to store data, for full Unicode support, one character may<br />
be represented as more than one byte. Normally 2 or 3 characters are used, depending on the<br />
language, but some characters require 4. If your data will include a lot of non-English characters,<br />
you can increase the size of certain columns by a factor to allow for the extra bytes. The value of the<br />
parameter should be 2, 3 or 4. Typically, 3 is sufficient. The columns affected by this are the User<br />
Name (not User ID) and various Description fields.<br />
On other databases, column sizes are specified in characters, and this parameter is not needed.<br />
-q Quiet mode, will not output commentary text.<br />
-v Verbose mode.<br />
-l Log output to file file_name.<br />
DPDBADMIN addschema Command Sample<br />
dpdbadmin addschema –u DBAdmin –p pwd3498 -d UserDb -domain mydomain -case<br />
lower<br />
This command will modify the database structure of the ODBC database with the data source name of UserDb. It<br />
uses a database administrator account with the User ID of DBAdmin and password pwd3498. A non-default<br />
Master Domain will be used, called “mydomain”. It specifies to convert domain names and User IDs to lower case.<br />
dpdbadmin addschema –u DBAdmin –p pwd3498 -d AuditDb -audit -noserver<br />
This command will create only the auditing tables in the ODBC database with the data source name of AuditDb. It<br />
uses a database administrator account with the User ID of DBAdmin and password pwd3498.<br />
3.8.2 Check Database Modifications<br />
The checkschema command is called from the <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard to check that all required<br />
database changes have been applied. Each table and field is checked individually to see if it exists within the<br />
database, but it will not be added if it does not exist.<br />
3.8.2.1 Prerequisite Information<br />
Database User Account<br />
Ensure that you know the username and password of a database user account for the database to be checked. It is<br />
suggested to use the <strong>Identikey</strong> <strong>Server</strong> database user account, as the database tables are required by that account,<br />
Database Name<br />
You will need the Data Source Name of the database (as registered with Windows or Linux as an ODBC Data<br />
Source).<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 66
3.8.2.2 Check the Database Structure<br />
1. Open a command prompt and go to the installation’s bin directory by typing:<br />
2. Type<br />
ODBC Database<br />
a. For Windows, open a command prompt and navigate to the installation’s bin directory by typing:<br />
cd \bin<br />
b. For Linux go to the location in which the ODBC data source was created.<br />
dpdbadmin checkschema –u user_name –p password -d dsn<br />
3. See below for more details regarding the parameters.<br />
The progress and success/failure of the command will be displayed in the command prompt window.<br />
3.8.2.3 Command Line Syntax<br />
dpdbadmin checkschema -d dsn [–u user_name] [–p password] [-audit]<br />
[-noserver] [-vdscontrol alternatename] [-q] [-v] [-l file_name]<br />
Table 30: DPDBADMIN checkschema Command Line Options<br />
Option Description<br />
-d ODBC Data Source Name (DSN)<br />
-u User name of a database user account (if required).<br />
-p Password of the database account. This option may be omitted if they have a blank password.<br />
-audit Check the Audit tables.<br />
-noserver Do not check the main tables used by the <strong>Identikey</strong> <strong>Server</strong>. This should only be used with the -audit option,<br />
when you only want to check the auditing tables.<br />
vdscontrol Alternative name for the Control table.<br />
-q Quiet mode, will not output commentary text.<br />
-v Verbose mode.<br />
-l Log output to file file_name.<br />
DPDBADMIN checkschema Command Sample<br />
dpdbadmin checkschema –u DBAdmin –p pwd3498 -d UserDb<br />
3.8.3 Remove Database Modifications<br />
This command removes from a database the tables added by the addschema command.<br />
It may be necessary to go through an approval process in your company before running this command. You may<br />
also need to have a database administrator run the command for you.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 67
3.8.3.1 Prerequisite Information<br />
Database <strong>Administrator</strong> Account<br />
ODBC Database<br />
In order to successfully modify the database structure, you will need the username and password of a database<br />
administrator account that is able to make changes to the database structure – for example, dropping tables. You<br />
must pass these credentials to the utility in the parameters of the command.<br />
Database Name<br />
You will need the Data Source Name of the database (as registered with Windows or Linux as an ODBC Data<br />
Source). This DSN must be registered on the computer from which the command line utility wil be run.<br />
3.8.3.2 Modify Database Structure<br />
1. Open a command prompt and navigate to the installation’s bin directory by typing:<br />
2. Type:<br />
a. For Windows, open a command prompt and navigate to the installation’s bin directory by typing:<br />
cd \bin<br />
b. For Linux go to the location in which the ODBC data source was created.<br />
dpdbadmin dropschema –u user_name –p password -d dsn<br />
3. See below for more details regarding the required parameters.<br />
The progress and success/failure of the command will be displayed in the command prompt window. If there was<br />
a failure, it can be run again after the problem has been rectified.<br />
3.8.3.3 Command Line Syntax<br />
dpdbadmin dropschema -d dsn [–u user_name] [–p password] [-audit]<br />
[-noserver] [-nouser] [-vdscontrol alternatename] [-q] [-v] [-l file_name]<br />
Table 31: DPDBADMIN dropschema Command Line Options<br />
Option Description<br />
-d ODBC Data Source Name (DSN)<br />
-u User name of a database administrator.<br />
-p Password of the database administrator. This option may be omitted if they have a blank password.<br />
-audit Drop the Audit tables.<br />
-noserver Do not drop the main tables used by the <strong>Identikey</strong> <strong>Server</strong>. This should only be used with the -audit<br />
option, when you only want to drop the auditing tables.<br />
-nouser Do not delete Digipass User table. This option is not currently supported.<br />
-q Quiet mode, will not output commentary text.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 68
Option Description<br />
-v Verbose mode.<br />
-l Log output to file file_name.<br />
DPDBADMIN checkschema Command Sample<br />
dpdbadmin dropschema –u DBAdmin –p pwd3498 -d UserDb<br />
ODBC Database<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 69
4 Sensitive Data Encryption<br />
Sensitive Data Encryption<br />
Sensitive data is encrypted by <strong>Identikey</strong> <strong>Server</strong> using an embedded key. If needed, this encryption may be<br />
strengthened by adding a custom key using the <strong>Identikey</strong> <strong>Server</strong> Configuration utility. The embedded and custom<br />
keys are subjected to a logical XOR process to produce a new key derived from both.<br />
You may also choose a different encryption algorithm (Cipher) if you prefer.<br />
All <strong>Identikey</strong> <strong>Server</strong>s MUST share the same encryption settings.<br />
Note<br />
4.1.1 Encrypted Data<br />
Encryption settings must be set before importing any Digipass. If you change the settings at a<br />
later date, all Digipass records will become invalidated, and require deleting and re-importing.<br />
Table 32: Encrypted Data Attributes - ODBC Database<br />
Column Table<br />
vdsStaticPwd vdsUser<br />
vdsAdminPrivileges vdsUser<br />
vdsSharedSecret vdsComponent<br />
vdsSharedSecret vdsBackEnd<br />
Table 33: Encrypted Data Attributes - Active Directory<br />
Column Table<br />
vasco-StaticPassword vasco-UserExt<br />
vasco-AdminPrivileges vasco-UserExt<br />
vasco-SharedSecret vasco-Component<br />
vasco-SharedSecret vasco-BackEnd<strong>Server</strong><br />
4.1.2 Which Encryption Algorithms can be used?<br />
3DES (default)<br />
3DES with 3 keys<br />
AES<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 70
4.1.3 Exporting Encryption Settings<br />
Sensitive Data Encryption<br />
Encryption settings may be exported to a password-protected text file from the <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
utility. This file must then be loaded to other <strong>Identikey</strong> <strong>Server</strong>s – see 11.3.6.3 Encryption for instructions.<br />
If using Active Directory as the data store for <strong>Identikey</strong> <strong>Server</strong>, the Digipass Extension for Active Directory Users and<br />
Computers snap-in may be used to export the settings:<br />
1. Open Active Directory Users and Computers.<br />
2. Right-click on the Users container and select the Digipass Extension Encryption Settings option.<br />
3. In the Configure Encryption Settings dialog, click the Import... button.<br />
4. Browse to the encryption settings file.<br />
5. Click on OK.<br />
6. Enter the required password.<br />
7. Click on OK.<br />
4.1.4 Digipass TCL Command-Line Administration<br />
If using Active Directory as the data store for <strong>Identikey</strong> <strong>Server</strong>, the customized encryption settings must be loaded<br />
into Digipass TCL Command-Line Administration if you use it to import Digipass.<br />
1. Open the file \Bin\dpadmincmd.xml in a text editor (or XML editing tool).<br />
2. Open the file \Bin\identikeyconfig.xml in a text editor (or XML editing tool).<br />
3. Copy and paste the whole VASCO -> Encryption section from <strong>Identikey</strong> <strong>Server</strong>, overwriting the same section<br />
in dpadmincmd.xml.<br />
4. Save dpadmincmd.xml and exit the editors.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 71
5 Set Up Active Directory Permissions<br />
5.1 Permissions Needed by the <strong>Identikey</strong> <strong>Server</strong><br />
Set Up Active Directory Permissions<br />
The <strong>Identikey</strong> <strong>Server</strong> Service runs under the 'Local System' account rather than as a named user account.<br />
Therefore, when connecting to Active Directory, the <strong>Identikey</strong> <strong>Server</strong> connects as the computer account, not a user<br />
account. The permissions that it has within Active Directory are the permissions of the computer account.<br />
An important exception to this occurs if you install the <strong>Identikey</strong> <strong>Server</strong> onto a Domain Controller. Any Service<br />
running as 'Local System' on a Domain Controller has all possible permissions to that Domain. In this case, no<br />
additional setup of permissions is required. Therefore, the rest of this section applies to the case where the<br />
<strong>Identikey</strong> <strong>Server</strong> is not on the Domain Controller.<br />
During installation, the computer account is added to the built-in 'RAS and IAS <strong>Server</strong>s' group in the Domain, as it<br />
will require the permissions assigned by default to this group.<br />
In order to function correctly, the <strong>Identikey</strong> <strong>Server</strong> requires the following permissions in Active Directory, that are<br />
not granted to 'RAS and IAS <strong>Server</strong>s' by default:<br />
Read access to the Digipass Configuration Container<br />
Read access to all User accounts (or at least, all who might need to be authenticated by the <strong>Identikey</strong> <strong>Server</strong>)<br />
Write access to the new attributes that are added to the User class for <strong>Identikey</strong> <strong>Server</strong> (these are in the<br />
auxiliary class vasco-UserExt)<br />
Full control over all Digipass (vasco-DPToken) and Digipass Application (vasco-DPApplication) objects<br />
Create and delete permission for Digipass (vasco-DPToken) objects in Organizational Units and containers<br />
(specifically the Digipass-Pool and Users containers)<br />
5.1.1 Giving Permissions to the <strong>Identikey</strong> <strong>Server</strong><br />
During installation, these additional permissions are granted to the 'RAS and IAS <strong>Server</strong>s' group automatically.<br />
There is also a manual way to grant these permissions, by running the 'setupaccess' command at the command<br />
prompt:<br />
dpadadmin.exe setupaccess -group “RAS and IAS <strong>Server</strong>s”<br />
See 2.5 DPADadmin Utility for more information on the setupaccess command.<br />
As mentioned above, this is not necessary if the <strong>Identikey</strong> <strong>Server</strong> is installed onto a Domain Controller.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 72
5.2 Permissions Needed by <strong>Administrator</strong>s<br />
5.2.1 Domain <strong>Administrator</strong>s<br />
Domain <strong>Administrator</strong>s already have all required permissions within their Domain.<br />
5.2.2 Delegated <strong>Administrator</strong>s<br />
Set Up Active Directory Permissions<br />
The term 'Delegated <strong>Administrator</strong>s' is used here to refer to administrators who have been delegated control over<br />
an Organizational Unit. Generally speaking, they have administrative control over the user and computer accounts<br />
within their Organizational Unit.<br />
See the Digipass Records topic in the Product Guide for more information on possible approaches to delegating<br />
Digipass administration.<br />
By default, these administrators will be able to view the Digipass User Account data for their users and the<br />
Digipass that are located within their Organizational Unit. However, they will not be able to modify any of that data<br />
or assign Digipass.<br />
If you wish to delegate responsibility for all Digipass-related administration within an Organizational Unit, the<br />
following additional permissions are required by the Delegated <strong>Administrator</strong>:<br />
Within the scope of the Organizational Unit, Write permission to the new attributes that are added to the User<br />
class for <strong>Identikey</strong> <strong>Server</strong> (these are in the auxiliary class vasco-UserExt) – you can add Write permissions for<br />
each individual Property Set or if appropriate, grant 'Write All Properties' permission<br />
Within the scope of the Organizational Unit, Full Control over all Digipass (vasco-DPToken) and Digipass<br />
Application (vasco-DPApplication) objects<br />
Create and Delete permission for Digipass (vasco-DPToken) objects within the Organizational Unit<br />
If the Delegated <strong>Administrator</strong> should be allowed to assign Digipass from the Digipass Pool to their users, they<br />
need:<br />
the Delete Digipass objects permission in the Digipass-Pool container<br />
Write All Properties permission on Digipass objects in the Digipass-Pool container<br />
If the Delegated <strong>Administrator</strong> should be allowed to move unassigned Digipass back to the Digipass-Pool, they<br />
need Create Digipass objects permission in the Digipass-Pool container<br />
5.2.3 Reduced-Rights <strong>Administrator</strong>s<br />
The term 'Reduced-Rights <strong>Administrator</strong>' is used here to refer to administrators who are granted permissions to<br />
perform only selected Digipass-related administration tasks. They may be granted these permissions within the<br />
scope of the whole Domain, or only within an Organizational Unit.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 73
Set Up Active Directory Permissions<br />
An example is a Helpdesk operator who is permitted to troubleshoot Digipass operations, but not to<br />
assign/unassign Digipass to/from users.<br />
By default, all users have read access to everything in the Active Directory. The modification permissions that can<br />
be granted to this kind of administrator are:<br />
Write permission for any of three Property Sets on the Digipass User Account fields:<br />
Digipass User Account Information – all attributes except those covered by the other two Property Sets,<br />
including Authorization Profiles/Attributes<br />
Digipass User Account Link – the link attribute used to share a Digipass between two user accounts<br />
Digipass User Account Stored Password – the Stored Password attribute<br />
Write permission for any individual properties on Digipass objects, except for one Property Set that is defined to<br />
control the Digipass assignment link<br />
Write permission for any individual properties on Digipass Application objects, except for one Property Set that<br />
is defined to include the Digipass 'blob' that is required for any administrative operation such as Reset PIN,<br />
Test, Set Event Counter, etc.<br />
Create and delete permission on Digipass and Digipass Application objects<br />
If the administrator should be allowed to move Digipass, they need:<br />
the Delete Digipass objects and Create Digipass objects permissions in the relevant Domain and/or<br />
Organizational Unit<br />
Write All Properties permission on Digipass objects<br />
Note<br />
5.2.4 System <strong>Administrator</strong>s<br />
This can be necessary for assigning Digipass to users, because a move from one location to<br />
another is controlled by permissions to delete from the source and create in the destination<br />
The term 'System <strong>Administrator</strong>' is used here to refer to an administrator who will be responsible for management<br />
of records which affect the configuration and running of the <strong>Identikey</strong> <strong>Server</strong>, rather than Digipass User Accounts<br />
and Digipass. They need permissions within the Digipass Configuration Container to create, modify and delete<br />
these objects:<br />
Component (vasco-Component)<br />
Policy (vasco-Policy)<br />
Report (vasco-Report)<br />
Report Format (vasco-ReportFormat)<br />
Back-End <strong>Server</strong> (vasco-BackEnd<strong>Server</strong>)<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 74
<strong>Server</strong> Configuration (vasco-Configuration)<br />
Set Up Active Directory Permissions<br />
In practice, System <strong>Administrator</strong>s can typically be given full control over the Digipass-Configuration container. If<br />
you wish to grant more limited permissions, this can be handled with the standard Active Directory permissions on<br />
these objects within the scope of the container.<br />
5.3 Assign Administration Permissions to a User<br />
Note<br />
This example assumes that the administrator's User account has read permissions for all User<br />
records already.<br />
To grant permissions to manage Digipass records, you will need to follow these steps:<br />
1. Right-click on the Organizational Unit in which to assign permissions. in the Active Directory Users and<br />
Computers extension.<br />
2. Select Delegate Control... from the right-click menu.<br />
The Delegate Control Wizard will be displayed.<br />
3. Select the User or Windows Group to assign permissions.<br />
4. Click on OK.<br />
5. Select the Delegate Common Tasks option button.<br />
6. Select Create, Delete and Manage Digipass from the list.<br />
7. Click on Next.<br />
8. Click on Finish.<br />
If you wish to grant permissions to modify Digipass User Account properties, you will need to follow these steps:<br />
9. Select View -> Advanced Features from the main menu.<br />
10. Right-click on the Organizational Unit in which to assign permissions.<br />
11. Select Properties from the right-click menu.<br />
12. Click on the Security tab.<br />
13. Click on the Advanced button.<br />
The Advanced Security Settings window will be displayed.<br />
14. Click on Add...<br />
15. Type the username of the User to assign the permissions to and click OK.<br />
16. Click on the Properties tab.<br />
17. Select User Objects from the Apply onto drop down list.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 75
18. Select the required permissions from:<br />
Write Digipass User Account Information<br />
Write Digipass User Account Link<br />
Write Digipass User Account Stored Password<br />
19. Click on OK.<br />
20. Click on OK.<br />
21. Click on OK.<br />
Set Up Active Directory Permissions<br />
If the administrator requires permissions to take Digipass out of the Digipass-Pool for assignment, you will need to<br />
follow these steps:<br />
22. Right-click on the Digipass Pool.<br />
23. Select Properties from the right-click menu.<br />
24. Click on the Security tab.<br />
25. Click on the Advanced button.<br />
The Advanced Security Settings window will be displayed.<br />
26. Click on Add...<br />
27. Select the User account.<br />
28. Click on OK.<br />
29. Click on the Object tab.<br />
30. Select Child objects only from the Apply onto drop down list.<br />
31. Tick the Allow box for:<br />
Delete Digipass Objects<br />
Create Digipass Objects (if you wish to allow the administrator to move Digipass records into the Digipass Pool)<br />
32. Click on OK.<br />
33. Click on Add...<br />
34. Select the User account.<br />
35. Click on OK.<br />
36. Click on the Object tab.<br />
37. Select Digipass objects from the Apply onto drop down list.<br />
38. Tick the Allow box for Write All Properties.<br />
39. Click on OK.<br />
40. Click on OK.<br />
41. Click on OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 76
5.4 Multiple Domains<br />
Set Up Active Directory Permissions<br />
When using the <strong>Identikey</strong> <strong>Server</strong> with multiple domains, extra steps must be followed to ensure that both the<br />
<strong>Identikey</strong> <strong>Server</strong> and administrators have permissions sufficient to access required data. The main issues are:<br />
The Digipass Configuration Container is only in one Domain. All <strong>Identikey</strong> <strong>Server</strong>s need read access to this<br />
container, even when they are in a different Domain. Cross-Domain access for administrators is a less likely<br />
requirement however.<br />
If a <strong>Identikey</strong> <strong>Server</strong> handles users and Digipass in more than one Domain, they need to be granted the<br />
necessary permissions in all the necessary Domains.<br />
In this manual, we will handle cross-Domain permissions using a combination of Domain Local and Domain Global<br />
groups. It is also possible in a 'native' mode Domain to use Universal groups, but this is not covered in the<br />
instructions below.<br />
Three possible scenarios for multiple domain setup are outlined below:<br />
5.4.1 Scenario 1 – Each <strong>Identikey</strong> <strong>Server</strong> Handles One Domain<br />
Each <strong>Identikey</strong> <strong>Server</strong> handles only the domain in which it is a member.<br />
Install the <strong>Identikey</strong> <strong>Server</strong> in each domain (the result will be at least as many <strong>Identikey</strong> <strong>Server</strong>s as domains).<br />
Give each <strong>Identikey</strong> <strong>Server</strong> access to the Digipass Configuration Domain:<br />
Domain Global Group(s)<br />
For each domain (apart from the Digipass Configuration Domain) -<br />
1. Create a Domain Global group<br />
2. Add the <strong>Identikey</strong> <strong>Server</strong>(s) to the Domain Global group (check which machines are in the 'RAS and IAS<br />
<strong>Server</strong>s' group to ensure the correct additions)<br />
Domain Local group<br />
In the Digipass Configuration Domain -<br />
3. Create or use an existing Domain Local group.<br />
4. Give the Domain Local group full read access to the Digipass Configuration Container.<br />
5. Add the Domain Global Group from each other domain to the Domain Local group.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 77
5.4.2 Scenario 2 – One <strong>Identikey</strong> <strong>Server</strong> Handles All Domains<br />
Set Up Active Directory Permissions<br />
<strong>Identikey</strong> <strong>Server</strong>s in one domain handle all domains. The Digipass Configuration Container should be located in the<br />
domain to which the <strong>Identikey</strong> <strong>Server</strong>s belong.<br />
Give the necessary access to User and Digipass data:<br />
Domain Global group<br />
In the RADIUS server Domain -<br />
1. Create a Domain Global group.<br />
2. Add the <strong>Identikey</strong> <strong>Server</strong>s to the Domain Global group (check which machines are in the 'RAS and IAS<br />
<strong>Server</strong>s' group to ensure the correct additions).<br />
Domain Local groups<br />
For each other Domain -<br />
3. Create a Domain Local group.<br />
4. Give the Domain Local group the required permissions (run the setupaccess command - See 2.5 DPADadmin<br />
Utility for more information).<br />
5. Add the Domain Global group from the <strong>Identikey</strong> <strong>Server</strong> Domain to the Domain Local group.<br />
5.4.3 Scenario 3 - Combination<br />
This scenario represents more complex setups, where a combination of steps from Scenarios 1 and 2 will be<br />
required. Use the steps given in the first two scenarios as a guide for what you will need to do for the combination<br />
scenario.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 78
6 Backup and Recovery<br />
Backup and Recovery<br />
This section explores the measures that <strong>Administrator</strong>s can undertake in backing up and recovering <strong>Identikey</strong><br />
<strong>Server</strong> datafiles in the event of a system failure.<br />
Note<br />
This section does not cover backup of executables and system files. In the event of a<br />
catastrophic failure these can be restored or reinstalled from the original distribution media (and<br />
any subsequent service packs/patches).<br />
Once the <strong>Identikey</strong> <strong>Server</strong> is installed and operational, backups should be made of important files and data.<br />
Any time changes are made to the system configuration, backups may need to be performed again.<br />
User and Digipass data should be backed up on a frequent, regular basis.<br />
6.1 What Must be Backed Up<br />
Configuration files for <strong>Identikey</strong> <strong>Server</strong>, Virtual Digipass Message Delivery Component and Digipass TCL<br />
Command Line Administration.<br />
SSL certificate(s)<br />
Audit Log data<br />
Data store<br />
DPX files (except for demo Digipass)<br />
Any scripts that have been written for Digipass TCL Command Line Administration, if they may be needed in<br />
the future.<br />
Important Note<br />
The <strong>Identikey</strong> <strong>Server</strong> installation includes a DPX directory containing sample DPX files for demo<br />
Digipass. These do not need to be backed up. However, if <strong>Identikey</strong> <strong>Server</strong> uses an ODBC<br />
database and you have copied the DPX files for your real Digipass into that directory, ensure you<br />
still have the original files. If you no longer have the DPX file(s) stored elsewhere, it is very<br />
important that you take a backup.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 79
6.1.1 Configuration Files<br />
Backup and Recovery<br />
The configuration files for the <strong>Identikey</strong> <strong>Server</strong>, Virtual Digipass Message Delivery Component and Digipass TCL<br />
Command Line Administration can be copied from:<br />
the Bin directory in Windows (by default in Windows C:\Program Files\VASCO\<strong>Identikey</strong> <strong>Server</strong>\Bin) to a secure<br />
location.<br />
/etc/vasco/ in Linux<br />
The files to be copied are:<br />
identikeyconfig.xml for all <strong>Identikey</strong> <strong>Server</strong>s<br />
mdcconfig.xml – a backup of one working file is sufficient.<br />
dpadmincmd.xml<br />
Tip<br />
6.1.2 SSL Certificates<br />
Save the files above with an extension that describes the server from which the file(s) were backed<br />
up. This makes it easier and quicker to locate the correct file during recovery.<br />
Any SSL certificates used with the <strong>Identikey</strong> <strong>Server</strong> should be backed up. If you are using a certificate generated by<br />
<strong>Identikey</strong> <strong>Server</strong>'s Configuration Wizard, this will be named either ikeycerts.pem or ikeypvk.pem.<br />
6.1.3 Audit Log Data<br />
If your organization requires that the Audit Log data be archived, the method required will depend on the audit<br />
settings. You may need to archive periodically, to avoid too much disk space being used or to keep the database<br />
from growing too large and slow.<br />
6.1.3.1 Write to Text File<br />
Ensure you make copies of all files contained in the directory into which the audit log files are written. By default<br />
this will be \Log (Windows) or /var/vasco (Linux), however it may have been configured to<br />
another location. Check the audit configuration settings if you are unsure.<br />
6.1.3.2 Write to ODBC Database<br />
Back up the database using the database's backup utility. If you are using the audit tables in the embedded<br />
database, they will be included in the backup of the data store and will not require a separate backup.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 80
6.1.3.3 Write to Windows Event Log<br />
Backup and Recovery<br />
By default, Event Log entries are written to the Application log. However, you can configure the entries to be written<br />
to another log. Check the audit configuration if you are unsure.<br />
Important Note<br />
The Event Log may be configured with a maximum size. When this size is reached, the oldest<br />
entries may be overwritten by new ones. To check this, view the Properties of the log in the<br />
Event Viewer. If older entries will be overwritten, you will need to archive them before that<br />
occurs.<br />
To archive an Event Log:<br />
1. Select Start -> Programs -> Control Panel.<br />
2. Double-click on Administrative Tools.<br />
3. Double-click on Event Viewer.<br />
4. Right-click on Application (or the correct log, if not Application).<br />
5. Click on Save log file as...<br />
6. Select a path and enter a filename.<br />
7. Select a file format from the Type drop down list.<br />
8. Click on the Save button.<br />
Note<br />
6.1.4 Write to Syslog<br />
6.1.5 DPX files<br />
The Audit Log data is not required for system recovery purposes.<br />
In Linux, audit data can be written to the Syslog. See 14.4 Linux Syslog for information on configuring Linux and<br />
<strong>Identikey</strong> <strong>Server</strong> correctly.<br />
The DPX files are normally provided on secure media, which can be stored securely as a backup. If you prefer<br />
another method of archive, copy the files to your preferred location. It is important to keep the DPX file transport<br />
keys secure and preferably in a separate location to the DPX files themselves.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 81
6.1.6 Data Store<br />
6.1.6.1 Data Source Settings<br />
Backup and Recovery<br />
If you have performed some adjustments to the ODBC Data Source (DSN) that are important to keep, make sure<br />
that you have a readout of the settings.<br />
6.1.6.2 Backup Strategies<br />
Warm Backup<br />
A 'warm' backup of the disk containing the database used by the <strong>Identikey</strong> <strong>Server</strong> via a RAID hardware<br />
configuration or server mirroring is a favorable backup method. It is both entirely up to date and incurs no<br />
downtime if a single disk failure occurs.<br />
This method requires either software RAID, or for better performance a hardware RAID configuration.<br />
Another technique that achieves the same effect is the 'shadow database'.<br />
However, it is still recommended to take a cold backup at intervals, as there is a possibility that a database<br />
corruption could be mirrored/shadowed under some circumstances.<br />
Cold Backup<br />
A 'cold' backup of the database allows administrators to implement a duplicate database as a safeguard on a<br />
regular basis. Generally speaking there are two methods that can be used to perform a cold backup:<br />
Backup Utility<br />
The first option is to use the vendor-specific backup utility that allows the contents of the database to backed up to<br />
a file or device while the system is running. Such a utility is provided with the embedded database PostgreSQL (see<br />
below).<br />
Shut Down and Copy the Database File<br />
The second option involves stopping the database server and any connecting server processes and copying the<br />
database files. However, this is only possible where the database vendor recommends this approach. Normally this<br />
is only appropriate if the database is contained in a single operating system file.<br />
Replicated Copy<br />
If replication has been configured between databases, a replicated copy can be used as a backup. However, it is<br />
still recommended to take a cold backup at intervals.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 82
6.1.6.3 Backup of PostgreSQL Embedded Database<br />
Backup and Recovery<br />
The PostgreSQL database available with the <strong>Identikey</strong> <strong>Server</strong> installation may be backed up while operational by<br />
completing these steps:<br />
1. Open command prompt in \PostgreSQL\Bin (Windows) or /usr/local/pgsql/bin<br />
(Linux).<br />
2. If using Windows, enter the following command:<br />
pg_dump -f "" -Fc -Z9 -U [-v] postgres<br />
If using a Linux distribution, enter the following command:<br />
vds_chroot pg_dump -f "" -Fc -Z9 -U [-v] postgres<br />
where:<br />
is the <strong>Identikey</strong> <strong>Server</strong> installation directory – by default, this will be /opt/vasco/identikey<br />
is the absolute path and file name of the file to which data will be backed up.<br />
is the database administrator account name. When installed, this is set to digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the backup is run.<br />
3. You will normally be prompted for the password of the database administrator account. When installed, this<br />
is set to digipassword.<br />
This command may also be run via a batch file in order to automatically take a backup at regular intervals. In order<br />
to remove the interactive prompt for the password, you can add a line to a PostgreSQL configuration file to allow<br />
local logins for a database administrator account without a password. Edit the file \PostgreSQL\data\pg_hba.conf (Windows) or /usr/local/pgsql/data/pg_hba.conf (Linux) with<br />
a text editor. At the bottom of this file, there is a list of rules for authenticating connections to the database, which<br />
by default will be:<br />
# TYPE DATABASE USER CIDR-ADDRESS METHOD<br />
# IPv4 local connections:<br />
host all all 127.0.0.1/32 md5<br />
# IPv6 local connections:<br />
#host all all ::1/128 md5<br />
Add the following line directly below # Ipv4 local connections:<br />
host postgres digipass 127.0.0.1/32 trust<br />
Backup <strong>Administrator</strong> Account<br />
You may prefer to create a second database administrator account that only has permission to back up the<br />
database.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 83
6.2 Recovery<br />
6.2.1 Active Directory<br />
Assumptions:<br />
Steps:<br />
Active Directory itself is still valid and operational.<br />
Up-to-date backups of the configuration files for the <strong>Identikey</strong> <strong>Server</strong> are available.<br />
Backup and Recovery<br />
1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same<br />
Domain as before.<br />
2. Retrieve your backup copy of the identikeyconfig.xml file.<br />
3. Reinstall <strong>Identikey</strong> <strong>Server</strong> on the server. The same settings as those chosen in the previous installation<br />
should be selected.<br />
Before you restart the machine, carry out the following:<br />
4. Restore the backup copy of the configuration file identikeyconfig.xml to \bin.<br />
5. Restore any customized files for the web sites (see 9.1 Customizing the Web Sites for more information).<br />
After restarting the machine:<br />
6. Check that you can view Digipass-specific information in the Administration Web Interface and the Digipass<br />
Extension for Active Directory Users and Computers.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 84
6.2.2 ODBC Database<br />
6.2.2.1 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Database Undamaged<br />
Backup and Recovery<br />
1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same<br />
Domain as before.<br />
2. Retrieve your backup copies of the file and any other files from the Bin directory that were backed up.<br />
3. Reinstall <strong>Identikey</strong> <strong>Server</strong> on the server. The same settings as those chosen in the previous installation<br />
should be selected. Do not run the Configuration Wizard.<br />
4. Restore the backup copy of the configuration file identikeyconfig.xml into the \Bin<br />
directory. Restore the backup copies of any other files that were backed up from the Bin directory at the<br />
same time.<br />
5. Start up the <strong>Identikey</strong> <strong>Server</strong> Service.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 85
6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong> Undamaged<br />
Backup and Recovery<br />
This procedure should be followed where a database has been damaged and no current, valid database exists on<br />
another server. The database is restored from an earlier backup.<br />
Windows<br />
1. Stop the <strong>Identikey</strong> <strong>Server</strong> Service.<br />
2. Restore database from backup. If you are using the embedded PostgreSQL database:<br />
a. Open a command prompt in \PostgreSQL\Bin.<br />
b. Enter the following command and hit ENTER:<br />
pg_restore -d postgres -c -U [-v] ""<br />
where:<br />
is the absolute path and file name of the file to restore from<br />
is the database administrator account name. The database administrator account<br />
created during installation is digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
c. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
d. Enter the following command and hit ENTER:<br />
vacuumdb -z -d postgres -U [-v]<br />
where:<br />
is the database administrator account name. The database administrator<br />
account created during installation is "digipass".<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
e. You will normally be prompted for the password of the database administrator account.<br />
This step forces the database to recalculate optimization statistics, because all the data has been<br />
removed and reloaded.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 86
Backup and Recovery<br />
3. Delete the replication queue files for all destination servers. This can be done by deleting all files in the<br />
\ReplData directory (Note: if you have re-configured replication to store its files in a<br />
different directory, delete the files in that directory instead).<br />
4. Restart the <strong>Identikey</strong> <strong>Server</strong> Service.<br />
Follow the 6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong> procedure below on all other <strong>Identikey</strong> <strong>Server</strong>s in<br />
the system. It is essential to resynchronize all the databases in the system.<br />
Linux<br />
1. Stop the <strong>Identikey</strong> <strong>Server</strong> Daemon.<br />
2. Restore database from backup. If you are using the embedded PostgreSQL database:<br />
a. Enter the following command:<br />
vds_chroot <br />
/opt/vasco/identikey/usr/local/pgsql/bin/pg_restore -d postgres -c -U [-v] ""<br />
where:<br />
is the directory in which <strong>Identikey</strong> <strong>Server</strong> is installed<br />
is the absolute path and file name of the file to restore from<br />
is the database administrator account name. The database administrator account<br />
created during installation is digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
b. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
c. Enter the following command:<br />
vds_chroot /opt/vasco/identikey/usr/local/pgsql/bin/vacuumdb<br />
-z -d postgres -U [-v]<br />
where:<br />
is the directory in which <strong>Identikey</strong> <strong>Server</strong> is installed<br />
is the database administrator account name. The database administrator account<br />
created during installation is "digipass".<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
d. You will normally be prompted for the password of the database administrator account.<br />
This step forces the database to recalculate optimization statistics, because all the data has been<br />
removed and reloaded.<br />
3. Delete the replication queue files for all destination servers. This can be done by deleting all files in the<br />
\ReplData directory (Note: if you have re-configured replication to store its files in a<br />
different directory, delete the files in that directory instead).<br />
4. Restart the <strong>Identikey</strong> <strong>Server</strong> Daemon.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 87
Backup and Recovery<br />
Follow the 6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong> procedure below on all other <strong>Identikey</strong> <strong>Server</strong>s in<br />
the system. It is essential to resynchronize all the databases in the system.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 88
6.2.2.3 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Restore Database<br />
Backup and Recovery<br />
This procedure is required where both the <strong>Identikey</strong> <strong>Server</strong> and its database have been lost. Configuration files and<br />
the database will be restored from backups.<br />
Windows<br />
1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same<br />
Domain as before.<br />
2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were<br />
backed up.<br />
3. Reinstall <strong>Identikey</strong> <strong>Server</strong> on the server. The same settings as those chosen in the previous installation<br />
should be selected. Do not run the Configuration Wizard.<br />
4. Restore the backup copy of the configuration file identikeyconfig.xml into the \Bin<br />
directory. Restore the backup copies of any other files that were backed up from the Bin directory at the<br />
same time.<br />
5. Stop the <strong>Identikey</strong> <strong>Server</strong> Service.<br />
6. Restore database from backup. If you are using the embedded PostgreSQL database:<br />
a. Open a command prompt in \PostgreSQL\Bin.<br />
b. Enter the following command and hit ENTER:<br />
pg_restore -d postgres -c -U [-v] ""<br />
where:<br />
is the absolute path and file name of the file to restore from<br />
is the database administrator account name. The database administrator<br />
account created during installation is digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
c. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
d. Enter the following command and hit ENTER:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 89
vacuumdb -z -d postgres -U [-v]<br />
where:<br />
Backup and Recovery<br />
is the database administrator account name. The database administrator<br />
account created during installation is digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
This step forces the database to recalculate optimization statistics, because all the data has been<br />
removed and reloaded.<br />
e. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
7. Start the <strong>Identikey</strong> <strong>Server</strong> Service.<br />
8. Follow the 6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong> procedure below on all other <strong>Identikey</strong> <strong>Server</strong>s<br />
in the system. It is essential to resynchronize all the databases in the system.<br />
Linux<br />
1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same<br />
Domain as before.<br />
2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were<br />
backed up.<br />
3. Reinstall <strong>Identikey</strong> <strong>Server</strong> on the server. The same settings as those chosen in the previous installation<br />
should be selected. Do not run the Configuration Wizard.<br />
4. Restore the backup copy of the configuration file identikeyconfig.xml into the /Bin<br />
directory. Restore the backup copies of any other files that were backed up from the Bin directory at the<br />
same time.<br />
5. Stop the <strong>Identikey</strong> <strong>Server</strong> Daemon.<br />
6. Restore database from backup. If you are using the embedded PostgreSQL database:<br />
a. Enter the following command:<br />
vds_chroot <br />
/opt/vasco/identikey/usr/local/pgsql/bin/pg_restore -d postgres -c -U [-v] ""<br />
where:<br />
is the directory in which <strong>Identikey</strong> <strong>Server</strong> is installed<br />
is the absolute path and file name of the file to restore from<br />
is the database administrator account name. The database administrator account<br />
created during installation is digipass.<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
b. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
c. Enter the following command:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 90
Backup and Recovery<br />
vds_chroot /opt/vasco/identikey/usr/local/pgsql/bin/vacuumdb<br />
-z -d postgres -U [-v]<br />
where:<br />
is the directory in which <strong>Identikey</strong> <strong>Server</strong> is installed<br />
is the database administrator account name. The database administrator account<br />
created during installation is "digipass".<br />
-v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is<br />
restored.<br />
This step forces the database to recalculate optimization statistics, because all the data has been<br />
removed and reloaded.<br />
d. You will normally be prompted for the password of the database administrator account. When installed,<br />
this is set to digipassword.<br />
7. Start the <strong>Identikey</strong> <strong>Server</strong> Daemon.<br />
8. Follow the 6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong> procedure below on all other <strong>Identikey</strong> <strong>Server</strong>s<br />
in the system. It is essential to resynchronize all the databases in the system.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 91
6.2.2.4 Copy Database from Other <strong>Identikey</strong> <strong>Server</strong><br />
Backup and Recovery<br />
This procedure will be required where multiple <strong>Identikey</strong> <strong>Server</strong>s are synchronizing with each other, where one<br />
database has become unsynchronized or unstable. It must be replaced with a 'safe' database – one containing upto-date,<br />
uncorrupted data. The instructions below assume a simple two-<strong>Identikey</strong> <strong>Server</strong> pair where one <strong>Identikey</strong><br />
<strong>Server</strong> (SVR-2) is using a database that has become unstable, and the other (SVR-1) is using a 'safe' database.<br />
To replace the database:<br />
1. Identify the <strong>Identikey</strong> <strong>Server</strong> with the 'safe' database. For these steps, it will be referred to as SVR-1.<br />
2. Stop the <strong>Identikey</strong> <strong>Server</strong> Service on SVR-1 and SVR-2.<br />
3. Take a complete copy of the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-1. If you are using the embedded<br />
PostgreSQL database, see 6.1.6.3 Backup of PostgreSQL Embedded Database for instructions.<br />
4. Delete the replication queue files for SVR-2 which is on SVR-1:<br />
a. On SVR-1, run the <strong>Identikey</strong> <strong>Server</strong> Configuration utility and change to the Destination <strong>Server</strong>s tab of<br />
the Replication section.<br />
b. Find the Destination <strong>Server</strong> row that represents SVR-2 and note the Display Name.<br />
c. Change to the Queue tab and check the File Path value. This will normally be \ReplData, but may have been re-configured.<br />
d. In that directory, delete all files with filename starting .<br />
5. The <strong>Identikey</strong> <strong>Server</strong> Service on SVR-1 may be restarted now if needed – it will build up a new replication<br />
queue until it can connect to SVR-2.<br />
6. Completely overwrite the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-2 with the copy from SVR-1. If you<br />
are using the embedded PostgreSQL database, see Step 2 of 6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong><br />
Undamaged.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 92
Backup and Recovery<br />
7. Delete the replication queue file on SVR-2 for all other <strong>Identikey</strong> <strong>Server</strong>s. This can be done by deleting all files<br />
in the \ReplData directory (Note: if you have re-configured replication to store its files in a<br />
different directory, delete the files in that directory instead).<br />
8. Restart the <strong>Identikey</strong> <strong>Server</strong> Service on SVR-2.<br />
Warning<br />
If the <strong>Identikey</strong> <strong>Server</strong> with the 'bad' database (SVR-2) was synchronizing with another <strong>Identikey</strong><br />
<strong>Server</strong>, you must copy over the other database as well. Follow the steps above for any <strong>Identikey</strong><br />
<strong>Server</strong>s with which SVR-2 was synchronizing.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 93
6.2.2.5 Rebuild <strong>Identikey</strong> <strong>Server</strong>, Copy Database<br />
Backup and Recovery<br />
This procedure will be required where multiple <strong>Identikey</strong> <strong>Server</strong>s are synchronizing with each other and one<br />
<strong>Identikey</strong> <strong>Server</strong>, together with its database, is lost. The instructions below assume one functional <strong>Identikey</strong> <strong>Server</strong><br />
(SVR-1) with an up-to-date database, and a server on which an <strong>Identikey</strong> <strong>Server</strong> must be rebuilt (SVR-2) and its<br />
database copied from the other <strong>Identikey</strong> <strong>Server</strong>.<br />
1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same<br />
Domain as before.<br />
2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were<br />
backed up.<br />
3. Reinstall <strong>Identikey</strong> <strong>Server</strong> on the server. The same settings as those chosen in the previous installation<br />
should be selected. Do not run the Configuration Wizard.<br />
4. Restore the backup copy of the configuration file identikeyconfig.xml into the \Bin<br />
directory. Restore the backup copies of any other files that were backed up from the Bin directory at the<br />
same time.<br />
5. On SVR-1, stop the <strong>Identikey</strong> <strong>Server</strong> service.<br />
6. Take a complete copy of the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-1. If you are using the embedded<br />
PostgreSQL database, see 6.1.6.3 Backup of PostgreSQL Embedded Database for instructions.<br />
7. Delete the replication queue file for SVR-2 which is on SVR-1.<br />
a. On SVR-1, run the <strong>Identikey</strong> <strong>Server</strong> Configuration utility and change to the Destination <strong>Server</strong>s tab of<br />
the Replication section.<br />
b. Find the Destination <strong>Server</strong> row that represents SVR-2 and note the Display Name.<br />
c. Change to the Queue tab and check the File Path value. This will normally be \ReplData, but may have been re-configured.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 94
d. In that directory, delete all files with filename starting .<br />
Backup and Recovery<br />
8. The <strong>Identikey</strong> <strong>Server</strong> Service on SVR-1 may be restarted now if needed – it will build up a new replication<br />
queue until it can connect to SVR-2.<br />
9. Completely overwrite the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-2 with the copy from SVR-1. If you<br />
are using the embedded PostgreSQL database, see Step 2 of 6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong><br />
Undamaged.<br />
10. Delete the replication queue file on SVR-2 for all other <strong>Identikey</strong> <strong>Server</strong>s. This can be done by deleting all<br />
files in the \ReplData directory (Note: if you have re-configured replication to store its files<br />
in a different directory, delete the files in that directory instead).<br />
11. Restart the <strong>Identikey</strong> <strong>Server</strong> Service on SVR-2.<br />
Warning<br />
If the <strong>Identikey</strong> <strong>Server</strong> with the 'bad' database (SVR-2) was synchronizing with another <strong>Identikey</strong><br />
<strong>Server</strong>, you must copy over the other database as well. Follow the steps above for any <strong>Identikey</strong><br />
<strong>Server</strong>s with which SVR-2 was synchronizing.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 95
7 Field Listings<br />
7.1 User Properties<br />
Table 34: User Fields<br />
Field Name Description<br />
Field Listings<br />
Static Password The static password. This may be used for static password checking by the <strong>Identikey</strong> <strong>Server</strong> or<br />
may be a record of a password in a Back-End System.<br />
In view mode, the system will only show whether a password is set or not.<br />
The Set Password and Reset Password commands are used to change this, although it can<br />
also be entered when creating the Digipass User account.<br />
Local Authentication Specifies whether authentication requests for the User account will be handled by the <strong>Identikey</strong><br />
<strong>Server</strong> using Local Authentication (see the Authenticating Users section in the Product Guide<br />
for more details on Local Authentication and Back-End Authentication).<br />
Normally, this field will be Default, meaning that the Policy applicable to the authentication<br />
request determines the setting. This field on the Digipass User account is used to override the<br />
Policy setting for special cases.<br />
When Local Authentication is used, there are two factors that determine whether Digipass<br />
authentication is used – any Policy restrictions on Digipass Types and/or Applications that can<br />
be used and whether the Digipass User account has any assigned Digipass that meet the<br />
restrictions. For example, if the Policy requires a DP300 and the User just has a DP700, they<br />
cannot use Digipass authentication under that Policy.<br />
This setting also affects the Provisioning Registration process (see the Software Digipass<br />
Provisioning section in the Product Guide).<br />
Options:<br />
Default Use the setting of the effective Policy.<br />
None The <strong>Identikey</strong> <strong>Server</strong> will not carry out Local Authentication for this<br />
User account. They may be handled using Back-End Authentication, or<br />
not handled at all by the <strong>Identikey</strong> <strong>Server</strong>.<br />
Digipass/Password The <strong>Identikey</strong> <strong>Server</strong> will always carry out Local Authentication for this<br />
User, using Digipass authentication if possible, otherwise the static<br />
password. Back-End Authentication may also be utilized.<br />
Digipass Only The <strong>Identikey</strong> <strong>Server</strong> will always carry out Local Authentication for this<br />
User, using Digipass authentication. If Digipass authentication is not<br />
possible, the user cannot log in. Back-End Authentication may also be<br />
utilized.<br />
Back-End Authentication Specifies whether authentication requests for the User account will be handled by the <strong>Identikey</strong><br />
<strong>Server</strong> using Back-End Authentication (see the Authenticating Users section in the Product<br />
Guide for more details on Local Authentication and Back-End Authentication).<br />
Normally, this field will be Default, meaning that the Policy applicable to the authentication<br />
request determines the setting. This field on the Digipass User account is used to override the<br />
Policy setting for special cases.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 96
Field Name Description<br />
Field Listings<br />
This setting also affects the Provisioning Registration process (see the Software Digipass<br />
Provisioning section in the Product Guide).<br />
Options:<br />
Default Use the setting of the effective Policy.<br />
None Back-End Authentication will not be used.<br />
If Needed The <strong>Identikey</strong> <strong>Server</strong> will utilize Back-End Authentication but only in<br />
certain cases:<br />
Dynamic User Registration<br />
Self-Assignment<br />
Password Autolearn<br />
Requesting a Challenge or Virtual Digipass OTP, when the<br />
Request Method includes a Password<br />
Static password authentication, when verifying a Virtual<br />
Digipass password-OTP combination or during the Grace Period<br />
Provisioning Registration<br />
Always The <strong>Identikey</strong> <strong>Server</strong> will utilize Back-End Authentication for every<br />
authentication and Provisioning Registration request.<br />
Disabled Specifies whether a Digipass User account is enabled or disabled. If disabled, all requests for<br />
the User will be rejected by the <strong>Identikey</strong> <strong>Server</strong>.<br />
The Disable and Enable commands are used to change this, although it can also be changed<br />
when creating or editing the Digipass User account.<br />
Locked Specifies whether a Digipass User account is locked or not. If locked, all requests for the User<br />
will be rejected by the <strong>Identikey</strong> <strong>Server</strong>.<br />
The Locked indicator is normally set automatically when the User exceeds a certain number of<br />
failed authentication attempts. The User Lock Threshold is set in the Policy.<br />
The Unlock command is used to change this, although it can also be changed when editing the<br />
Digipass User account.<br />
Linked User Account It is possible to share Digipass between different User accounts, by linking User accounts<br />
together. This feature is intended for the case where one person, such as an administrator, has<br />
multiple User accounts. If their accounts are linked, there is no need to give more than one<br />
Digipass to that person.<br />
This feature is used by assigning the Digipass to one User account, then linking all the other<br />
User accounts for the person to the one that has the Digipass.<br />
Read only. The Link and Unlink commands must be used to change this.<br />
If a User is linked to another User, their Linked User Account field will show the UserId and<br />
Domain of the linked User, for example:<br />
testuser [vasco.com]<br />
Created On The date and time that the Digipass User account was created. Read-only.<br />
Last Modified On The date and time that the Digipass User account was last modified. Read-only.<br />
Domain The Domain to which the User belongs.<br />
Read only. This cannot be changed.<br />
Organizational Unit The Organizational Unit in which the User is located. This is optional as the User does not have<br />
to be located in an Organizational Unit.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 97
Field Name Description<br />
User Name The full name of the User.<br />
Read only. The Move command must be used to change this.<br />
Email Address The email address of the User.<br />
Phone No. The telephone number of the User.<br />
Mobile No. The mobile phone number of the User. This will be used for Virtual Digipass logins.<br />
Description Any descriptive text or notes.<br />
Field Listings<br />
Assigned Digipass list This lists all Digipass that are assigned to the User. For each Digipass, the list of active<br />
Applications is given with the Application Type indicated in brackets(). For example:<br />
0058384426 RESP_ONLY(RO), CHALLENGE(CR)<br />
In this example line, the Digipass with Serial Number 0058384426 has two active Applications:<br />
one Response Only Application RESP_ONLY and one Challenge/Response Application<br />
CHALLENGE.<br />
Other Digipass properties are shown in this list – for more information, see the Digipass<br />
Properties table.<br />
If the User does not have any Digipass assigned directly, but is linked to another User to use<br />
their Digipass (see Linked User Account), the linked User's Digipass list is shown with the Serial<br />
Numbers in square brackets (eg. [0058384426]).<br />
Read-only. The Assign Digipass and Unassign Digipass commands much be used to change<br />
this.<br />
Administrative Privileges This lists all the administrative privileges for which the User has permission.<br />
7.2 User Attributes<br />
Table 35: User Attribute Fields<br />
Field Name Description<br />
Attribute Group Attribute Groups provide a way to add different attributes to the User account for different client<br />
components.<br />
A SOAP client application may request a certain Attribute Group – it will only be given the<br />
user's attributes for the matching Attribute Group. A different application may request the same<br />
Attribute Group or a different one.<br />
An IIS Module (for example, in Digipass Pack for IIS Basic Authentication) may also request<br />
an Attribute Group. The Attribute Group entered in the Configuration GUI for the IIS Module will<br />
be requested.<br />
If the <strong>Identikey</strong> <strong>Server</strong> Data Store is shared with Digipass Plug-In for SBR, the SBR Plug-In<br />
may retrieve other Attribute Groups.<br />
Name The name of the attribute. This must match the name of an attribute expected by the client<br />
component. For the Digipass Pack for IIS Basic Authentication, this would be either User-<br />
Name or Password.<br />
Usage Specifies the usage of the User attribute. This is an optional setting.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 98
Field Name Description<br />
Options:<br />
Field Listings<br />
Basic Designates an attribute used by the Digipass Pack for IIS Basic<br />
Authentication.<br />
Check Note: Not currently in use with <strong>Identikey</strong> <strong>Server</strong>.<br />
Used to specify a RADIUS check attribute.<br />
Profile Note: Not currently in use with <strong>Identikey</strong> <strong>Server</strong>.<br />
Used to specify the name of a RADIUS Profile.<br />
Return Note: Not currently in use with <strong>Identikey</strong> <strong>Server</strong>.<br />
Used to specify a RADIUS return attribute.<br />
Value This value of the attribute. For the Digipass Pack for IIS Basic Authentication, this would be a<br />
User ID or password.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 99
7.3 Digipass Properties<br />
Table 36: Digipass Fields<br />
Field Name Description<br />
Domain The Domain to which the Digipass belongs.<br />
Read only. The Move command must be used to change this.<br />
Field Listings<br />
Organizational Unit The Organizational Unit in which the Digipass is located. This is optional as the Digipass does<br />
not have to be located in an Organizational Unit.<br />
Read only. The Move command must be used to change this.<br />
Digipass Type The type of Digipass represented by the Digipass record (eg. DP300).<br />
Description A custom text description of the Digipass. This can be used to search for specific attributes of a<br />
Digipass, eg. color, company logo.<br />
Reserve for Individual<br />
Assignment<br />
When used, this option prevents the Digipass from being assigned using the Auto-Assignment<br />
feature or by Provisioning Registration. It also prevents it from being assigned by an<br />
administrator who uses the 'Assign next available...' option in the assignment wizard.<br />
Assigned to User User ID of the Digipass User account that the Digipass is assigned to, if it is assigned. This User<br />
account must be in the same Domain as the Digipass.<br />
Read-only. The Assign command must be used to change this.<br />
Date Assigned The date and time when the Digipass was assigned to its current User.<br />
Read-only.<br />
Grace Period End The date on which the Grace Period will expire, or did expire, for this Digipass. If the date shows<br />
today's date or before, the Grace Period has already expired. If it is blank, there is no Grace<br />
Period.<br />
BVDP Mode Specifies whether and how the Backup Virtual Digipass feature can be used for this Digipass.<br />
Note that in order for the Backup Virtual Digipass feature to function, it must also be<br />
activated in the DPX file for the Digipass.<br />
Normally, this field will be Default, meaning that the Policy applicable to the authentication<br />
request determines the setting. This field on the Digipass record is used to override the Policy<br />
setting for special cases.<br />
Options:<br />
Default Use the setting of the effective Policy.<br />
No Backup Virtual Digipass is not permitted.<br />
Yes - Permitted Backup Virtual Digipass is permitted, but not mandatory.<br />
The Enabled Until date is not applicable when using this<br />
option, but the Uses Remaining count is.<br />
Yes – Time Limited Backup Virtual Digipass is permitted, but not mandatory.<br />
Both the Enabled Until date and the Uses Remaining count<br />
will be in effect.<br />
Yes - Required Backup Virtual Digipass is mandatory. This may be useful if<br />
the User may have lost the Digipass, to prevent it from<br />
being used until they have found it again.<br />
The Enabled Until date is not applicable when using this<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 100
Field Name Description<br />
option, but the Uses Remaining count is.<br />
Field Listings<br />
Enabled Until The date on which the Backup Virtual Digipass feature may no longer be used, provided that the<br />
effective Enable Backup VDP setting is Yes – Time Limited (it is ignored otherwise).<br />
If this date is blank, it will be set automatically the first time that the User requests a<br />
Backup Virtual Digipass OTP, using the Backup Virtual Digipass Time Limit defined in the<br />
Policy.<br />
Once this date has expired, it requires administrator intervention either to extend it or to reset it<br />
to blank for the next time that the User needs to use Backup Virtual Digipass.<br />
Uses Remaining The remaining number of times that the Backup Virtual Digipass feature may be used for this<br />
Digipass. Once this number has reached zero, Backup Virtual Digipass can no longer be used<br />
with this Digipass, unless the administrator increases it or resets it to blank.<br />
If this number is blank and there is a Backup Virtual Digipass Max. Uses/User defined in the<br />
Policy, it will be set automatically the first time that the User requests a Backup Virtual Digipass<br />
OTP, based on the Max. Uses/User.<br />
Static Vector ID The presence of a value here indicates that a Digipass is a Software Digipass capable of<br />
Provisioning. Its specific value is not of use to an administrator normally. It represents a lookup<br />
key of a database record used in the Provisioning process (DPSoft Parameters) that stores the<br />
Static Vector value.<br />
Last Activation The date and time at which the last Provisioning Registration operation took place using this<br />
Digipass, when an Activation Code was generated for it.<br />
There is a configurable minimum interval of time between Registration operations for a<br />
Digipass. See the Software Digipass Provisioning section in the Product Guide for more details.<br />
This value is reset to blank by the Reset Activation command.<br />
Activation Locations This is typically only used for Digipass for Web, to keep track of the number of different<br />
locations at which a particular User has activated it. The value is a comma-separated list of<br />
hash values, where each hash value represents one location.<br />
There is a configurable maximum number of activation locations for a Digipass. See the<br />
Software Digipass Provisioning section in the Product Guide for more details.<br />
This value is reset to blank by the Reset Activation command.<br />
Activation Count The total number of Provisioning Registration operations that have taken place using this<br />
Digipass, when an Activation Code was generated for it. This includes Registration operations<br />
for which the corresponding Activate operation was not completed successfully.<br />
There is a configurable maximum number of activation attempts for a Digipass. See the<br />
Software Digipass Provisioning section in the Product Guide for more details.<br />
This value is reset to 0 by the Reset Activation command.<br />
Created On The date and time that the Digipass was created. Read-only.<br />
Last Modified On The date and time that the Digipass was last modified. Read-only.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 101
7.4 Digipass Application Tab<br />
Table 37: Digipass Application Fields<br />
Field Name Description<br />
Field Listings<br />
Application Name A name for the Digipass Application. This is taken from the DPX file (always upper case). Readonly.<br />
Application Type The type of Digipass Application:<br />
RO – Response Only<br />
CR – Challenge/Response<br />
SG – Signature<br />
MM – Multi-Mode<br />
Read-only.<br />
Status This field indicates whether the Application is active or not. If it is not active, it cannot be used<br />
for authentication, provisioning or signature validation.<br />
Read-only. The Activate Application and Deactivate Application commands much be used to<br />
change this.<br />
Application Info This list indicates various internal settings of the Digipass Application. They are not edited<br />
directly but some are updated as side-effects of Digipass operations such as verification of One<br />
Time Passwords. Others represent programming parameters and never change.<br />
Created On The date and time that the Digipass Application was created. Read-only.<br />
Last Modified On The date and time that the Digipass Application was last modified. Read-only.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 102
7.5 Policy Properties<br />
Note<br />
Changes to Policy settings will not take effect immediately on all <strong>Identikey</strong> <strong>Server</strong>s unless<br />
Replication is used to synchronize the <strong>Identikey</strong> <strong>Server</strong>s. Where Replication is not used, changes<br />
to Policy settings will take effect when each <strong>Identikey</strong> <strong>Server</strong> is restarted, once the Policy change<br />
is available to it in its data store. Alternatively, if there is no restart, the cache of Policy settings<br />
will refresh from the data store after approximately every 15 minutes.<br />
Table 38: Policy Fields<br />
Field Name Description<br />
Description This description can be entered to record the purpose of the Policy.<br />
Field Listings<br />
Inherits from Policy Contains the Name of the Policy from which settings will be inherited, referred to as the<br />
'parent Policy'. Settings are inherited individually, depending on the value in the Policy field;<br />
they inherit the parent Policy value in the following cases:<br />
Choice lists/radio buttons – if the selected value is Default<br />
Text fields – if the field is blank<br />
Numeric fields – if the field is blank (not 0)<br />
List fields – if the list is empty<br />
The Show Effective Policy Settings... button can be used to display the result of inheriting<br />
settings combined with settings on the current Policy.<br />
Local Authentication Specifies whether authentication requests using the Policy will be handled by the <strong>Identikey</strong><br />
<strong>Server</strong> using Local Authentication (see the Authenticating Users section in the Product Guide<br />
for more details on Local Authentication and Back-End Authentication).<br />
When Local Authentication is used, there are two factors that determine whether Digipass<br />
authentication is used – any Policy restrictions on Digipass Types and/or Applications that<br />
can be used and whether the Digipass User account has any assigned Digipass that meet the<br />
restrictions. For example, if the Policy requires a DP300 and the User just has a DP700, they<br />
cannot use Digipass authentication under that Policy.<br />
This setting also affects the Provisioning Registration process (see the Software Digipass<br />
Provisioning section in the Product Guide).<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
None The <strong>Identikey</strong> <strong>Server</strong> will not carry out Local Authentication under<br />
this Policy. They may be handled using Back-End Authentication,<br />
or not handled at all by the <strong>Identikey</strong> <strong>Server</strong>.<br />
Digipass/Password The <strong>Identikey</strong> <strong>Server</strong> will always carry out Local Authentication<br />
under this Policy, using Digipass authentication if possible,<br />
otherwise the static password. Back-End Authentication may also<br />
be utilized.<br />
Digipass Only The <strong>Identikey</strong> <strong>Server</strong> will always carry out Local Authentication<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 103
Field Name Description<br />
Field Listings<br />
under this Policy, using Digipass authentication. If Digipass<br />
authentication is not possible, the user cannot log in. Back-End<br />
Authentication may also be utilized.<br />
Back-End Authentication Specifies whether authentication requests using the Policy will be handled by the <strong>Identikey</strong><br />
<strong>Server</strong> using Back-End Authentication (see the Authenticating Users section in the Product<br />
Guide for more details on Local Authentication and Back-End Authentication).<br />
This setting also affects the Provisioning Registration process (see the Software Digipass<br />
Provisioning section in the Product Guide).<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
None Back-End Authentication will not be used.<br />
If Needed The <strong>Identikey</strong> <strong>Server</strong> will utilize Back-End Authentication but only<br />
in certain cases:<br />
Dynamic User Registration<br />
Self-Assignment<br />
Password Autolearn<br />
Requesting a Challenge or Virtual Digipass OTP, when the<br />
Request Method includes a Password<br />
Static password authentication, when verifying a Virtual<br />
Digipass password-OTP combination or during the Grace<br />
Period<br />
Provisioning Registration<br />
Always The <strong>Identikey</strong> <strong>Server</strong> will utilize Back-End Authentication for every<br />
authentication and Provisioning Registration request.<br />
Back-End Protocol Specifies the protocol to be used for Back-End Authentication.<br />
If you have your own Back-End Authentication Engines, they will have Protocol names to<br />
identify them. The name for the required Engine must be defined in the Back-End Protocol for<br />
the Policy.<br />
The following standard options are available:<br />
Windows Authentication using the Windows operating system (this is only<br />
available when the <strong>Identikey</strong> <strong>Server</strong> runs on Windows).<br />
RADIUS Authentication using a RADIUS server.<br />
e-Directory Authentication using Novell's e-Directory.<br />
ADAM Authentication using a Microsoft ADAM server.<br />
Active Directory Authentication using Microsoft's Active Directory.<br />
Created On The date and time that the Policy was created. Read-only.<br />
Last Modified On The date and time that the Policy was last modified. Read-only.<br />
Dynamic User Registration Specifies whether the Dynamic User Registration (DUR) feature is enabled for the Policy. If<br />
this feature is used, when the <strong>Identikey</strong> <strong>Server</strong> receives an authentication request for a User<br />
for the first time and Back-End Authentication is successful, it will create a Digipass User<br />
account automatically. If DUR is used in conjunction with Auto-Assignment, a Digipass will<br />
be assigned to the new User account immediately.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 104
Field Name Description<br />
Field Listings<br />
This setting also determines whether the Provisioning Registration process is allowed to<br />
perform DUR or not.<br />
Password Autolearn Specifies whether the Password Autolearn feature is enabled for the Policy. This feature<br />
enables the <strong>Identikey</strong> <strong>Server</strong> to update the password stored in the Digipass User account<br />
when Back-End Authentication is successful.<br />
This setting also determines whether the Provisioning Registration process will update the<br />
password after successful Back-End Authentication or not.<br />
Stored Password Proxy Specifies whether the Stored Password Proxy feature is enabled for the Policy. This feature<br />
can be used in conjunction with the Back-End Authentication Always setting and the<br />
Password Autolearn feature. With this combination, even though a Back-End Authentication<br />
check is done every login, it is done using the password stored in the Digipass User account.<br />
Therefore the User does not have to enter it during their login, unless it has changed in the<br />
Back-End System. This mode of operation is referred to as Password Replacement.<br />
Default Domain The default Domain in which the <strong>Identikey</strong> <strong>Server</strong> should look for and create Digipass User<br />
accounts, if a Domain is not specified by the user credentials. The process of resolving the<br />
User ID and Domain name is described in the User ID and Domain Resolution section in the<br />
Product Guide and in 3.5.1.2 Identifying the Domain for a Login Attempt of this document.<br />
User Lock Threshold This indicates the number of consecutive failed login attempts that will cause a Digipass User<br />
account to become Locked. For example, if the User Lock Threshold is 3, the account will<br />
become Locked on the third failed login attempt. Unlocking the account requires<br />
administrator action.<br />
Note that not all kinds of login failure will result in locking. For example, if the UserId is<br />
incorrect or the account is Disabled, the failure would not count towards the lock threshold.<br />
Locking is used mainly for incorrect OTPs and static passwords.<br />
The locking mechanism is also used for Provisioning and Signature Validation.<br />
Windows Group Check Specifies whether and how the Windows Group Check feature is to be used. This feature is<br />
typically used for a staged deployment of Digipass when the Auto-Assignment method is<br />
used. It can also be used when only some Users are required to use Digipass or when only<br />
some Users will be permitted access and they have to use Digipass.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
No check Do not use the Windows Group Check feature.<br />
Pass requests for users not in<br />
listed groups back to host<br />
system<br />
Reject requests for users not in<br />
listed group<br />
Use only Back-End<br />
Authentication for users not in<br />
listed groups<br />
Use the Windows Group Check so that any Users who are<br />
not in one of the listed groups are ignored by the <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
Use of this setting for Provisioning or Signature Validation<br />
will have the same effect as the Reject... setting.<br />
Use the Windows Group Check so that any Users who are<br />
not in one of the listed groups are rejected by the <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
Use Back-End Authentication only for any Users who are<br />
not in one of the listed groups.<br />
Use of this setting for Provisioning or Signature Validation<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 105
Field Name Description<br />
will have the same effect as the Reject... setting.<br />
Field Listings<br />
Group List This lists the names of the Windows Groups to be checked according to the Windows Group<br />
Check radio button setting. There are some important limitations of this check:<br />
Certain built-in Active Directory groups such as Domain Users and Everyone will not be<br />
checked. The check is intended to be used with a new group created specifically for this<br />
purpose.<br />
Nested group membership will not be detected by the check.<br />
There is no Domain qualifier for a group. The named group must be created in each Domain<br />
where User accounts exist that need to be added to the group.<br />
A local machine group can be used also.<br />
Assignment Mode Specifies the method of automated Digipass Assignment that will be used for this Policy, if<br />
any. There are two methods, Auto-Assignment and Self-Assignment.<br />
Auto-Assignment is used in conjunction with Dynamic User Registration (DUR). When DUR<br />
occurs, the next available Digipass is assigned to the new Digipass User account. A Grace<br />
Period is set for the Digipass according to the Grace Period setting in the Policy.<br />
Self-Assignment is typically used with DUR also, but if the Digipass User accounts are<br />
created first by the administrator, DUR is not necessary. In the Self-Assignment mode, a User<br />
is able to assign themselves a Digipass by entering the Serial Number, a valid OTP from the<br />
Digipass and their static password. There is no Grace Period associated with Self-<br />
Assignment, because the User has to use the Digipass to perform Self-Assignment.<br />
In both cases, any Applicable Digipass restrictions for the Policy apply. For example, it will not<br />
be permitted to self-assign a DP300 if the Policy restricts Digipass Types to DPGO3 and<br />
DPGO1. In addition, if the User already has a Digipass assigned that meets the Policy<br />
restrictions, they will not be able to self-assign another Digipass.<br />
This setting is not applicable to Provisioning or Signature Validation.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
Auto-Assignment Use the Auto-Assignment method.<br />
Self-Assignment Use the Self-Assignment method.<br />
Neither Do not use either method of automated assignment.<br />
Grace Period Default time period (in days) to give Users between Auto-Assignment of a Digipass and the<br />
date they must start using their Digipass to login. Before that time they can still use a static<br />
password (unless the Local Authentication setting is Digipass Only). However, the first time<br />
that an OTP is used to log in, the Grace Period is ended at that point if it has not already<br />
ended.<br />
This setting does not affect manual assignment by an administrator or Provisioning.<br />
Serial No. Separator The character (or short sequence of characters) that will be included at the end of the<br />
Digipass Serial Number during a Self-Assignment login. It allows the <strong>Identikey</strong> <strong>Server</strong> to<br />
easily recognize that a Self-Assignment attempt is being made and extract the Serial Number<br />
from the credentials.<br />
Search Upwards in Org. Unit<br />
hierarchy<br />
This controls the search scope for an available Digipass for Auto-Assignment or Provisioning<br />
Registration, or for a specific Digipass for Self-Assignment.<br />
This setting does not affect manual assignment by an administrator.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 106
Field Name Description<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
Field Listings<br />
No The search scope is only the Organizational Unit in which the<br />
User account belongs. If the User does not belong to an<br />
Organizational Unit, the search will look for Digipass that also do<br />
not belong to an Organizational Unit.<br />
Yes The search will start in the User account's Organizational Unit,<br />
but if necessary it will then move upwards through the<br />
Organizational Unit hierarchy until it reaches the top. See the<br />
Location of Digipass Records topic in the Product Guide for more<br />
information.<br />
Application Names The Policy can specify a restriction on which Digipass Applications may be used when it is<br />
effective. If the list is empty, there is no restriction. If there are one or more entries, they will<br />
indicate the Application Names that are permitted.<br />
Application Type The Policy can restrict which Digipass Application Type (eg. Response Only,<br />
Challenge/Response) may be used when it is effective.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
No Restriction Digipass Application Type is not restricted.<br />
Response Only Only Digipass Applications of Type RO (Response Only) or MM<br />
(Multi-Mode) may be used.<br />
Challenge/Response Only Digipass Applications of Type CR (Challenge/Response) or<br />
MM (Multi-Mode) may be used.<br />
Signature Only Digipass Applications of Type SG (Signature) or MM (Multi-<br />
Mode) may be used.<br />
Multi-Mode Only Digipass Applications of Type or MM (Multi-Mode) may be<br />
used.<br />
Digipass Types The Policy can specify a restriction on which Digipass Types may be used when it is effective.<br />
If the list is empty, there is no restriction. If there are one or more entries, they will indicate<br />
the Digipass Types that are permitted.<br />
Allow PIN change Specifies whether Digipass Users will be allowed to change their <strong>Server</strong> PIN during<br />
authentication requests to which the current Policy applies. Normally this setting is enabled,<br />
but it can be used to prevent PIN changes if required.<br />
1-Step Challenge/Response<br />
– Permitted<br />
Controls whether 1-step Challenge/Response logins will be enabled for the current Policy<br />
and, if so, where the challenge should originate.<br />
In order to enable 1-step Challenge/Response, you also need to set the Challenge Check<br />
Mode (see below).<br />
Note that 1-step Challenge/Response is not applicable in a RADIUS environment.<br />
Options:<br />
Default<br />
No 1-step Challenge/Response may not be used.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 107
Field Name Description<br />
1-Step Challenge/Response<br />
– Challenge Length<br />
1-Step Challenge/Response<br />
– Add Check Digit<br />
2-Step Challenge/Response<br />
– Request Method<br />
2-Step Challenge/Response<br />
– Request Keyword<br />
Primary Virtual Digipass –<br />
Request Method<br />
Primary Virtual Digipass –<br />
Request Keyword<br />
Field Listings<br />
Yes – <strong>Server</strong> Challenge 1-step Challenge/Response may be used provided that the<br />
<strong>Identikey</strong> <strong>Server</strong> that verifies the response generated the<br />
challenge.<br />
Yes – Any Challenge 1-step Challenge/Response may be used with any random<br />
challenge.<br />
Specifies the length of the challenge (excluding a check digit) which should be generated for<br />
1-step Challenge/Response logins.<br />
A check digit may be added to the generated challenge. This allows the Digipass to identify<br />
invalid Challenges more quickly.<br />
The method by which a User has to request a 2-step Challenge/Response login.<br />
This is the only mode of Challenge/Response available in a RADIUS environment.<br />
The 'request' is made in the password field during login. The request will fail if the User does<br />
not have a Challenge/Response-capable Digipass assigned. This includes Digipass<br />
Applications of Type CR, SG and MM.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
None Do not use 2-step Challenge/Response.<br />
Keyword Use the Request Keyword. This is permitted to be blank.<br />
Password Use the static password.<br />
KeywordPassword Use the Request Keyword followed by the static password. No<br />
separator characters or whitespace should be between them.<br />
PasswordKeyword Use the static password followed by the Request Keyword. No<br />
separator characters or whitespace should be between them.<br />
Defines the Keyword that a User must enter to request a 2-step Challenge/Response login, if<br />
a method using a Keyword is selected in the Request Method.<br />
This is permitted to be blank.<br />
The method by which a User has to request a Primary Virtual Digipass login.<br />
The 'request' is made in the password field during login. The request will be ignored if the<br />
User does not have a Primary Virtual Digipass assigned.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
None Do not use Primary Virtual Digipass.<br />
Keyword Use the Request Keyword. This is permitted to be blank.<br />
Password Use the static password.<br />
KeywordPassword Use the Request Keyword followed by the static password. No<br />
separator characters or whitespace should be between them.<br />
PasswordKeyword Use the static password followed by the Request Keyword. No<br />
separator characters or whitespace should be between them.<br />
Defines the Keyword that a User must enter to request a Primary Virtual Digipass login, if a<br />
method using a Keyword is selected in the Request Method. This is permitted to be blank.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 108
Field Name Description<br />
Backup Virtual Digipass –<br />
Enable Backup VDP<br />
Backup Virtual Digipass –<br />
Time Limit<br />
Backup Virtual Digipass –<br />
Max. Uses/User<br />
Backup Virtual Digipass –<br />
Request Method<br />
Field Listings<br />
Specifies whether and how the Backup Virtual Digipass feature can be used when this Policy<br />
is effective. Note that in order for the Backup Virtual Digipass feature to function, it must also<br />
be activated in the DPX file for the Digipass.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
No Backup Virtual Digipass is not permitted.<br />
Yes - Permitted Backup Virtual Digipass is permitted, but not mandatory.<br />
The Time Limit is not applicable when using this option, but the<br />
Max. Uses/User limit is.<br />
Yes – Time Limited Backup Virtual Digipass is permitted, but not mandatory.<br />
Both the Time Limit and the Max. Uses/User limit will be in<br />
effect.<br />
Yes - Required Backup Virtual Digipass is mandatory.<br />
The Time Limit is not applicable when using this option, but the<br />
Max. Uses/User limit is.<br />
When the Enable Backup VDP setting is Yes – Time Limited, the Time Limit setting indicates<br />
the number of days for which the Backup Virtual Digipass feature may be used by a User,<br />
once they start using it.<br />
The Backup Virtual Digipass Enabled Until setting on the Digipass record will be set<br />
automatically the first time that the User requests a Backup Virtual Digipass OTP, using the<br />
Time Limit defined in the Policy. Once this date has expired, it requires administrator<br />
intervention either to extend it or to reset it to blank for the next time that the User needs to<br />
use Backup Virtual Digipass.<br />
Note that if a User has more than one Digipass capable of Backup Virtual Digipass, they will<br />
have a separate limit for each one.<br />
The maximum number of uses of the Backup Virtual Digipass feature permitted for each<br />
User, if they do not have a specific limit set for them.<br />
If the Backup Virtual Digipass Uses Remaining on the Digipass record is blank and there is<br />
a Max. Uses/User limit defined in the Policy, the Uses Remaining will be set automatically the<br />
first time that the User requests a Backup Virtual Digipass OTP.<br />
Once the Uses Remaining has reached zero, Backup Virtual Digipass can no longer be used<br />
with this Digipass, unless the administrator increases it or resets it to blank.<br />
Note that if a User has more than one Digipass capable of Backup Virtual Digipass, they will<br />
have a separate limit for each one.<br />
The method by which a User has to request a Backup Virtual Digipass login.<br />
The 'request' is made in the password field during login. The request will be ignored if the<br />
User does not have a Digipass assigned that is activated for the Backup Virtual Digipass<br />
feature, or if other Policy or Digipass settings do not permit Backup Virtual Digipass use.<br />
Options:<br />
Default Use the setting of the parent Policy.<br />
None Do not use Backup Virtual Digipass.<br />
Keyword Use the Request Keyword. This is permitted to be blank.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 109
Field Name Description<br />
Backup Virtual Digipass –<br />
Request Keyword<br />
Password Use the static password.<br />
Field Listings<br />
KeywordPassword Use the Request Keyword followed by the static password. No<br />
separator characters or whitespace should be between them.<br />
PasswordKeyword Use the static password followed by the Request Keyword. No<br />
separator characters or whitespace should be between them.<br />
Defines the Keyword that a User must enter to request a Backup Virtual Digipass login, if a<br />
method using a Keyword is selected in the Request Method. This is permitted to be blank.<br />
Identification Time Window Controls the maximum number of time steps' variation allowable between a Digipass and the<br />
<strong>Identikey</strong> <strong>Server</strong> during login. This only applies to time-based Digipass Applications when<br />
verifying a One Time Password.<br />
The Dynamic Time Window option may be used to allow more variation according to the<br />
length of time since the last successful login.<br />
If this setting is not specified at all, there is an inbuilt default value of 20.<br />
Signature Time Window Controls the maximum number of time steps' variation allowable between a Digipass and the<br />
<strong>Identikey</strong> <strong>Server</strong> during Digital Signature verification. This only applies to time-based Digipass<br />
Applications when validating a signature, but even then it may be used or not according to<br />
the Online Signature Level setting.<br />
If this setting is not specified at all, there is an inbuilt default value of 24.<br />
Initial Time Window Controls the maximum allowed time variation allowable between a Digipass and the <strong>Identikey</strong><br />
<strong>Server</strong>, the first time that the Digipass is used. The time is specified in hours. This Initial Time<br />
Window is also used directly after a Reset Application operation, which can be used if it<br />
appears that the internal clock in the Digipass has drifted too much since the last successful<br />
login.<br />
This only applies to time-based Digipass Applications when verifying a One Time Password.<br />
In either case, after the first successful login, the Initial Time Window is no longer active.<br />
If this setting is not specified at all, there is an inbuilt default value of 6.<br />
Event Window Controls the maximum number of events' variation allowable between a Digipass and the<br />
<strong>Identikey</strong> <strong>Server</strong> during login. This only applies to event-based Digipass Applications. It<br />
always applies when verifying a One Time Password but for Signature validation, it depends<br />
on the Online Signature Level setting whether the Event Window is used or not.<br />
If this setting is not specified at all, there is an inbuilt default value of 20.<br />
Identification Threshold Specifies the number of consecutive failed authentication attempts allowed before the<br />
Digipass Application is locked from future authentication attempts. Once the Digipass<br />
Application is locked, the Reset Appl Lock command is required to unlock it for further<br />
authentication.<br />
This locking mechanism is separate from the User Lock Threshold and is normally not<br />
necessary. It only applies when a single Digipass Application can be used for a login, either<br />
because the User only has one Digipass with one Application, or because the Policy<br />
restrictions narrow the list down to one Digipass Application. If Policy restrictions are used in<br />
this way, the Identification Threshold can be used to lock a User out of one kind of login (eg.<br />
a VPN) while still permitting them to use another kind (eg. a web application).<br />
If this setting is not specified at all, this feature is not used.<br />
Signature Threshold Specifies the number of consecutive failed Signature validation attempts allowed before the<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 110
Field Name Description<br />
Field Listings<br />
Digipass Application is set to be locked from future signature validation attempts. Once the<br />
Digipass Application is locked, the Reset Appl Lock command is required to unlock it for<br />
further signature validation.<br />
This locking mechanism is separate from the User Lock Threshold and is normally not<br />
necessary. It only applies when a single Digipass Application can be used for a signature<br />
validation, either because the User only has one Digipass with one signature-capable<br />
Application, or because the Policy restrictions narrow the list down to one Digipass<br />
Application. If Policy restrictions are used in this way, the Signature Threshold can be used to<br />
lock a User out of one kind of signature validation while still permitting them to use another<br />
kind.<br />
If this setting is not specified at all, this feature is not used.<br />
Max. Days Since Last Use This setting specifies the maximum number of days for which a Digipass Application can go<br />
unused for authentication or signature validation. After this limit, authentication and signature<br />
validation will be rejected until an admnistrator performs a Reset Application operation.<br />
If this setting is not specified at all, this feature is not used.<br />
Challenge Check Mode This setting is for advanced control over time-based Challenge/Response authentication.<br />
The value 1 should be used for standard RADIUS Challenge/Response. This is the inbuilt<br />
default value if the setting is not specified at all.<br />
0 No check is made. This is necessary for 1-step<br />
Challenge/Response.<br />
1 The challenge presented for verification must be the last one that<br />
was generated specifically for that Digipass. This is the normal<br />
mode of operation in 2-step Challenge/Response.<br />
2 The challenge presented for verification is ignored; the last one<br />
that was generated specifically for that Digipass is used.<br />
3 Only one verification is permitted per time step. This option only<br />
applies to time-based Challenge/Response. This is a method of<br />
avoiding a potential replay of a captured response if the same<br />
challenge comes up again in the same time step.<br />
4 If the same challenge and response are presented for verification<br />
twice in a row during the same time step, they are rejected. This<br />
is an advanced method of avoiding a potential replay of a capture<br />
challenge/response.<br />
Online Signature Level This setting is for advanced control of Signature validation.<br />
The value 0 can be used for Digipass Applications that are neither time- nor event-based.<br />
This is the inbuilt default value if the setting is not specified at all.<br />
0 The signature is validated in offline mode. This is useful when the<br />
signatures may not be validated in the same sequence as they<br />
were generated by the user. It is also useful when there may be<br />
some delay after the signature is generated by the user, before<br />
the signature is validated.<br />
For time-based Digipass Applications:<br />
This mode is typically used with a large time step.<br />
When this mode is used, no clock synchronization occurs<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 111
Field Name Description<br />
Field Listings<br />
between the Digipass and the <strong>Identikey</strong> <strong>Server</strong>. The <strong>Identikey</strong><br />
<strong>Server</strong> will not reject an older signature than the most recently<br />
validated signature, provided it is still within the Signature Time<br />
Window.<br />
For event-based Digipass Applications:<br />
When this mode is used, the <strong>Identikey</strong> <strong>Server</strong> will not reject an<br />
older signature than the most recently validated signature,<br />
provided it is still within the Event Window.<br />
1 The signature is validated in online mode. This is useful when the<br />
signatures are expected or required to be validated immediately<br />
after they are generated.<br />
For time-based Digipass Applications:<br />
This mode is typically used with a small time step.<br />
When this mode is used, clock synchronization occurs between<br />
the Digipass and the <strong>Identikey</strong> <strong>Server</strong>. The <strong>Identikey</strong> <strong>Server</strong> will<br />
reject an older signature than the most recently validated<br />
signature. A newer signature must be within the Signature Time<br />
Window.<br />
This mode will allow more than one signature to be validated in<br />
the same time step, provided that the same exact signature is<br />
not repeated twice in a row.<br />
For event-based Digipass Applications:<br />
When this mode is used, the <strong>Identikey</strong> <strong>Server</strong> will reject an older<br />
signature than the most recently validated signature. A newer<br />
signature must be within the Event Window.<br />
2 The signature is validated in strict online mode. This is useful for<br />
time-based signatures when you want to prevent more than one<br />
signature from the same time step from being validated.<br />
Otherwise, this mode is the same as online mode.<br />
3 The signature is validated using the Deferred Event Count. This<br />
mode only applies to event-based signatures. For each signature<br />
validation request, the Deferred Event Count must be supplied as<br />
a parameter.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 112
7.6 Client Properties<br />
Note<br />
Changes to Client records (add, change, delete) will not take effect immediately on all <strong>Identikey</strong><br />
<strong>Server</strong>s unless Replication is used to synchronize the <strong>Identikey</strong> <strong>Server</strong>s. Where Replication is not<br />
used, changes to Client records will take effect when each <strong>Identikey</strong> <strong>Server</strong> is restarted, once the<br />
Client change is available to it in its data store. Alternatively, if there is no restart, the cache of<br />
Client records will refresh from the data store after approximately every 15 minutes.<br />
Table 39: Client Fields<br />
Field Name Description<br />
Field Listings<br />
Client Type The type of Client component represented by the record. For SOAP clients, the type needs to match<br />
the Component Type parameter passed in the SOAP requests. Each application can identify itself as<br />
a different type of Client.<br />
In addition there are some standard 0ptions:<br />
Administration Program<br />
RADIUS Client<br />
Citrix Web Interface<br />
Outlook Web Access<br />
IIS6 Module<br />
Location The IP address or name of the machine represented by the record. For all Client types except<br />
RADIUS Clients, this must be the source IP address of requests originating from that Client.<br />
For a RADIUS Client, it must be the NAS-IP-Address or NAS-Identifier values sent in the RADIUS<br />
requests.<br />
A RADIUS Client of Location default can be used to accept RADIUS requests from all IP addresses,<br />
using the same Shared Secret. However, where a RADIUS Client record with the exact Location<br />
exists, its Shared Secret will be used in preference to the default RADIUS Client's Shared Secret.<br />
Protocol The protocol by which requests will be received from the Client.<br />
SOAP The standard SOAP protocol over HTTPS. This is used by programs<br />
using the SOAP interface from the <strong>Identikey</strong> <strong>Server</strong> SDK and the<br />
Web Administration Interface.<br />
RADIUS The standard RADIUS protocol. This is used by various remote<br />
network access hardware and software systems. It can also be used<br />
as a simple authentication programming interface.<br />
SEAL A proprietary TCP/IP based protocol used by <strong>Identikey</strong> <strong>Server</strong> and<br />
VACMAN Middleware 3.x. It is used by the IIS6 Module, Digipass<br />
TCL Command-Line Administration and for Replication between<br />
<strong>Identikey</strong> <strong>Server</strong>s.<br />
Policy The name of the Policy that should be used for authentication, Provisioning and signature validation<br />
requests from the Component.<br />
Shared Secret The RADIUS Shared Secret between the <strong>Identikey</strong> <strong>Server</strong> and the RADIUS Client.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 113
Field Name Description<br />
Confirm Shared Secret Allows confirmation of a new shared secret.<br />
Created On The date and time that the Client was created. Read-only.<br />
Last Modified On The date and time that the Client was last modified. Read-only.<br />
Field Listings<br />
License Key For each SEAL authentication Clients (IIS Modules), a License Key is required. This consists of a set<br />
of parameters followed by a signature. See 8 Licensing for more information.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 114
7.7 Back-End <strong>Server</strong> Properties<br />
Note<br />
Changes to Back-End <strong>Server</strong> records (add, change, delete) will not take effect immediately on all<br />
<strong>Identikey</strong> <strong>Server</strong>s unless Replication is used to synchronize the <strong>Identikey</strong> <strong>Server</strong>s. Where<br />
Replication is not used, changes to Back-End <strong>Server</strong> records will take effect when each <strong>Identikey</strong><br />
<strong>Server</strong> is restarted, once the Back-End <strong>Server</strong> change is available to it in its data store.<br />
Alternatively, if there is no restart, the cache of Back-End <strong>Server</strong> records will refresh from the<br />
data store after approximately every 15 minutes.<br />
Table 40: Back-End <strong>Server</strong> Fields<br />
Field Name Description<br />
Field Listings<br />
Protocol Back-End Authentication Protocol. RADIUS, Active Directory, ADAM and e-Directory are<br />
currently supported.<br />
Domain This field provides the ability to assign particular Back-End <strong>Server</strong>s to a given Domain.<br />
This is optional.<br />
Priority The priority in the case that there are multiple Back-End <strong>Server</strong>s. The highest priority<br />
server is tried first, then the next highest, etc.<br />
Authentication IP IP Address on which the RADIUS <strong>Server</strong> receives authentication requests.<br />
Authentication Port UDP Port on which the RADIUS <strong>Server</strong> receives authentication requests.<br />
Accounting IP IP Address on which the RADIUS <strong>Server</strong> receives accounting requests.<br />
Accounting Port UDP Port on which the RADIUS <strong>Server</strong> receives accounting requests.<br />
Shared Secret Shared secret between the <strong>Identikey</strong> <strong>Server</strong> and the RADIUS <strong>Server</strong>.<br />
Confirm Shared Secret Allows confirmation of a new shared secret.<br />
Timeout Number of seconds to wait for a response from the RADIUS <strong>Server</strong> before either retrying<br />
or trying another RADIUS <strong>Server</strong>.<br />
No. of Retries Number of times to retry if no response is received from the RADIUS <strong>Server</strong>.<br />
Base Search DN The DN where the search for user accounts starts.<br />
Security Principle DN The DN of the security principle used to access the directory.<br />
Security Principle Password the password of the security principle.<br />
Created On Date/time of creation.<br />
Last Modified On Date/time of last modification.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 115
7.8 Reports Properties<br />
Table 41: Report fields<br />
Field Name Description<br />
Report Name The name the report was given when it was created.<br />
Domain Name The domain the report was created in.<br />
Report Type The report Type.<br />
Field Listings<br />
List Analysis Report List analysis reports list items that match the<br />
predefined criteria<br />
Detailed Analysis Report The Detailed Analysis Report shows detail of<br />
the events specified in the report definition<br />
Distribution Analysis Report Distribution analysis reports break down the<br />
values of certain items over other items.<br />
Trend Analysis Report Trend analysis reports express a<br />
trend/evolution over a requested period of time<br />
for a set of reported items. The system<br />
therefore makes sub counts at a regular<br />
interval of the amount of times an item has<br />
occurred<br />
Description The description of the report that was entered when the report was created.<br />
Data Source Where the data in the report comes from. The sources can be:<br />
Users The User data will be used to generate the<br />
report<br />
Users + Audit The User data and audit data will be used to<br />
generate the report<br />
Digipass<br />
Digipass + Audit<br />
Audit<br />
Digipass data will be used to generate the<br />
report<br />
Digipass data and audit data will be used to<br />
generate the report.<br />
Only Audit data will be used to generate the<br />
report.<br />
Grouping Level The grouping level will be used to group the information on the report into the format you<br />
require. The grouping levels are:<br />
Client The report information will be grouped for<br />
each client<br />
Domain The report information will be grouped for<br />
each Domain<br />
Organizational Unit The report information will be grouped for<br />
each Organizational Unit<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 116
User<br />
Digipass<br />
Field Listings<br />
The report information will be grouped for<br />
each client<br />
The report information will be grouped for<br />
each Digipass<br />
Time Frequency For Trend Analysis reports. This type of report shows trends over a time period, taking sub<br />
counts at certain time periods. Use this field to specify the sub-count time frequency<br />
Created On Date the report was created<br />
Updated On Date the report definition was last modified<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 117
7.9 <strong>Identikey</strong> <strong>Server</strong> Properties<br />
Note<br />
Changes to <strong>Identikey</strong> <strong>Server</strong> records (add, change, delete) will not take effect immediately on all<br />
<strong>Identikey</strong> <strong>Server</strong>s unless Replication is used to synchronize the <strong>Identikey</strong> <strong>Server</strong>s. Where<br />
Replication is not used, changes to <strong>Identikey</strong> <strong>Server</strong> records will take effect when each <strong>Identikey</strong><br />
<strong>Server</strong> is restarted, once the <strong>Identikey</strong> <strong>Server</strong> change is available to it in its data store.<br />
Alternatively, if there is no restart, the cache of <strong>Identikey</strong> <strong>Server</strong> records will refresh from the<br />
data store after approximately every 15 minutes.<br />
Table 42: <strong>Identikey</strong> <strong>Server</strong> Fields<br />
Field Name Description<br />
Location The IP address of the <strong>Identikey</strong> <strong>Server</strong> represented by the record.<br />
Field Listings<br />
Policy The name of the Policy that should be used for administration logon requests from the Component,<br />
including live connections from the Audit Viewer. This Policy is used if there is no specific<br />
Administration Program Client record for the location of the administration logon.<br />
Created On The date and time that the Client was created. Read-only.<br />
Last Modified On The date and time that the Client was last modified. Read-only.<br />
License Key For each <strong>Identikey</strong> <strong>Server</strong>, a License Key is required. This consists of a set of parameters followed by<br />
a signature. See 8 Licensing for more information.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 118
7.10 Data Changes Requiring a Restart of <strong>Identikey</strong> <strong>Server</strong><br />
7.10.1 Changes to the Data Store<br />
Field Listings<br />
No data changes made in the Web Administration Interface, Digipass TCL Command-Line Administration or a<br />
SOAP administration client require a restart of the <strong>Identikey</strong> <strong>Server</strong> to take effect straight away. As this<br />
administration is carried out through the <strong>Identikey</strong> <strong>Server</strong>, the <strong>Identikey</strong> <strong>Server</strong> can immediately update any cached<br />
data.<br />
In addition, when multiple <strong>Identikey</strong> <strong>Server</strong>s are replicating database changes to each other, they update their<br />
cached data as changes are replicated.<br />
However, modifications listed in the Cached Data List topic below will not take effect until the <strong>Identikey</strong> <strong>Server</strong> is<br />
restarted, or until the caches re-load the data automatically, in the following cases:<br />
Multiple <strong>Identikey</strong> <strong>Server</strong>s are sharing a database. In this case, only the <strong>Identikey</strong> <strong>Server</strong> with which the data<br />
change is made will update its caches.<br />
Multiple <strong>Identikey</strong> <strong>Server</strong>s with their own database each are used, but they are not synchronized using<br />
<strong>Identikey</strong> <strong>Server</strong> Replication.<br />
Direct modifications are made to the database, for example with an SQL tool or using the VASCO Data<br />
Migration Tool.<br />
Note that direct modifications to the database are not replicated to any other <strong>Identikey</strong> <strong>Server</strong>s – the same<br />
modifications must be made to each <strong>Identikey</strong> <strong>Server</strong>'s database (or the whole database re-copied).<br />
Where multiple <strong>Identikey</strong> <strong>Server</strong>s are in use, with multiple databases, user-configured synchronization between the<br />
databases must be considered. A <strong>Identikey</strong> <strong>Server</strong> will not know about a data change made in another <strong>Identikey</strong><br />
<strong>Server</strong>'s database until that change has been copied to its own database.<br />
7.10.1.1 Automatic Re-Loading of Cached Data<br />
In the <strong>Identikey</strong> <strong>Server</strong>, all cached data is periodically re-loaded from the data store. This time period, around 15<br />
minutes, is tracked for each entry separately. Therefore, even without a restart, data changes will typically take<br />
effect within a matter of minutes (unless synchronization between databases is slower).<br />
7.10.1.2 Cached Data List<br />
The following data modifications relate to cached data:<br />
Creation, editing and deletion of Policy records<br />
Creation, editing and deletion of Client records<br />
Creation, editing and deletion of Back-End <strong>Server</strong> records<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 119
Creation, editing and deletion of <strong>Identikey</strong> <strong>Server</strong> records<br />
Creation, editing and deletion of Domain records<br />
7.10.2 Changes to Configuration Settings<br />
Field Listings<br />
Configuration settings are modified using the <strong>Identikey</strong> <strong>Server</strong> Configuration utility, the Web Administration, SOAP<br />
commands, TCL commands. or can be modified directly in the XML file. Configuration changes done using the<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration utility or directly in the XML file require a restart. The <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
utility automatically prompts to restart the Service upon exiting. However if you modify the file directly, you will<br />
need to restart the <strong>Identikey</strong> <strong>Server</strong> Service using the Windows Service Control Manager. Configuration changes<br />
done using Web Administration, or the SOAP or TCL commands do not require a restart.<br />
Each <strong>Identikey</strong> <strong>Server</strong> has separate configuration settings. Changes to settings for one <strong>Identikey</strong> <strong>Server</strong> will not be<br />
automatically applied to other <strong>Identikey</strong> <strong>Server</strong>s.<br />
Storage Advanced Settings<br />
The settings edited using Advanced Settings tab in the Storage section are not replicated to<br />
other <strong>Identikey</strong> <strong>Server</strong>s. Normally these settings should be the same on all <strong>Identikey</strong> <strong>Server</strong>s, so<br />
you need to make sure they are applied to each one.<br />
As they are stored in the database itself, if you copy a database from one <strong>Identikey</strong> <strong>Server</strong> to<br />
another, these settings will be copied also.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 120
8 Licensing<br />
8.1 How is Licensing Handled?<br />
Licensing<br />
<strong>Identikey</strong> <strong>Server</strong> requires a License Key for each <strong>Identikey</strong> <strong>Server</strong> component. The License Key is stored in the<br />
<strong>Identikey</strong> <strong>Server</strong> record in the data store. It is tied to the location (IP address) where the <strong>Identikey</strong> <strong>Server</strong> is installed<br />
– the <strong>Identikey</strong> <strong>Server</strong> will 'listen' on this IP address for SOAP and RADIUS requests.<br />
A License Key must be obtained from https://sc.vasco.com/registration/identikey/. This will generate a License Key<br />
and allow you to download it in a text file. The License Key can then be loaded from the file into the data store.<br />
This process normally occurs in the <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard, but may also be carried out later using<br />
the Web Administration Interface.<br />
The <strong>Identikey</strong> <strong>Server</strong> will not authenticate a user without a valid License Key, except to permit administration and<br />
reporting. Signature Validation and Provisioning will not be carried out without a valid License Key.<br />
Certain Client modules – such as the IIS 6 Module for Citrix Web Interface – also require a License Key to be<br />
loaded into their Client component record. The <strong>Identikey</strong> <strong>Server</strong>s to which they connect will otherwise reject all<br />
authentication requests from them.<br />
SOAP and RADIUS clients do not require a License Key in their Client component record. However, the <strong>Identikey</strong><br />
<strong>Server</strong> License Key requires parameters to enable the use of SOAP and RADIUS.<br />
Certain types of request processing need to be enabled by parameters in the <strong>Identikey</strong> <strong>Server</strong> License Key:<br />
Authentication, Signature Validation and Provisioning.<br />
If you acquire new functionality, you will need to obtain new License Keys for all your <strong>Identikey</strong> <strong>Server</strong>s. This can be<br />
done using the Web Administration Interface.<br />
Evaluation Licenses<br />
An evaluation license allows you to utilize full functionality until the evaluation period runs out. At the end of this<br />
period, you will need to either uninstall the product or buy a permanent license. Contact your VASCO supplier's<br />
representative to acquire the licences you will need. For your convenience, the evaluation serial number is provided<br />
for you in the evaluation license activation web page. However, you still need to obtain and load a License Key.<br />
Client module licenses can also be evaluation (time-limited) licenses.<br />
8.2 Licensing Parameters<br />
Table 43: License Parameters for <strong>Identikey</strong> <strong>Server</strong><br />
Parameter Value<br />
Product The name of the VASCO product, eg. <strong>Identikey</strong> <strong>Server</strong>.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 121
Parameter Value<br />
Component The type of Component licensed, eg. <strong>Identikey</strong> <strong>Server</strong>.<br />
Version Current version number of the licensed VASCO product.<br />
Location The IP address for the machine represented by the Component record.<br />
Company The name of your company.<br />
Username Your name.<br />
SerialNo The serial number for the VASCO product.<br />
Generated The date and time that the license file was generated.<br />
Expires Used for evaluation license only – expiry date.<br />
SOAP Enable SOAP request processing.<br />
RADIUS Enable RADIUS request processing.<br />
Authentication Enable Authentication request processing.<br />
Signature Enable Signature Validation request processing.<br />
Provisioning Enable Provisioning request processing.<br />
8.2.1 Sample License File<br />
----- VASCO PRODUCT LICENCE -----<br />
Product=<strong>Identikey</strong> <strong>Server</strong><br />
Component=<strong>Identikey</strong> <strong>Server</strong><br />
Version=3.1<br />
Expires=2009/06/19 02:40:32 GMT<br />
Location=test.vasco.com<br />
Company=VASCO Data Security<br />
Username=Mr Demo User<br />
SerialNo=0A2B4C6D8E<br />
Generated=2009/05/20 02:40:32 GMT<br />
SOAP=Yes<br />
Authentication=Yes<br />
Signature=Yes<br />
----- SIGNATURE -----<br />
3:302C02147A487891E0745D<br />
6866E0Af8DDB7D6AF092BFCD<br />
27021474601702DbFCE5B500<br />
D76354022F0489DB159B62<br />
----- END LICENCE -----<br />
8.3 View License Information<br />
To view the license information for a specific component:<br />
Licensing<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 122
1. Log into the Web Administration Interface.<br />
2. For a Client component, click on the Clients tab.<br />
The Client List will be displayed.<br />
3. For an <strong>Identikey</strong> <strong>Server</strong> component, click on the System tab.<br />
The <strong>Identikey</strong> <strong>Server</strong> List will be displayed.<br />
4. Click on the required component record's link to view its property pages.<br />
5. Click on the License tab.<br />
8.4 Obtain and Load a License Key<br />
Note<br />
An active internet connection is required to obtain a License Key.<br />
1. Follow the steps in 8.3 View License Information to view the License property tab for the required<br />
component.<br />
2. Click on the Get License Key button.<br />
A browser window will be opened, with the VASCO license activation page loaded. Some details of the<br />
component will be entered automatically for you.<br />
3. Enter any other required information into the web page.<br />
Licensing<br />
4. When the License Key has been generated, right-click on the link where it says 'Right-click and save the file<br />
to disk'. Select the option to save the link – save it with a .dat extension, for example as license.dat.<br />
The license file will also be emailed to you.<br />
5. A download of your License Key file should begin. Keep note of where you save the file, and its name.<br />
6. Once the download is complete, go back to the Web Administration Interface and the License property tab.<br />
7. Click on the Load License Key button.<br />
8. Browse to the download location and select the License Key file.<br />
9. Click on Upload to load the License Key from the file into the component record.<br />
10. If you have new functionality enabled in the license, you will need to restart the <strong>Identikey</strong> <strong>Server</strong> in order for<br />
the new functionality to become available.<br />
In addition, the new functionality may need to be enabled in other <strong>Identikey</strong> <strong>Server</strong>s in your system. If so, you<br />
will need to follow this procedure for each one.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 123
8.5 Re-Licensing<br />
Licensing<br />
You will need to obtain and load new License Keys for your <strong>Identikey</strong> <strong>Server</strong> components in the following situations:<br />
You need to change from an evaluation license to a permanent license.<br />
You need to enable new functionality.<br />
The <strong>Identikey</strong> <strong>Server</strong>'s IP address is going to change or has changed.<br />
You are performing an <strong>Identikey</strong> <strong>Server</strong> upgrade where the minor or major versions are increasing (for<br />
example, from 3.0 to 3.1 or 4.0).<br />
See 8.4 Obtain and Load a License Key above for instructions on obtaining a new License Key in the first two<br />
cases.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 124
9 Web Sites<br />
9.1 Customizing the Web Sites<br />
Web Sites<br />
The User Self Management Web Site and OTP Request Site can be customized by modifying the pages provided<br />
with the installation. You may wish to:<br />
change the colors and graphics to match your corporate colors/logos<br />
integrate the pages into a larger web site<br />
translate or customize the text<br />
Any cosmetic part of the web pages may be modified. Completely new web pages may be used, provided that the<br />
correct form fields are posted to the CGI program, and query string variables are interpreted correctly. <strong>Server</strong><br />
scripting languages such as PHP or ASP, or any other way of generating HTML, can be used.<br />
This section provides the instructions and reference material that you require to customize the site. It is assumed<br />
that the reader has some web development knowledge.<br />
9.2 CGI Program<br />
A CGI script is used for the User Self Management Web Site and OTP Request Site.<br />
The CGI program carries out the following actions:<br />
Read and validate the input. This input is gathered from:<br />
Configuration settings from the registry<br />
Form variables posted<br />
Send an authorisation request to the RADIUS <strong>Server</strong> (if used, and provided that there were no validation errors)<br />
and interpret the response. Requests are sent to the <strong>Server</strong> using the RADIUS protocol. A component identifier<br />
Self-Mgt Site will indicate in the Audit Console which audit messages relate to requests from the User Self-<br />
Management Web Site.<br />
(OTP Request Site only) Send a request to the Message Delivery Component to send an OTP to the User's<br />
mobile phone via text message.<br />
Output the HTML to direct the user to the page that will indicate success or failure, or display a challenge. This<br />
is achieved by returning the HTML for a basic ‘please wait’ page with a ‘meta-refresh’ instruction to go directly<br />
to the appropriate page. The meta-refresh will happen immediately, but on a slow link you may notice the<br />
intermediate page.<br />
The CGI program cannot be customized. Its behaviour is controlled by the configuration settings and the posted<br />
form variables. The configuration settings are listed below; the posted form variables are specified in the<br />
Customizing the Web Site section.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 125
9.2.1 Configuration Settings<br />
Web Sites<br />
Various configuration settings are used by the CGI program to locate the RADIUS server(s) and to enable tracing.<br />
These can be modified using the Start->Programs menu option “User CGI Configuration”.<br />
The configuration settings are stored in the Windows Registry, at the path:<br />
HKEY_LOCAL_MACHINE\Software\VASCO\User CGI<br />
Table 44: Configuration Settings for CGI Program<br />
Name Type Value Default<br />
Trace-Mask Number<br />
(DWORD)<br />
Used to enable internal tracing levels. In general, just<br />
use these values:<br />
0 = no tracing<br />
FFFFFFFF (hexadecimal) = full tracing<br />
Trace-File String Full path and filename of output file for internal tracing.<br />
NB: the file will be created if it is missing, but not the<br />
directory.<br />
Source-IP-Address String Source IP address to bind to when sending API requests,<br />
if any (only required if there are multiple IP addresses on<br />
the machine).eg. 10.9.255.7<br />
0<br />
<br />
<br />
<strong>Server</strong>1-IP-Address String IP address of primary RADIUS <strong>Server</strong>. eg. 10.2.255.45 127.0.0.1<br />
<strong>Server</strong>1-Port Number<br />
(DWORD)<br />
API port of primary RAIUS <strong>Server</strong> (in general, this should<br />
not be changed from the default).<br />
<strong>Server</strong>2-IP-Address String IP address of backup RADIUS <strong>Server</strong>, or blank if there is<br />
no backup.<br />
<strong>Server</strong>2-Port Number<br />
(DWORD)<br />
API port of backup RAIUS <strong>Server</strong> (in general, this should<br />
not be changed from the default)<br />
20003<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 126<br />
20003
9.3 Form Fields<br />
9.3.1 Registration – Main Pages<br />
Web Sites<br />
User Registration (UR), Digipass Assignment (DA) and Password Synchronization (PS) are all implemented using a<br />
single invocation of the CGI program. This permits them to be carried out either separately or in any combination.<br />
You can choose to separate them in your customized web site or keep them together as you prefer.<br />
If Challenge/Response or a Virtual Digipass is used, the user will enter their User ID, static password and Serial<br />
Number into the main page without a Digipass Response. They will be directed to a challenge page, which is<br />
specified in the next topic, in which they should enter either a Response to the challenge or the OTP sent to their<br />
mobile phone. The following table applies only to the main page.<br />
The following posted form fields must be used on the main page, according to the particular function and other<br />
conditions specified below:<br />
Table 45: Form Fields for Main Registration Page<br />
Form Field Name Visible Label<br />
(Default)<br />
dpcgi_operation “register” for User Registration, Digipass<br />
Assignment or Password Synchronization.<br />
Value(s) Required?<br />
dpcgi_success_page Relative or absolute URL of web page to go to if<br />
the function is successful.<br />
dpcgi_fail_page Relative or absolute URL of web page to go to if<br />
the function fails.<br />
dpcgi_challenge_page Relative or absolute URL of web page to go to if<br />
a challenge is returned for the user.<br />
UR PS DA<br />
Y Y Y<br />
Y Y Y<br />
Y Y Y<br />
(4) (1)<br />
dpcgi_userid UserId UserID in the <strong>Identikey</strong> <strong>Server</strong>. Y Y Y<br />
dpcgi_password Password Static password. Y Y Y<br />
dpcgi_serialno Serial Number Digipass serial number. Y<br />
dpcgi_response Digipass Response Digipass response (without static PIN if there is<br />
one).<br />
(5) (2)<br />
dpcgi_newpin New PIN New static PIN (for Go 1/Go 3). (3)<br />
dpcgi_confirmpin Confirm New PIN Confirm the new static PIN. (3)<br />
dpcgi_usecombinedpwd “True” to send the password, serial number,<br />
response and PIN to the <strong>Identikey</strong> <strong>Server</strong> in one<br />
attribute.<br />
“False” to send the contents of the password<br />
field<br />
(1) If any users may self-assign a Challenge/Response Digipass, provide this form field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 127
(2) If any users may self-assign a Response Only Digipass, provide this form field.<br />
Web Sites<br />
(3) If any users may self-assign a Response Only Digipass which uses a static PIN at the beginning of the<br />
response (eg. Go 1/Go 3), where the Digipass are initialized with no initial static PIN, they have to enter a<br />
new PIN the first time they use the Digipass. If they are self-assigning the Digipass, that means that they<br />
have to enter the new PIN and confirm it during the self-assignment process. They can do this by adding<br />
the new PIN twice at the end of the Digipass Response, however it may be more user-friendly to provide<br />
these two separate form fields.<br />
(4) If any users have a Challenge/Response application or a Primary Virtual Digipass, include this field.<br />
(5) If any users have a Response Only application, include this field.<br />
9.3.1.1 Registration – Challenge Page<br />
The Registration challenge page will be used for Digipass Challenge/Response or Virtual Digipass. The user enters<br />
their response to the challenge, to complete the registration process.<br />
The following posted form fields must be used on the challenge page:<br />
Table 46: Form Fields for Registration Challenge Page<br />
Form Field Name Visible Label<br />
(Default)<br />
Value(s) Required?<br />
dpcgi_operation “register” for User Registration, Digipass Assignment or<br />
Password Synchronization.<br />
dpcgi_success_page Relative or absolute URL of web page to go to if the<br />
function is successful.<br />
dpcgi_fail_page Relative or absolute URL of web page to go to if the<br />
function fails.<br />
dpcgi_userid UserId UserID in the <strong>Identikey</strong> <strong>Server</strong>. Y<br />
dpcgi_response Digipass Response Digipass response or Virtual Digipass OTP. Y<br />
dpcgi_challenge Challenge Digipass challenge returned to the user. Y<br />
Note<br />
If you make dpcgi_challenge a visible form field, ensure that it is not modifiable. An alternative is<br />
to make it a hidden form field, while also displaying the challenge in HTML text rather than as a<br />
form field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 128<br />
Y<br />
Y<br />
Y
9.3.1.2 PIN Change<br />
Web Sites<br />
The PIN Change function is only applicable for Digipass Response Only where the <strong>Server</strong> PIN is entered at the start<br />
of the response (eg. Go 1/Go 3).<br />
The following posted form fields must be used on the PIN Change page:<br />
Table 47: Form Fields for <strong>Server</strong> PIN Change Page<br />
Form Field Name Visible Label<br />
(Default)<br />
Value(s) Required?<br />
dpcgi_operation “changepin” for PIN Change. Y<br />
dpcgi_success_page Relative or absolute URL of web page to go to if the<br />
function is successful.<br />
dpcgi_fail_page Relative or absolute URL of web page to go to if the<br />
function fails.<br />
dpcgi_userid UserId UserID in the <strong>Identikey</strong> <strong>Server</strong>. Y<br />
dpcgi_response Digipass Response Digipass response (without static PIN if there is one). Y<br />
dpcgi_currentpin Current PIN Current static PIN to be changed. (6)<br />
dpcgi_newpin New PIN New static PIN. Y<br />
dpcgi_confirmpin Confirm New PIN Confirm the new static PIN. Y<br />
(6) If the Digipass has had its <strong>Server</strong> PIN reset by the administrator because the user has forgotten it, there is<br />
no current <strong>Server</strong> PIN to enter here. In all other cases, the current <strong>Server</strong> PIN must be provided to permit<br />
the PIN change.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 129<br />
Y<br />
Y
9.3.1.3 Login Test – Main Page<br />
Web Sites<br />
If a Challenge/Response application or Primary Virtual Digipass is used, the user will enter just their UserId (and<br />
maybe password) into the main page without a Digipass Response. If using the Backup Virtual Digipass, they will<br />
need to enter the trigger specified in server settings (password and/or a Keyword) into the password field.<br />
They will be directed to a challenge page, specified in the next topic. The following table applies only to the main<br />
page.<br />
The following posted form fields must be used on the main page:<br />
Table 48: Form Fields for Main Login Test Page<br />
Form Field Name Visible Label<br />
(Default)<br />
Value(s) Required?<br />
dpcgi_operation “testlogin” for Login Test. Y<br />
dpcgi_success_page Relative or absolute URL of web page to go to if<br />
the function is successful.<br />
dpcgi_fail_page Relative or absolute URL of web page to go to if<br />
the function fails.<br />
dpcgi_challenge_page Relative or absolute URL of web page to go to if a<br />
challenge is returned for the user.<br />
dpcgi_userid UserId UserID in the <strong>Identikey</strong> <strong>Server</strong>. Y<br />
dpcgi_response Digipass<br />
Response<br />
Digipass response (with static PIN if there is one). (8)<br />
(7) If any users have a Challenge/Response Digipass, a Primary Digipass or use the Backup Virtual Digipass<br />
feature, provide this form field.<br />
(8) If any users have a Response Only Digipass, provide this form field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 130<br />
Y<br />
Y<br />
(7)
9.3.1.4 Login Test – Challenge Page<br />
Web Sites<br />
The user enters their response to the challenge or the OTP sent to their mobile phone to complete the login test.<br />
The following posted form fields must be used on the challenge page:<br />
Table 49: Form Fields for Login Test Challenge Page<br />
Form Field Name Visible Label (Default) Value(s) Required?<br />
dpcgi_operation “testlogin” for Login Test. Y<br />
dpcgi_success_page Relative or absolute URL of web page to go to if<br />
the function is successful.<br />
dpcgi_fail_page Relative or absolute URL of web page to go to if<br />
the function fails.<br />
dpcgi_userid UserID User ID in the <strong>Identikey</strong> <strong>Server</strong>. Y<br />
dpcgi_response Digipass Response Digipass response. Y<br />
dpcgi_challenge Challenge Digipass challenge returned to the user. Y<br />
Note<br />
If you make dpcgi_challenge a visible form field, make sure that it is not modifiable. An<br />
alternative is to make it a hidden form field, while also displaying the challenge in HTML text<br />
rather than as a form field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 131<br />
Y<br />
Y
9.3.2 OTP Request Site<br />
9.3.2.1 Request Page<br />
The request page must contain the following fields:<br />
Table 50: Form Fields for OTP Request Page<br />
Name Type<br />
Username text Visible<br />
Password Password Visible<br />
dpcgi_operation “VDPrequest” Hidden<br />
dpcgi_vdp_success_page Name of “OTP was sent” Page Hidden<br />
dpcgi_vdp_fail_page Name of “OTP not sent” Page Hidden<br />
dpcgi_vdp_wrongtoken_page Name of “Not a Virtual Digipass” Page Hidden<br />
Web Sites<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 132
9.4 Query String Variables<br />
Web Sites<br />
The query string variables that are passed to the web pages by the CGI program are mainly concerned with status<br />
and error reporting. There is also a variable that is used to pass a challenge to the pages that display one.<br />
9.4.1 Failure/Error Handling<br />
There are three main groups of failures that can occur, which should be handled in a different manner. In all cases<br />
there is a numeric error code, however in some cases there is an auxiliary code and message such as the return<br />
code and message from the <strong>Identikey</strong> <strong>Server</strong>. The main error codes will be assigned in three separate ranges, so<br />
that the web pages can identify which category of error is returned.<br />
API return codes – these are returned by the VASCO API used to make the authentication request to the<br />
<strong>Server</strong>. In some cases there will be an auxiliary code and message.<br />
CGI errors – these errors are detected by the CGI program, mainly when the web pages are not providing or<br />
enforcing the posted form fields correctly. These will not generally have an auxiliary code and message, but it<br />
is possible.<br />
Internal errors – these are technical errors that ‘should not occur’. In some cases there will be an auxiliary<br />
code and message.<br />
The intention of using this code-based scheme is to allow translation and customization of the messages. The<br />
main error code will be translated into a message by the web pages themselves. The pages can also translate the<br />
auxiliary code into a message, for the <strong>Identikey</strong> <strong>Server</strong> codes, but normally, the pages would not know how to<br />
translate it into a message, and should display the auxiliary message as provided.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 133
9.4.2 Query String Variable List<br />
Web Sites<br />
The following table indicates which variables are used for the User Self Management Web Site and the required<br />
conditions:<br />
Table 51: Query String Variable List<br />
Variable Value Condition Used by Site<br />
result 0 Successful authentication request Both<br />
Unsuccessful authentication request Both<br />
CGI or internal error occurred Both<br />
challenge <br />
serialNo <br />
auxcode <br />
<br />
auxmsg <br />
Examples:<br />
success: /vmsite/success.html?result=0<br />
<br />
Challenge returned by API User Self<br />
Management Web<br />
Site only<br />
Successful Auto- or Self-<br />
Assignment<br />
Unsuccessful authentication request<br />
due to Controller rejecting password<br />
CGI or internal error occurred,<br />
where another error code is relevant<br />
Unsuccessful authentication request<br />
due to Controller rejecting password<br />
CGI or internal error occurred,<br />
where an error message is relevant<br />
User Self<br />
Management Web<br />
Site only<br />
invalid Digipass response due to code replay: /vmsite/fail.html?result=1000&auxcode=2&auxmsg=Code+Replay+Attempt<br />
challenge: /vmsite/challenge.html?challenge=738453<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 134<br />
Both<br />
Both<br />
Both<br />
Both
9.4.3 Return Code Listing<br />
In the following tables, the Message is the one that is provided by the standard web pages that we install.<br />
9.4.3.1 API Return Codes<br />
9.4.3.2 CGI Errors<br />
The following codes are the ones that in normal cases might be returned:<br />
Table 52: API Return Codes<br />
Code Message Auxiliary Code/<br />
Message?<br />
Notes<br />
Web Sites<br />
-1 Error during request to <strong>Server</strong> N We are unable to distinguish the error<br />
from the client side of the API – the<br />
administrator would have to look at the<br />
Audit Console.<br />
Table 53: CGI Error Return Codes<br />
Code Message Auxiliary<br />
Code/<br />
Message?<br />
-100 Only the POST method is permitted N<br />
-101 No dpcgi_operation was posted N<br />
-102 An invalid dpcgi_operation was posted N<br />
-103 dpcgi_challenge_page cannot be used for this operation N<br />
-104 dpcgi_password cannot be used for this operation N<br />
-105 dpcgi_serialno cannot be used for this operation N<br />
-106 dpcgi_currentpin cannot be used for this operation N<br />
-107 dpcgi_newpin cannot be used for this operation N<br />
-108 dpcgi_confirmpin cannot be used for this operation N<br />
-109 dpcgi_challenge cannot be used for this operation N<br />
-110 dpcgi_success_page must be entered for this operation N<br />
-111 dpcgi_fail_page must be entered for this operation N<br />
-112 dpcgi_userid must be entered for this operation N<br />
-113 dpcgi_password must be entered for this operation N<br />
-114 dpcgi_response must be entered for this operation N<br />
-115 dpcgi_newpin must be entered for this operation N<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 135
9.4.3.3 Internal Errors<br />
Web Sites<br />
Code Message Auxiliary<br />
Code/<br />
Message?<br />
-116 dpcgi_confirmpin must be entered for this operation N<br />
-117 A Digipass Response is required to assign a Digipass N<br />
-118 A New PIN can only be set when assigning a Digipass N<br />
-119 Enter the new PIN in the New PIN and Confirm New PIN fields N<br />
-120 The New PIN and Confirm New PIN fields have different values N<br />
-121 A challenge was returned, but there is no dpcgi_challenge_page N<br />
-122 Unknown parameter N<br />
-123 The Content-Length passed in was invalid N<br />
-124 dpcgi_serialno must be entered for this operation N<br />
-131 Wrong token page is forbidden N<br />
Table 54: Internal Error Codes<br />
Code Message Auxiliary<br />
Code/<br />
Message?<br />
-1000 Cannot read Trace-Mask configuration setting Y<br />
-1001 Cannot read Trace-File configuration setting Y<br />
-1002 Cannot open Trace-File Y<br />
-1003 Cannot read Source-IP-Address configuration setting Y<br />
-1004 Cannot read <strong>Server</strong>1-IP-Address configuration setting Y<br />
-1005 Cannot read <strong>Server</strong>1-Port configuration setting Y<br />
-1006 Cannot read <strong>Server</strong>2-IP-Address configuration setting Y<br />
-1007 Cannot read <strong>Server</strong>2-Port configuration setting Y<br />
-1008 Invalid configuration setting Source-IP-Address Y<br />
-1009 Invalid configuration setting <strong>Server</strong>1-IP-Address Y<br />
-1010 Invalid configuration setting <strong>Server</strong>1-Port Y<br />
-1011 Invalid configuration setting <strong>Server</strong>2-IP-Address Y<br />
-1012 Invalid configuration setting <strong>Server</strong>2-Port Y<br />
-1014 Cannot read HTTP request data N<br />
-1015 Request to <strong>Server</strong> not completed Y<br />
-1016 Cannot read Self-Management Site registry key Y<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 136
Web Sites<br />
Code Message Auxiliary<br />
Code/<br />
Message?<br />
-1017 The specified Source-IP-Address is not on this machine N<br />
-1018 Cannot read Trace-Header configuration setting Y<br />
-1019 Invalid configuration setting Trace-Header Y<br />
-1020 The Trace file name must not contains quotes ' or ". N<br />
-1021 No File found in the trace file N<br />
-1030 Error reading <strong>Server</strong> 1 Secret - return code was N<br />
-1031 Error reading <strong>Server</strong> 2 Secret - return code was N<br />
-1032 Error reading No of Retries - return code was N<br />
-1033 Error reading Timeout - return code was N<br />
-1034 Error writing Protocol - return code was N<br />
-1040 The Shared Secret and Confirm Shared Secret do not match. N<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 137
10 Login Options<br />
10.1 Login Permutations<br />
Login Options<br />
The information required to be entered during a login will vary according to the configuration settings of the<br />
relevant Policy, the login method, and any actions to be performed during the login.<br />
This section refers to authentication processing only, not Signature Validation or Provisioning.<br />
10.1.1 Login Methods<br />
The login methods specified are:<br />
Response Only<br />
Challenge/Response:<br />
10.1.2 Login Actions<br />
1-Step Challenge/Response: a random challenge is presented on the login page before the User ID is known.<br />
This is supported for SOAP clients and form-based IIS Modules.<br />
2-Step Challenge/Response: a challenge is generated after the user submits their User ID with a request to<br />
be given a challenge. The user then logs in with the response to the challenge in a second step. This is<br />
supported for all kinds of authentication client.<br />
Virtual Digipass - Primary or Backup<br />
A User may be allowed to do these things during a login:<br />
Set their <strong>Server</strong> PIN – on first use or after a PIN reset.<br />
Change their <strong>Server</strong> PIN.<br />
10.1.3 Login Variables<br />
Inform the <strong>Identikey</strong> <strong>Server</strong> that their static password for the Back-End System – eg. Windows - has been<br />
modified.<br />
Perform a Self-Assignment for a Digipass in their possession.<br />
The variables which a User may need to enter, in order to do one of the above functions are listed below. The<br />
code or word used to designate each variable in the following tables is included in brackets.<br />
One Time Password (OTP)<br />
Password (Password)<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 138
<strong>Server</strong> PIN (PIN)<br />
Serial Number of their Digipass (Serial No)<br />
Serial Number Separator (Sep.)<br />
Request Keyword (Keyword)<br />
10.1.4 Password Format<br />
In a SOAP authentication request, there are two Password Formats that can be used:<br />
Cleartext Combined<br />
Login Options<br />
Using this format, all the login variables listed above must be entered into a single password field. This format<br />
applies when the login screen or web page cannot be extended with additional entry fields.<br />
Cleartext Separate<br />
Using this format, the login variables are entered in separate fields.<br />
In RADIUS authentication requests, the PAP password protocol corresponds to the Cleartext Combined password<br />
format. The CHAP, MS-CHAP and MS-CHAP2 password protocols are handled as different password formats (as<br />
the password is hashed in various ways according to the protocol). In general, these hash-based password formats<br />
are not capable of combining different login variables, unless all the variables are already known to the <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
In administrative logons and IIS Module authentication requests, the Cleartext Combined password format is always<br />
used.<br />
10.1.5 Policy Settings<br />
The Policy settings which will affect the variables required in logins are:<br />
Stored Password Proxy<br />
If this attribute is set to Enabled, each User's password must be kept up to date in the <strong>Identikey</strong> <strong>Server</strong>. This is<br />
typically achieved by enabling Password Autolearn.<br />
Password Autolearn<br />
If the <strong>Identikey</strong> <strong>Server</strong> is informed of a User's password change, the new password will only be recorded by the<br />
<strong>Identikey</strong> <strong>Server</strong> if Password Autolearn is enabled in the relevant Policy<br />
Serial Number Separator<br />
If a Serial Number Separator is specified, the User may enter their Digipass serial number exactly as it appears<br />
on the back of their Digipass (or in the documentation provided to the User), including dashes. If a Serial<br />
Number Separator is not specified, the Digipass serial number must be padded to 10 characters, with all nonnumerical<br />
characters removed.<br />
Back-End Authentication<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 139
Login Options<br />
In the following login permutations tables, 'Back-End Authentication Required' means that the Back-End<br />
Authentication setting is set to Always or If Needed.<br />
Note<br />
Back-End Authentication is required for Self-Assignment and Password Autolearn logins.<br />
10.1.6 Response Only – Cleartext Combined Password Format<br />
The following two tables apply to the following cases:<br />
SOAP using Cleartext Combined password format<br />
Administration logins<br />
RADIUS using PAP<br />
IIS Modules<br />
The first table applies in these cases when:<br />
EITHER the Stored Password Proxy feature is enabled<br />
OR Back-End Authentication is not enabled<br />
Table 55: Login Permutations - Response Only Cleartext Combined (1)<br />
<strong>Server</strong> PIN<br />
Required<br />
Login Type Existing PIN?<br />
Separator?<br />
Normal login Yes N/A PIN+OTP<br />
Password Field Contents<br />
Set PIN No N/A OTP+NewPIN+NewPIN<br />
Change PIN Yes N/A PIN+OTP+NewPIN+NewPIN<br />
Changed Password Yes N/A Password+PIN+OTP<br />
Set PIN and Changed Password No N/A Password+OTP+NewPIN+NewPIN<br />
Change PIN and Changed Password Yes N/A Password+PIN+OTP+NewPIN+NewPIN<br />
Self-Assignment 1 Yes Yes SerialNo+Sep.+Password+PIN+OTP<br />
No <strong>Server</strong> Normal login N/A N/A OTP<br />
No SerialNo+Password+PIN+OTP<br />
No Yes SerialNo+Sep.+Password+OTP+NewPIN+NewPIN<br />
No SerialNo+Password+OTP+NewPIN+NewPIN<br />
1 If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to<br />
10 characters with preceding zeroes. Note that Back-End Authentication is required for successful Self-Assignment.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 140
PIN<br />
Required<br />
Login Type Existing PIN?<br />
Separator?<br />
Password Field Contents<br />
Changed Password N/A N/A Password+OTP<br />
Self-Assignment N/A Yes SerialNo+Sep.+Password+OTP<br />
The second table applies in these cases when:<br />
The Stored Password Proxy feature is not enabled<br />
AND Back-End Authentication is enabled<br />
Table 56: Login Permutations - Response Only Cleartext Combined (2)<br />
<strong>Server</strong> PIN<br />
Required<br />
No <strong>Server</strong><br />
PIN<br />
Required<br />
Login Type Existing PIN?<br />
No SerialNo+Password+OTP<br />
Separator?<br />
Normal login Yes N/A Password+PIN+OTP<br />
Password Field Contents<br />
Set PIN No N/A Password+OTP+NewPIN+NewPIN<br />
Change PIN Yes N/A Password+PIN+OTP+NewPIN+NewPIN<br />
Changed Password Yes N/A Password+PIN+OTP<br />
Set PIN and Changed Password No N/A Password+OTP+NewPIN+NewPIN<br />
Change PIN and Changed Password Yes N/A Password+PIN+OTP+NewPIN+NewPIN<br />
Self-Assignment 2 Yes Yes SerialNo+Sep.+Password+PIN+OTP<br />
No SerialNo+Password+PIN+OTP<br />
Normal login N/A N/A Password+OTP<br />
Changed Password N/A N/A Password+OTP<br />
Login Options<br />
No Yes SerialNo+Sep.+Password+OTP+NewPIN+NewPIN<br />
No SerialNo+Password+OTP+NewPIN+NewPIN<br />
Self-Assignment N/A Yes SerialNo+Sep.+Password+OTP<br />
No SerialNo+Password+OTP<br />
Examples<br />
Self-Assignment of a GO 1 Digipass with no existing <strong>Server</strong> PIN and Serial Number Separator set to '::'.<br />
3-179-0987::pA192ss086382012341234<br />
Self-Assignment of a GO 3 Digipass with no <strong>Server</strong> PIN required and no Serial Number Separator set.<br />
0031790987PA192ss0863820<br />
2 If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to<br />
10 characters with preceding zeroes. Note that Back-End Authentication is required for successful Self-Assignment.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 141
10.1.7 Response Only – CHAP/MS-CHAP/MS-CHAP2<br />
The following table applies to the following case only:<br />
RADIUS using CHAP, MS-CHAP or MS-CHAP2<br />
EITHER the Stored Password Proxy feature is enabled<br />
OR Back-End Authentication is not enabled<br />
Table 57: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP2<br />
Login Type <strong>Server</strong> PIN<br />
Required?<br />
Normal login Yes PIN+OTP<br />
No OTP<br />
Password Field Contents<br />
10.1.8 2-Step Challenge/Response – Cleartext Combined Password Format<br />
The following table applies to the following cases:<br />
SOAP using Cleartext Combined password format<br />
Administration logins<br />
RADIUS using PAP<br />
IIS Modules<br />
Challenge/Response in RADIUS is only supported for PAP.<br />
The column Stored Password Proxy Off AND Back-End Auth. Required contains Yes when:<br />
The Stored Password Proxy feature is not enabled<br />
AND Back-End Authentication is enabled<br />
In most cases, this does not affect 2-Step Challenge/Response; just when a Keyword only is used.<br />
Login Options<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 142
Table 58: Login Permutations – 2-Step Challenge/Response Cleartext Combined<br />
Login Type Serial Number Separator?<br />
Request Method<br />
2-Step Challenge/Response<br />
Stored<br />
Password<br />
Proxy Off<br />
AND Back-<br />
End Auth.<br />
Required 3<br />
Login Options<br />
Pre-Challenge Response<br />
Normal login N/A Keyword Yes Keyword Password+OTP<br />
No Keyword OTP<br />
Password N/A Password OTP<br />
Keyword-Password N/A Keyword+Password OTP<br />
Password-Keyword N/A Password+Keyword OTP<br />
Changed Password N/A Keyword N/A Keyword Password+OTP<br />
Password N/A Password OTP<br />
Keyword-Password N/A Keyword+Password OTP<br />
Password-Keyword N/A Password+Keyword OTP<br />
Self-Assignment 4 Yes N/A N/A SerialNo+Sep.+Password OTP<br />
No N/A N/A SerialNo+Password OTP<br />
3 Back-End Authentication is required for Self-Assignment and Password Autolearn logins.<br />
4 If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to<br />
10 characters with preceding zeroes.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 143
10.1.9 Virtual Digipass<br />
Login Options<br />
The 2-step Virtual Digipass login is possible when using a SOAP client, the RADIUS Access-Challenge mechanism<br />
or an IIS Module in form-based authentication mode. The static password is required in either the first or the<br />
second step, but not both.<br />
However, many RADIUS environments and IIS Module 'basic authentication' do not support the 2-step login<br />
process. If the 2-step login process is not possible, two separate 1-step logins are required. The second login must<br />
include the Password as well as the OTP, but it is not necessary to provide the Password in the first login, if only a<br />
Keyword is used.<br />
Using the Cleartext Combined password format, all inputs in the table below are entered into the Password field.<br />
Using the Cleartext Separate password format, the Keyword and/or Password are always entered into the Static<br />
Password field, while the OTP is entered into the OTP field.<br />
Table 59: Login Permutations – Virtual Digipass<br />
Login<br />
Type<br />
Normal<br />
login<br />
Changed<br />
Password<br />
Request Method 2-step login Two 1-step logins<br />
Step 1 Step 2 Step 1 Step 2<br />
Keyword Keyword Password+OTP Keyword Password+OTP<br />
Password Password OTP Password Password+OTP<br />
Keyword-Password Keyword+Password OTP Keyword+Password Password+OTP<br />
Password-Keyword Password+Keyword OTP Password+Keyword Password+OTP<br />
Keyword Keyword Password+OTP Keyword Password+OTP<br />
Password Password OTP Password Password+OTP<br />
Keyword-Password Keyword+Password OTP Keyword+Password Password+OTP<br />
Password-Keyword Password+Keyword OTP Password+Keyword Password+OTP<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 144
11 <strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
11.1 <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard<br />
The <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard runs in two different modes:<br />
First Time Mode<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
After the <strong>Identikey</strong> <strong>Server</strong> is installed, the Configuration Wizard needs to be run in First Time mode. This ensures<br />
that all necessary configuration to get the <strong>Identikey</strong> <strong>Server</strong> operational is accomplished as easily as possible. This<br />
mode creates the <strong>Identikey</strong> <strong>Server</strong> configuration file and initializes the data store with default data and the first<br />
administrator account.<br />
Afterwards, configuration settings can be managed using the <strong>Identikey</strong> <strong>Server</strong> Configuration utility. The data store<br />
can be managed using the Web Administration Interface and Digipass TCL Command-Line Administration.<br />
The Configuration Wizard starts up in First Time mode if the <strong>Identikey</strong> <strong>Server</strong> configuration file is not present.<br />
Maintenance Mode<br />
If the <strong>Identikey</strong> <strong>Server</strong> configuration file is present, the Configuration Wizard will start up in Maintenance mode.<br />
In Maintenance mode, an operations menu is available to carry out certain maintenance tasks that cannot be<br />
carried out with the day-to-day administration tools. These tasks are:<br />
Re-run Installation Wizard<br />
Change <strong>Server</strong> location<br />
Back Up Audit Messages - Back up Audit Message files or databases<br />
Rescue administrator - create a new administrator account<br />
Rescue Administration Client - create or modify an Administration Program client<br />
Install SSL server certificate<br />
Restore Default Policies and Reports<br />
11.2 Redeploy Administration Web Interface<br />
After running the Configuration Wizard or making changes to SSL certificate settings, the Administration Web<br />
Interface must be redeployed:<br />
1. Open a command line window.<br />
2. Navigate to the \webadmin directory.<br />
3. Delete the existing certificate from the keystore using the following command:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 145
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
java -jar admintool.jar certificate delete <br />
where is the location and file name of the keystore and is the<br />
password on the keystore.<br />
For example:<br />
java -jar admintool.jar certificate delete c:\Program Files\VASCO\<strong>Identikey</strong><br />
3.1\webadmin\keystore.jks password1<br />
4. Add the new certificate that has been generated:<br />
java -jar admintool.jar certificate add <br />
where is the location and file name of the keystore, is the<br />
password on the keystore and is the certificate that was generated after re-running the<br />
configuration wizard.<br />
For example:<br />
java -jar admintool.jar certificate add c:\Program Files\VASCO\<strong>Identikey</strong><br />
3.1\webadmin\ keystore.jks password1 c:\Program Files\VASCO\<strong>Identikey</strong><br />
3.1\bin\ikeycerts.pem<br />
5. Restart the web server application.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 146
11.3 <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
A Graphical User Interface (GUI) is available for use in configuring the <strong>Identikey</strong> <strong>Server</strong>. There are several sections<br />
in <strong>Identikey</strong> <strong>Server</strong> Configuration, which can be reached by clicking on the corresponding image on the left hand<br />
side.<br />
When settings are changed, click on the Apply or OK button to write them to the configuration file. Clicking OK also<br />
closes <strong>Identikey</strong> <strong>Server</strong> Configuration.<br />
Note<br />
A restart of the <strong>Identikey</strong> <strong>Server</strong> service or daemon is required after any change to <strong>Identikey</strong><br />
<strong>Server</strong> configuration settings. When exiting the Configuration Wizard, you will be prompted to<br />
allow an automatic restart of the service.<br />
The Administration Web Interface must also be redeployed if any changes are made to the SSL<br />
certificate settings. This includes running the Configuration Wizard. See 11.2 Redeploy<br />
Administration Web Interface for instructions.<br />
11.3.1 Starting the Configuration GUI<br />
Windows<br />
To start the <strong>Identikey</strong> <strong>Server</strong> Configuration, click on the Start Button and select Programs -> VASCO -><strong>Identikey</strong><br />
<strong>Server</strong> -> <strong>Identikey</strong> <strong>Server</strong> Configuration.<br />
Linux<br />
To start the <strong>Identikey</strong> <strong>Server</strong> Configuration in graphical interface mode, open a command prompt and enter:<br />
vds_chroot /usr/sbin/ikconfigwizardgui<br />
To start the <strong>Identikey</strong> <strong>Server</strong> Configuration GUI in console mode, open a command prompt and enter:<br />
11.3.2 General Section<br />
vds_chroot /usr/sbin/ikconfigwizardconsole<br />
This section contains a few general settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 147
11.3.2.1 <strong>Server</strong> Location<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The <strong>Server</strong> Location setting contains the licensed IP address for the <strong>Identikey</strong> <strong>Server</strong>. The <strong>Identikey</strong> <strong>Server</strong> uses<br />
this IP address to listen for SOAP and RADIUS requests. There must be a <strong>Identikey</strong> <strong>Server</strong> component record with<br />
this Location, containing a valid License Key. The setting is carried forward to the Communication Protocols<br />
pages.<br />
11.3.2.2 Administration Session Settings<br />
11.3.2.3 Tracing<br />
The following settings control the number and lifetime of administration sessions for this <strong>Identikey</strong> <strong>Server</strong>:<br />
Max Concurrent Sessions: the maximum number of concurrent administration sessions permitted. If this is set<br />
to 0, concurrent sessions will be unlimited.<br />
Max Session Time (seconds): the maximum allowed length of an administration session. There is no way to<br />
extend a session beyond this limit.<br />
Idle Timeout (seconds): the maximum length of time of inactivity allowed during a session, before the session<br />
it automatically terminated by the <strong>Identikey</strong> <strong>Server</strong>.<br />
To enable or disable tracing by <strong>Identikey</strong> <strong>Server</strong>:<br />
1. Select a Tracing option.<br />
2. Enter a path and filename for the tracing file into the File field. The file path entered must be the full absolute<br />
path.<br />
Note<br />
11.3.3 Communicators Section<br />
11.3.3.1 SOAP<br />
If the File field is left blank or the path does not exist, the <strong>Identikey</strong> <strong>Server</strong> will not output tracing.<br />
If the file does exist, tracing will be appended to the file. If the path is valid but the file does not<br />
exist, it will be created.<br />
This section contains settings for the Communicator modules (see the Structure of <strong>Identikey</strong> <strong>Server</strong> section in the<br />
Product Guide).<br />
The SOAP Communicator settings are:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 148
11.3.3.2 RADIUS<br />
11.3.3.3 SEAL<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Enable SOAP: whether to listen for and process SOAP requests or not. Note that the <strong>Identikey</strong> <strong>Server</strong>'s License<br />
Key must enable SOAP for it to be enabled.<br />
IP Address: the IP address on which to listen for SOAP requests. This is read-only, as it must be the same as<br />
the licensed IP address for the <strong>Identikey</strong> <strong>Server</strong>. It can be changed in the General section using the <strong>Server</strong><br />
Location setting (see 11.3.2.1 <strong>Server</strong> Location).<br />
Port: the port number on which to listen for SOAP requests.<br />
DPX File Upload Location: the directory in which DPX files uploaded using the SOAP administration interface<br />
will be stored by the <strong>Identikey</strong> <strong>Server</strong>. This is used by the Web Administration Interface.<br />
<strong>Server</strong> Certificate: the details for the SSL server certificate. The Certificate File address must be the address<br />
of a .pem file.<br />
Client Certificate: the details for the SSL client certificate.<br />
CA certificate store is the absolute address to the file that contains the approved CA list. See the SOAP<br />
SSL section in the Product Guide.<br />
Require Client Certificate indicates whether the client certificate is required to during SSL processing. See<br />
the SOAP SSL section in the Product Guide for further information. The valid values are:<br />
Never<br />
Optional<br />
Required<br />
Required - Signed Address Only<br />
Re-Verify on re-negotiation - see the SOAP SSL section in the Product Guide for more details.<br />
The RADIUS Communicator settings are:<br />
Enable RADIUS: whether to listen for and process RADIUS requests or not. Note that the <strong>Identikey</strong> <strong>Server</strong>'s<br />
License Key must enable RADIUS for it to be enabled.<br />
IP Address: the IP address on which to listen for RADIUS requests. This is read-only, as it must be the same as<br />
the licensed IP address for the <strong>Identikey</strong> <strong>Server</strong>. It can be changed in the General section using the <strong>Server</strong><br />
Location setting (see 11.3.2.1 <strong>Server</strong> Location).<br />
Authentication Port: the port number on which to listen for RADIUS Access-Requests. You may specify more<br />
than one port, using a comma-separated list.<br />
Accounting Port: the port number on which to listen for RADIUS Accounting-Requests. You may specify more<br />
than one port, using a comma-separated list.<br />
The SEAL Communicator settings are:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 149
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Enable SEAL: whether to listen for and process SEAL requests or not. Note that SEAL does not need to be<br />
enabled in the <strong>Identikey</strong> <strong>Server</strong>'s License Key.<br />
Caution<br />
Replication updates from other <strong>Identikey</strong> <strong>Server</strong>s are received by the SEAL Communicator. If you<br />
disable it, this <strong>Identikey</strong> <strong>Server</strong> will not be able to receive Replication updates.<br />
11.3.4 Scenarios Section<br />
Digipass TCL Command-Line Administration also uses SEAL to connect to the <strong>Identikey</strong> <strong>Server</strong>.<br />
IP Address: the IP address on which to listen for SEAL requests. This does not have to be the same as the<br />
licensed IP address for the <strong>Identikey</strong> <strong>Server</strong>.<br />
Port: the port number on which to listen for SEAL requests.<br />
DPX File Upload Location: the directory in which DPX files uploaded using the SEAL administration interface<br />
will be stored by the <strong>Identikey</strong> <strong>Server</strong>. This is used by the Web Administration Interface.<br />
Require administration client component registration: whether to use strict client component checking for<br />
SEAL administration logons or not. If this option is enabled, there must be an Administration Program client<br />
component record for every Location at which Digipass TCL Command-Line Administration runs and for every<br />
Location at which an Audit Viewer sets up a Live Connection to an <strong>Identikey</strong> <strong>Server</strong>.<br />
This section contains settings for the Scenario modules (see the Structure of <strong>Identikey</strong> <strong>Server</strong> section in the<br />
Product Guide). Some Scenario modules do not have specific settings except to enable or disable them, while<br />
others do have further settings.<br />
11.3.4.1 Authentication Scenario<br />
The only setting for this Scenario is to enable or disable it. Note that the <strong>Identikey</strong> <strong>Server</strong>'s License Key must<br />
enable Authentication for it to be enabled.<br />
11.3.4.2 Signature Validation Scenario<br />
The only setting for this Scenario is to enable or disable it. Note that the <strong>Identikey</strong> <strong>Server</strong>'s License Key must<br />
enable Signature for it to be enabled.<br />
11.3.4.3 Provisioning Scenario<br />
This Scenario has the following settings:<br />
Enable Provisioning: whether to process Provisioning requests or not. Note that the <strong>Identikey</strong> <strong>Server</strong>'s License<br />
Key must enable Provisioning for it to be enabled.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 150
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Min Intervals: the minimum length of time in minutes between activation attempts for a particular Digipass.<br />
Max Attempts: the total number of activation attempts (successful or unsuccessful) per Digipass.<br />
Max Locations: the maximum number of different locations at which a particular Digipass can be activated.<br />
This only applies where the location is specified as part of Provisioning (Digipass for Web).<br />
11.3.4.4 Administration Scenario<br />
The only setting for this Scenario is to enable or disable it. Note that no License Key is required for administration<br />
to be enabled.<br />
11.3.4.5 Reporting Scenario<br />
11.3.4.6 Audit Scenario<br />
This Scenario has the following settings:<br />
Enable Reporting: whether to process Reporting requests or not. Note that no License Key is required for<br />
reporting to be enabled.<br />
Source: the type of audit data source to use for report generation. UTF8 File and ODBC Database are the<br />
supported options.<br />
If UTF8 File is selected, the following settings are required:<br />
File Path: the full absolute path to the directory in which the audit text files can be found. Note that the<br />
search for audit files is not recursive - all files must be in this exact directory.<br />
Extension: the file extension that identifies which files in the File Path are audit files to be read. For<br />
example, .audit.<br />
If ODBC Database is selected, the following settings are required:<br />
DSN: the ODBC Data Source Name for the audit database.<br />
Username: the username with which to log into the audit database, if required.<br />
Password: the password to log into the audit database, if required.<br />
The only setting for this Scenario is to enable or disable it. Note that no License Key is required for the Audit<br />
Scenario to be enabled.<br />
When this Scenario is disabled, live connections from the Audit Viewer are not possible to this <strong>Identikey</strong> <strong>Server</strong>.<br />
11.3.4.7 Replication Scenario<br />
The only setting for this Scenario is to enable or disable it. Note that no License Key is required for administration<br />
to be enabled.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 151
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
When this Scenario is disabled, Replication updates sent to this <strong>Identikey</strong> <strong>Server</strong> will not be processed.<br />
11.3.4.8 Configuration Scenario<br />
This scenario allows configuration settings to be edited from the Administration Web Interface.<br />
The scenario may be enabled or disabled. No other settings are required.<br />
11.3.5 Engines Section<br />
This section allows you to set up custom Back-End Authentication Engine plug-in modules (see the Structure of<br />
<strong>Identikey</strong> <strong>Server</strong> section in the Product Guide and the <strong>Identikey</strong> <strong>Server</strong> SDK Guide).<br />
Click on the Add... button if you wish to add a new plug-in engine. The Add Plugin Engine window will be<br />
displayed. Select an engine and click on Edit... to change the settings for that engine. The Edit Plugin Window<br />
will be displayed. Both windows contain the same information. Add or edit the details as follows:<br />
1. Enter a Display Name for the engine (this will just be used in the Engines list).<br />
2. Enter a Library Path, indicating where the engine is kept.<br />
3. Enter a Protocol to be used when the engine is connecting to <strong>Identikey</strong> <strong>Server</strong>.<br />
4. Enter Custom Fields - the Name and Value of fields used to pass parameters into the back-end engine.<br />
They are entirely user-defined and the name and value are passed into the back-end engine as a string.<br />
To test the connection to the plug-in engine, select an engine and click Test. Enter the domain name, User Id and<br />
Password and click Authenticate.<br />
11.3.6 Storage Section<br />
This section contains settings to configure the <strong>Identikey</strong> <strong>Server</strong> data store.<br />
11.3.6.1 ODBC Data Sources<br />
The database(s) used to store data required by <strong>Identikey</strong> <strong>Server</strong> are listed in this tab.<br />
You may wish to add another database to this list if load-balancing or fail-over mechanisms need to be<br />
implemented.<br />
1. Click on the Add... button if you wish to add a new database or Edit... if you wish to modify the settings for<br />
an existing database.<br />
2. The Add New ODBC Data Source window will be displayed.<br />
3. Enter a Display Name for the data source (this will just be used in data source list).<br />
4. Enter the name (DSN) of the ODBC data source.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 152
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
5. Enter the Username and Password of a database administrator account with permissions to read, update,<br />
create and delete data used by <strong>Identikey</strong> <strong>Server</strong> (see 3.6 Database User Accounts).<br />
6. Click on the Test Connection button.<br />
If the information has been entered correctly, the test should be successful.<br />
7. Enter the minimum time the <strong>Identikey</strong> <strong>Server</strong> should wait before trying to reconnect to this data source (in<br />
seconds), after the connection has broken, into the Min Reconnect Interval (s).<br />
8. Enter the maximum time the <strong>Identikey</strong> <strong>Server</strong> should wait before retrying the connection to this data source<br />
into the Max Reconnect Interval (s).<br />
9. Click on the OK button to close the window.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 153
11.3.6.2 LDAP Data Sources<br />
11.3.6.3 Encryption<br />
Active Directory domains to which the <strong>Identikey</strong> <strong>Server</strong> can connect are listed in this tab.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
1. Click on the Add... button if you wish to add a new domain or Edit... if you wish to modify the settings for an<br />
existing domain.<br />
2. The Add LDAP Domain window will be displayed.<br />
3. Enter the Fully Qualified Domain Name for the domain.<br />
4. If required, enter the name of a server in the domain in the Preferred <strong>Server</strong> field.<br />
If a Preferred <strong>Server</strong> is specified, the <strong>Identikey</strong> <strong>Server</strong> will attempt to connect to it rather than the first<br />
available server in the domain.<br />
5. If the <strong>Identikey</strong> <strong>Server</strong> should only connect to the Preferred <strong>Server</strong>, tick the Preferred <strong>Server</strong> Only checkbox.<br />
6. To use an encrypted connection, tick the Encrypt Remote Connections checkbox.<br />
7. Enter a port number to use for unencrypted connections in the Unencrypted Port field.<br />
8. If the Encrypt Remote Connections checkbox is ticked, enter a port number to use for encrypted<br />
connections in the Encrypted Port field.<br />
9. Enter an integer in the Max. Bind Lifetime field.<br />
10. Click on the OK button to close the window.<br />
See 4 Sensitive Data Encryption for more information on encryption in the <strong>Identikey</strong> <strong>Server</strong> data store. All <strong>Identikey</strong><br />
<strong>Server</strong>s must share the same encryption settings.<br />
To modify encryption settings for the first <strong>Identikey</strong> <strong>Server</strong>:<br />
1. If required, enter a custom encryption key in the Storage Key field. This must consist of 32 hex digits. The<br />
Storage Key is used to derive a unique encryption key for your installation.<br />
Caution<br />
If you change from having no Storage Key to having a Storage Key specified, all Digipass records<br />
already in the data store will be invalidated. They will need to be deleted and re-imported.<br />
However, Passwords and Shared Secrets in the data store will still be valid (they will be<br />
converted to the new Storage Key when they are next updated).<br />
If you change from one Storage Key to a different Storage Key, all Digipass records, Passwords<br />
and Shared Secrets in the data store will be invalidated, and will have to be re-entered.<br />
2. If required, select an encryption algorithm from the Cipher Name drop down list. The available algorithms are<br />
aes256 (AES), des_ede (Triple DES) and des_ede3 (Triple DES with 3 keys).<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 154
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
If you have any other <strong>Identikey</strong> <strong>Server</strong>s, you need to export the new encryption settings and import them into<br />
the other <strong>Identikey</strong> <strong>Server</strong>s.<br />
3. Click on Export...<br />
4. Browse to a directory in which to create an encryption settings file.<br />
5. Enter a file name to export the settings to.<br />
6. Click on OK.<br />
7. Enter a password to protect the Storage Key.<br />
8. Click on OK.<br />
For each other <strong>Identikey</strong> <strong>Server</strong>, launch the <strong>Identikey</strong> <strong>Server</strong> Configuration utility and open the Encryption<br />
tab:<br />
9. Click on Import...<br />
10. Browse to the encryption settings file.<br />
11. Click on OK.<br />
12. Enter the required password.<br />
13. Click on OK.<br />
11.3.6.4 Advanced Configuration Settings<br />
This tab contains settings related to database connection management, as well as User ID and Domain handling.<br />
While the top two settings are stored in the <strong>Identikey</strong> <strong>Server</strong> configuration file, the other settings are stored inside<br />
the database itself, in the Control table. Each database has its own Control table, so those settings may need to be<br />
modified in more than one database.<br />
See 3.7 Database Connection Handling for more details about the connection management settings.<br />
Data Source-Independent Connection Settings<br />
The following settings are not specific to a data source, but relate to the handling of connections to all data<br />
sources:<br />
Connection Wait Time (ms): the time in milliseconds to wait for a database connection to become available<br />
when processing a command, before giving up and failing the request.<br />
Enable Load Sharing: whether to use the extra data sources (after the first one) when the first one is busy<br />
(enabled), or only when it cannot be contacted (disabled).<br />
Data Source-Specific Connection Settings<br />
The following settings are specific to each data source and can be configured differently in each if required. Use<br />
the Data Source Connection drop-down to view and edit the settings for each data source.<br />
Max Connections: the maximum number of connections to establish to this data source.<br />
Idle Timeout (seconds): the maximum time for which a connection can be idle before it is closed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 155
User ID and Domain Settings<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The following settings are stored in the Control table and are therefore configured in each data source separately.<br />
However, they should normally be the same in each data source. You will have to make sure that they are<br />
configured in each data source, as there is no automatic replication of these settings.<br />
User ID Conversion / Case<br />
Use Windows User Name Resolution<br />
Master Domain<br />
They are explained in more detail below:<br />
User ID Conversion<br />
The case in which the <strong>Identikey</strong> <strong>Server</strong> will save and retrieve User IDs will depend on:<br />
The capabilities and settings of the database used as the data store for the <strong>Identikey</strong> <strong>Server</strong>. Your database<br />
may require case sensitivity in queries, or may store all data in lower or upper case.<br />
Configuration settings for the <strong>Identikey</strong> <strong>Server</strong>.<br />
The <strong>Identikey</strong> <strong>Server</strong> may be configured to save and retrieve User IDs and domain names in:<br />
Lower case<br />
Upper case<br />
No conversion – data is saved or searched on exactly as entered.<br />
The default configuration setting for the <strong>Identikey</strong> <strong>Server</strong> when using an embedded database is Convert to Lower.<br />
When using another ODBC database, the default is No Conversion.<br />
Caution<br />
Before changing the configuration setting, you need to make sure that existing User IDs and<br />
Domain names will not be invalidated by the new setting, or that they are deleted before the<br />
setting is changed. For example, if the current setting is No Conversion and you change to<br />
Convert to Lower, a User ID “TestUser” would become invalid. This Digipass User account must<br />
be deleted before changing the Case Conversion setting.<br />
Typically, this setting should be changed shortly after installation, so you do not have to deal<br />
with a lot of existing Digipass User account and Domain records.<br />
If you want to move from Convert to Lower to Convert to Upper, or vice versa, it will be necessary<br />
to make the change in two steps, via No Conversion. While the setting is No Conversion, upper or<br />
lower case User IDs and Domains can be created and deleted as necessary.<br />
This is especially important for the Master Domain name. The default Master Domain “master”<br />
will become invalid if you change to Convert to Upper. Therefore, you will need to create a new<br />
Domain with an upper case name and make it the Master Domain, while the Case Conversion<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 156
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
setting is No Conversion. See Master Domain below for instructions to change the Master<br />
Domain.<br />
To modify the Case Conversion setting for the <strong>Identikey</strong> <strong>Server</strong>:<br />
1. Select a data source from the list.<br />
2. If you wish the <strong>Identikey</strong> <strong>Server</strong> to convert User IDs to upper or lower case, select Convert to Upper or<br />
Convert to Lower from the Case drop down list.<br />
To leave User IDs and domains as they are entered, select No Conversion.<br />
3. Click on OK.<br />
4. The same setting must be applied in each database for each <strong>Identikey</strong> <strong>Server</strong>. This setting change is not<br />
replicated automatically to other databases.<br />
Windows User Name Resolution<br />
<strong>Identikey</strong> <strong>Server</strong> can use Windows functions to identify User IDs as Windows User accounts. This may be required<br />
if Windows is used as the back-end authenticator for <strong>Identikey</strong> <strong>Server</strong>.<br />
1. Select a data source from the list.<br />
2. To have the <strong>Identikey</strong> <strong>Server</strong> look up a User ID with Windows to find the SAM-Account-Name for the account<br />
and Fully Qualified Domain Name, tick the Use Windows User Name Resolution checkbox.<br />
3. Click on OK.<br />
4. The same setting must be applied in each database for each <strong>Identikey</strong> <strong>Server</strong>. This setting change is not<br />
replicated automatically to other databases.<br />
Master Domain<br />
The Master Domain is used as a default Domain as well as having special significance for administrative access.<br />
For more details, see 3.5.1.1 Master Domain.<br />
To modify the domain used as the Master Domain:<br />
1. If the new Master Domain does not already have a Domain record, create the new Domain using the Web<br />
Administration Interface.<br />
2. Make sure there is an administrator account in the new Master Domain that has Set Administrative<br />
Privileges permission.<br />
3. In the Advanced Settings tab of the Storage section in <strong>Identikey</strong> <strong>Server</strong> Configuration, select a data source<br />
from the list.<br />
4. Modify the name in the Master Domain field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 157
11.3.7 Auditing<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Caution<br />
Ensure that the name of the Master Domain is set to the correct case, as required by the Case<br />
Conversion setting. For example, if the Case Conversion setting is Convert to Lower, the Master<br />
Domain name must be all lower case.<br />
5. Click on OK.<br />
6. The same setting must be applied in each database for each <strong>Identikey</strong> <strong>Server</strong>. This setting change is not<br />
replicated automatically to other databases.<br />
7. Click Apply or OK to make sure all changes are committed.<br />
8. Login to the Web Administration Interface as the administrator account identified in step 2. Give this account<br />
any privileges that it requires that are missing. You will need to log off and on again as this account for the<br />
new privileges to take effect.<br />
9. Delete the original 'master' domain if no longer required.<br />
Note<br />
All User accounts must be deleted from a domain before the domain record can be deleted.<br />
To view or edit auditing settings, use the Auditing section. For more information about setting up auditing, see 14<br />
Auditing.<br />
Enable or Disable an Audit Method<br />
Use the checkbox next to the Display Name of the required Audit Method in the list.<br />
Add an Audit Method<br />
1. Click on the Add... button.<br />
2. Select a Plug-in type from the drop down list.<br />
3. Click on OK.<br />
The Plugin window will be displayed.<br />
4. Enter a name to use for display purposes in the Display Name field.<br />
5. Tick the Reject audit message if this method fails checkbox if you want the <strong>Identikey</strong> <strong>Server</strong> to return an<br />
error if it fails to record an auditing message.<br />
6. Tick the Record audit message if no other audit method has recorded it checkbox if messages should only<br />
be logged by this auditing plug-in if they have not been previously logged by any other plug-in.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 158
7. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
8. Enter the Text file settings.<br />
Enter the address of the log file<br />
Check the Always keep file open checkbox if required.<br />
Check the Use GMT/UTC checkbox if required.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Check the Allow multiple lines in file checkbox if multiple lines of messages are required, instead of one<br />
long line of concatenated messages.<br />
9. Click on OK.<br />
Edit an Audit Method<br />
1. Select an auditing plug-in from the Methods list.<br />
2. Click on the Edit... button.<br />
The Plug-In window will be displayed.<br />
3. Make the required changes.<br />
4. Click on OK.<br />
5. Click on Apply.<br />
Delete an Audit Method<br />
1. Select an auditing plug-in from the Methods list.<br />
2. Click on the Delete button.<br />
The record will be deleted.<br />
11.3.8 Replication Section<br />
This section contains settings related to the sending of Replication updates to other <strong>Identikey</strong> <strong>Server</strong>s.<br />
Note<br />
For more information about setting up replication on your system, see 17<br />
Replication.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 159
11.3.8.1 Enable Replication<br />
To configure the current <strong>Identikey</strong> <strong>Server</strong> to replicate data to other <strong>Identikey</strong> <strong>Server</strong>s:<br />
1. Click on Edit.<br />
11.3.8.2 Source <strong>Server</strong><br />
2. Tick the Enable Replication checkbox.<br />
Define a source server to be replicated:<br />
1. Enter the IP address of the source server.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
2. Enter the minimum number of seconds the system should wait before trying to reconnect to this server.<br />
3. Enter the maximum number of seconds the system should wait before trying to reconnect to this server.<br />
11.3.8.3 Destination <strong>Server</strong><br />
11.3.8.4 Queue<br />
1. Click on the Create button under the Destination <strong>Server</strong>s heading.<br />
2. Enter a display name for the destination <strong>Identikey</strong> <strong>Server</strong>.<br />
3. Enter the IP address and port to use in connecting to the <strong>Identikey</strong> <strong>Server</strong>. This must normally correspond to<br />
the IP Address and Port settings in the SEAL Communicator section of the destination <strong>Identikey</strong> <strong>Server</strong>'s<br />
configuration. However, if Network Address Translation is active between the two <strong>Identikey</strong> <strong>Server</strong>s, be<br />
careful to select the correct IP address and port that will reach the <strong>Identikey</strong> <strong>Server</strong>.<br />
4. Click on OK.<br />
The replication queue files hold data that is yet to be replicated on to other <strong>Identikey</strong> <strong>Server</strong>s.<br />
1. If you wish to change the location of the replication queue files, modify the File Path field. This directory<br />
must already exist.<br />
2. Set a Max File Size (Mb) for each queue file (there is one per Destination <strong>Server</strong>). If the file reaches this size,<br />
replication queue entries will no longer be writeable to the file, and the <strong>Identikey</strong> <strong>Server</strong> will cease processing<br />
requests that result in a database update.<br />
3. The maximum number of retries specifies how many times the <strong>Identikey</strong> <strong>Server</strong> should attempt to resend<br />
entries in the replication queue that failed at the destination server. Enter a number in the Max Retries field.<br />
4. The retry interval specifies how long the <strong>Identikey</strong> <strong>Server</strong> should wait before attempting to resend entries in<br />
the replication queue that failed at the destination server. Enter a number of seconds in the Retry Interval<br />
field.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 160
11.3.9 Configuration File<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration writes to an XML file named identikeyconfig.xml in the install/bin directory for<br />
Windows, or the chroot envrionment in Linux. It is possible to edit this file directly instead of using <strong>Identikey</strong> <strong>Server</strong><br />
Configuration, but is not recommended.<br />
For Windows you will need to restart the <strong>Identikey</strong> <strong>Server</strong> Service using the Windows Service Control Manager after<br />
editing and saving the file, before the changes will take effect.<br />
To enter the chroot environment in Linux enter:<br />
vds_chroot /bin/bash<br />
is /opt/vasco/identikey by default.<br />
Note<br />
The configuration file is UTF-8 encoded – do not put any non-UTF-8 characters into the file.<br />
The XML tag names in the configuration file are case-sensitive.<br />
11.3.9.1 Windows - Example Configuration File<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 161
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 162
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 163
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 164
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 165
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 166
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 167
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
11.3.9.2 Linux Example Configuration File<br />
<br />
- <br />
- <br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 168
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
- <br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 169
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
- <br />
<br />
<br />
<br />
- <br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 170
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 171
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
-<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 172
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 173
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
- <br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 174
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 175
11.4 Command Line Options<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The <strong>Identikey</strong> <strong>Server</strong> is started via a single executable file named ikeyserver.exe (Windows) or ikeyserver (Linux).<br />
This command is rarely executed by the <strong>Administrator</strong> as it is automatically executed when the server on which<br />
<strong>Identikey</strong> <strong>Server</strong> has been installed is started up. The <strong>Identikey</strong> <strong>Server</strong> is started via an operating system specific<br />
framework used to start and stop services (Windows) or daemons (Linux).<br />
Command line options can be used to override the <strong>Identikey</strong> <strong>Server</strong> configuration file and run <strong>Identikey</strong> <strong>Server</strong> with<br />
a custom configuration file.<br />
11.4.1 Windows Service Control Manager<br />
Under Windows the <strong>Identikey</strong> <strong>Server</strong> is started using the Windows Service Control Manager (SCM). The SCM<br />
allows services to be started, stopped, and paused. The SCM also allows the passing of command line<br />
parameters. The SCM is accessed via the Services icon on the control panel. Command line parameters may be<br />
passed to the <strong>Identikey</strong> <strong>Server</strong> service by double-clicking on the <strong>Identikey</strong> <strong>Server</strong> service in the services window<br />
and then entering the parameters in the Start Parameters field under the General tab.<br />
11.4.2 Linux Runtime Configuration<br />
Under Linux the <strong>Identikey</strong> <strong>Server</strong> is started as a Daemon by the invocation of a Linux shell script that is run<br />
automatically as part of the Linux runtime configuration framework. All runtime configuration scripts allow<br />
daemons to be started, stopped and paused. Command line parameters may be specified by modifying the<br />
runtime confugration script for the intended daemon.<br />
11.4.3 Running <strong>Identikey</strong> <strong>Server</strong> with Command Line Options<br />
11.4.3.1 Command Line Option flags<br />
Issuing the command 'ikeyserver –help' either in a Windows command line instance or under a Linux shell prompt<br />
will display the following:<br />
Flags:<br />
-d, --debug Run <strong>Identikey</strong> <strong>Server</strong> in debug mode<br />
-h, --help Display this help message<br />
-c, --config=CONFIG_FILENAME Optional argument used to override the configuration file which is used by the<br />
<strong>Identikey</strong> <strong>Server</strong>.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 176
11.4.3.2 Windows<br />
11.4.3.3 Linux<br />
Note<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The Configuration GUI will only modify the default configuration file. If the <strong>Identikey</strong> <strong>Server</strong> has<br />
been started using an alternate configuration file, its configuration settings can only be altered by<br />
editing the file in a text editor.<br />
To run <strong>Identikey</strong> <strong>Server</strong> with command line options <strong>Identikey</strong> <strong>Server</strong> will have to be run in debug mode. This allows<br />
the <strong>Identikey</strong> <strong>Server</strong> executable to be run from the Windows command line. To run <strong>Identikey</strong> <strong>Server</strong> in debug<br />
mode, follow the instructions above in 11.4.1 Windows Service Control Manager pass the command line<br />
parameter -d to the Windows service.<br />
Under Linux it is not mandatory that the <strong>Identikey</strong> <strong>Server</strong> is run under the debug mode when it is invoked from the<br />
command line.<br />
11.5 <strong>Identikey</strong> <strong>Server</strong> Web Administration Configuration<br />
11.5.1 List<br />
11.5.1.1 Location<br />
Configuration may be performed via the <strong>Identikey</strong> <strong>Server</strong> Web Administration. Click on the System tab for a drop<br />
down menu. Use the Web Administration Online Help for detailed on each page.<br />
Select the List menu item to display a list of <strong>Identikey</strong> <strong>Server</strong>s.<br />
The Location setting contains the licensed IP address for the <strong>Identikey</strong> <strong>Server</strong>. The <strong>Identikey</strong> <strong>Server</strong> uses this IP<br />
address to listen for SOAP and RADIUS requests. There must be an <strong>Identikey</strong> <strong>Server</strong> component record with this<br />
Location, containing a valid License Key. The component location is carried forward to the Communication<br />
Protocols pages.<br />
Click the Location to change the IP address for the <strong>Identikey</strong> <strong>Server</strong> and the base policy.<br />
Click Edit on the Summary tab to change the policy ID. Click the License tab to change the license details.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 177
11.5.1.2 <strong>Identikey</strong> <strong>Server</strong> Name<br />
Clicking on the <strong>Identikey</strong> <strong>Server</strong> Name will allow changes to the following settings:<br />
Policy<br />
User<br />
Digipass<br />
Challenge<br />
Virtual Digipass<br />
Digipass Control Parameters<br />
11.5.2 Add <strong>Identikey</strong> <strong>Server</strong><br />
11.5.3 <strong>Server</strong> Status<br />
11.5.3.1 Replication<br />
11.5.3.2 Admin Session<br />
Use this tab to add another <strong>Identikey</strong> <strong>Server</strong>.<br />
Use this tab to get the Replication Status of nominated <strong>Identikey</strong> <strong>Server</strong>s.<br />
Use this tab to manage Administration sessions.<br />
11.5.4 <strong>Server</strong> Configuration<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The tabs shown when you click on <strong>Server</strong> Configuration correspond to the headings in . 11.3.2 General Section<br />
The tabs comprise:<br />
General<br />
Audit<br />
Amend the Audit Settings.<br />
Storage<br />
Communicators<br />
Replication<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 178
Scenarios<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 179
11.6 Web Administration Setup Tool<br />
11.6.1 Overview<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The Web Administration Setup Tool is a Java application that allows the management of <strong>Identikey</strong> <strong>Server</strong><br />
connections and SSL certificate usage in the Administration Web Interface. Java Runtime Environment is required<br />
in order to run this tool.<br />
The Web Administration Setup Tool stores its information using the Java preferences API. On Windows, it uses the<br />
Windows registry. On Linux, it uses the running user's file system, and is stored in the java/.userPrefs directory.<br />
User Account<br />
The user that runs the web server application should be the same user running the Web Administration Setup Tool<br />
under Linux, otherwise changes will not be reconciled in the Administration Web Interface.<br />
Note<br />
11.6.2 Running the Application<br />
Windows<br />
Any changes made with the Web Administration Setup Tool will not take effect until the<br />
Administration Web Interface and the web server application have been restarted.<br />
1. Open a command prompt.<br />
2. Navigate to the directory in which the Java executable is located.<br />
3. Enter the following command:<br />
Linux<br />
java -jar admintool.jar<br />
1. Open a command prompt.<br />
2. Enter the following commands:<br />
vds_chroot /bin/bash<br />
java -jar admintool.jar<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 180
Note<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The vds_chroot command will enter you into the chroot environment. This is necessary for all<br />
Setup Tool commands.<br />
To exit the chroot environment, enter:<br />
exit<br />
11.6.3 Available Commands<br />
The commands should be in the following format:<br />
java -jar admintool.jar [options]<br />
The following commands are available:<br />
Setup Tool Command Explanation<br />
autoadd <br />
<br />
Creates a new <strong>Identikey</strong> <strong>Server</strong> connection for the Administration Web<br />
Interface.<br />
If a certificate archive and password is specified, the <strong>Identikey</strong> <strong>Server</strong>'s SSL<br />
certificate will be added to it. If no certificate archive is specified, it will be<br />
added to the existing keystore.<br />
A connection limit (number of concurrent connections to allow) and<br />
connection timeout may also be specified.<br />
server list List the available <strong>Identikey</strong> SOAP servers<br />
server add <br />
<br />
Add a new <strong>Identikey</strong> <strong>Server</strong> connection.<br />
A connection limit (number of concurrent connections to allow) and<br />
connection timeout may also be specified.<br />
server delete Remove an existing <strong>Identikey</strong> <strong>Server</strong><br />
server default Set the specified <strong>Identikey</strong> SOAP server as the default<br />
server localaddress <br />
Specify a local IP address to specify when connecting to the provided server<br />
name.<br />
certificate list Displays the list of certificate alias which are in the used certificate archive<br />
certificate list <br />
<br />
certificate add <br />
<br />
certificate delete <br />
<br />
certificate delete <br />
<br />
Displays the list of certificate alias which are in the specifiedcertificate<br />
archive (opened using the specified passphrase)<br />
Installs the certificate into an existing or new certificate archive using the<br />
provided passphrase and alias the certificate using the provided name.<br />
Removes the certificate with the specified alias from the provided<br />
Removes the certificate with the default alias "<strong>Identikey</strong><strong>Server</strong>" certificate<br />
archive using the provided password.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 181
Setup Tool Command Explanation<br />
autoadd <br />
11.6.4 Command Usage Examples<br />
11.6.4.1 Adding an <strong>Identikey</strong> <strong>Server</strong> and SSL Certificate<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Combines the functionality of the server add and certificate add commands<br />
and automates the retrieval of the certificate from the <strong>Identikey</strong> <strong>Server</strong>.<br />
The following command will add an <strong>Identikey</strong> <strong>Server</strong> and add the <strong>Identikey</strong> <strong>Server</strong>'s certificate to the keystore:<br />
java -jar admintool.jar autoadd <br />
where is the display name of the <strong>Identikey</strong> <strong>Server</strong>, is the address and port number of the <strong>Identikey</strong><br />
<strong>Server</strong>, is the location and file name of the keystore and is the<br />
password on the keystore.<br />
Example<br />
java -jar admintool.jar autoadd IK<strong>Server</strong>1 https://192.168.1.1:8888<br />
etc/vasco/keystore.jks password1<br />
will create a new <strong>Identikey</strong> <strong>Server</strong> record which will be displayed in the Web Administration application using the<br />
name “IK<strong>Server</strong>1” and will connect to the <strong>Identikey</strong> SOAP communicator using http – using SSL - at address<br />
192.168.1.1 and port 8888. It will add the <strong>Identikey</strong> <strong>Server</strong>'s SSL certificate to the keystore specified.<br />
NOTE<br />
Protocol strings must be provided (http or https for SSL connections).<br />
<strong>Server</strong> creation can be verified by running the following command:<br />
java -jar admintool.jar server list<br />
which will display the current list of servers.<br />
NOTE<br />
The server name and url must both be unique. Attempting to add another server with a different<br />
name and the same url will fail. Adding a server with the same name and different url will<br />
overwrite the existing entry for the <strong>Identikey</strong> <strong>Server</strong> of that name.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 182
11.6.4.2 Adding an <strong>Identikey</strong> <strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The following command will add an <strong>Identikey</strong> <strong>Server</strong> only, without adding a certificate to the keystore:<br />
java -jar admintool.jar server add <br />
where is the display name of the <strong>Identikey</strong> <strong>Server</strong> and is the address and port number of the<br />
<strong>Identikey</strong> <strong>Server</strong>.<br />
Example<br />
java -jar admintool.jar server add IK<strong>Server</strong>1 http://192.168.1.1:8888<br />
will create a new <strong>Identikey</strong> <strong>Server</strong> record which will be displayed in the Web Administration application using the<br />
name “IK<strong>Server</strong>1” and will connect to the <strong>Identikey</strong> SOAP communicator using http at address 192.168.1.1 and<br />
port 8888.<br />
11.6.4.3 Adding an SSL Certificate<br />
To connect to an <strong>Identikey</strong> <strong>Server</strong> which is using an SSL connection, the server's certificate must be added to the<br />
Web Administration application's certificate archive. If this is not done while adding an <strong>Identikey</strong> <strong>Server</strong> using the<br />
autoadd command, it can be done by executing the<br />
The certificate used by the <strong>Identikey</strong> <strong>Server</strong> is usually created with the filename “ikeycerts.pem” and located in :<br />
Windows - \vasco\<strong>Identikey</strong> <strong>Server</strong>\bin<br />
Linux - /etc/vasco<br />
To add this certificate to the Web Administration application's certificate archive, run the following command:<br />
java -jar admintool.jar certificate add <br />
<br />
where is the file path and name of the certificate archive, is the certificate<br />
archive password and is the file path and name of the SSL certificate to add to the<br />
certificate archive.<br />
Example<br />
or<br />
java -jar admintool.jar certificate add /etc/vasco/keystore.jks password1<br />
/etc/vasco/ikeycerts.pem<br />
java -jar admintool.jar certificate add \vasco\<strong>Identikey</strong><br />
<strong>Server</strong>\bin\keystore.jks password1 \vasco\<strong>Identikey</strong><br />
<strong>Server</strong>\bin\ikeycerts.pem<br />
will add the ikeycerts.pem certificate to the specified certificate archive keystore.jks, using the certificate archive<br />
password password1.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 183
NOTE<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Ensure that the connection url to the server is updated - https should be used rather than http.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 184
11.7 Message Delivery Component Configuration<br />
11.7.1 Required Information<br />
To configure gateway settings you will need:<br />
Gateway details:<br />
OR<br />
Protocol to use in connecting to the gateway.<br />
An address string and port to use in connecting to the gateway.<br />
The path and filename of a certificate file, if required.<br />
The required Query String.<br />
The Query Method (GET or POST) required by the gateway.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
A customized configuration file ordered from your VASCO supplier. This will need to be imported using the<br />
Configuration GUI.<br />
Username and password for the gateway account.<br />
11.7.2 MDC Configuration GUI<br />
A Graphical User Interface (GUI) is available for use in configuring the MDC in Windows installations. To open the<br />
MDC Configuration GUI, click on the Start Button and select Programs -> VASCO -> <strong>Identikey</strong> <strong>Server</strong> -> Virtual<br />
Digipass MDC Configuration.<br />
Note<br />
The MDC must be restarted after any change is made in the Configuration GUI or configuration<br />
file.<br />
If using the MDC on a Linux system, the configuration file can be found in etc/vasco/mdcconfig.xml.<br />
11.7.2.1 Modify Gateway Account Login Details<br />
The MDC needs a Username and password for the gateway in order to send text messages through it. Modify the<br />
Username if needed and change the Password and Confirm Password fields if required. The Password and Confirm<br />
Password fields must contain identical data.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 185
11.7.2.2 Configure Internet Connection Details<br />
Enable or disable the use of an HTTP Proxy and enter details if required.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
1. Enable or disable the use of the HTTP Proxy by ticking or clearing the Use HTTP Proxy checkbox.<br />
2. If required, enter an IP address, port and timeout for the HTTP Proxy.<br />
3. Enter a maximum number of internet connections to allow in the Max. Connections field.<br />
11.7.2.3 Configure Tracing<br />
The MDC makes use of a trace file to record information about events that occur on the system, for use in<br />
troubleshooting. This could include generic information, changing conditions, or problems and errors that have<br />
been encountered.<br />
The level of tracing that the MDC employs depends on its configuration settings.<br />
Caution<br />
Enabling Full Tracing should only be done for troubleshooting purposes. There are no limits set<br />
on the size of the tracing file, so if the option is left on too long on a high-load system the file<br />
may dramatically slow down or crash Windows, due to excessive I/O or filling up the hard drive.<br />
This is not highly likely for MDC, but should be considered.<br />
Because there are no size limitations set on the trace file, it is not recommended that you have tracing permanently<br />
enabled. If your system is set up with Basic Tracing always enabled, ensure that the file size does not cause<br />
problems by deleting or archiving it whenever it gets too large.<br />
Basic tracing includes:<br />
Critical error/warning messages [CRITC]<br />
Major error/warning messages [MAJOR]<br />
Minor error/warning messages [MINOR]<br />
Configuration messages [CONFG]<br />
Full tracing includes:<br />
Critical error/warning messages [CRITC]<br />
Major error/warning messages [MAJOR]<br />
Minor error/warning messages [MINOR]<br />
Configuration messages [CONFG]<br />
Informational messages [INFOR]<br />
Data tracing messages [DATA]<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 186
Debugging messages (useful for support purposes) [DEBUG]<br />
Security messages, messages that may contain security sensitive data [SECUR]<br />
Turn Tracing On or Off<br />
1. Select a Tracing option.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
2. If you have selected Basic Tracing or Full Tracing, enter a path and filename for the tracing file into the File<br />
Name field.<br />
The file path entered must be the full absolute path.<br />
Note<br />
If the File Name field is left blank or the file path does not exist, the MDC will not output tracing.<br />
If the file does exist, tracing will be appended to the file. If it does not exist, it will be created.<br />
11.7.2.4 Import HTTP Gateway settings<br />
Import a customized configuration file ordered from your VASCO supplier, containing the configuration details for<br />
your gateway needed by the MDC.<br />
1. Click on the Gateway Settings tab.<br />
2. Enter a name for the gateway.<br />
3. Click on Import Settings.<br />
4. Select a file from the Browse window.<br />
5. Click on OK.<br />
The import progress will be displayed.<br />
6. Click on OK.<br />
11.7.2.5 Edit Advanced Settings<br />
1. Click on the Gateway Settings tab.<br />
2. Ensure that the Edit Advanced Settings checkbox is ticked.<br />
3. Select a protocol to use in connecting to the gateway from the Protocol drop down list (typically HTTP).<br />
4. Enter an address string to use in connecting to the gateway in the Address field.<br />
5. Enter a port in the Port field (typically 80 for HTTP connections).<br />
6. Enter the path and filename of a certificate file if required.<br />
7. Modify the Query String field if required.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 187
Example Query String:<br />
username=[acc_user]&password=[acc_pwd]&device=[otp_dest]&network=tgsm&message=[otp_msg]<br />
8. Select a Query Method according to what the gateway requires (typically POST).<br />
11.7.2.6 Export HTTP Gateway settings<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Once you have entered the necessary gateway configuration information into the Configuration GUI, you may wish<br />
to export the settings into a file for backup purposes or to transfer to another server.<br />
1. Click on the Gateway Settings tab.<br />
2. Ensure that the Edit Advanced Settings checkbox is ticked.<br />
3. Click on Export Settings.<br />
4. Select a directory from the Browse window.<br />
5. Enter a filename.<br />
6. Click on OK.<br />
The export progress will be displayed.<br />
11.7.2.7 Gateway Result Pages<br />
A result page is returned by the gateway service when a text message is submitted by the GET or POST methods.<br />
This page would normally be a HTML formatted page containing specific error codes and/or additional messages<br />
for success/failure.<br />
Three types of result messages are generally categorized as:<br />
Information<br />
Success of message delivery (the message has been accepted by the server)<br />
Warning<br />
The submission/delivery failed, but it is most likely a specific error only affecting this User. The User’s login will fail<br />
on the first step. Possible causes are:<br />
Error<br />
Phone number invalid<br />
Temporary gateway failure<br />
Error(s) occurred while attempting delivery. This means that the delivery failed for a particular User, but the error<br />
might be affecting all Users. In this case, the User’s login will fail immediately. Possible such errors are:<br />
Account data incorrect (Account User or password wrong)<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 188
Account credit expired (for a pre-paid gateway account)<br />
Communication error with gateway (network error)<br />
Other permanent gateway errors<br />
Audit Console Logging<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
A gateway result page can be recognized by key words and phrases, and an alternate message created for logging<br />
to the audit console whenever the result is received. Variables can be extracted from the result page and used in<br />
the log message to provide extra information.<br />
Result Page Rules<br />
The result page rule patterns use the following syntax:<br />
[Var-Name1] [] [Var-Name2] …<br />
Where the template is constructed in the following way:<br />
: a character string which must be matched in the page returned by the gateway. Note that<br />
multiple can appear in a single template, but they must not be overlapping. Matching is casesensitive.<br />
[]: Omits a variable part of the result page between two segments, when matching a template.<br />
This can be useful to ignore arbitrary data or time/date data in the returned web page.<br />
[Var-Namex]: Describes a segment of the result page between two segments or at the end of the<br />
result page, which will be written to a variable. Usually this will be data that can provide more detailed<br />
information why a particular message submission has failed. The variable name inside the [] brackets can then<br />
be used as part of the audit message template to create a meaningful message.<br />
Example<br />
If the server returns the following result page<br />
“Submission successful at 10:00, 11/11/02, status: 00 - message delivery in progress.”<br />
for successful transmission, or<br />
“Submission unsuccessful at 10:05, 11/11/02, status: 47 – number too short”<br />
for an unsuccessful submission, then the following result page rules can be configured:<br />
Message Rule Name: Success<br />
Message Rule Pattern: successful at [DateTime], status: [Status] – [Message]<br />
Variables retrieved: DateTimeStatusMessage<br />
Message Rule Name: Warning<br />
Message Rule Pattern: unsuccessful at [DateTime], status: 47 – [Message]<br />
Variables retrieved: DateTimeMessage<br />
Message Rule Name: Error<br />
Message Rule Pattern: unsuccessful at [DateTime], status: [status] – [Message]<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 189
Variables retrieved: DateTimeStatusMessage<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
No Match Available If no Rule matches a Result page returned, an error will be logged to the Audit Console,<br />
reporting that the result page returned from the gateway could not be matched.<br />
Ordering Rules The order of the result page template in the configuration data can be used to match more specific<br />
messages first and finally catch any “other” message, which the gateway might send.<br />
Audit message template<br />
Once a result page template a matched, a corresponding audit message is constructed with the variables retrieved<br />
from the result page rule.<br />
The message template will use the following syntax:<br />
[VAR-Name1] [Var-Name2] …<br />
: a character string which will appear literally in the constructed audit message.<br />
[Var-Namex]: Variable which is derived from the matched variables from the corresponding result page<br />
template.<br />
The following variables are predefined and can be used in the audit message template:<br />
Table 60: MDC Audit Message Variables<br />
[otp_dest] The destination address (a mobile phone number) the OTP was sent to.<br />
[otp_msg] The message that was submitted. This variable will also contain the OTP, so should not be used for the<br />
construction of audit messages.<br />
[acc_user] Account name for the gateway.Not recommended for use in audit messages.<br />
[acc_pwd] Account password for the gateway.Not recommended for use in audit messages.<br />
[Username] the User ID of the User requesting the OTP<br />
Examples of variable use:<br />
Insufficient credit on account [acc_user] when sending to [username]<br />
Message not sent to User "[Username]"/[otp_dest]. Gateway reported: [message]<br />
Modify a Gateway Result Message Rule<br />
Ensure that the Edit Advanced Settings checkbox on the Gateway Settings tab is ticked.<br />
1. Click on the Gateway Results tab.<br />
2. Select a Rule to modify.<br />
3. Click on Edit.<br />
4. Make any required changes.<br />
5. Click on OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 190
Add a Gateway Result Message Rule<br />
1. Click on the Gateway Results tab.<br />
2. Click on Add.<br />
3. Enter a descriptive name for the Rule in the Description field.<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
4. Enter the full text or a partial match of the text displayed by the gateway in the Matching Pattern field.<br />
5. Select an Audit Message Level for the Rule.<br />
Each level of message will be displayed with a different color background in the Audit Console.<br />
Info – normal<br />
Warning – yellow<br />
Error – red<br />
6. Enter the message text you wish the User to see into the Message Text field.<br />
7. Click on OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 191
11.7.3 MDC Configuration File<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The MDC Configuration GUI writes to an .xml file named MDCConfig.xml in the install\bin (Windows) or etc/vasco<br />
(Linux) directory. It is possible to edit this file directly instead of using the MDC Configuration GUI.<br />
Example Configuration File<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 192
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<br />
<br />
<br />
<br />
<br />
Caution<br />
The configuration file is UTF8 encoded. Non-UTF8 encoded characters should not be added to<br />
the configuration file, or it will not load.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 193
11.7.4 Configuration Settings<br />
The table below lists the options, their default values, and a brief explanation of each.<br />
Table 61: Message Delivery Component Configuration Settings<br />
Option Name Config. GUI<br />
Field<br />
General tab<br />
Gateway/<br />
ProxyIP<br />
Gateway/<br />
ProxyPort<br />
Gateway/<br />
Timeout<br />
Gateway/<br />
MaxConnections<br />
Tracing/<br />
TraceFile<br />
Tracing/<br />
TraceMask<br />
Gateway-Acnt/<br />
Username<br />
Gateway-Acnt/<br />
Password<br />
Gateway Settings tab<br />
Gateway/<br />
Description<br />
Gateway/<br />
HTTPMethod<br />
Default Value Notes<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Proxy IP IP address of the HTTP proxy used by the MDC to contact the HTTP<br />
gateway. This can be used when the firewall settings do not allow a<br />
direct connection.Empty - no proxy being used. Data type: String with<br />
valid IP4 address<br />
Port Port number to contact the HTTP proxy on.Must be supplied if the<br />
ProxyIP setting is used. Data type: Integer with valid Port address (1-<br />
65535)<br />
Proxy Timeout 30 Time in seconds that the MDC will wait on a response from the<br />
HTTP/gateway. Data type: integer<br />
Max<br />
Connections<br />
10 Maximum allowed number of concurrent connections to the HTTP<br />
gateway. Data type: Integer (1-100)<br />
File Name The file that tracing output should be written to using the absolute<br />
path and file name. Data type: String<br />
Tracing 0 The tracemask specifies how much tracing is done.<br />
0 – no tracing<br />
1 – basic tracing<br />
2 – full tracing<br />
Data type: Integer<br />
(General<br />
tab)Username<br />
(General<br />
tab)Password &<br />
Confirm<br />
Password<br />
Gateway/ URL Protocol and<br />
Address<br />
<br />
<br />
Sets the account Username the HTTP gateway. The given value will be<br />
used as content for the variable [acc_User] in the query string. Data<br />
type: String<br />
Sets the account password the HTTP gateway. The given value will be<br />
used as content for the variable [acc_pwd] in the query string. Data<br />
type: String<br />
Gateway Name This is an informational field, naming or describing the HTTP gateway.<br />
It can be set to provide a description for a particular service, but is<br />
ignored by the MDC. Data type: String<br />
Query Method POST Designates either the GET or POST method for use in transferring<br />
account and message data to the HTTP/HTTPS gateway. Data type:<br />
String (“GET” or “POST”)<br />
<br />
Required parameter.Sets the URL to the HTTP gateway. The address<br />
should not contain any variables, but is should contain the protocol<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 194
Option Name Config. GUI<br />
Field<br />
Gateway/<br />
HTTPQuery<br />
Gateway/<br />
CertFile<br />
Gateway Results tab<br />
Results/<br />
Resultnn/ Name<br />
Results/<br />
Resultnn/<br />
Pagematch<br />
Results/<br />
Resultnn/<br />
MsgType<br />
Query String <br />
Certificate File .\curl-cabundle.crt<br />
Default Value Notes<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
identifier. Note: the protocol identifier of “https://” can be used to<br />
SSL-encrypt the link between the MDC and the HTTP gateway. In this<br />
case it is required to specify a filename where the server certificates<br />
can be found. Data type: String<br />
Required parameter.Defines the query string which will be submitted<br />
to the http server, either using POST or GET (as specified by HttpGw-<br />
Method). This string must contain all required variables that are<br />
expected by the HTTP gateway. Contained in the query string must be<br />
the following parameters which will be set by the MDC before<br />
submitting the query:<br />
[acc_user] specifies the account name for the gateway which will be<br />
used to submit the information§<br />
[acc_pwd]password for the gateway account specified by the<br />
[Username] parameters§<br />
[otp_msg]specifies the part of the query string, where the OTP<br />
message will be substituted§<br />
[otp_dest]specifies the part of the query string, where the destination<br />
for the OTP (usually the mobile phone number) will be substituted.The<br />
query string should also incorporate any other parameters which<br />
might be expected by the gateway.<br />
Example:<br />
Data type: String<br />
When using the HTTPS protocol, the server certificate file is used to<br />
authenticate the message gateway and to derive the data encryption<br />
keys. It can contain either one or multiple server certificates.The file<br />
needs to be PEM-encoded,X.509 compliant certificate.It can be<br />
created by exporting the required Root CA from any browser (eg.<br />
Internet Explorer) using the base-64 format - equivalent to PEM. Data<br />
type: String<br />
Description Name of this entry, as displayed by the MDC Configuration GUI. This<br />
field has no functional meaning. Data type: String<br />
Matching<br />
Pattern<br />
Audit Message<br />
Level<br />
<br />
Result Page Template to match the result page returned by the HTTP<br />
service. If this template is matched, the corresponding audit message<br />
is composed and returned to the <strong>Identikey</strong> <strong>Server</strong> Audit message.<br />
Data type: String<br />
2 Type of message to appear in the audit log:<br />
0 INFO – informational message (login on)<br />
1 WARNING – warning message (login fails)<br />
2 ERROR – error message (login fails)<br />
Data type: Integer (0-2)<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 195
Option Name Config. GUI<br />
Field<br />
Results/<br />
Resultnn/<br />
Message<br />
Message Text <br />
Default Value Notes<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
Audit Message Template for the message to be compiled and sent<br />
back to the <strong>Identikey</strong> <strong>Server</strong>. The message is returned as Information,<br />
Warning or Error, depending on the MsgType parameter in the same<br />
section. Includes [variable] options. Data type: String<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 196
11.8 Digipass TCL Command Line Utility<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
The Digipass Command Line Utility uses an xml file to store necessary configuration settings. This file can be found<br />
at \Bin\dpadmincmd.xml (Windows) or /etc/vasco/dpadmincmd.xml (Linux).<br />
If the TCL Command Line Utility is being used on the server machine, the xml file will be created by the wizard. If<br />
the TCL Command Line Utility is not being used on the server machine, you will have to create the XML file using<br />
the template provided at \Bin\dpadmincmd.tmpl (Windows) or /etc/vasco/dpadmincmd.tmpl<br />
(Linux), and replace:<br />
the trace file<br />
the local address<br />
connection 00 - the IP address of the remote server<br />
11.8.1 Sample Configuration File<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Port type="unsigned" data="20003" /><br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 197
<br />
<br />
<br />
<br />
<strong>Identikey</strong> <strong>Server</strong> Configuration Settings<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 198
12 <strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
12.1 Create Organizational Structure<br />
12.1.1 Domains<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
The creation of the organizational structure is only applicable where <strong>Identikey</strong> <strong>Server</strong> uses an ODBC database as its<br />
data store. If it uses Active Directory, it will utilise the existing Active Directory organizational structure.<br />
Domains can be used to divide administration between specific organizational divisions, where some<br />
administrators should only have access to a single group of users rather than all. They may mirror actual domains<br />
in the corporate network.<br />
Master Domain<br />
<strong>Identikey</strong> <strong>Server</strong> installation creates a master domain – named Master by default – in the data store. This domain<br />
can be used to allow global administration and store unallocated Digipass records. Any administrators whose<br />
Digipass User record is in the Master Domain may act as global administrators.<br />
12.1.1.2 Create a New Domain<br />
Pre-requisites<br />
The global administrator account used for this process must have at least these privileges:<br />
Admin Logon<br />
Access Data in all domains<br />
Create domain<br />
View domain<br />
Instructions<br />
1. Log on to the Administration Web Interface with a global administrator account.<br />
2. Click on Organization-> Add domain<br />
3. Enter a Domain name.<br />
4. If desired, enter a description for the domain.<br />
5. Click on Create.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 199
12.1.2 Organizational Units<br />
12.1.2.1 Create an Organizational Unit<br />
Org units in IK3.1 are mainly used to organize users and Digipass.<br />
To create an org unit in a domain:<br />
1. Open the Administration Web Interface.<br />
2. Click on Organization->List<br />
3. Locate the domain in which to place the organizational unit.<br />
4. View details of the selected domain<br />
5. Click on Add Org. Unit<br />
6. Enter a name for the organizational unit.<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
7. Select a parent organizational unit, if applicable. This will locate the new organizational unit as a child of the<br />
selected one.<br />
8. If desired, enter a description for the new organizational unit.<br />
9. Click on Create.<br />
12.1.3 <strong>Administrator</strong>s<br />
There are two basic types of administrators.<br />
Global administrators<br />
Global administrators are not restricted by domain, and can read and/or write data regardless of the domain to<br />
which it belongs.<br />
Delegated administrators<br />
This type of administrator is restricted to administration of data in the domain in which the account is located.<br />
12.1.3.1 Create a Delegated <strong>Administrator</strong><br />
This task implies defining and assigning for each of the newly added domains an admin user who will perform user<br />
and Digipass administration. In case of delegated administration, administration will be performed by a domain<br />
specific administrator. A domain specific admin user will be part of his domain.<br />
For each domain, an administrator has to be created and administrative rights assigned.<br />
To create an admin user:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 200
1. Open the Administration Web Interface.<br />
2. Go to Users -> Create<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
3. Enter a User ID and domain for the administrator. They will be restricted to User and Digipass administration<br />
in this domain.<br />
4. Click on Create.<br />
5. Click on the Click here to manage link.<br />
6. Click on Admin Privileges.<br />
7. Click on Edit.<br />
8. Assign the necessary user and Digipass admin privileges by selecting the privilege name and clicking the ><br />
button.<br />
9. When complete, click on Save.<br />
12.1.3.2 Create a Global <strong>Administrator</strong><br />
Global administrator accounts are created in the master domain, and the administrative privileges assigned them<br />
apply throughout all domains. To create a global administrator:<br />
1. Open the Administration Web Interface.<br />
2. Click on Users -> Create<br />
3. Enter a User ID for the administrator.<br />
4. Enter the name of the master domain (default master domain is Master).<br />
5. Click on Create.<br />
6. Click on the Click here to manage link.<br />
7. Click on Admin Privileges.<br />
8. Click on Edit.<br />
9. Assign the necessary user and Digipass admin privileges by selecting the privilege name and clicking the ><br />
button.<br />
10. When complete, click on Save.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 201
12.2 How To Set Up Virtual Digipass<br />
12.2.1 Pre-requisites<br />
Reading<br />
It is recommended that you read the following topics before starting this process:<br />
Types of Digipass topic in the Introduction section of the Product Guide<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
Virtual Digipass Implementation Considerations topic in the Digipass section of the Product Guide<br />
Select Virtual Digipass Options<br />
There are three basic options available when implementing Virtual Digipass with <strong>Identikey</strong> <strong>Server</strong>:<br />
Primary Virtual Digipass only<br />
Backup Virtual Digipass, in conjunction with hardware or software Digipass<br />
Combination of Primary and Backup Virtual Digipass<br />
12.2.2 Import Virtual Digipass records<br />
You will receive Primary Virtual Digipass records in a .dpx file, with a DPX File Key, as you would receive with<br />
normal Digipass records. Import them as you would normal Digipass records.<br />
Backup Virtual Digipass do not have records of their own. Information on Backup Virtual Digipass is contained in<br />
the record for the Digipass which is being supplemented by the Backup Virtual Digipass.<br />
12.2.3 Set Up SMS Gateway<br />
MDC Access<br />
If required, configure an ID and password for the Message Delivery Component to use when passing text<br />
messages to the SMS Gateway.<br />
12.2.4 Set Up Message Delivery Component<br />
Installation<br />
See the relevant Installation Guide (Windows or Linux) for instructions on installing the Message Delivery<br />
Component.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 202
MDC Configuration<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
For instructions on configuring the Message Delivery Component to work with <strong>Identikey</strong> <strong>Server</strong> and the SMS<br />
Gateway, see 11.7 Message Delivery Component Configuration.<br />
12.2.5 Configure <strong>Identikey</strong> <strong>Server</strong><br />
If the Message Delivery Component is installed on a different machine to the <strong>Identikey</strong> <strong>Server</strong>, the <strong>Identikey</strong> <strong>Server</strong><br />
must be configured with the connection details. To do this, open the configuration file - identikeyconfig.xml - and<br />
find the VDPClient details. Edit the MDC-IPAddress and MDC-Port settings.<br />
12.2.6 Edit <strong>Identikey</strong> <strong>Server</strong> Policy<br />
You may need to read the Policy information in the Product Guide before following these instructions.<br />
12.2.6.1 Primary Virtual Digipass<br />
Set Up Policy<br />
1. Open the Administration Web Interface.<br />
2. Click on Policy -> List.<br />
3. Select the Policy in which you wish to enable the use of Virtual Digipass.<br />
4. Click on the Virtual Digipass tab.<br />
5. Click Edit.<br />
6. Find the Primary Virtual Digipass section.<br />
7. Select one of the following options as the Request Method::<br />
Keyword – User enters the Request Keyword into the password field.<br />
Password - User enters their static password only into the password field.<br />
KeywordPassword – User enters the Request Keyword, followed by their static password, into the<br />
password field.<br />
PasswordKeyword - User enters their static password, followed by the Request Keyword, into the<br />
password field.<br />
8. If you have selected an option which includes the use of a Request Keyword, enter it in the PVDP Request<br />
Keyword field.<br />
9. Click on Save.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 203
12.2.6.2 Backup Virtual Digipass<br />
Permitted, Not Mandatory<br />
1. Open the Administration Web Interface.<br />
2. Click on Policy -> List.<br />
3. Select the Policy in which you wish to enable the use of Virtual Digipass.<br />
4. Click Edit.<br />
5. Click on the Virtual Digipass tab.<br />
6. Find the Backup Virtual Digipass section.<br />
7. Select Yes – Permitted from the Enable Backup VDP drop down list.<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
8. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual<br />
Digipass.<br />
9. Click on Save.<br />
Permitted, Not Mandatory, Time-Limited<br />
1. Open the Administration Web Interface.<br />
2. Click on Policy -> List.<br />
3. Select the Policy in which you wish to enable the use of Virtual Digipass.<br />
4. Click Edit.<br />
5. Click on the Virtual Digipass tab.<br />
6. Find the Backup Virtual Digipass section.<br />
7. Select Yes – Time Limited from the Enable Backup VDP drop down list.<br />
8. Enter a time limit (in days) into the Time Limit field. At the end of this time period – calculated from their first<br />
use - the User will no longer be permitted to use a Backup Virtual Digipass.<br />
9. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual<br />
Digipass.<br />
Mandatory<br />
1. Open the Administration Web Interface.<br />
2. Click on Policy -> List.<br />
3. Select the Policy in which you wish to enable the use of Virtual Digipass.<br />
4. Click Edit.<br />
5. Click on the Virtual Digipass tab.<br />
6. Find the Backup Virtual Digipass section.<br />
7. Select Yes – Required from the Enable Backup VDP drop down list.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 204
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
8. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual<br />
Digipass.<br />
9. Click on Save.<br />
Backup Virtual Digipass may also be enabled for individual Users, via each Digipass record. This over<br />
12.2.7 Test Virtual Digipass<br />
Primary Virtual Digipass<br />
To test a Primary Virtual Digipass:<br />
1. Open the Administration Web Interface.<br />
2. Click on Digipass -> List.<br />
3. Click on the Virtual Digipass to be tested.<br />
4. From the Application Type tab click on the Test VDP button.<br />
5. Enter the mobile phone number to which the VDP should be sent.<br />
6. Click on Generate.<br />
The Administration Web Interface will attempt to send an OTP to the Message Delivery Component, which<br />
will attempt to forward it to the SMS Gateway. The success or failure of these attempts will be displayed.<br />
7. If the OTP was received by your mobile phone, enter it into the OTP field and click on Verify.<br />
The success or failure of the verification attempt will be displayed.<br />
Backup Virtual Digipass<br />
To test a Backup Virtual Digipass:<br />
1. Open the Administration Web Interface.<br />
2. Click on Digipass -> List.<br />
3. Click on the Digipass belonging to the Backup Virtual Digipass to be tested.<br />
4. From the Application Type tab click on the Test BVDP button.<br />
5. Enter the mobile phone number to which the OTP should be sent.<br />
6. Click on Generate.<br />
The Administration Web Interface will attempt to send an OTP to the Message Delivery Component, which<br />
will attempt to forward it to the SMS Gateway. The success or failure of these attempts will be displayed.<br />
7. If the OTP was received by your mobile phone, enter it into the OTP field and click on Verify.<br />
The success or failure of the verification attempt will be displayed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 205
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
12.3 Connect the Administration Web Interface to a New <strong>Identikey</strong> <strong>Server</strong><br />
12.3.1 Windows<br />
12.3.2 Linux<br />
Note<br />
The <strong>Identikey</strong> <strong>Server</strong> to which the Administration Web Interface will be connecting needs to have<br />
a Client Component record of type Administration Program in its data store for the machine on<br />
which the Administration Web Interface is running.<br />
1. Open a command line window.<br />
2. Navigate to the \webadmin directory.<br />
3. If you are using the default keystore and keystore password, enter the following command:<br />
java -jar admintool.jar autoadd <br />
where is the display name for the server and is its location.<br />
For example:<br />
java -jar admintool.jar autoadd Belgium https://198.162.1.1:8888<br />
4. If you have moved the keystore from its default location, or entered a custom keystore password during<br />
installation, enter the following command:<br />
java -jar admintool.jar autoadd <br />
where is the display name for the server, is the server location, is the<br />
path and filename for the keystore, and is the password set for the keystore.<br />
1. Enter the chroot environment:<br />
vds_chroot /bin/bash<br />
2. Navigate to /webadmin on the machine where the webadmin is running.<br />
3. If you are using the default keystore and keystore password, enter the following command:<br />
java -jar admintool.jar autoadd <br />
where is the display name for the server and is its location.<br />
For example:<br />
java -jar admintool.jar autoadd Belgium https://198.162.1.1:8888<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 206
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
4. If you have moved the keystore from its default location, or entered a custom keystore password during<br />
installation, enter the following command:<br />
java -jar admintool.jar autoadd <br />
where is the display name for the server, is the server location, is the<br />
path and filename for the keystore, and is the password set for the keystore.<br />
12.4 Create Custom Report Definition<br />
Before attempting to create a custom report definition, it is recommended that you read the Reporting section of<br />
the Product Guide.<br />
1. Open the Administration Web Interface.<br />
2. Click on the Reports tab and select Define report from the drop-down list.<br />
3. Type a name for the report definition.<br />
4. Select the type of report definition required:<br />
List Analysis Report – a list of all items that match the criteria specified in the report definition<br />
Detailed Analysis Report - detail of selected events<br />
Distribution Analysis Report - counts of events and/or objects<br />
Trend Analysis Report – trends in event or object numbers over a specified period of time<br />
5. Enter a description for the report definition – something which will help you and/or other administrators know<br />
what data will be found in the report.<br />
6. Select a grouping level:<br />
Client – connections requested and/or approved by machines with Client Component records<br />
7. Click on Next<br />
Data from Audit sources only<br />
Domain – Digipass and Digipass User information<br />
Data from data store (eg. list of Digipass Users by Domain) or Audit sources (eg. rejected authentication<br />
requests)<br />
Organizational Unit – Digipass and Digipass User information<br />
Data from data store (eg. list of Digipass Users by Organizational Unit) or Audit sources (eg. rejected<br />
authentication requests)<br />
User – Digipass and Digipass User information<br />
Data from data store (eg. list of Digipass Users with Digipass assigned) or Audit sources (eg. rejected<br />
authentication requests)<br />
Digipass – Digipass information<br />
Data from data store (eg. list of unassigned Digipass) or Audit sources<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 207
8. Enter a name for the new query.<br />
9. Click on Add New.<br />
10. Select the name of a field, the condition, and the value on which to filter.<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
Example – To report on rejected authentication requests, select Audit:Code from the Field drop down list,<br />
select Equals from the Condition drop down list, and enter I007003 in the Value field.<br />
11. Click on Next.<br />
12. If desired, add more queries.<br />
13. Click on Next.<br />
14. Select Usage and Update permissions. Usage permissions control which administrators may view a report –<br />
Update permissions control which administrators may modify a report definition.<br />
15. Click on Next.<br />
16. To use the standard XML template, Select the Use the default XML template only option button. Or to use a<br />
custom template, select the Add new template in addition to default XML template option button and enter<br />
the location of the template and a name to use in referring to it.<br />
17. Click on Save.<br />
18. Click on Finish.<br />
12.4.1 Query Filters<br />
The tables below list the fields on which a report query may be filtered, and the data type required for each.<br />
User field list<br />
Display name Type Value(s) required<br />
User:User ID String<br />
User:Domain String<br />
User:Organizational Unit String<br />
User:User Name String<br />
User:Email String<br />
User:Phone String<br />
User:Mobile String<br />
User:Description String<br />
User:Has Digipass Number<br />
User:Local Authentication Number<br />
User:Backend Authentication Number<br />
User:Disabled Checkbox 0 or 1<br />
User:Lock Count Number<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 208
User:Locked Checkbox 0 or 1<br />
User:Status String<br />
User:Profiles String<br />
User:Link String<br />
Domain Link String<br />
User:Created time Date<br />
User:Modified time Date<br />
The fields specified in the user field list can be referred to in the XSLT templates.<br />
Digipass field list<br />
Display name Type<br />
Digipass:Serial Number String<br />
Digipass:Domain String<br />
Digipass:Digipass Type String<br />
Digipass:Application Names String<br />
Digipass:Application Types String<br />
Digipass:Status String<br />
Digipass:User ID String<br />
Digipass:Assigned Date<br />
Digipass:Grace Period End Date<br />
Digipass:Backup VDP Enabled CheckBox<br />
Digipass:Backup VDP Expires Date<br />
Digipass:Backup VDP Uses Left Number<br />
Digipass:Created time Date<br />
Digipass:Modified time Date<br />
The fields specified in this Digipass field list can be referred to in the XSLT templates.<br />
Audit field list<br />
DisplayName Type<br />
Audit:Source String<br />
Audit:Type code Number<br />
Audit:Type String<br />
Audit:Code String See Audit Messages for a list<br />
of possible codes and<br />
messages used by the Audit<br />
System.<br />
Audit:Description String See Audit Messages for a list<br />
of possible codes and<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 209
Audit:Category String<br />
Audit:TimeStamp Date<br />
Audit:AMID String<br />
Audit:Reason String<br />
Audit:Area String<br />
Audit:Operation String<br />
Audit:Error Code Number<br />
Audit:Error Message String<br />
Audit:Error Details String<br />
Audit:Source Location String<br />
Audit:<strong>Server</strong> Location String<br />
Audit:Client Location String<br />
Audit:Version String<br />
Audit:Data Source String<br />
Audit:Data Source Location String<br />
Audit:Configuration Details String<br />
Audit:Outcome String<br />
Audit:Reason String<br />
Audit:Characteristics String<br />
Audit:Credentials String<br />
Audit:Session ID String<br />
Audit:Application String<br />
Audit:Request ID String<br />
Audit:Password Protocol String<br />
Audit:Input Details String<br />
Audit:Action String<br />
Audit:Output Details String<br />
Audit:Policy ID String<br />
Audit:From String<br />
Audit:To String<br />
messages used by the Audit<br />
System.<br />
Audit:Message String See Audit Messages for a list<br />
of possible codes and<br />
messages used by the Audit<br />
System.<br />
Audit:Quota Number<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 210
Audit:Object String<br />
Audit:Command String<br />
Audit:Downtime Number<br />
Audit:Fields String<br />
Audit:Request Type String<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 211
12.5 Install a Commercial SSL Certificate<br />
12.5.1 Windows<br />
Before installing a commercial SSL certificate, you will need to:<br />
obtain the .pem files required for the certificate<br />
note the location of the certificate files<br />
know the password for the keystore<br />
Install Certificate<br />
1. Run the <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard.<br />
2. Select Install SSL Certificate and click on Next.<br />
3. Select Install my own SSL Certificate and click on Next.<br />
4. Browse to the certificate file and click on Open.<br />
5. Enter the password for the SSL certificate.<br />
6. Browse to the trusted certificates file and click on Open.<br />
7. Click on Next.<br />
8. Click on Proceed.<br />
Configure Administration Web Interface to Use Certificate<br />
1. Open a command line window.<br />
2. Navigate to the \webadmin directory.<br />
3. Enter the following command:<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
java -jar admintool.jar autoadd <br />
where is the display name of the <strong>Identikey</strong> <strong>Server</strong>, is the address and port number of the<br />
<strong>Identikey</strong> <strong>Server</strong>, is the location and file name of the keystore and <br />
is the password on the keystore.<br />
For example:<br />
java -jar admintool.jar autoadd IK<strong>Server</strong>1 https://192.168.1.1:8888<br />
c:\Program Files\VASCO\<strong>Identikey</strong> 3.1\webadmin\keystore.jks password1<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 212
12.5.2 Linux<br />
Install Certificate<br />
1. Run the <strong>Identikey</strong> <strong>Server</strong> Configuration Wizard.<br />
2. Select Install SSL Certificate and click on Next.<br />
3. Select Install my own SSL Certificate and click on Next.<br />
4. Browse to the certificate file and click on Open.<br />
5. Enter the password for the SSL certificate.<br />
6. Browse to the trusted certificates file and click on Open.<br />
7. Click on Next.<br />
8. Click on Proceed.<br />
Configure Administration Web Interface to Use Certificate<br />
1. Navigate to the usr/share/vasco directory.<br />
2. Enter the following command:<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
java -jar admintool.jar autoadd <br />
where is the display name of the <strong>Identikey</strong> <strong>Server</strong>, is the address and port number of the<br />
<strong>Identikey</strong> <strong>Server</strong>, is the location and file name of the keystore and <br />
is the password on the keystore.<br />
For example:<br />
java -jar admintool.jar autoadd IK<strong>Server</strong>1 https://192.168.1.1:8888<br />
etc/vasco/keystore.jks password1<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 213
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
12.6 How to Set Up a Stand-Alone <strong>Identikey</strong> <strong>Server</strong> in RADIUS Environment<br />
You may wish to use this topology if:<br />
RADIUS attributes are not required<br />
One of the supported password protocols will be in use: PAP, CHAP, MS-CHAPv1, or MS-CHAPv2<br />
12.6.1 Information required<br />
12.6.2 Instructions<br />
IP address of the RADIUS client<br />
Shared secret used by the RADIUS client - or select a secret to use now if the RADIUS client isn't yet equipped<br />
with a shared secret<br />
Administration Web Interface<br />
1. Click on Clients -> Register<br />
2. Enter this data:<br />
Client Type: Select RADIUS Client<br />
Location: Enter the IP address of the RADIUS client<br />
Policy ID: Select the policy you want to use for this RADIUS client<br />
Protocol ID: Select RADIUS<br />
Shared Secret: Enter the shared secret used by the RADIUS client<br />
3. Click on Create.<br />
RADIUS Client Configuration<br />
4. Configure your RADIUS client to send authentication request to the <strong>Identikey</strong> server (the IP/port of the RADIUS<br />
communicator can be found in the <strong>Identikey</strong> <strong>Server</strong> Configuration utility).<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 214
12.7 How to Set Up <strong>Identikey</strong> <strong>Server</strong> as RADIUS Proxy Target<br />
You may wish to use this topology if:<br />
The RADIUS server supports the proxying of authentication while returning attributes itself<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
The RADIUS server can forward the authentication request using one of the supported password protocols is<br />
used: PAP, CHAP, MS-CHAPv1, MS-CHAPv2<br />
The RADIUS server supports an Access-Challenge response from <strong>Identikey</strong> <strong>Server</strong>, if required. The Access-<br />
Challenge mechanism is used for Challenge/Response and Virtual Digipass, although it is still possible to use<br />
Virtual Digipass without that mechanism.<br />
If the RADIUS server is capable, this scenario allows <strong>Identikey</strong> <strong>Server</strong> to operate in an environment that uses<br />
certificate-based EAP protocols such as PEAP and EAP-TTLS. To make this work, the RADIUS server decrypts the<br />
user credentials into a simpler protocol before forwarding the request to <strong>Identikey</strong> <strong>Server</strong>.<br />
12.7.1 Information required<br />
12.7.2 Instructions<br />
IP address of the RADIUS server<br />
Shared secret used by the RADIUS server<br />
Administration Web Interface<br />
1. Click on Clients -> Register<br />
2. Enter this data:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 215
Client Type: Select RADIUS Client<br />
Location: Enter the IP address of the RADIUS client<br />
Policy ID: Select the policy you want to use for this RADIUS client<br />
Protocol ID: Select RADIUS<br />
Shared Secret: Enter the shared secret used by the RADIUS client<br />
3. Click on Create.<br />
RADIUS Client Configuration<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
4. Configure your RADIUS client to send authentication request to the <strong>Identikey</strong> server (the IP/port of the RADIUS<br />
communicator can be found in the <strong>Identikey</strong> <strong>Server</strong> Configuration utility).<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 216
12.8 How to Set Up <strong>Identikey</strong> <strong>Server</strong> as Intermediate <strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
When used as an intermediate authentication server, <strong>Identikey</strong> <strong>Server</strong> can be set up in two basic modes – OTPonly,<br />
where <strong>Identikey</strong> <strong>Server</strong> keeps a record of a User's static password and relays it to the Back-End <strong>Server</strong>, and<br />
OTP-Password, where the User enters an OTP and their password, which is not stored by <strong>Identikey</strong> <strong>Server</strong> but is<br />
relayed to the Back-End <strong>Server</strong> for authentication.<br />
OTP Only<br />
OTP and Password<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 217
12.8.2 Information required<br />
12.8.3 Instructions<br />
IP address of the RADIUS client<br />
Shared secret used by the RADIUS client<br />
IP address of the RADIUS server<br />
Shared secret used by the RADIUS server<br />
Administration Web Interface<br />
1. Click on Clients -> Register<br />
2. Enter this data:<br />
Client Type: Select RADIUS Client<br />
Location: Enter the IP address of the RADIUS client<br />
Policy ID: Select the policy you want to use for this RADIUS client<br />
Protocol ID: Select RADIUS<br />
Shared Secret: Enter the shared secret used by the RADIUS client<br />
3. Click on Create.<br />
4. Configure the RADIUS client to send authentication requests to the <strong>Identikey</strong> <strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
The IP/port of the RADIUS communicator can be found using the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
5. Go to Back-end->Register RADIUS Back-End<br />
Backend server ID: an identifier for the RADIUS server<br />
Domain name: master if the RADIUS <strong>Server</strong> should process auth request from all domains, else a specific<br />
domain<br />
Priority: use this if you want to define multiple back-end servers for failover reasons - the one with the<br />
highest priority will be used first<br />
Authentication IP Address: The IP address that the RADIUS <strong>Server</strong> is using for authentication requests<br />
Authentication port: The Port that the RADIUS <strong>Server</strong> is using for authentication requests<br />
Accounting IP Address: The IP address that the RADIUS <strong>Server</strong> is using for accounting requests<br />
Accounting port: The Port that the RADIUS <strong>Server</strong> is using for accounting requests<br />
Shared Secret: the shared secret of the RADIUS <strong>Server</strong><br />
Timeout: timeout on the connection to the RADIUS <strong>Server</strong><br />
Retries: Number of retries before abandoning attempts to send an authentication request to the RADIUS<br />
<strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 218
6. Click on Create<br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 219
12.9 Add a New Domain to <strong>Identikey</strong> <strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> Advanced Setup<br />
These topic will lead you through the processes required to set up <strong>Identikey</strong> <strong>Server</strong> authentication in a new domain,<br />
where <strong>Identikey</strong> <strong>Server</strong> is already set up in another domain.<br />
12.9.1 Solution 1: Install an Extra <strong>Identikey</strong> <strong>Server</strong> in the New Domain.<br />
Follow the regular installation process to install an <strong>Identikey</strong> <strong>Server</strong> on the new domain.<br />
Note<br />
Ensure that your license covers the new <strong>Identikey</strong> <strong>Server</strong>.<br />
12.9.2 Solution 2: Configure New Domain for Existing <strong>Identikey</strong> <strong>Server</strong><br />
1. Check that the schema in the new domain contains the schema extensions required by <strong>Identikey</strong> <strong>Server</strong>. See<br />
2.5.2 Check Schema Extensions for more information.<br />
2. Set up the Digipass-Pool and Digipass-Reserve containers in the new domain. See 2.5.3 Set Up Digipass<br />
Containers in Domain for detailed information.<br />
3. Ensure that trusts are configured correctly between the domains to allow <strong>Identikey</strong> <strong>Server</strong> access to data in<br />
the new domain.<br />
4. Read 5 Set Up Active Directory Permissions for information on the Active Directory permissions that might<br />
need to be set in order to administer the Digipass Users and Digipass in that domain.<br />
5. Add the domain to <strong>Identikey</strong> <strong>Server</strong>'s configuration settings. See 11.3.6.2 LDAP Data Sources for more<br />
information.<br />
6. Optionally, install the Digipass Extension for Active Directory Users & Computers on a machine in the new<br />
domain which has the Active Directory Users & Computers tool installed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 220
13 Reporting<br />
13.1 Reporting Overview<br />
13.1.1 What fields can be included in reports?<br />
Fields from the following sources can be used in a report:<br />
Users<br />
Digipass<br />
Audit Data<br />
Users + Audit<br />
Digipass + Audit<br />
13.1.2 How can these fields be grouped?<br />
These fields can be grouped based on the following based on the following fields:<br />
Client<br />
Domain<br />
Organizational Unit<br />
User<br />
Digipass<br />
The information on the report will be grouped based on the field defined above.<br />
13.1.3 How to define a Query<br />
Queries consist of:<br />
a Datafield, which is a field from the database,<br />
an Operator, which is the operation to be performed on the datafield,<br />
Reporting<br />
a Value, which is the value the datafield will be compared against. A value is not necessary with all operators.<br />
To define a query you must select a datafield and an operator. Operators can be selected from the following:<br />
ISBLANK<br />
NOTBLANK<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 221
EQUALS<br />
NOTEQUALS<br />
STARTS<br />
INCLUDES<br />
ENDS<br />
NOTSTARTS<br />
NOTENDS<br />
NOTINCLUDES<br />
><br />
>=<br />
<<br />
Name Type Description<br />
Email String User Email<br />
Phone String User Phone No<br />
Mobile Number User Mobile No<br />
Desc String User Description<br />
Has_dp Number User Has Digipass<br />
Digipass String User Digipass serial number<br />
Local_auth Number User Local Authentication<br />
Backend_auth Number User Back-End Authentication<br />
Disabled Y/N User Disabled<br />
Lock_count Number User Lock Count<br />
Locked Y/N User Locked<br />
Status String User Status<br />
Profiles String User Profiles<br />
Link_userid String User Link<br />
Link_domain String Domain Link<br />
Created<br />
Modified<br />
Digipass Fields<br />
Name Type Description<br />
Serial_no String DP Serial No<br />
Domain String DP Domain<br />
Org_unit String DP Organisational Unit<br />
Dp_type String DP Type<br />
Appl_names String DP Application Names<br />
Apply_types String DP Application Types<br />
Status String DP Status<br />
Userid String DP User ID<br />
Assigned Date DP Assign Date<br />
Grace_period_end Date DP Grace Period End Date<br />
Bvdp_enabled Y/N Backup Virtual DP Enabled<br />
Bvdp_expires Date BVDP Expiration Date<br />
Bvdp_uses_left Number BVDP Uses Left<br />
Reporting<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 223
Name Type Description<br />
Reserve Number DP Reserved<br />
Description String Digipass Description<br />
Created Date DP Creation Date<br />
Modified Date DP Modification Date<br />
Audit Fields<br />
Name Type Description<br />
Source String Audit Source<br />
Msg_type Number Audit Message Type<br />
Type_name String Audit Type Name<br />
Code String Audit Code<br />
Desc String Audit Description<br />
Category String Audit Category<br />
Timestamp Date Audit TimeStamp<br />
Amid String Audit Amid<br />
Reason String Audit Reason<br />
Area String Area<br />
Operation String Operation<br />
Error_Code Number Error Code<br />
Error_Message String Error Message<br />
Error_Stack String Error Details<br />
Audit_Location String Source Location<br />
<strong>Server</strong>_Location String <strong>Server</strong> Location<br />
Client_Location String Client Location<br />
Version String Version<br />
Data_Source_Type String Data Source<br />
Data_Source_Location String Data Source Location<br />
Configuration_Details String Configuration Details<br />
Outcome String Outcome<br />
Reason String Reason<br />
Characteristics String Characteristics<br />
Credential_Type String Credentials<br />
Session_ID String Session ID<br />
Reporting<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 224
Name Type Description<br />
Application_Name String Application Name<br />
Request_ID String Request ID<br />
Password_Protocol String Password Protocol<br />
Input_Details String Input Details<br />
Action String Action<br />
Output_Details String Output Details<br />
Policy_ID String Policy ID<br />
From_Location String From<br />
To_Location String To<br />
Info_Message String Message<br />
Quota Number Quota<br />
Object String Object<br />
Command String Command<br />
Downtime Number Downtime<br />
Field_Details String Fields<br />
Packet_Type String Request Type<br />
Note<br />
13.1.4 Report Permissions<br />
Two or more values after the operator will be interpreted as if the word 'and' was between them.<br />
Reporting<br />
You can define Usage Permissions and Update Permissions for reports. Usage Permissions defines who is allowed<br />
to use the report. Update Permissions defines who is allowed to change the report definition. Both Usage and<br />
Update permissions can have the following values:<br />
13.2 Types of Report<br />
Private - only the owner can run this report<br />
Domain - all administrators in this domain can run this report<br />
Public - all administrators in all the domains can run this report.<br />
There are four report types. All report templates are based on these report types:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 225
List Analysis Report<br />
Detailed Analysis Report<br />
Distribution Analysis Report<br />
Trend Analysis Report.<br />
13.2.1 Standard Reports.<br />
Reporting<br />
The <strong>Identikey</strong> <strong>Server</strong> reporting package will come with standard reports. Standard reports are provided for the most<br />
common administration tasks.<br />
The standard reports can be grouped by their use:<br />
Reports produced by the Helpdesk to help with troubleshooting functional problems<br />
Detailed authentication report<br />
User authentication history report<br />
Detailed Digipass registration report<br />
Detailed activity summary report<br />
Detailed Signature Validation report<br />
Detailed Provisioning report<br />
Signature Validation history report<br />
Reports produced by System administrators to help with troubleshooting system problems<br />
Failed Operations summary report<br />
Succeeded Operations summary report<br />
Reports produced by <strong>Administrator</strong>s for Accounting information<br />
Authentication activity by user report<br />
Authentication activity by client report<br />
Provisioning activity by user report<br />
Provisioning activity by client report<br />
Transaction Signing Activity by User Application report<br />
Transaction Signing Activity by Client report<br />
Reports produced by <strong>Administrator</strong>s for System auditing information<br />
Administration activity summary report<br />
Digipass availability by type report<br />
Digipass deployment trend report<br />
Digipass deployment by type report<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 226
13.2.2 Custom Reports<br />
Authentication trend report<br />
Transaction Signing Activity Trend<br />
Provisioning activity trend report<br />
Account lock trend report<br />
Digipass assignment activity summary report<br />
Reporting<br />
Custom reports can be defined to fulfil requirements not met by the standard reports. Custom reports are based<br />
on the standard report types with a report query defined to suit your organization's requirements.<br />
13.2.3 Formatting Templates<br />
Report data is always generated into XML, then an XSLT transformation is applied to give the output. The XSLT<br />
transformation requires a formatting template. Each report definition requires at least one template so that it can<br />
be produced in the format required. Each report definition can have more than one Formatting Template. The<br />
template to be used can be selected when running the report.<br />
13.3 Archiving Strategy<br />
Large amounts of data means that reports take a long time to run. Have an archiving strategy in place that moves<br />
out data over a certain age. Make a decision about what data you will require in your reports, and for how long you<br />
need to keep it live on the Data Source.<br />
Archived data cannot be reported upon.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 227
14 Auditing<br />
14.1 Text File<br />
Setting up auditing in the <strong>Identikey</strong> <strong>Server</strong> requires three basic steps:<br />
1. Set up audit message destination. If this will be a text file or the Windows Event Log, no configuration is<br />
required.<br />
2. Configure auditing in the <strong>Identikey</strong> <strong>Server</strong> to send audit messages to the correct destination.<br />
3. Configure Audit Viewer to retrieve, filter and display audit messages.<br />
14.1.1 Text File Name Variables<br />
Auditing<br />
A number of variables may be included in the name or path of an audit text file.Time/date variables will influence<br />
how often a new text file is created.<br />
Table 62: Audit Text File Name/Path Variables<br />
Variable Notes<br />
{year} Current year in format 'YYYY' eg. 2006<br />
{month} Current month in format 'MM' eg. November becomes 11<br />
{mday} Current day of the month in format 'DD' eg. 06<br />
{yday} Current day of the year in format 'DDD' – this will be a number between 1 and 366<br />
{week} Current week of the year in format 'WW' eg. The 6 th week of the year will be 06<br />
{source} The name of the program from which the audit message was received by the Audit System eg.<br />
Authentication <strong>Server</strong><br />
Example<br />
Entering the following into the Log File field in the <strong>Identikey</strong> <strong>Server</strong> Configuration:<br />
c:\Audit Files\{source}\audit-{year}-{month}-{mday}.audit<br />
would cause:<br />
A directory named <strong>Identikey</strong> <strong>Server</strong> to be created in the Audit Files directory<br />
A new audit text file to be created daily<br />
A file named audit-2006-11-06.audit to be created on the 6 th November 2006<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 228
14.1.2 Configure Auditing to Text File<br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
2. Click on the Auditing icon.<br />
3. Click on the Add... button.<br />
4. Select Text File from the list box.<br />
5. Click on OK.<br />
The Add Text File Method window will be displayed.<br />
6. Enter a name to use for display purposes in the Display Name field.<br />
Auditing<br />
7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will<br />
be returned by the <strong>Identikey</strong> <strong>Server</strong> if an audit message cannot be written with this method.<br />
8. Tick the Record audit message if no other audit method has recorded it checkbox if required.<br />
9. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
10. Enter the location and a name for the text file. See 14.1.1 Text File Name Variables for more information.<br />
11. To speed up the auditing process, tick the Always keep file open checkbox. This will mean that the file is<br />
locked while the <strong>Identikey</strong> <strong>Server</strong> is running.<br />
12. Tick the Use GMT/UTC checkbox to record dates and times in GMT/UTC. Otherwise, they will be recorded in<br />
local time. The text file will indicate the time zone used.<br />
13. Click on OK.<br />
14. Click on Apply.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 229
14.2 Windows Event Log<br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
2. Click on the Auditing icon.<br />
3. Click on the Add... button.<br />
4. Select Event Log from the list box.<br />
5. Click on OK.<br />
The Add Event Log Method window will be displayed.<br />
6. Enter a name to use for display purposes in the Display Name field.<br />
Auditing<br />
7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will<br />
be returned by the <strong>Identikey</strong> <strong>Server</strong> if an audit message cannot be written with this method.<br />
8. Tick the Record audit message if no other audit method has recorded it checkbox if required.<br />
9. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
10. Select a log type or enter a new log type to be created in the Log Type drop down list.<br />
11. Click on OK.<br />
12. Click on Apply.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 230
14.3 ODBC Audit Message Database<br />
14.3.1 Set up ODBC Database<br />
14.3.1.1 Create database<br />
See 3.1 Database Support for information on the ODBC databases supported by <strong>Identikey</strong> <strong>Server</strong>.<br />
14.3.1.2 Create database schema<br />
Auditing<br />
Two tables are required in the database. These can be created by the DPDBadmin utility using the -audit<br />
parameter (see 3.8.1 Modify Database Schema),<br />
or manually.<br />
Table 63: Required Audit Database Tables<br />
Table Name Purpose<br />
vdsAuditMessage Basic audit message, including mandatory fields<br />
vdsAuditMsgField Contains extra (non-mandatory) audit message fields which may be included in an audit<br />
message<br />
Image 2: Audit Database Table Relationships<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 231
vdsAuditMessage Table<br />
Auditing<br />
This table will contain one record per audit message generated, with non-mandatory information held in the<br />
vdsAuditMsgField table.<br />
Table 64: vdsAuditMessage Required Fields<br />
Column Name Data Type Primary<br />
Key<br />
Allow NULL Details<br />
vdsTimeStamp timestamp* Yes No Date/time of event.<br />
vdsAMID varchar(32) Yes No 32 hex digit Audit Message ID (without “0x”<br />
prefix).<br />
vdsSource varchar(64) No Source component name.<br />
vdsType integer No Numeric type.<br />
vdsCode varchar(8) No Message code eg. “I-010003”.<br />
vdsDesc varchar(255) No Standard description for audit message.<br />
vdsCategory varchar(32) No Name of category eg. “Authentication”.<br />
* For some databases, this is DATETIME (SQL <strong>Server</strong>, Sybase Enterprise) or DATE (Oracle) – this is not an<br />
automatically generated timestamp, but just a date/time field. Millisecond precision or greater is required.<br />
vdsAuditMsgField Table<br />
This table may contain several records for a single audit message.<br />
Table 65: vdsAuditMsgField Required Fields<br />
Column Name Data Type Primary<br />
Key<br />
Allow NULL Details<br />
vdsTimeStamp timestamp* Yes No Date/time of event.<br />
vdsAMID varchar(32) Yes No 32 hex digit AMID (without “0x” prefix).<br />
vdsFieldID integer Yes No Integer (dataset) ID of optional field.<br />
vdsFieldValue varchar(1024) No Yes Value of optional field, represented as string.<br />
* For some databases, this is DATETIME (SQL <strong>Server</strong>, Sybase Enterprise) or DATE (Oracle) – this is not an<br />
automatically generated timestamp, but just a date/time field. Millisecond precision or greater is required.<br />
14.3.1.3 Create Database Account(s)<br />
Create at least one database account. These permissions are required for the <strong>Identikey</strong> <strong>Server</strong> and Audit Viewer:<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 232
Table 66: Required Account Permissions<br />
Program Table Permission(s) required<br />
<strong>Identikey</strong> <strong>Server</strong> All Write<br />
Audit Viewer All Read<br />
14.3.1.4 Create DSN on <strong>Identikey</strong> <strong>Server</strong> machine<br />
Create a Data Source Name for the database on the machine on which the <strong>Identikey</strong> <strong>Server</strong> is installed.<br />
14.3.1.5 Create DSN on Audit Viewer machine<br />
Create a Data Source Name for the database on the machine on which the Audit Viewer is installed.<br />
14.3.2 Configure <strong>Identikey</strong> <strong>Server</strong><br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
2. Click on the Auditing icon.<br />
3. Click on the Add... button.<br />
4. Select ODBC Database from the list box.<br />
5. Click on OK.<br />
The Add ODBC Audit Method window will be displayed.<br />
6. Enter a name to use for display purposes in the Display Name field.<br />
Auditing<br />
7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will<br />
be returned by the <strong>Identikey</strong> <strong>Server</strong> if an audit message cannot be written with this method.<br />
8. Tick the Record audit message if no other audit method has recorded it checkbox if required.<br />
9. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
10. Enter the DSN for the database.<br />
11. Enter the username and password of the database account to be used by the <strong>Identikey</strong> <strong>Server</strong> (if required).<br />
12. Click on OK.<br />
13. Click on Apply.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 233
14.3.3 Configure Audit Viewer<br />
Note<br />
A Data Source Name must be configured on the Audit Viewer computer for the database.<br />
1. Select New Audit Source -> ODBC Database from the File menu.<br />
2. Enter a display name to be used for the database within the Audit Viewer.<br />
3. Enter the Data Source Name for the database.<br />
4. Enter the User ID and password of an administrator account for the database.<br />
5. Tick the Store User ID and Password checkbox to save login details in the Audit Viewer.<br />
6. Click on OK.<br />
14.4 Linux Syslog<br />
For Linux systems, auditing data will be written to the Syslog.<br />
The Syslog requires the Audit Messages to have the following attributes :<br />
Priority<br />
Facility<br />
Timestamp<br />
Source Hostname<br />
Source Application name<br />
Event payload<br />
Auditing<br />
The values in the attributes on the Audit Message determine where the message gets written to, and whether it<br />
appears on the Syslog or not.<br />
Audit Message type to Syslog Priority Mapping<br />
The table below defines the mapping of Audit Message Type to Syslog Priority. You can use the Syslog Priority to<br />
direct the Audit Message Types to any log file, pipe, or remote syslog service.<br />
Table 67: Audit Message Types and Syslog Priority<br />
Message Type Syslog Priority<br />
Success LOG_NOTICE<br />
Fail LOG_NOTICE<br />
Info LOG_INFO<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 234
Warning LOG_WARNING<br />
Error LOG_ERR<br />
14.4.1 Configure the System Log<br />
Auditing<br />
The host's syslog daemon needs to be configured to additionally point to the chroot location in order to pick up the<br />
identikey syslog audit events. This configuration will depend on the environment and how it is set up.<br />
Ubuntu 8.0.4<br />
1. Edit /etc/default/syslogd, adding option -a /opt/vasco/identikey/dev/log to the SYSLOGD parameter.<br />
RedHat 5<br />
1. Edit /etc/sysconfig/syslog, adding option -a /opt/vasco/identikey/dev/log to the SYSLOGD_OPTIONS<br />
parameter.<br />
2. For standard SELinux environments, the Syslog daemon may not have the correct permissions necessary to<br />
create the additional socket within the chroot. To resolve this, run the following command:<br />
SuSE<br />
cat /etc/selinux/targeted/contexts/files/file_contexts &&<br />
restorecon -F /opt/vasco/identikey/dev<br />
/opt/vasco/identikey/dev -d system_u:object_r:device_t:s0<br />
/opt/vasco/identikey/dev/log -s system_u:object_r:devlog_t:s0<br />
EOF<br />
1. Run the following command:<br />
14.4.2 Modify Configuration File<br />
echo SYSLOGD_ADDITIONAL_SOCKET=\"/opt/vasco/identikey/dev/log\" >><br />
/etc/sysconfig/syslog && SuSEconfig && /etc/init.d/syslog restart<br />
You may need to amend the syslog configuration file, to define the location to which specific audit logs should be<br />
written.<br />
For example, if the <strong>Identikey</strong> <strong>Server</strong> Syslog configuration has the audit Log Type set to local0, the syslog<br />
configuration file will need to define where to write this type of log message to. Check the ownership and<br />
permissions of the log file so that Syslog has permissions to write to it.<br />
Having changed the syslog configuration files, you will need to restart the host's syslog daemon.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 235
14.4.3 Configure <strong>Identikey</strong> <strong>Server</strong> to Write Audit Messages to the Syslog<br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
2. Click on the Auditing icon.<br />
3. Click on the Add... button.<br />
4. Select System Log from the list box.<br />
5. Click on OK.<br />
The Add System Log Audit Method window will be displayed.<br />
6. Enter a name to use for display purposes in the Display Name field.<br />
Auditing<br />
7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will<br />
be returned by the <strong>Identikey</strong> <strong>Server</strong> if an audit message cannot be written with this method.<br />
8. Tick the Record audit message if no other audit method has recorded it checkbox if required.<br />
9. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
10. Select a log type or enter a new log type to be created in the Log Type drop down list.<br />
11. Click on OK.<br />
12. Click on Apply.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 236
14.5 Live Connection - <strong>Identikey</strong> <strong>Server</strong> to Audit Viewer<br />
14.5.1 Configure <strong>Identikey</strong> <strong>Server</strong><br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration GUI.<br />
2. Click on the Auditing icon.<br />
3. Click on the Add... button.<br />
4. Select Live Connection from the list box.<br />
5. Click on OK.<br />
The Add Live Connection Method window will be displayed.<br />
6. Enter a name to use for display purposes in the Display Name field.<br />
Auditing<br />
7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will<br />
be returned by the <strong>Identikey</strong> <strong>Server</strong> if an audit message cannot be written with this method.<br />
8. Tick the Only record message if no previous method has recorded it checkbox if required.<br />
9. Select one or more audit message types to be logged by this plug-in:<br />
Error<br />
Warning<br />
Information<br />
Success<br />
Failure<br />
10. Enter the IP address and port number on which the <strong>Identikey</strong> <strong>Server</strong> will listen for auditing connections.<br />
11. Enter the maximum number of concurrent connections to allow.<br />
12. Click on OK.<br />
13. Click on Apply.<br />
14.5.2 Configure Audit Viewer<br />
1. Select New Audit Source -> <strong>Server</strong> from the File menu.<br />
2. Enter a display name to be used for the messages within the Audit Viewer.<br />
3. Enter the IP address of the <strong>Identikey</strong> <strong>Server</strong>.<br />
4. Enter the port on which the <strong>Identikey</strong> <strong>Server</strong> will listen for auditing connections.<br />
5. Click on OK.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 237
15 Tracing<br />
The level of tracing for the <strong>Identikey</strong> <strong>Server</strong> can be configured using the <strong>Identikey</strong> <strong>Server</strong> Configuration GUI.<br />
Tracing messages will be recorded to a text file.<br />
15.1 Trace Message Types<br />
Table 68: Tracing Message Types<br />
Message Type<br />
Code<br />
[CRITC] Critical error/warning<br />
Notes Examples<br />
[MAJOR] Major error/warning [MAJOR] > Failed to execute command. Error <br />
[MINOR] Minor error/warning [MINOR]> Cannot get License Key from Component record<br />
[CONFG] Configuration/initialization [CONFG] > ODBC Database audit plugin is successfully<br />
loaded<br />
[CONFG] > Component cache configured as:<br />
max age : 900<br />
max size : 1000<br />
clean threshold : 800<br />
min clean interval : 60<br />
[ALERT] Alerts [ALERT] > disconnecting from server.<br />
[INFO] Informational messages [INFO ] > Audit: {Info} {Initialization} {I-002002} {The<br />
Digipass Authentication library has been initialized<br />
successfully.}<br />
[INFO ] > Creating Digipass object.<br />
[VINFO] Verbose informational messages [VINFO] > Event log source is <br />
[VINFO][ODBCConnection::OpenConnection] > Established<br />
connection to ODBC database<br />
[DATA] Data tracing [DATA ] > Prepared SQL statement "SELECT vdsDomain,<br />
vdsDescription, vdsCreateTime, vdsModifyTime FROM<br />
vdsDomain ORDER BY vdsDomain"<br />
[TEMP] Temporary data values [TEMP ] > Updated list is <br />
[RESRC] Resource usage [RESRC] > Socket Bound to <br />
[DEBUG] Debugging (useful for support<br />
purposes)<br />
[DEBUG] > Registering Binary with Event<br />
log for Source < <strong>Identikey</strong> <strong>Server</strong> 3<br />
{Application}><br />
[DEBUG] > Committed transaction<br />
Tracing<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 238
Message Type<br />
Code<br />
[SECUR] Security messages, messages that<br />
may contain security sensitive data<br />
15.2 Trace Message Levels<br />
Notes Examples<br />
Tracing<br />
There are two tracing levels available when configuring tracing from the <strong>Identikey</strong> <strong>Server</strong> Configuration GUI – Basic<br />
and Full. This can be customised further if required by directly editing the configuration file. The message types<br />
recorded by each level are shown in the table below.<br />
Table 69: Tracing Message Levels<br />
CRITC<br />
MAJOR<br />
MINOR<br />
CONFG<br />
ALERT<br />
INFO<br />
Basic Full<br />
CRITC<br />
MAJOR<br />
MINOR<br />
CONFG<br />
ALERT<br />
INFO<br />
VINFO<br />
DATA<br />
TEMP<br />
RESRC<br />
DEBUG<br />
SECUR<br />
15.3 Trace Message Contents<br />
Basic and Full tracing levels output different amounts of information in trace messages.<br />
Table 70: Tracing Message Contents<br />
Trace Level Message Contents<br />
Basic [date_time] [thread ID] [level code] message<br />
Full [date_time] [thread ID] [level code] [internal function name] message<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 239
16 Digipass TCL Command-Line Administration<br />
16.1 Introduction<br />
Digipass TCL Command-Line Administration<br />
Digipass TCL Command-Line Administration (DPCLA) allows interactive command-line and scripted administration<br />
of Digipass related data. It has a number of possible uses:<br />
Interactive command-line administration<br />
Scripted administration<br />
Complex bulk administration tasks<br />
Reporting on the data in the data store<br />
The DPCLA consists of the following components:<br />
DPADMINCMD<br />
This is a command-line program that can be used interactively or called from within a batch file, script or other<br />
program. This provides a command shell based on the TCL interpreter.<br />
VASCO TCL Extension Library<br />
The main functionality is provided by the VASCO extensions to TCL. This provides a set of additional commands in<br />
a “vasco” namespace.<br />
The extension library is used by DPADMINCMD, which loads the namespace automatically. However, if you have<br />
your own TCL environment already, you can load the extension library directly into it, without having to use<br />
DPADMINCMD. In that case, you will need to use the namespace qualifier.<br />
Other scripting environments such as Python, Perl and VBScript also have modules available that enable them to<br />
use TCL, allowing the VASCO extensions to be used in a variety of environments.<br />
TCL Runtime<br />
The <strong>Identikey</strong> <strong>Server</strong> installation program also installs the TCL 8.4 runtime environment, which is necessary to run<br />
DPADMINCMD.<br />
Caution<br />
Windows command-line functions may be run from within the Digipass TCL Command-Line<br />
Administration. A new Windows command-line console may also be opened.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 240
16.1.2 Knowledge Requirements<br />
Digipass TCL Command-Line Administration<br />
Digipass TCL Command-Line Administration is an extension of the TCL 8.4 scripting language, and administrators<br />
will require a basic competence in TCL in order to use the command-line utility. However, for simple usage, no<br />
great knowledge of TCL is required.<br />
For an introduction to TCL, see http://www.tcl.tk/about/language.html. Other pages on the www.tcl.tk web site<br />
may also provide useful background on TCL and its capabilities. For a more comprehensive tutorial, see<br />
http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html (but note that we install version 8.4, so there may be minor<br />
differences in 8.5).<br />
16.1.3 Data Store Connection<br />
DPCLA makes a connection to the data store in a similar way to the Administration Web Interface. This connection<br />
requires an administrative login.<br />
16.1.4 Configuration File.<br />
Digipass TCL Command-Line Administration requires a configuration file (dpacmincmd.xml file) to be present<br />
before it can run correctly. This file can be created by the Digipass TCL Command-Line Administration installation<br />
wizard, or created using a template. See 11.8Digipass<br />
TCL Command Line Utility for more details.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 241
16.2 Using DPADMINCMD – Basics<br />
You can use TCL interactively with a command prompt or you can use it to run a script.<br />
16.2.1 Using an Interactive TCL Command Prompt<br />
Digipass TCL Command-Line Administration<br />
Using DPADMINCMD to open an interactive TCL command prompt can be done as follows:<br />
Windows<br />
1. Open a Windows command prompt in the \Bin directory.<br />
2. Enter the following command:<br />
Linux<br />
dpadmincmd<br />
1. Enter the chroot environment:<br />
vds_chroot /bin/bash<br />
2. Enter the following command:<br />
dpadmincmd<br />
A command prompt will be opened, at which you can enter TCL commands. DPADMINCMD automatically loads the<br />
VASCO TCL extensions, so that they can be used without needing to specify the VASCO 'namespace'.<br />
Digipass TCL Command-Line Administration Version 3.0.0.12<br />
Copyright (C) VASCO Data Security Inc. 2006<br />
All rights reserved<br />
%<br />
Before any data administration commands will work, you need to perform an administrative logon to the <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
% logon {userid admin password password}<br />
1<br />
%<br />
If the logon is successful, the output indicates a session number. Otherwise, an error message will be displayed.<br />
Once there has been a successful logon, you can enter other commands, for example:<br />
% user query {userid admin}<br />
{domain master userid admin has_dp Unassigned status 0 created<br />
{2006/05/11 11:05:32} modified {2006/05/11 11:05:32}}<br />
%<br />
To log off, use the logoff command; to exit, use the exit command.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 242
16.2.2 Running a Script<br />
Digipass TCL Command-Line Administration<br />
Using DPADMINCMD to run a script requires an administration logon to be specified with command-line<br />
parameters, unless the script itself contains a logon command.<br />
For a logon requiring credentials, the -u (userid) and -p (password) parameters are required.<br />
1. If using Windows, open a command prompt in the \Bin directory.<br />
If using Linux, enter the chroot environment:<br />
vds_chroot /bin/bash<br />
2. Enter the following command for an implicit logon and press Enter:<br />
dpadmincmd -i scriptname<br />
3. Or, enter the following command for an explicit logon and press Enter:<br />
dpadmincmd -u userid -p password scriptname<br />
The scriptname parameter can be a file name or path and file name.<br />
If your script requires parameters, enter these after the scriptname.<br />
Example<br />
dpadmincmd -i myscript.tcl param1 param2<br />
The script file must contain a sequence of TCL commands. DPADMINCMD will first perform the logon, and if<br />
successful, will execute each command in the script in sequence. The TCL language allows you to write simple<br />
sequential scripts or add more complex control flow, functions and so on.<br />
The script does not need to use the logoff or exit commands explicitly. DPADMINCMD will logoff the session if<br />
necessary at exit time.<br />
Character Substitution<br />
When using a non-printing ASCII character substitution (eg. \t for a horizontal tab) in a string, enclose the string in<br />
double quotes. If the string is enclosed in { }, the string will be displayed exactly as entered.<br />
eg. “Error: \t Component does not exist. \n \t \t Please check the Component name.” will be displayed as:<br />
Error: Component does not exist.<br />
Please check the Component name.<br />
Whereas {Error: \t Component does not exist. \n \t \t Please check the Component name.} will be displayed as:<br />
Error: \t Component does not exist. \n \t \t Please check the Component name.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 243
16.2.3 Help<br />
To access help from the command prompt, use these commands:<br />
Table 71: DPADMINCMD Help Commands<br />
Command Notes<br />
Digipass TCL Command-Line Administration<br />
help Provides basic information about DPADMINCMD, including a list of all<br />
commands available.<br />
help Provides information about the specific command, including required<br />
parameters, optional parameters and available subcommands.<br />
help Provides information about the specific subcommand, including required and<br />
optional parameters.<br />
16.2.4 Command Parameters<br />
16.2.5 Result Output<br />
Some notes on command parameters in TCL:<br />
Parameters are given in list form: {field1 value1 field2 value2 ...}<br />
Parameter values that include whitespace require double quotes or { }, for example {field1 “value 1” field2<br />
{value 2} ...}<br />
Commands may be substituted for parameters using square brackets, where the command will return the type<br />
of parameter(s) required. eg.<br />
foreach i [user query {domain master} {domain userid has_dp}] { puts $i }<br />
In this example, a query returns a list of Users with Digipass assigned, which is used in the foreach command.<br />
Results are typically returned in list form, with pairs of field names and values, eg:<br />
{domain master userid user0001 has_dp Assigned}<br />
Some commands do not return field information, only a simple message, eg:<br />
Created Component.<br />
Queries return a list of list results, with only the requested fields displayed. These may be formatted for better<br />
readability by wrapping the query in another command, eg:<br />
foreach i [user query {domain master} {domain userid has_dp}] { puts $i }<br />
The result from the example above will display each user record in the master domain on a separate line, and only<br />
display the requested fields (domain, userid and has_dp), eg:<br />
domain master userid admin has_dp Assigned<br />
domain master userid user0001 has_dp Unassigned<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 244
16.2.6 Error Handling<br />
Digipass TCL Command-Line Administration<br />
When an error occurs in a VASCO TCL Extension command, information about the error will be written to the<br />
standard TCL error variables. This allows error handling in scripts, and allows a user to obtain information about<br />
the last error received when using an interactive command line. For example, if this command was entered:<br />
% user get {userid doesnotexist}<br />
and a User with the ID of doesnotexist could not be found, then this error would be returned:<br />
Error code: Error message: <br />
Information about that error could be retrieved from standard TCL error variables using these commands:<br />
Returns:<br />
And<br />
-13<br />
Returns:<br />
% puts $errorCode<br />
% puts $errorInfo<br />
Error code: Error message: <br />
while executing<br />
"user get {userid doesnotexist}<br />
16.2.7 International Characters<br />
DPADMINCMD supports international characters, but your console window must be able to support the characters<br />
or they will not display correctly. The Lucida Console font is typically used.<br />
16.2.8 Syntax Notes<br />
The following points should be remembered for basic interactive and scripted usage:<br />
Result values that include whitespace, including date/time values, are given { } by TCL<br />
Comments in scripts are preceded with a #<br />
A backslash character at the end of a line indicates that the command is continued on the next line.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 245
16.2.9 Sample Scripts<br />
Digipass TCL Command-Line Administration<br />
Below are some sample scripts which perform basic tasks. They range in complexity to provide an example of what<br />
can be done, and the techniques required.<br />
Check if a Component Record exists<br />
This script checks for the existence of a RADIUS Client Component record with a specific IP address. If a<br />
Component record of that type and location does not exist, a message will be displayed onscreen.<br />
# Check if a specified RADIUS Client Component exists<br />
if [catch {component get {comp_type "RADIUS Client" location 192.168.122.213 }} result] {<br />
puts "Component does not exist: $result"<br />
}<br />
Create a Record if it doesn't exist<br />
This script builds on the previous sample to check for the existence of a RADIUS Client Component record and, if<br />
one does not currently exist, to create one. It requires a location parameter to be passed to the script when it is run<br />
from DPADMINCMD.<br />
# Get IP-address location from command-line argument<br />
set loc [lindex $argv 0]<br />
# Create the component if it does not exist<br />
if [catch "component get {comp_type {RADIUS Client} location $loc}" result] {<br />
if [catch "component create {comp_type {RADIUS Client} \<br />
location $loc \<br />
policy_id {<strong>Identikey</strong> <strong>Server</strong> 3<br />
Local Authentication} \<br />
shared_secret default \<br />
protocol RADIUS}" result] {<br />
puts "Error creating component: $result"<br />
} else {<br />
puts "Created component"<br />
}<br />
} else {<br />
puts "Component already exists"<br />
}<br />
To run this script from DPADMINCMD, you would need to use the following syntax:<br />
dpadmincmd -i scriptname loc<br />
Bulk User Administration<br />
This script collects all Digipass User records belonging to the domain named Domain1 and unlocks any which were<br />
locked.<br />
# Get all the users of the domain Domain1<br />
if [catch {user query {domain Domain1}} users] {<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 246
puts "Unable to retrieve users: $users"<br />
} else {<br />
# Loop for each user<br />
foreach user $users {<br />
# Get the user information into an array for easier<br />
access<br />
array set userinfo $user<br />
}<br />
}<br />
Digipass TCL Command-Line Administration<br />
# Check if the locked information is present as it may not return a<br />
# value is the user is not locked<br />
if [info exists userinfo(locked)] {<br />
# If the user is locked, try to unlock it<br />
if [string equal $userinfo(locked) yes] {<br />
if [catch "user update {userid $userinfo(userid) domain Domain1 locked no}" result] {<br />
puts "Error unlocking $userinfo(userid): $result"<br />
} else {<br />
puts "Unlocked $userinfo(userid)"<br />
}<br />
}<br />
}<br />
# Clear-out the current user information<br />
array set userinfo [list]<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 247
17 Replication<br />
17.1 Concepts<br />
Replication can be configured to allow multiple <strong>Identikey</strong> <strong>Server</strong>s to keep their data synchronized.<br />
Active Directory<br />
Replication<br />
Active Directory has its own replication, which will replicate data between Domain Controllers. In some<br />
circumstances, however, Active Directory replication can be slow enough to cause problems in <strong>Identikey</strong> <strong>Server</strong><br />
authentications. Due to these problems, each <strong>Identikey</strong> <strong>Server</strong> using Active Directory as its data store has a<br />
Digipass Cache. Digipass records used in recent authentication requests are kept in the cache for a set amount of<br />
time, and checked against Active Directory records. See 2.4 Active Directory Replication Issues for more<br />
information on the Digipass Cache.<br />
Where <strong>Identikey</strong> <strong>Server</strong>s use Active Directory as their data store, this Digipass Cache can be replicated between<br />
<strong>Identikey</strong> <strong>Server</strong>s. This ensures that authentication data is as up-to-date as possible.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 248
ODBC Databases<br />
Replication<br />
Where multiple <strong>Identikey</strong> <strong>Server</strong>s use different ODBC databases as their data stores, replication ensures that each<br />
database is up to date with the latest data changes.<br />
17.1.1 Replication Queue<br />
The replication queue for each <strong>Identikey</strong> <strong>Server</strong> which is configured as a replication destination is written to two<br />
files – a data and an index file – in \ReplData. The files are named using the destination<br />
<strong>Identikey</strong> <strong>Server</strong> name. Check the <strong>Identikey</strong> <strong>Server</strong> Configuration for the destination server to check the configured<br />
name.<br />
17.1.2 Record-level Replication<br />
The replication method used by <strong>Identikey</strong> <strong>Server</strong> involves replication of entire records, rather than individual record<br />
attributes. This means that data clashes can occur when a single record is updated at the same time from different<br />
sources. If this occurs, the later change will be the one chosen and written to the database. Superseded changes<br />
are ignored.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 249
17.1.3 Replication Process<br />
Replication<br />
The writing of an data update to the replication queue (creating a replication entry) and sending a replication entry<br />
to another <strong>Identikey</strong> <strong>Server</strong> is handled by two separate processes.<br />
Write to Replication Queue<br />
The process which writes to the replication queue is run before any data changes are committed to the database. If<br />
the data change cannot be written to the replication queue – usually because the replication queue file has<br />
exceeded the maximum size allowed – the data change will not be committed to the database.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 250
Send Replication Queue Entry<br />
Replication<br />
The other process sends replication entries from a replication queue to the required <strong>Identikey</strong> <strong>Server</strong>. If the<br />
destination <strong>Identikey</strong> <strong>Server</strong> cannot write the change to its database, it sends back a failure message. The process<br />
will:<br />
1. Leave the entry in the queue.<br />
2. Set a retry time for the entry (this depends on the Retry Interval set in the <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
utility).<br />
3. Attempt replication for the entry according to the number of retries set in the <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
utility. After the Maximum number of retries is reached, the entry is removed from the queue and its details<br />
audited.<br />
Note<br />
This does not include problems in connecting to the other <strong>Identikey</strong> <strong>Server</strong>. Queue retries will be<br />
suspended until the connection is re-established.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 251
17.1.4 Connection Handling<br />
Replication<br />
When the <strong>Identikey</strong> <strong>Server</strong> service is started, the <strong>Identikey</strong> <strong>Server</strong> will establish a connection to each destination<br />
<strong>Identikey</strong> <strong>Server</strong> configured for replication. It will keep this connection open until the service is stopped or the<br />
connection is broken. If the connection is broken, it will attempt to reconnect after the minimum reconnect interval<br />
set in the <strong>Identikey</strong> <strong>Server</strong> Configuration has elapsed. If that fails, it will continue to attempt reconnection at<br />
increasing time intervals until it reaches the maximum reconnect interval set in the Configuration GUI. It will<br />
continue to attempt reconnection at the maximum reconnect interval until it succeeds.<br />
The <strong>Identikey</strong> <strong>Server</strong> ceases replication efforts to the destination <strong>Identikey</strong> <strong>Server</strong> until the connection is reestablished.<br />
This means that entries in the queue will not be lost because of a broken connection. Replication to<br />
other <strong>Identikey</strong> <strong>Server</strong>s will not be affected.<br />
A manual reconnect may be attempted at any time using the Administration Web Interface, if the data store used<br />
by the <strong>Identikey</strong> <strong>Server</strong> is an ODBC database.<br />
17.1.4.1 Component Record<br />
It is important to note that a <strong>Identikey</strong> <strong>Server</strong> will not accept replication updates from another machine unless it has<br />
a Component record for that machine with the Component Type set to <strong>Identikey</strong> <strong>Server</strong>.<br />
17.1.5 Monitoring Replication<br />
17.1.5.1 Auditing<br />
Audit messages are recorded when:<br />
connections are made or fail<br />
an update send was successful<br />
an update send failed<br />
an update was received and the receiving server sent back a data update success<br />
an update was received and the receiving server sent back a data update failure<br />
17.1.5.2 Administration Web Interface<br />
The Web Administration Interface will contain a Replication Status dialog. This dialog allows you to check the<br />
current status of replication for an <strong>Identikey</strong> <strong>Server</strong>. It also includes the number of entries currently in the<br />
replication queue.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 252
17.1.6 Forwarding Replication Entries<br />
Replication<br />
Replication forwarding is required where more than two <strong>Identikey</strong> <strong>Server</strong>s are replicating, either in a simple<br />
replication chain or more complicated arrangement. The ID of the originating <strong>Identikey</strong> <strong>Server</strong> and the <strong>Identikey</strong><br />
<strong>Server</strong>(s) to which it is sending the information are added to the replication entry. This allows the receiving<br />
<strong>Identikey</strong> <strong>Server</strong> to check which other <strong>Identikey</strong> <strong>Server</strong>s have already been sent the replication entry. It will forward<br />
the entry only to those <strong>Identikey</strong> <strong>Server</strong>s not listed.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 253
17.2 Configuring Replication<br />
Replication<br />
This topic provides high-level instructions for configuring replication between <strong>Identikey</strong> <strong>Server</strong>s in various<br />
situations. For more detailed instructions, see the online help for the Administration Web Interface.<br />
17.2.1 Active Directory<br />
These instructions assume that you have two <strong>Identikey</strong> <strong>Server</strong>s currently installed and operational, using Active<br />
Directory as their data store.<br />
1. Stop the <strong>Identikey</strong> <strong>Server</strong> service on each machine.<br />
2. Configure <strong>Identikey</strong> <strong>Server</strong> 1 to replicate to <strong>Identikey</strong> <strong>Server</strong> 2.<br />
3. Configure <strong>Identikey</strong> <strong>Server</strong> 2 to replicate to <strong>Identikey</strong> <strong>Server</strong> 1.<br />
4. Restart the <strong>Identikey</strong> <strong>Server</strong> service or daemon on each machine.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 254
17.2.2 ODBC Database<br />
17.2.2.1 Configure Replication to a Second <strong>Identikey</strong> <strong>Server</strong><br />
Replication<br />
These instructions assume that you have one <strong>Identikey</strong> <strong>Server</strong> installed and operational (SVR-1), and wish to set up<br />
another <strong>Identikey</strong> <strong>Server</strong>(SVR-2) and replicate between the two.<br />
1. Install <strong>Identikey</strong> <strong>Server</strong> on SVR-2.<br />
2. Configure SVR-2 identically – except IP addresses - to SVR-1, using the <strong>Identikey</strong> <strong>Server</strong> Configuration GUI or<br />
the configuration file.<br />
3. Ensure that SVR-2 is functioning correctly.<br />
4. On SVR-1, create an <strong>Identikey</strong> <strong>Server</strong> record for SVR-2.<br />
5. On SVR-1, load the License Key for SVR-2 into the <strong>Identikey</strong> <strong>Server</strong> record just created.<br />
6. On SVR-1, create a Client record of type Administration Program for the SVR-2's Administration Web<br />
Interface.<br />
This will ensure that the Administration Web Interface for SVR-2 can connect to SVR-2 once the database is<br />
replaced.<br />
7. Stop the <strong>Identikey</strong> <strong>Server</strong> service or daemon on SVR-1 and SVR-2.<br />
8. Take a complete copy of the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-1. If you are using the embedded<br />
PostgreSQL database, see 6.1.6.3 Backup of PostgreSQL Embedded Database for instructions.<br />
9. Configure the <strong>Identikey</strong> <strong>Server</strong> on SVR-1 to replicate to SVR-2. Ensure that the encryption settings are<br />
replicated. Use the import/export encryption settings facility.<br />
10. The <strong>Identikey</strong> <strong>Server</strong> service on SVR-1 may be restarted now if needed – it will build up a replication queue<br />
until it can connect to SVR-2.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 255
Replication<br />
11. Overwrite the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-2 with the copy from SVR-1. If you are using<br />
the embedded PostgreSQL database, see Step 2 of 6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong> Undamaged.<br />
12. Configure the <strong>Identikey</strong> <strong>Server</strong> on SVR-2 to replicate to SVR-1.<br />
13. Restart the <strong>Identikey</strong> <strong>Server</strong> service or daemon on SVR-2. If you did not restart the service on SVR-1 earlier, restart<br />
it now.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 256
17.2.2.2 Configure Replication to a Third or Subsequent <strong>Identikey</strong> <strong>Server</strong><br />
Replication<br />
These instructions assume that you have two or more <strong>Identikey</strong> <strong>Server</strong>s replicating to each other, and wish to add<br />
another <strong>Identikey</strong> <strong>Server</strong> (SVR-3) in a simple replication chain.<br />
1. Select which <strong>Identikey</strong> <strong>Server</strong> - SVR-1 or SVR-2 – will be replicating data with SVR-3. For these instructions,<br />
SVR-2 is assumed.<br />
2. Install <strong>Identikey</strong> <strong>Server</strong> on SVR-3.<br />
3. Configure the <strong>Identikey</strong> <strong>Server</strong> on SVR-3 identically to that on SVR-2, using the <strong>Identikey</strong> <strong>Server</strong> Configuration<br />
GUI or the configuration file.<br />
4. Ensure that SVR-3 is functioning correctly.<br />
5. On SVR-2, create an <strong>Identikey</strong> <strong>Server</strong> record for SVR-3.<br />
6. On SVR-2, create a Client record of type Administration Program for the SVR-3's Administration Web<br />
Interface.<br />
This will ensure that the Administration Web Interface for SVR-3 can connect to SVR-3 once the database is<br />
replaced.<br />
7. On SVR-2, load the License Key for SVR-3 into the <strong>Identikey</strong> <strong>Server</strong> record just created.<br />
8. Stop the <strong>Identikey</strong> <strong>Server</strong> service or daemon on SVR-2 and SVR-3.<br />
9. Take a complete copy of the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-2. If you are using the embedded<br />
PostgreSQL database, see 6.1.6.3 Backup of PostgreSQL Embedded Database for instructions.<br />
10. Configure the <strong>Identikey</strong> <strong>Server</strong> on SVR-2 to replicate to SVR-3. Ensure that the encryption settings are<br />
replicated. Use the import/export encryption settings facility.<br />
11. The <strong>Identikey</strong> <strong>Server</strong> service on SVR-2 may be restarted now if needed – it will build up a replication queue<br />
until it can connect to SVR-3.<br />
12. Overwrite the database used by the <strong>Identikey</strong> <strong>Server</strong> on SVR-3 with the copy from SVR-2. If you are using<br />
the embedded PostgreSQL database, see Step 2 of 6.2.2.2 Restore Database, <strong>Identikey</strong> <strong>Server</strong> Undamaged.<br />
13. Configure the <strong>Identikey</strong> <strong>Server</strong> on SVR-3 to replicate to SVR-2.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 257
Replication<br />
14. Restart the <strong>Identikey</strong> <strong>Server</strong> service or daemon on SVR-3. If you did not restart the service on SVR-2 earlier,<br />
restart it now.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 258
17.2.2.3 Add Redundant Replication<br />
Replication<br />
You may wish to add redundancy replication into your system to add extra protection in case of connection<br />
problems or data corruption. Redundant replication adds an extra link to a standard replication chain, so that<br />
replication can occur via more than one route.<br />
The instructions below assume a replication chain, with replication being added between a primary <strong>Identikey</strong><br />
<strong>Server</strong> (P-SVR-2) and a backup <strong>Identikey</strong> <strong>Server</strong> (B-SVR-1).<br />
1. Configure the <strong>Identikey</strong> <strong>Server</strong> on B-SVR-1 to replicate to P-SVR-2. Ensure that the encryption settings are<br />
replicated. Use the import/export encryption settings facility.<br />
2. Configure the <strong>Identikey</strong> <strong>Server</strong> on P-SVR-2 to replicate to B-SVR-1. Ensure that the encryption settings are<br />
replicated. Use the import/export encryption settings facility.<br />
3. Restart the <strong>Identikey</strong> <strong>Server</strong> service or daemon on each machine.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 259
18 Troubleshooting<br />
18.1 Troubleshooting Tools<br />
This section describes some tools and strategies available to you in troubleshooting problems.<br />
18.1.1 View Audit Information<br />
The <strong>Identikey</strong> <strong>Server</strong> can be configured to output audit messages to a number of locations:<br />
Windows Event Log<br />
Syslog<br />
Text file<br />
ODBC database<br />
Live Audit Viewer connection<br />
Troubleshooting<br />
If you are unsure how and where the <strong>Identikey</strong> <strong>Server</strong> is recording audit messages, open the <strong>Identikey</strong> <strong>Server</strong><br />
Configuration utility and open the Auditing section.<br />
18.1.1.1 Windows Event Viewer<br />
18.1.1.2 Syslog<br />
18.1.1.3 Text file<br />
Filter for audit messages from the <strong>Identikey</strong> <strong>Server</strong> by:<br />
1. Click on View -> Filter...<br />
2. Select<strong>Identikey</strong> <strong>Server</strong> from the Event Source drop down list.<br />
3. Click on OK.<br />
Audit information may be written to the Syslog under Linux. See the <strong>Identikey</strong> <strong>Server</strong> Installation Guide for Linux for<br />
details on how to enable audit information to be written to the Syslog.<br />
To view audit messages written to a text file by the <strong>Identikey</strong> <strong>Server</strong>, either open the text file using a text editor, or<br />
use the Audit Viewer.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 260
Troubleshooting<br />
See 14.1 Text File for information on configuring the <strong>Identikey</strong> <strong>Server</strong> to write audit messages to a text file and<br />
viewing audit text files in the Audit Viewer.<br />
18.1.1.4 ODBC Database<br />
18.1.2 Tracing<br />
To view audit messages written to an ODBC database by the <strong>Identikey</strong> <strong>Server</strong>, open the Audit Viewer.<br />
See 14.3 ODBC Audit Message Database for information on configuring the <strong>Identikey</strong> <strong>Server</strong> to write audit<br />
messages to an ODBC database and viewing audit messages from the database in the Audit Viewer.<br />
If you are having problems starting the <strong>Identikey</strong> <strong>Server</strong> or logging in via the <strong>Identikey</strong> <strong>Server</strong>, enabling tracing may<br />
allow you to track down the cause.<br />
1. Open the <strong>Identikey</strong> <strong>Server</strong> Configuration utility.<br />
2. Select either Basic Tracing or Full Tracing (see the Auditing and Tracing section of the Product Guide for<br />
more information).<br />
3. Enter a path and filename to which tracing information should be written, or use the default.<br />
4. Click on OK.<br />
5. Attempt a login.<br />
6. Check the trace file for information on the start-up conditions of the <strong>Identikey</strong> <strong>Server</strong> and of the login attempt.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 261
18.2 How To Troubleshoot<br />
This section gives you step-by-step guidelines for trouble shooting the components of <strong>Identikey</strong> <strong>Server</strong>.<br />
18.2.1 Connection Problems<br />
Troubleshooting<br />
If a program or web site is returning an error message of 'connection refused' or similar when attempting a<br />
connection to an <strong>Identikey</strong> <strong>Server</strong>, check that a Client record of the correct type exists in the <strong>Identikey</strong> <strong>Server</strong>'s data<br />
store for that program or web site. For example, an Administration Web Interface will be unable to administer data<br />
for an <strong>Identikey</strong> <strong>Server</strong> until a Client record of type Administration Program has been created for it.<br />
18.2.2 Installation Check<br />
The information in this section will enable you to check that various files have been installed in the correct locations<br />
and registered (where required), and Windows registry entries have been created and the correct values inserted.<br />
18.2.2.1 Windows Registry Entries<br />
Table 72: Registry Entries<br />
General<br />
Registry Path Key Name Value Notes<br />
HKEY_LOCAL_MACHINE\<br />
Software\VASCO Data Security\<br />
HKEY_LOCAL_MACHINE\<br />
Software\VASCO Data Security\<br />
InstalledProducts\<br />
HKEY_LOCAL_MACHINE\<br />
Software\VASCO Data Security\<br />
InstalledComponents\<br />
HKEY_LOCAL_MACHINE\Software\VAS<br />
CO Data Security\<strong>Identikey</strong> <strong>Server</strong>\<br />
Digipass Extension for Active Directory Users and Computers<br />
HKEY_LOCAL_MACHINE\<br />
Software\VASCO Data Security\ AD<br />
U&C Extension\<br />
InstallDirectory Typically c:\program<br />
files\VASCO\<strong>Identikey</strong> <strong>Server</strong><br />
<strong>Identikey</strong> <strong>Server</strong> 1 1 = installed<br />
0 = not installed<br />
If the Pack has been incorrectly<br />
installed, the key will typically be<br />
missing rather than having a value<br />
of 0.<br />
Check the recorded version<br />
numbers for various components.<br />
Version 1.0.0. Version number for the <strong>Identikey</strong><br />
<strong>Server</strong>.<br />
ApiLibrary \Bin\<br />
aal3ad30.dll<br />
HKEY_LOCAL_MACHINE\ DialogLibrary \Bin\<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 262
Registry Path Key Name Value Notes<br />
Software\VASCO Data Security\ AD<br />
U&C Extension\<br />
HKEY_LOCAL_MACHINE\<br />
Software\VASCO Data Security\ AD<br />
U&C Extension\<br />
Message Delivery Component<br />
HKEY_LOCAL_MACHINE\<br />
System\CurrentControlSet\<br />
Services\EventLog\Application\ Virtual<br />
Digipass Message Delivery Component\<br />
HKEY_LOCAL_MACHINE\<br />
System\CurrentControlSet\<br />
Services\EventLog\Application\ Virtual<br />
Digipass Message Delivery Component\<br />
Note<br />
18.2.2.2 Check Permissions<br />
dpwxlib.dll<br />
HelpFile \ Doc\<br />
AD_Extension_Help.chm<br />
EventMessageFil<br />
e<br />
\Bin\<br />
mdcserver.exe<br />
Troubleshooting<br />
TypesSupported 1 1 = EVENTLOG_ERROR_TYPE<br />
See 9.2.1 Configuration Settings for VASCO CGI configuration settings in the Windows registry.<br />
Directory or File Permission(s) required Notes<br />
User Self Management Web Site (IIS)<br />
/dpselfservice/cgi execute<br />
\UserSite\CGI\usercgi.exe execute This is required on Windows<br />
<strong>Server</strong> 2003 only.<br />
OTP Request Site (IIS)<br />
/requestotp/cgi execute<br />
\VDPSite\CGI\vdpcgi.exe execute This is required on Windows<br />
<strong>Server</strong> 2003 only.<br />
Table 73: Permissions Required<br />
18.2.2.3 Default Policy and Component Created<br />
A default Policy and a Component for the <strong>Identikey</strong> <strong>Server</strong> should have been created during the installation. If they<br />
have not been created, the <strong>Identikey</strong> <strong>Server</strong> will not process authentication requests.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 263
Note<br />
Troubleshooting<br />
These steps should only be followed if the Policies and Components have not been modified<br />
since installation.<br />
To check that Policies and Components were created successfully during installation:<br />
1. Open the Administration Web Interface.<br />
2. Click on Policies -> List.<br />
A Policy named <strong>Identikey</strong> <strong>Server</strong> Administration Logon should be included in the Policies List.<br />
3. Click on Components -> List.<br />
4. Check that a Component named <strong>Identikey</strong> <strong>Server</strong> is included in the Components List.<br />
5. Click on the <strong>Identikey</strong> <strong>Server</strong> Component record.<br />
6. <strong>Identikey</strong> <strong>Server</strong> Administration Logon should be selected in the Policy drop down list.<br />
18.2.3 Administration Web Interface Connection<br />
Security settings in your browser or firewall may block access to the Administration Web Interface. If this occurs,<br />
you will need to add it to the Trusted Sites list or add an exception to an access rule in the browser and/or firewall<br />
security settings.<br />
18.2.4 Message Delivery Component<br />
18.2.4.1 Enable Tracing<br />
1. Open the Configuration utility for the Message Delivery Component.<br />
2. Select either Basic Tracing or Full Tracing (see the Auditing and Tracing section of the Product Guide for<br />
more information).<br />
3. Enter a path and filename to which tracing information should be written.<br />
4. Click on OK.<br />
18.2.5 Open Port Numbers on Firewall<br />
The <strong>Identikey</strong> <strong>Server</strong> uses several different ports to communicate. If these are blocked by a firewall, some features<br />
will not work correctly. Listed below are the ports used by the <strong>Identikey</strong> <strong>Server</strong>, and the default port number used<br />
for each. If not otherwise specified, the settings are in Configuration.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 264
18.2.5.1 Incoming Ports<br />
Table 74: List of Incoming Ports Used by the <strong>Identikey</strong> <strong>Server</strong><br />
Port Default Configuration Source<br />
SOAP Port 8080 Communicators section, SOAP tab,<br />
Port field.<br />
RADIUS<br />
Authentication Port<br />
RADIUS Accounting<br />
Port<br />
18.2.5.2 Outgoing Ports<br />
1812 Communicators section, RADIUS<br />
tab, Authentication Port field.<br />
1813 Communicators section, RADIUS<br />
tab, Accounting Port field.<br />
SEAL Port 20003 Communicators section, SEAL tab,<br />
Port field.<br />
Live Audit Port 20006 Auditing section, Live Audit Viewer<br />
method properties, Port field<br />
Table 75: List of Outgoing Ports Used by the <strong>Identikey</strong> <strong>Server</strong><br />
Web Administration Interface<br />
SOAP Clients<br />
RADIUS Clients<br />
RADIUS Back-End <strong>Server</strong>s<br />
RADIUS Clients<br />
RADIUS Back-End <strong>Server</strong>s<br />
Digipass TCL Command-Line<br />
Administration<br />
IIS Modules<br />
Replication from other <strong>Identikey</strong><br />
<strong>Server</strong>s<br />
Audit Viewer<br />
Port Default Configuration Destination<br />
RADIUS<br />
Authentication Port<br />
RADIUS Accounting<br />
Port<br />
1812 Back-End <strong>Server</strong> records<br />
(Authentication Port field)<br />
1813 Back-End <strong>Server</strong> records<br />
(Accounting Port field)<br />
SEAL Port 20003 Replication section, Destination<br />
<strong>Server</strong>s tab, destination server<br />
properties, Port field<br />
RADIUS Back-End <strong>Server</strong>s<br />
RADIUS Back-End <strong>Server</strong>s<br />
Replication to other <strong>Identikey</strong><br />
<strong>Server</strong><br />
Database Port N/A ODBC Driver ODBC Database, when located on a<br />
separate machine<br />
LDAP Port 389 Back-End <strong>Server</strong> records Novell e-Directory, Active Directory<br />
or ADAM Back-End <strong>Server</strong>s<br />
18.2.6 SOAP/SSL Certificates<br />
Troubleshooting<br />
Please note that the test SSL certificate generated by the Configuration Wizard has a limited life. It may be<br />
necessary to renew it periodically. To avoid having to renew the test SSL certificate periodically you may purchase<br />
an SSL certificate.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 265
19 Audit Messages<br />
To set up auditing in the <strong>Identikey</strong> <strong>Server</strong>, see 11.3.7<br />
19.1 Audit Message Listing<br />
Table 76: Audit Messages List<br />
Message<br />
Code<br />
Auditing.<br />
Description Notes<br />
Audit Messages<br />
E000001 A system error has occurred. This message is used whenever there is a general<br />
processing error. It will contain full details of the error.<br />
E001001 The Digipass Plug-In failed to start up. The Plug-In encountered a fatal error on startup such<br />
as an invalid or missing configuration file.<br />
E001002 The Digipass Plug-In has been forced into the<br />
disabled state.<br />
The Plug-In has started up, but is in a disabled state<br />
in which it will not process authentication requests.<br />
This is typically due to a license problem (an invalid or<br />
missing License Key in the Plug-In's Component<br />
record); an invalid Component Location setting in the<br />
configuration file; or a missing Component record for<br />
the Plug-In.<br />
E001003 The Authentication <strong>Server</strong> failed to start up The Authentication <strong>Server</strong> encountered a fatal error on<br />
startup. This is typically due to an invalid or missing<br />
configuration file or failure to connect to the data<br />
store.<br />
E002001 The Active Directory AAL3 library failed to<br />
initialize.<br />
E002002 The Digipass Authentication library failed to<br />
initialize.<br />
The Active Directory 'AAL3' library encountered a fatal<br />
error on initialization, eg. invalid configuration settings<br />
in the configuration file.<br />
The 'Authentication' library encountered a fatal error<br />
on initialization, eg. invalid configuration settings in<br />
the configuration file.<br />
E002004 The RADIUS protocol handler failed to initialize. The protocol handler that receives and processes<br />
RADIUS requests did not start up. This may be<br />
because of a missing License Key in the<br />
Authentication <strong>Server</strong> Component record, or because<br />
the License Key in that Component record does not<br />
enable RADIUS support. Look for the line RADIUS=Yes<br />
in the License Key details.<br />
A common reason for this error, when RADIUS is<br />
enabled in the License Key, is that the RADIUS ports<br />
are already in use by another process on the machine.<br />
Alternatively, the configuration settings may be invalid.<br />
E002006 The Replication library failed to initialize. The Replication library encountered a fatal error on<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 266
Message<br />
Code<br />
E002007 Initialization of a Replication destination server<br />
failed.<br />
E002008 The Authentication <strong>Server</strong> protocol handler failed<br />
to initialize.<br />
E002009 The VM2 Compatibility protocol handler failed to<br />
initialize.<br />
E009001 An error occurred in the Virtual Digipass<br />
Message Delivery Component.<br />
E012001 The RADIUS Profile was not found in Steel-Belted<br />
RADIUS.<br />
E012002 The RADIUS Attribute was not known by Steel-<br />
Belted RADIUS.<br />
Description Notes<br />
Audit Messages<br />
initialization, eg. invalid configuration settings in the<br />
configuration file.<br />
The Replication library found the configuration of a<br />
Destination <strong>Server</strong> to be invalid. The library will still<br />
start up if its main configuration settings are valid and<br />
there is at least one valid Destination <strong>Server</strong>. For the<br />
invalid Destination <strong>Server</strong>s, this audit message is<br />
generated.<br />
The protocol handler that receives and processes<br />
administration requests and authentication requests<br />
from the IIS modules failed initialization. This is<br />
typically due to invalid configuration settings or<br />
because the API port is already in use by another<br />
process on the machine.<br />
The protocol handler that receives and processes<br />
authentication requests from the VACMAN Middleware<br />
version 2 IIS modules failed initialization. This is<br />
typically due to invalid configuration settings or<br />
because the API port is already in use by another<br />
process on the machine.<br />
The MDC encountered an error during the process of<br />
submitting a request to the HTTP gateway and<br />
interpreting the response. This may indicate a<br />
configuration problem for the gateway or connectivity<br />
issues. The audit message may contain further details<br />
from the gateway.<br />
When a RADIUS Profile name is in the Digipass User<br />
Account but that name is not found in SBR, the login<br />
is failed with this error.<br />
This can also occur if there is no RADIUS Profile in the<br />
Digipass User Account, but there is a Default RADIUS<br />
Profile configured that was not found in SBR.<br />
When the Digipass User Account has a RADIUS<br />
attribute in its Authorization Profiles/Attributes list,<br />
the attribute must be found in SBR. When such an<br />
attribute is not known to SBR, the login is failed with<br />
this error.<br />
The most likely reason for this error to occur is that<br />
the spelling of the attribute Name is different in SBR<br />
compared to the Digipass User account. This may also<br />
occur if the Value of the attribute does not convert to<br />
the correct data type expected by SBR. For example, if<br />
an IP address attribute has a Value which is not a<br />
representation of an IP address.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 267
Message<br />
Code<br />
E013001 A connection to an ODBC data source could not<br />
be established.<br />
Description Notes<br />
Audit Messages<br />
An attempt to connect to an ODBC data source failed.<br />
This may occur because:<br />
the database is unavailable for some reason such as<br />
rebooting<br />
the database is too busy temporarily to service the<br />
connection<br />
there are networking problems<br />
your credentials used in connecting to the database<br />
are invalid.<br />
E013002 A connection to an ODBC data source is broken. An established connection to an ODBC data source<br />
has broken. This may occur because:<br />
the database suddenly becomes unavailable for some<br />
reason such as rebooting<br />
the database becomes too busy temporarily to service<br />
the connection<br />
there are networking problems.<br />
W004001 A connection attempt to Active Directory failed. An attempt to connect to an Active Directory Domain<br />
Controller failed. This may occur because: the Domain<br />
Controller is unavailable for some reason such as<br />
rebooting; the Domain Controller is too busy<br />
temporarily to service the connection; or there are<br />
DNS or networking problems.<br />
W004004 A connection attempt to a Replication destination<br />
server failed.<br />
W005001 A connection to Active Directory has terminated<br />
due to an error.<br />
W005004 A connection to a Replication destination server<br />
has terminated due to an error.<br />
An attempt by the Replication library to connect to a<br />
Destination <strong>Server</strong> failed. This may occur because: the<br />
incorrect IP address or port is configured; the<br />
Destination <strong>Server</strong> is unavailable for some reason<br />
such as rebooting; or there are<br />
networking/connectivity problems such as an<br />
intermediate firewall blocking the port.<br />
An established connection to an Active Directory<br />
Domain Controller has broken. This may occur<br />
because: the Domain Controller suddenly becomes<br />
unavailable for some reason such as rebooting; the<br />
Domain Controller becomes too busy temporarily to<br />
service the connection; or there are DNS or<br />
networking problems.<br />
An established connection to a Destination <strong>Server</strong> has<br />
broken. This may occur because the Destination<br />
<strong>Server</strong> suddenly becomes unavailable for some reason<br />
such as rebooting, or because of a temporary<br />
networking or connectivity problem.<br />
W006001 An invalid RADIUS packet has been received. A RADIUS request received was invalid (did not<br />
conform to the RADIUS protocol). The request is<br />
discarded.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 268
Message<br />
Code<br />
W006002 A RADIUS request has been received from an<br />
unknown source.<br />
W006003 A request has been received from a RADIUS<br />
Client with no Shared Secret defined.<br />
W006004 A RADIUS request forwarded by this server has<br />
been received – there must be a circular proxy<br />
chain.<br />
W006005 An Access-Challenge received from the RADIUS<br />
<strong>Server</strong> cannot be handled.<br />
Description Notes<br />
Audit Messages<br />
This can also occur when a response is received from<br />
a RADIUS <strong>Server</strong> to which a request was forwarded, if<br />
the response was invalid. The response is discarded.<br />
A RADIUS request was received but there is no<br />
RADIUS Client Component for the source of the<br />
request, and there is no “default” RADIUS Client<br />
Component. The request is discarded.<br />
This audit message will be repeated at intervals when<br />
the same unknown source sends requests, but not for<br />
every request.<br />
A RADIUS request was received where there is a<br />
RADIUS Client Component for the source of the<br />
request, but that Component record does not have a<br />
Shared Secret defined. Therefore, it is not possible to<br />
handle the request and it is discarded.<br />
This will not occur if there is a “default” RADIUS Client<br />
Component that has a Shared Secret.<br />
This audit message will be repeated at intervals when<br />
the same source sends requests, but not for every<br />
request.<br />
This can occur when the <strong>Identikey</strong> <strong>Server</strong> forwards a<br />
request to a RADIUS <strong>Server</strong>, and the RADIUS <strong>Server</strong><br />
forwards the request back, due to its own proxy rules.<br />
It can also occur indirectly in a longer 'proxy chain'.<br />
The request is discarded, otherwise an infinite loop<br />
could be created.<br />
If this occurs, there must be an error in the proxy<br />
configuration of the RADIUS <strong>Server</strong>(s).<br />
This can occur when the <strong>Identikey</strong> <strong>Server</strong> forwards a<br />
request to a RADIUS <strong>Server</strong> and the RADIUS <strong>Server</strong><br />
responds with an Access-Challenge. An Access-<br />
Challenge can only be handled when the <strong>Identikey</strong><br />
<strong>Server</strong> forwards the password unmodified to the<br />
RADIUS <strong>Server</strong>. If the <strong>Identikey</strong> <strong>Server</strong> verifies an OTP<br />
and forwards the static password to the RADIUS<br />
<strong>Server</strong>, it is not possible to handle an Access-<br />
Challenge from the RADIUS <strong>Server</strong>.<br />
W006006 A RADIUS <strong>Server</strong> is not responding. The <strong>Identikey</strong> <strong>Server</strong> has not managed to get a<br />
response from the RADIUS <strong>Server</strong> for some time. This<br />
message indicates that there may be a problem with<br />
the RADIUS <strong>Server</strong>.<br />
W009001 Virtual Digipass One Time Password delivery<br />
failed.<br />
The MDC could not successfully deliver a text<br />
message via the HTTP gateway. The audit message<br />
should contain further details from the gateway.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 269
Message<br />
Code<br />
W010001 A blank password was used for Back-End<br />
Authentication, as Stored Password Proxy is<br />
disabled and the user did not enter a static<br />
password.<br />
W011001 A Backup Virtual Digipass quota of uses has<br />
been finished.<br />
W011002 No Digipass was found to assign to a new<br />
Digipass User Account for Auto-Assignment.<br />
Description Notes<br />
Audit Messages<br />
This message only occurs when the Back-End<br />
Authentication setting is Always.<br />
When Stored Password Proxy is disabled, the<br />
<strong>Identikey</strong> <strong>Server</strong> does not pass on the password<br />
stored in the Digipass User Account to Windows for<br />
Back-End Authentication. If a User does not enter their<br />
password as well as their OTP, the login will fail<br />
because their password has not been provided to<br />
Windows.<br />
BVDP Uses Remaining has just been decremented to<br />
0 for a Digipass. The User will not be able to use that<br />
Digipass for Backup Virtual Digipass logins until the<br />
Uses Remaining is increased or cleared.<br />
No available Digipass were found for Auto-<br />
Assignment. This may be because: there were no<br />
unassigned Digipass in the right location; the<br />
unassigned Digipass did not conform to Policy<br />
restrictions; the unassigned Digipass were Reserved<br />
for individual assignment.<br />
The location in which the <strong>Identikey</strong> <strong>Server</strong> searches for<br />
available Digipass records can be controlled to some<br />
extent using the Search Upwards in Org. Unit<br />
hierarchy setting.<br />
W011003 A Digipass User Account has become locked. A User just exceeded the User Lock Threshold of<br />
failed logins and their Digipass User Account is now<br />
Locked. <strong>Administrator</strong> action is required to unlock the<br />
account.<br />
W012002 A Replication update received has been ignored,<br />
as the local data is more up-to-date.<br />
The Authentication <strong>Server</strong> has received a data update<br />
from another Authentication <strong>Server</strong> via the Replication<br />
process, but its local data is already newer than the<br />
data received via Replication.<br />
It is normal that this can occur, but it can also indicate<br />
a potential synchronization issue.<br />
W012003 A Replication queue entry has not been inserted. This can occur when a replication queue has reached<br />
its maximum size. This is most likely to occur when<br />
the destination server is down or cannot be contacted<br />
due to a networking problem.<br />
W013001 An invalid request has been received by the<br />
Authentication <strong>Server</strong>.<br />
W013002 A request has been received by the<br />
Authentication <strong>Server</strong> from an unknown source.<br />
The Authentication <strong>Server</strong> has received an invalid<br />
authentication, administration or Replication request.<br />
The Authentication <strong>Server</strong> has received an<br />
authentication, administration or Replication request<br />
from an unknown or unauthorized source. If the<br />
request was from a valid source, this message<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 270
Message<br />
Code<br />
Description Notes<br />
Audit Messages<br />
indicates that a Component record is missing (or that<br />
a required restart of the Service has not been made<br />
since the creation of the necessary Component<br />
record).<br />
W014001 The License Key is missing or invalid. A valid, unexpired license key is required to process<br />
any kind of authentication request. This message will<br />
be generated periodically when authentication<br />
requests are received by the Authentication <strong>Server</strong>,<br />
when it does not have a valid License Key.<br />
I001001 The Digipass Plug-In has started up successfully. Configuration details are given in the audit message.<br />
I001002 The Authentication <strong>Server</strong> has started up<br />
successfully.<br />
I002001 The Active Directory AAL3 library has been<br />
initialized successfully.<br />
I002002 The Digipass Authentication library has been<br />
initialized successfully.<br />
I002004 The RADIUS protocol handler has been initialized<br />
successfully.<br />
I002006 The Replication library has been initialized<br />
successfully.<br />
I002007 Initialization of a Replication destination server<br />
succeeded.<br />
I002008 The Authentication <strong>Server</strong> protocol handler has<br />
been initialized successfully.<br />
I002009 The VM2 Compatibility protocol handler has been<br />
initialized successfully.<br />
I003001 The Digipass Plug-In has shut down.<br />
I003002 The Authentication <strong>Server</strong> has shut down.<br />
I004001 A connection attempt to Active Directory was<br />
successful.<br />
I004004 A connection attempt to a Replication destination<br />
Configuration details are given in the audit message.<br />
Note that the Authentication <strong>Server</strong> can start up<br />
successfully even if a component such as the RADIUS<br />
protocol handler does not start up successfully.<br />
The Active Directory 'AAL3' library has completed<br />
initialization. Configuration details are given in the<br />
audit message.<br />
The 'Authentication' library has completed<br />
initialization. Configuration details are given in the<br />
audit message.<br />
The protocol handler that receives and processes<br />
RADIUS requests started up. Configuration details are<br />
given in the audit message.<br />
The Replication library was initialized successfully.<br />
Configuration details are given in the audit message.<br />
The Replication library initialized a Destination <strong>Server</strong><br />
successfully. Configuration details are given in the<br />
audit message.<br />
The protocol handler that receives and processes<br />
administration requests and authentication requests<br />
from the IIS modules was initialized successfully.<br />
Configuration details are given in the audit message.<br />
The protocol handler that receives and processes<br />
authentication requests from the VACMAN Middleware<br />
version 2 IIS modules was initialized successfully.<br />
Configuration details are given in the audit message.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 271
Message<br />
Code<br />
server was successful.<br />
I005001 A connection to Active Directory has been<br />
terminated normally.<br />
I005002 A connection to Active Directory has been timed<br />
out for load-balancing.<br />
I005004 A connection to a Replication destination server<br />
has been terminated normally.<br />
Description Notes<br />
Audit Messages<br />
An established connection to an Active Directory<br />
Domain Controller has ended with a normal<br />
disconnection.<br />
An established connection to an Active Directory<br />
Domain Controller has been ended for load-balancing<br />
purposes. Periodically the connections will be dropped<br />
and new ones established, in case there is a less busy<br />
Domain Controller available. The time period is<br />
defined by the configuration setting Max-Bind-<br />
LifeTime in the file, in minutes.<br />
An established connection to a Replication Destination<br />
<strong>Server</strong> has ended with a normal disconnection.<br />
I006001 A RADIUS Access-Request has been received. The <strong>Identikey</strong> <strong>Server</strong> has received an Access-Request.<br />
The audit message will indicate what action will be<br />
taken as well as key details of the request.<br />
I006002 A RADIUS Accounting-Request has been<br />
received.<br />
The <strong>Identikey</strong> <strong>Server</strong> has received an Accounting-<br />
Request. The audit message will indicate what action<br />
will be taken as well as key details of the request.<br />
I006003 A RADIUS <strong>Server</strong> has started responding again. After the <strong>Identikey</strong> <strong>Server</strong> had not managed to get a<br />
response from the RADIUS <strong>Server</strong> for some time, this<br />
message indicates that it is responding again.<br />
I007001 A RADIUS Access-Accept has been issued. The <strong>Identikey</strong> <strong>Server</strong> has accepted an Access-<br />
Request. Note however that it is still possible that after<br />
the <strong>Identikey</strong> <strong>Server</strong> has accepted the request,<br />
another component of the overall process may still<br />
decide to reject the request ultimately.<br />
I007002 A RADIUS Access-Challenge has been issued. The <strong>Identikey</strong> <strong>Server</strong> has issued a challenge, either<br />
Challenge/Response or Virtual Digipass.<br />
I007003 A RADIUS Access-Reject has been issued. The <strong>Identikey</strong> <strong>Server</strong> has rejected an Access-Request.<br />
I007004 A RADIUS Accounting-Response has been<br />
issued.<br />
I008001 A Digipass has been moved for assignment to a<br />
user.<br />
I008002 A user-to-user link has been removed due to<br />
assignment of a Digipass.<br />
The <strong>Identikey</strong> <strong>Server</strong> has acknowledged an<br />
Accounting-Request. Note however that unless the<br />
request is forwarded to a RADIUS <strong>Server</strong>, no<br />
processing is carried out by the <strong>Identikey</strong> <strong>Server</strong>.<br />
Upon assignment of a Digipass to a User, if the<br />
Digipass is not already in the same location<br />
(Organizational Unit) as the User, it is moved to that<br />
location.<br />
If a Digipass User Account is linked to another in order<br />
to share the Digipass, it must not have a Digipass<br />
assigned itself. If a Digipass is assigned, the link will<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 272
Message<br />
Code<br />
I009001 A Virtual Digipass One Time Password has been<br />
delivered.<br />
Description Notes<br />
be broken.<br />
Audit Messages<br />
The MDC successfully delivered a text message via<br />
the HTTP gateway, as reported by the gateway. The<br />
audit message may contain further details from the<br />
gateway.<br />
Note that depending on the gateway, it may still be<br />
possible for delivery to fail after the gateway has<br />
reported success.<br />
I010001 User authentication was not handled. The <strong>Identikey</strong> <strong>Server</strong> decided not to handle an<br />
authentication request due to Policy and/or Digipass<br />
User Account settings. The main reasons why this<br />
may occur are: the effective Local Authentication and<br />
Back-End Authentication settings were both None;<br />
the User failed the Windows Group Check, using the<br />
Pass requests for users not in listed groups back to<br />
host system option.<br />
Note that the 'effective' settings are the effective<br />
settings of the Policy, unless the Digipass User<br />
Account overrides the Policy.<br />
I010002 A stored password change was unhandled. The <strong>Identikey</strong> <strong>Server</strong> decided not to handle a<br />
password change request due to Policy and/or<br />
Digipass User Account settings. The main reasons<br />
why this may occur are: the effective Local<br />
Authentication and Back-End Authentication settings<br />
were both None; the User failed the Windows Group<br />
Check, using the Pass requests for users not in listed<br />
groups back to host system option.<br />
Note that the 'effective' settings are the effective<br />
settings of the Policy, unless the Digipass User<br />
Account overrides the Policy.<br />
I011001 A Digipass Grace Period has been ended by the<br />
use of a One Time Password.<br />
I011002 A Backup Virtual Digipass expiration date has<br />
been set due to the first request for a Virtual One<br />
Time Password.<br />
I011003 A Backup Virtual Digipass time limit has been<br />
expired by the use of the normal One Time<br />
Password.<br />
The first time that an assigned Digipass is used<br />
successfully to log in, if a Grace Period is still active, it<br />
is ended immediately. They must continue to use their<br />
Digipass to log in after that point.<br />
A User has requested a Backup Virtual Digipass OTP<br />
for the first time, when the effective Backup VDP<br />
Enabled setting is Yes – Time Limited and they did<br />
not already have an Enabled Until date set on their<br />
Digipass. At this time, they are given the Time Limit<br />
from the Policy by adding it to the current date.<br />
A User who has been using Backup Virtual Digipass<br />
has used their normal OTP login using the Digipass<br />
again. When the effective Backup VDP Enabled<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 273
Message<br />
Code<br />
I011004 A Backup Virtual Digipass quota of uses has<br />
been set due to the first request for a Virtual One<br />
Time Password.<br />
I011005 A Digipass User Account has been created using<br />
Dynamic User Registration.<br />
I011006 A new static password has been stored using<br />
Password Autolearn.<br />
I011007 A Digipass has been assigned to a new Digipass<br />
User Account using Auto-Assignment.<br />
I011008 A Digipass has been assigned to a Digipass User<br />
Account using Self-Assignment.<br />
I011009 A Digipass challenge has been issued for a Self-<br />
Assignment attempt.<br />
Description Notes<br />
Audit Messages<br />
setting is Yes – Time Limited, using the normal OTP<br />
login ends their time limit immediately. This is done by<br />
setting the Enabled Until date on their Digipass to the<br />
current date.<br />
An administrator action is required to reset their<br />
Enabled Until date, if the User is to be allowed to use<br />
Backup Virtual Digipass again.<br />
A User has requested a Backup Virtual Digipass OTP<br />
for the first time, when the effective Backup VDP<br />
Max. Uses/User setting is greater than 0 and they did<br />
not already have a Uses Remaining date set on their<br />
Digipass. At this time, they are given the Max.<br />
Uses/User limit from the Policy.<br />
A Digipass User Account has been created<br />
automatically upon successful Back-End<br />
Authentication. This occurs when the Dynamic User<br />
Registration feature is enabled.<br />
A new static password has been stored in the<br />
Digipass User Account after successful Back-End<br />
Authentication. This occurs when the Password<br />
Autolearn feature is enabled.<br />
Upon creation of a new Digipass User Account<br />
through Dynamic User Registration, an available<br />
Digipass has been assigned to the new account<br />
automatically. This occurs when the Auto-Assignment<br />
feature is enabled.<br />
A User has successfully assigned a Digipass to<br />
themselves using the Self-Assignment feature.<br />
A User has obtained a challenge during an attempt to<br />
assign a Digipass to themselves using the Self-<br />
Assignment feature. In order to complete the<br />
assignment, they must provide the correct response to<br />
the challenge from the Digipass.<br />
I011010 A user has changed their Digipass PIN. A User has changed their <strong>Server</strong> PIN during their<br />
login, or set it up on first use or after a PIN reset.<br />
I011011 Successfully assigned Digipass The Digipass has been successfully assigned during<br />
Software Digipass Provisioning.<br />
I011012 Added new Digipass for Web activation location A new Digipass has been added for a Web activation<br />
location during Software Digipass Provisioning.<br />
I011013 Static Password Update Successful The static password for the User has been<br />
successfully changed.<br />
I013001 A connection to an ODBC data source has been<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 274
Message<br />
Code<br />
made successfully.<br />
I013002 A connection to an ODBC data source has been<br />
terminated normally.<br />
S001001 A query for a single [object] record was<br />
successful.<br />
Description Notes<br />
Audit Messages<br />
An established connection to an ODBC data source<br />
has ended with a normal disconnection.<br />
The <strong>Identikey</strong> <strong>Server</strong> or an administrator has made a<br />
successful query to the data store for a single record.<br />
In the case of the <strong>Identikey</strong> <strong>Server</strong> this may be a<br />
search for its Component record; for an administrator<br />
it could be any single record query. The audit<br />
message has details of the record found.<br />
S001002 A query for [object] records was successful. The <strong>Identikey</strong> <strong>Server</strong> or an administrator has made a<br />
successful query to the data store for some records.<br />
In the case of the <strong>Identikey</strong> <strong>Server</strong> this may be a<br />
search for a RADIUS Client Component record; for an<br />
administrator it could be any list query. The audit<br />
message has details of the records found but this may<br />
be truncated.<br />
S001003 A command of type [object] [command] was<br />
successful.<br />
An administrator has issued a successful data<br />
modification command such as an update of settings<br />
or one of the Digipass Application operations like<br />
Reset PIN. The audit message has details of the<br />
command and results.<br />
S002001 User authentication was successful. The 'Authentication' library has passed authentication<br />
for a request. Note however that the <strong>Identikey</strong> <strong>Server</strong><br />
or another component of the overall process may still<br />
decide to reject the request ultimately.<br />
S002002 User authentication issued a challenge. The 'Authentication' library has issued a challenge for<br />
an authentication request, either Challenge/Response<br />
or Virtual Digipass.<br />
S002004 A stored password change was successful. The Authentication <strong>Server</strong> has successfully processed<br />
a password change request.<br />
S003001 A Replication update was sent successfully. This message is audited at the source server, when a<br />
database change is sent to a destination server and<br />
processed successfully.<br />
S003002 A Replication update received has been<br />
processed successfully.<br />
This message is audited at the destination server,<br />
when a database change is received and processed<br />
successfully.<br />
S004001 An administrative logon was successful. An administrative logon to the Authentication <strong>Server</strong><br />
was successful.<br />
S004002 A Live Audit connection was successful. A Live Audit connection to the Authentication <strong>Server</strong><br />
was successful.<br />
S005001 Registration Successful The registration of a Software Digipass during<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 275
Message<br />
Code<br />
Description Notes<br />
Provisioning was successful.<br />
Audit Messages<br />
S005002 Activation Successful The activation of a software Digipass during Software<br />
Digipass Provisioning was successful.<br />
S006001 Signature Validation Successful. When signing a transaction using the Signature<br />
Verification function, the signature validation was<br />
successful.<br />
F001001 A query for a single [object] record failed. The <strong>Identikey</strong> <strong>Server</strong> or an administrator has made an<br />
unsuccessful query to the data store for a single<br />
record. In the case of the <strong>Identikey</strong> <strong>Server</strong> this may be<br />
a search for its Component record; for an<br />
administrator it could be any single record query. The<br />
audit message has basic details of the failure, but<br />
there should be a preceding E000001 with more<br />
details.<br />
F001002 A query for [object] records failed. The <strong>Identikey</strong> <strong>Server</strong> or an administrator has made an<br />
unsuccessful query to the data store for some<br />
records. In the case of the <strong>Identikey</strong> <strong>Server</strong> this may<br />
be a search for a RADIUS Client Component record;<br />
for an administrator it could be any list query. The<br />
audit message has basic details of the failure, but<br />
there should be a preceding E000001 with more<br />
details.<br />
F001003 A command of type [object] [command] failed. An administrator has issued an unsuccessful data<br />
modification command such as an update of settings<br />
or one of the Digipass Application operations like<br />
Reset PIN. The audit message has basic details of the<br />
failure, and there may be a preceding E000001 with<br />
more details.<br />
F002001 User authentication failed. The 'Authentication' library has failed authentication<br />
for a request. The audit message has details of the<br />
failure (see 20 Error and Status Codes) and there may<br />
be a preceding E000001 with error details.<br />
F002003 A stored password change failed. The Authentication <strong>Server</strong> has not processed a<br />
password change request. The audit message has<br />
details of the failure (see 20 Error and Status<br />
Codes) and there may be a preceding E000001 with<br />
error details.<br />
F003001 Sending a Replication update was unsuccessful. This message is audited at the source server, when a<br />
database change is not sent to a destination server<br />
successfully, or it was sent but the processing at the<br />
destination was unsuccessful.<br />
F003002 Processing a Replication update received was This message is audited at the destination server,<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 276
Message<br />
Code<br />
Description Notes<br />
Audit Messages<br />
unsuccessful. when a database change is received but is not<br />
processed successfully.<br />
F004001 An administrative logon was rejected. The 'Authentication' library has failed an<br />
administrative login request. The audit message has<br />
details of the failure (see 20 Error and Status<br />
Codes) and there may be a preceding E000001 with<br />
error details.<br />
Note that this may occur even when preceded by a<br />
successful authentication (S002001) message, for<br />
example if the user's credentials were OK but they did<br />
not have Administrative Logon privilege.<br />
F004002 A Live Audit connection was rejected. The 'Authentication' library has failed a Live Audit<br />
connection request. The audit message has details of<br />
the failure (see 20 Error and Status Codes)<br />
and<br />
there may be a preceding E000001 with error details.<br />
Note that this may occur even when preceded by a<br />
successful authentication (S002001) message, for<br />
example if the user's credentials were OK but they did<br />
not have Administrative Logon or Live Audit<br />
Connection privilege.<br />
F005001 Static Password verification failed During Software Digipass Provisioning the static<br />
password for the User was not verified.<br />
F005001 Backend Authentication failed During Software Digipass Provisioning, the back-end<br />
authentication for the User failed.<br />
F005001 Digipass assignment failed Assignment of the digipass failed during Software<br />
Digipass Provisioning.<br />
F005001 Reactivation not allowed. The specified Software Digipass may not be<br />
reactivated. The number of reactivations for Software<br />
Digipass is limited. The limit may have been<br />
exceeded.<br />
F005002 Multiple Digipass found where a single Digipass<br />
was required<br />
During Software Digipass Provisioning more than one<br />
Digipass was found that fulfilled the criteria specified.<br />
F005002 OTP verification Failed The One Time Password generated from the Digipass<br />
used in the Provisioning process has not passed<br />
validation.<br />
F006001 Signature Verification failed. When attempting to sign a transaction using an<br />
electronic Signature, the signature did not pass the<br />
verification phase. The transaction will not be signed.<br />
F006001 Multiple Digipass found where a single Digipass<br />
was required.<br />
When using the Signature function, <strong>Identikey</strong> <strong>Server</strong><br />
found more than one Digipass record assigned to the<br />
user.<br />
F006001 Required request input fields missing The Signature function requires up to eight input<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 277
Message<br />
Code<br />
Description Notes<br />
Audit Messages<br />
fields. The input fields are defined when the<br />
Signature function is set up. One or more of those<br />
input fields was missing in this transation.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 278
20 Error and Status Codes<br />
This section lists the standard error and status codes with the associated messages.<br />
20.1 Error Code Listing<br />
Table 77: Error Code List<br />
Error Code Message Notes<br />
0 (No error)<br />
Error and Status Codes<br />
-1 An unspecified error occurred This error code may occur when a more specific error code<br />
is not available or was recorded separately.<br />
-2 The parameters supplied were invalid Parameters supplied to a function or command were<br />
invalid.<br />
-3 A memory error occurred Memory allocation failed. This is normally due to the system<br />
running low on memory.<br />
-10 A communications error occurred Inter-process or inter-component communication failed.<br />
This may also occur with communications to Active<br />
Directory or a database. This error is normally accompanied<br />
by further details.<br />
-11 A license error has occurred General-purpose license failure when a more specific code<br />
is not available or was recorded separately.<br />
-12 An operating system call failed A system call failed. This may include file handling, Active<br />
Directory Services Interface and other calls. It is normally<br />
accompanied by further details.<br />
-13 The object was not found An attempt was made to perform an operation on an object,<br />
such as an Active Directory object, but the object did not<br />
exist. For example, this may occur when one administrator<br />
deletes a record that another administrator is about to<br />
update, when the update operation is attempted.<br />
-14 The object already exists An attempt was made to create an object, such as an<br />
Active Directory object, but the object already exists. For<br />
example, this may occur when two administrators try to<br />
create the same record at the same time.<br />
-15 The supplied buffer was of the incorrect size An internal data buffer was of insufficient length to hold the<br />
data required.<br />
-16 A version error has occurred A version mismatch has occurred. Further details in the<br />
error record will indicate what versions were mismatched.<br />
-17 The supplied data are invalid General-purpose error when input data to an operation is<br />
incorrect. Further details of the error will be recorded.<br />
-18 The object is invalid An attempt was made to perform an operation upon an<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 279
Error Code Message Notes<br />
object type that was not recognized.<br />
Error and Status Codes<br />
-19 The command is invalid An attempt was made to perform an operation using a<br />
command that was not recognized.<br />
-20 The object is in use An attempt was made to delete an object, such as an<br />
Active Directory object, but that object was in use.<br />
This may occur when you try to delete a Policy, but another<br />
Policy inherits from the one you are deleting, or a<br />
Component uses the Policy.<br />
-21 The operation is not supported General-purpose error when an operation is attempted on<br />
an object that does not support it. For example, an attempt<br />
is made to generate a Virtual Digipass OTP using a Digipass<br />
that is not enabled for Virtual Digipass.<br />
-22 An object error has occurred General-purpose error on an operation on an object. This<br />
should be supplemented with more specific details.<br />
-23 A required field was missing An operation was attempted without specifying one or more<br />
mandatory input fields.<br />
-24 Auditing failed An operation failed because auditing was mandatory, but<br />
failed.<br />
-30 The configuration is invalid The configuration data in the configuration file are invalid.<br />
The error record should indicate which specific data were<br />
invalid.<br />
-31 A type mismatch has occurred General-purpose error when one datatype is expected but a<br />
different datatype was provided.<br />
-32 One or more objects were not initialized Internal initialization error. More specific error details will be<br />
recorded.<br />
-33 The cache is full An attempt was made to add an entry to a cache, but the<br />
cache has reached its configured maximum size.<br />
-34 The cache entry has reached the maximum<br />
reference count<br />
-35 The system is currently too busy to service the<br />
request<br />
An attempt was made to retrieve an item from a cache, but<br />
the item was already in use and the configuration indicates<br />
a limit on the number of times an item can be retrieved<br />
from the cache at one time.<br />
The system received a new request for processing, but hit a<br />
resource usage limit of some type. This indicates that the<br />
system is too loaded to handle the request. For example,<br />
there may be no spare database connection to use, even<br />
after waiting a short time for one to become available.<br />
-80 A timeout has occurred An operation failed because of a timeout.<br />
-100 An invalid plugin was supplied Audit configuration specifies a plugin method that is<br />
unknown or that could not be successfully loaded.<br />
-101 There is no space left to write the message While auditing to text file, the server was unable to write.<br />
This would normally occur if disk space has run out.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 280
Error Code Message Notes<br />
Error and Status Codes<br />
-140 A Digipass error has occurred General-purpose failure of a Digipass operation such as<br />
OTP verification, Reset PIN, Unlock, etc. This is normally<br />
accompanied by a more specific error code and message<br />
from the VACMAN Controller library.<br />
-150 Delivery of the Virtual Digipass One-Time<br />
Password failed<br />
A Virtual Digipass OTP was generated successfully, but<br />
delivery by text message failed. A separate message will<br />
give more details about the failure.<br />
-200 The license has expired The License Key has an expiration date set, and the date<br />
has passed. A permanent License Key must be obtained.<br />
-201 The license data are invalid One of the details embedded into the License Key is invalid<br />
for the Component in which it is being loaded. The<br />
Component will not be able to use the License Key. This<br />
may be IP address, Component Type, or any other detail<br />
that can be seen in the License Key text.<br />
-202 The License Key is corrupted The signature at the bottom of the License Key is invalid.<br />
This would typically occur if the License Key details were<br />
modified in any way.<br />
-250 Decryption has failed - no Storage Key is<br />
specified in the Encryption Settings<br />
-251 Decryption has failed - an incorrect Cipher is<br />
specified in the Encryption Settings<br />
-252 Decryption has failed - an incorrect Storage<br />
Key is specified in the Encryption Settings<br />
Some encrypted data has been created or modified using<br />
configured, rather than default, encryption settings. This<br />
error occurs when that data is read by a component that<br />
does not have configured encryption settings – the<br />
component is therefore unable to decrypt the data.<br />
It is necessary to configure the encryption settings in the<br />
component. See 4 Sensitive Data Encryption for more<br />
information on encryption settings.<br />
Some encrypted data has been created or modified using<br />
differently configured encryption settings. This error occurs<br />
when that data is read by a component with configured<br />
encryption settings that use a different Cipher Name – the<br />
component is therefore unable to decrypt the data.<br />
It is necessary to make sure that the encryption settings in<br />
all components are identical. See 4 Sensitive Data<br />
Encryption for more information.<br />
Some encrypted data has been created or modified using<br />
differently configured encryption settings. This error occurs<br />
when that data is read by a component with configured<br />
encryption settings that use a different Storage Key – the<br />
component is therefore unable to decrypt the data.<br />
It is necessary to make sure that the encryption settings in<br />
all components are identical. See 4 Sensitive Data<br />
Encryption for more information.<br />
-300 A database error occurred General-purpose error on a database operation. This should<br />
be supplemented with more specific details.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 281
Error Code Message Notes<br />
Error and Status Codes<br />
-350 The request received was discarded A replication update that was received was found to be<br />
superseded by a later change. In this case, the update is<br />
discarded, as it is no longer relevant.<br />
This may occur when creating a record, after a record has<br />
been deleted then re-created.<br />
It may occur when modifying a record, if a later<br />
modification occurred before replication could apply the first<br />
change.<br />
-351 The request received must be retried A replication update that was received could not be applied<br />
immediately. In this case, the update is rejected. The retry<br />
mechanism at the source server will re-send the update,<br />
according to its configuration settings.<br />
This may occur if a record does not exist yet, when trying to<br />
apply a modification or deletion.<br />
It may occur after a record has been deleted and recreated,<br />
when a modification of the record is replicated but<br />
the sequence of deletion and re-creation has not been<br />
followed in the correct order.<br />
-352 A replication queue entry had an invalid hash<br />
value<br />
When an entry was read from the replication queue before<br />
sending, its integrity hash value check failed. This suggests<br />
that the queue entry may have been modified since it was<br />
added to the queue. In this case, the queue entry is not<br />
trusted and an error is reported.<br />
-353 The replication queue is full An operation failed because it needed to update the<br />
database, but the update could not be added to the<br />
Replication queue. If the queue is full, no database updates<br />
are allowed, to avoid the databases getting too far out of<br />
synchronization.<br />
Check the Replication Status dialog in the Administration<br />
MMC Interface and the Replication audit messages to<br />
investigate why the queue has become full. It is necessary<br />
to reduce the queue size in order for the system to continue<br />
to function.<br />
If this error occurs often, without good reason, consider<br />
increasing the maximum queue size. This can be<br />
configured in the Replication tab of the Authentication<br />
<strong>Server</strong> Configuration GUI.<br />
-500 The Service was already started When trying to start a Service, the Service was already<br />
running.<br />
-501 The Service was already stopped When trying to stop a Service, the Service was not running.<br />
-10051 File name is blank. No file name was specified.<br />
-10052 Failed to open File. The file could not be opened. The file does not exist or the<br />
user attempting to open the file does not have read<br />
permission for the file.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 282
Error Code Message Notes<br />
Error and Status Codes<br />
-10057 User ID is longer than 255 characters. The maximum User ID length has been exceeded.<br />
-10059 Password is longer than 255 characters. The maximum Password length has been exceeded.<br />
-10060 User Name is longer than 64 characters. The maximum User Name length has been exceeded.<br />
-10061 Serial Number is longer than 10 characters. The maximum Serial Number length has been exceeded.<br />
Serial Number must be 10 characters, with no dashes (-)<br />
and with leading zeros (0) to make it up to 10 characters.<br />
-10062 Serial Number is less than 10 characters long. The minimum Serial Number length has not been provided.<br />
Serial Number must be 10 characters, with no dashes (-)<br />
and with leading zeros (0) to make it up to 10 characters.<br />
-10063 Serial Number contains non-alphanumeric<br />
characters.<br />
-10064 Organizational Unit is longer than 255<br />
characters.<br />
The Serial Number contains non-alphanumeric characters.<br />
Serial Number must be 10 alphanumeric characters, with<br />
no dashes (-).<br />
The maximum Organizational Unit length has been<br />
exceeded.<br />
-10065 Domain is longer than 255 characters. The maximum Domain length has been exceeded.<br />
-10066 Distinguished Name is longer than 1024<br />
characters.<br />
The maximum LDAP Distinguished Name (DN) length has<br />
been exceeded.<br />
-10067 Mobile Number is longer than 64 characters. The maximum Mobile Phone length has been exceeded.<br />
-10069 A syntax error occurred reading from the file. A syntax error occurred while reading lines from the import<br />
file: double-quotes were missing; there are too many fields<br />
in the line; a comma is missing between fields.<br />
-10070 The file contains characters that are not UTF-8<br />
encoded.<br />
The import file must be fully UTF-8 encoded when extended<br />
or Unicode characters are included. This message indicates<br />
that non-UTF-8 characters were found in the file.<br />
-10072 Phone Number is longer than 64 characters. The maximum Phone Number length has been exceeded.<br />
-10073 Email Address is longer than 64 characters. The maximum Email Address length has been exceeded.<br />
-10074 No User ID was given. Either the User ID or, for<br />
Active Directory, the Dishinguished Name is<br />
needed to import a user.<br />
-10075 The Mobile No. is invalid. Only numbers,<br />
spaces, dashes (-) and brackets are allowed<br />
with a + at the start to indicate a country code<br />
if needed.<br />
-10076 The Phone No. is invalid. Only numbers,<br />
spaces, dashes (-) and brackets are allowed<br />
with a + at the start to indicate a country code<br />
if needed.<br />
-10077 The specified email address contains invalid<br />
characters and is not in the form<br />
user@domain.<br />
A User ID must be supplied to import a user. The only<br />
exception is when using Active Directory, it is sufficient to<br />
give the Distinguished Name instead of the User ID.<br />
The Mobile Number is only allowed to include numeric<br />
characters, spaces, dashes(-) and brackets (){}[]. In addition<br />
a + is allowed at the start for the country code.<br />
The Phone Number is only allowed to include numeric<br />
characters, spaces, dashes(-) and brackets (){}[]. In addition<br />
a + is allowed at the start for the country code.<br />
The Email Address is only allowed to include alphanumeric<br />
characters, @, dots (.), underscores (_) and dashes (-).<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 283
Error Code Message Notes<br />
-10078 The Field Header was not found or invalid<br />
when reading from the file.<br />
Error and Status Codes<br />
The first line of an import file must be a header line. The<br />
header line is a comma-separated list of field names,<br />
indicating which fields are included in every other line of the<br />
file.<br />
This message indicates that the header line was not found,<br />
that it included unknown field names or that it was not a<br />
comma-separated list of field names.<br />
See the Import User Records topic in the online Help for<br />
the Administration MMC Interface for a definition of the<br />
import file header format.<br />
-400 There was no comms descriptor available The comms descriptor map has not been loaded. (support)<br />
-401 The supplied address could not be resolved name resolution, i.e. DNS, netbios etc<br />
-402 A socket error occurred. Descriptor should be<br />
closed<br />
(communication protocol mismatch<br />
-403 Descriptor was in the wrong state e.g. trying to bind the socket twice<br />
-404 The maximum number of open descriptors has<br />
been reached<br />
-405 The connection has been closed by the remote<br />
end<br />
-406 The command would block, use 'select' should not be seen as a runtime error<br />
-407 The command is in progress, use 'select' should not be seen as a runtime error<br />
-408 The comms descriptor is not valid e.g. the socket has not been created<br />
-450 The key received was invalid The encryption key is somehow invalid<br />
-550 The config file/registry data could not be read This error may be returned when a corrupt config file is<br />
used<br />
-600 One of the RADIUS attributes was invalid RADIUS attribute field layout is invalid<br />
-601 The action will result in a size limitation being<br />
exceeded<br />
A buffer overflow would occur, this is only used within the<br />
RADIUS library<br />
-602 An invalid dictionary file was used this does not appear to be returned anywhere<br />
-650 Initialisation of lock failed<br />
-700 Failed to open handle Normally occurs when a file cannot be opened<br />
-800 An invalid length was supplied looks like this error is currently only used in the case where<br />
a programming error has occurred, resulting in an incorrect<br />
length parameter being passed to the mschap function<br />
"CreateVSAttribute"<br />
-801 Memory allocation failed This appears to only be used by the "demotoken" code<br />
-802 Password was blank Can occur when attempting to verify a MSCHAP/MSCHAP2<br />
password when the subsequently hashed password<br />
provided by the used is equivlent to hashing a blank string,<br />
i.e. the provided password is blank<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 284
Error Code Message Notes<br />
Error and Status Codes<br />
-803 Password was invalid Occurs within MSCHAP/MSCHAP2 password verification<br />
when the provided password is incorrect and it is not a<br />
blank string<br />
-1001 The packet is from an unknown source A client component does not exist for the client who sent<br />
the packet<br />
-1002 The shared secret of the packet's source is<br />
unknown<br />
There is no shared secret within the client component for<br />
the peer which sent this packet<br />
-1003 Incorrect response authenticator The response packet returned from the RADIUS server<br />
bears an incorrect authenticator<br />
-1004 The Message-Authenticator attribute was not<br />
correct<br />
The message-authenticator appears to only be checked in a<br />
response<br />
-1005 The packet is not from the address sent to The response from the backend does not match the source<br />
address to which the request was sent<br />
20.2 Status Code Listing<br />
Table 78: Status Code List<br />
Status Code Message Notes<br />
0 No error<br />
<br />
The status codes from -1 downwards match the Error<br />
Codes above.<br />
1000 The credentials were invalid General-purpose failure due to invalid username or<br />
password, when a more specific status is unavailable.<br />
1002 The user failed the Windows Group Check The <strong>Identikey</strong> <strong>Server</strong> rejected an authentication<br />
request due to the Windows Group Check failing.<br />
This can occur when the effective Windows Group<br />
Check option is Authenticate listed groups, reject<br />
others.<br />
Note that the 'effective' setting is the effective setting<br />
of the Policy, unless the Digipass User Account<br />
overrides the Policy.<br />
1004 The challenge has expired A response to challenge has been given, but the<br />
expiration time for the challenge has expired. The<br />
default expiration time is one minute, however this<br />
can be configured in the configuration file<br />
VASCO/AAL3/Authlib/Challenge-Cache/Max-Age<br />
setting (in seconds).<br />
1005 The user does not have permission to perform General-purpose failure of an administration<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 285
Status Code Message Notes<br />
Error and Status Codes<br />
the specified action command when the administrator does not have<br />
sufficient privileges to carry out the command.<br />
1007 The user account is locked The Digipass User Account is Locked. This is normally<br />
due to consecutive login failures, as determined by<br />
the Policy setting User Lock Threshold. Alternatively<br />
the administrator can actively lock the account.<br />
To unlock the User account, an administrator has to<br />
uncheck the Locked checkbox on the User record.<br />
1008 The One Time Password has already been used This status code occurs specifically when an OTP is<br />
rejected because it has already been used. It may also<br />
occur when the OTP has not been used but is older<br />
than the most recently used OTP.<br />
This can sometimes happen when an authentication<br />
request is re-sent automatically.<br />
1009 The user account is disabled The Digipass User Account is Disabled. This may be<br />
because the administrator has actively disabled the<br />
account, or because the corresponding Windows User<br />
account has become disabled or expired.<br />
1010 No user account was found An authentication request was rejected because no<br />
Digipass User account was found and Local<br />
Authentication is required by the Policy.<br />
1011 The static password was incorrect As part of Local Authentication, verification of the<br />
static password failed.<br />
1012 The One Time Password was incorrect Verification of the OTP failed. More specific details<br />
may be found in the VACMAN Controller error code<br />
and message.<br />
1013 The challenge was invalid A response to a challenge was given, but the<br />
challenge was not the latest one issued for that<br />
Digipass. This is controlled by the Check Challenge<br />
Policy setting.<br />
1014 The Digipass Grace Period has expired A User attempted to log in with their static password,<br />
but their Grace Period had already expired. They have<br />
to use a Digipass to log in.<br />
If they do not have their Digipass yet, the<br />
administrator will have to allow them more time by<br />
modifying the Grace Period End date on their<br />
Digipass record.<br />
1015 Backup Virtual Digipass is not allowed A User attempted to request a Backup Virtual Digipass<br />
OTP, but they were not permitted. This would normally<br />
occur when either:<br />
The effective Backup VDP Enabled setting is Yes –<br />
Time Limited, and the Digipass Backup VDP Enabled<br />
Until date is the current date or before.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 286
Status Code Message Notes<br />
Error and Status Codes<br />
The Digipass Backup VDP Uses Remaining counter<br />
has reached 0.<br />
In both cases, administrator intervention is required to<br />
permit the User to continue to use Backup Virtual<br />
Digipass. The Enabled Until or Uses Remaining limits<br />
need to be increased to permit this.<br />
Note that the 'effective' setting is the effective setting<br />
of the Policy, unless the Digipass record overrides the<br />
Policy.<br />
1016 The Digipass is not available A User attempted Self-Assignment, but the Digipass<br />
they requested either could not be found within the<br />
search scope or was already assigned to someone<br />
else.<br />
This may occur because of a mistyped Serial Number.<br />
Otherwise, the search scope may be incorrect or the<br />
Digipass may not be in the correct location to be<br />
made available to the User. See the Location of<br />
Digipass Records section in the Product Guide.<br />
1017 The user account has no mobile number for<br />
Virtual Digipass<br />
1018 No password was supplied for a Virtual Digipass<br />
login<br />
A User requested a Primary or Backup Virtual Digipass<br />
OTP, but it could not be delivered because the User<br />
account had no mobile phone number. In Active<br />
Directory this is the first Mobile No. on the record.<br />
A User attempted a Virtual Digipass login, but did not<br />
enter a password in the second stage of the login. See<br />
10.1.9 Virtual Digipass for more information.<br />
1019 The new password confirmation failed In a password change request, the new password was<br />
not confirmed correctly.<br />
1020 Local authentication failed General-purpose failure of Local Authentication when<br />
a more specific status code is not available. Additional<br />
information should provide more specific details.<br />
1021 Back-end authentication reported that the<br />
password has expired<br />
Back-End Authentication (eg. Windows) failed<br />
because the password was correct but it has expired.<br />
1022 Back-end authentication failed Back-End Authentication (eg. Windows) failed. A<br />
specific error code and message will accompany this<br />
record.<br />
1030 The policy was invalid An authentication request was rejected because the<br />
applicable Policy had invalid settings or failed to load.<br />
This should not occur, but is possible due to the delay<br />
in Active Directory replication for example. The two<br />
main ways in which a Policy can become invalid are:<br />
One or more choice list settings are Default in the<br />
Policy, and its parent Policy if it has one.<br />
A circular chain of Policies has been created, for<br />
example: Policy A inherits from Policy B; Policy B<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 287
Status Code Message Notes<br />
1031 The policy does not allow a self-assignment<br />
attempt<br />
1032 Hashed passwords cannot be verified by<br />
Windows<br />
Error and Status Codes<br />
inherits from Policy C; Policy C inherits from Policy A.<br />
The Policy must be fixed in order for authentication to<br />
be permitted using that Policy.<br />
A User attempted Self-Assignment, but it is not<br />
permitted under the Policy.<br />
An authentication request could not be processed<br />
successfully because Back-End Authentication using<br />
Windows was required, but the User's password was<br />
hashed. It is not possible to verify hashed passwords<br />
with Windows. This can occur when a CHAP-based<br />
protocol is used – this includes CHAP, MS-CHAP, MS-<br />
CHAP2, EAP-MD5 and other more complex protocols<br />
that utilize a one-way hash of the password entered<br />
by the User.<br />
Note that the effective Back-End Authentication<br />
setting is the effective setting of the Policy, unless the<br />
Digipass User Account overrides the Policy.<br />
1033 A Digipass must be used The effective Local Authentication setting is Digipass<br />
Only and the User tried to log in with a static<br />
password.<br />
Note that the 'effective' setting is the effective setting<br />
of the Policy, unless the Digipass User Account<br />
overrides the Policy.<br />
1034 Challenge/Response is not supported by CHAPbased<br />
protocols<br />
1035 Challenge/Response is not supported by<br />
Windows 2000<br />
Challenge/Response is only supported in RADIUS<br />
using the PAP protocol. An attempt was made to<br />
generate a challenge using a CHAP-based protocol –<br />
this includes CHAP, MS-CHAP, MS-CHAP2, EAP-MD5<br />
and other more complex protocols.<br />
This status code can only occur in the Digipass Plug-<br />
In for IAS. There is a product limitation on Windows<br />
2000 only that Challenge/Response is not supported.<br />
It will occur if the User attempted to request a<br />
challenge.<br />
1036 1-Step Challenge/Response is disabled A request was made to generate a random challenge<br />
for 1-step Challenge/Response, but the applicable<br />
Policy does not have 1-step Challenge/Response<br />
enabled or does not specify the challenge length and<br />
check digit indicator.<br />
1037 Password Autolearn is disabled A request was made to update a user's Stored<br />
Password, but Password Autolearn is disabled, so the<br />
update is not permitted. Password Autolearn must be<br />
enabled for the password update request to be<br />
processed.<br />
1038 The administration session ID is not known at An administration command has been received, but<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 288
Status Code Message Notes<br />
Error and Status Codes<br />
this location the internal session ID is not recognised at the<br />
location from which the command came. This can<br />
only occur by attempting to reuse a session ID from<br />
another location.<br />
1039 The administration session is no longer active An administration command has been received, but<br />
the session has stopped or is unrecognised. This can<br />
occur due to an idle timeout, a maximum session<br />
length timeout or a restart of the <strong>Identikey</strong> <strong>Server</strong>.<br />
1040 Back-end authentication returned a Challenge<br />
that cannot be handled<br />
1041 No Digipass was found for the given Serial<br />
Number<br />
1042 Self-Assignment was attempted but Back-End<br />
Authentication did not occur to authenticate the<br />
static password<br />
This can occur when the <strong>Identikey</strong> <strong>Server</strong> forwards a<br />
request to a RADIUS <strong>Server</strong> and the RADIUS <strong>Server</strong><br />
responds with an Access-Challenge. An Access-<br />
Challenge can only be handled when the <strong>Identikey</strong><br />
<strong>Server</strong> forwards the password unmodified to the<br />
RADIUS <strong>Server</strong>. If the <strong>Identikey</strong> <strong>Server</strong> verifies an OTP<br />
and forwards the static password to the RADIUS<br />
<strong>Server</strong>, it is not possible to handle an Access-<br />
Challenge from the RADIUS <strong>Server</strong>.<br />
It can also occur if you use RADIUS Back-End<br />
Authentication for an IIS Module. In that case, Access-<br />
Challenge is not supported from the RADIUS <strong>Server</strong>.<br />
During a Self-Assignment attempt, the Serial Number<br />
provided by the User was not found in the data store.<br />
This mainly occurs when the Serial Number is entered<br />
incorrectly. It can also occur because the Digipass<br />
record is not in the User's Domain or Organizational<br />
Unit.<br />
Self-Assignment is not allowed without Back-End<br />
Authentication. This is required to validate the static<br />
password.<br />
1050 Reactivation is not allowed A reactivation attempt was refused for one of the<br />
following reasons:<br />
The Digipass has already been activated from<br />
the maximum number of allowed locations. This<br />
limit is controlled by the Provisioning Scenario<br />
configuration setting Max Locations.<br />
The maximum number of allowed activation<br />
attempts has already been reached. This limit is<br />
controlled by the Provisioning Scenario<br />
configuration setting Max Attempts.<br />
The minimum time interval required between<br />
activation attempts has not yet been reached<br />
since the last activation attempt. This limit is<br />
controlled by the Provisioning Scenario<br />
configuration setting Min Interval.<br />
1051 Multiple Digipass found where a single Digipass An activation attempt was made where the user had<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 289
Status Code Message Notes<br />
Error and Status Codes<br />
was required two or more Digipass that could be used. The<br />
activation request did not specify which Digipass<br />
should be used to handle the request.<br />
1052 The user account has no static password to<br />
encrypt the activation code<br />
If no Local Authentication or Back-End Authentication<br />
is done during an activation request, a static password<br />
is required from the Digipass User account. The<br />
password is used to encrypt the activation code.<br />
1053 No Digipass was available for assignment No available Digipass was found for the Provisioning<br />
Register request. The Digipass must be capable of<br />
activation and meet the Digipass restrictions in the<br />
Policy settings if any.<br />
1054 Error generating activation code Generation of an activation code for Provisioning<br />
failed. More specific details may be found in the<br />
VACMAN Controller error code and message.<br />
1060 The Signature failed validation Verification of the signature failed. More specific<br />
details may be found in the VACMAN Controller error<br />
code and message.<br />
1061 The Signature has already been used This status code occurs specifically when a signature<br />
is rejected because it has already been used. It may<br />
also occur when the signature has not been used but<br />
is older than the most recently used signature.<br />
This behaviour depends on the effective Online<br />
Signature Level Policy setting.<br />
1062 A Host/Confirmation Code is required but the<br />
Digipass Application is not able to generate it<br />
For an authentication request, a Host Code was<br />
required to be returned. The Digipass Application for<br />
which the OTP was validated was not capable of<br />
generating a Host Code.<br />
For a signature validation request, a Confirmation<br />
Code was required to be returned. The Digipass<br />
Application for which the signature was validated was<br />
not capable of generating a Confirmation Code.<br />
The DPX file that was used to import the Digipass<br />
Application controls whether the Host or Confirmation<br />
Code can be generated.<br />
3001 A Digipass Challenge was returned This status code is the standard code when a<br />
challenge is issued and does not indicate any kind of<br />
error.<br />
3002 No challenge was identified for the authentication A response to a challenge was given, but no challenge<br />
could be found. The most likely reason for this to<br />
occur is that the challenge is too old and has been<br />
removed from the challenge cache. It can also occur if<br />
no 'challenge key' was supplied with which to look up<br />
the challenge.<br />
3003 Back-end authentication returned a Challenge This occurs when a RADIUS <strong>Server</strong> responds with an<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 290
Status Code Message Notes<br />
Error and Status Codes<br />
Access-Challenge, in a case where the <strong>Identikey</strong><br />
<strong>Server</strong> can handle it.<br />
5001 The user failed the Windows Group Check The <strong>Identikey</strong> <strong>Server</strong> decided not to handle an<br />
authentication request due to the Windows Group<br />
Check failing. This can occur when the effective<br />
Windows Group Check option is Pass requests for<br />
users not in listed groups back to host system.<br />
Note that the 'effective' setting is the effective setting<br />
of the Policy, unless the Digipass User Account<br />
overrides the Policy.<br />
5002 Neither local nor back-end authentication was<br />
done due to policy and/or user settings<br />
The <strong>Identikey</strong> <strong>Server</strong> decided not to handle an<br />
authentication request because the effective Local<br />
Authentication and Back-End Authentication settings<br />
were both None.<br />
Note that the 'effective' settings are the effective<br />
settings of the Policy, unless the Digipass User<br />
Account overrides the Policy.<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 291
21 Technical Support<br />
If you encounter problems with a VASCO product please do the following:<br />
Technical Support<br />
1. Read the Troubleshooting topic in the <strong>Administrator</strong> <strong>Reference</strong> for help in discovering the source of your<br />
problem.<br />
2. Check if your problem is resolved in the Knowledge Base located at the following URL:<br />
http://www.vasco.com/support.<br />
3. If you do not find the information you need in the Knowledge Base, please contact the company that sold you<br />
the VASCO product.<br />
Only after doing these steps, if your problem is not yet solved, please contact VASCO support:<br />
21.1 Support Contact Information<br />
E-mail<br />
support@vasco.com<br />
Website<br />
http://www.vasco.com/support/contacts.html<br />
Phone<br />
Australia +61 2 8061 3700 (Sydney)<br />
Belgium +32 2 609 9770 (Brussels)<br />
Singapore +65 6 232 2727<br />
USA +1 508 366 3400 (Boston)<br />
<strong>Identikey</strong> <strong>Server</strong> <strong>Administrator</strong> <strong>Reference</strong> 292