purpose, or those arising by law, statute, usage of trade or course of dealing. The entire risk as to the results and performance of the product is assumed by you. Neither we nor our dealers or suppliers shall have any liability to you or any other person or entity for any indirect, incidental, special or consequential damages whatsoever, including but not limited to loss of revenue or profit, lost or damaged data of other commercial or economic loss, even if we have been advised of the possibility of such damages or they are foreseeable; or for claims by a third party. Our maximum aggregate liability to you, and that of our dealers and suppliers shall not exceed the amount paid by you for the Product. The limitations in this section shall apply whether or not the alleged breach or default is a breach of a fundamental condition or term, or a fundamental breach. Some states/countries do not allow the exclusion or limitation or liability for consequential or incidental damages so the above limitation may not apply to you.
Copyright
Copyright © 2010 VASCO Data Security, Inc., VASCO Data Security International GmbH. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of VASCO Data Security Inc.
Trademarks
VASCO®, Vacman®, IDENTIKEY®, aXsGUARD®, DIGIPASS®, and ® are registered or unregistered trademarks of VASCO Data Security, Inc. and/or VASCO Data Security International GmbH in the U.S. and other countries.
Table of Contents
1
Introduction... 17
1.1 Available Guides... 17
2
Active Directory Schema... 18
2.1 Schema Extensions... 18
2.1.1 Added Object Classes... 18
2.1.2 Added Attributes... 19
2.1.3 Added Permission Property Sets... 23
2.2 Active Directory Auditing... 24
2.2.1 Auditing Inside the Active Directory Users and Computers Extension... 24
2.3 Custom Search Options... 25
2.3.1 Saved Queries... 25
2.3.2 Using the Custom Search for DIGIPASS... 27
2.3.3 Using the Custom Search for Users... 28
2.4 Active Directory Replication Issues... 31
2.4.1 Old Data Used After Attribute Modified... 31
2.4.1.1 Single IDENTIKEY Server using more than one Domain Controller... 31
2.4.1.2 Administrator and IDENTIKEY Server using different Domain Controllers...32
2.4.1.3 Multiple IDENTIKEY Servers Using Different Domain Controllers...32
2.4.1.4 Two Administrators Modifying the Same Attribute...32
2.4.2 Old Data Used Overwrites New Data... 33
2.4.3 Factors Affecting Replication Issues...33
2.4.4 Solutions and Mitigations... 34
2.4.4.1 Digipass Cache...34
2.5 DPADadmin Utility... 36
2.5.1 Extend Active Directory Schema... 36
2.5.2 Check Schema Extensions... 38
2.5.2.1 Check the Database Structure...38
2.5.2.2 Command Line Syntax...38
2.5.3 Set Up Digipass Containers in Domain... 39
2.5.3.1 Prerequisite Information...39
2.5.3.2 Set Up Digipass Containers...39
2.5.3.3 Command Syntax...39
2.5.4 Assign Digipass Permissions to a Group... 40
2.5.4.1 Pre-requisites... 40
2.5.4.2 Command Syntax...40
2.5.5 Delete all Digipass-Related Data from Active Directory... 41
3.1 Database Support... 43
3.1.1 Unicode Support... 44
3.2 Embedded Database... 44
3.2.1 Service Account... 44
3.2.2 Database Administration Account... 45
3.2.3 Database Administration... 45
3.2.3.2 Changing the Digipass User's Password... 45
3.2.4 Connection Limitations... 46 3.3 Database Schema... 47 3.3.1 vdsControl Table... 47 3.3.2 vdsUser Table... 48 3.3.3 vdsUserAttr Table... 48 3.3.4 vdsDigipass Table... 49 3.3.5 vdsDPApplication Table... 50 3.3.6 vdsDPSoftParams Table... 50 3.3.7 vdsPolicy Table... 51 3.3.8 vdsComponent Table... 53 3.3.9 vdsBackEnd Table... 53 3.3.10 vdsDomain Table... 54 3.3.11 vdsOrgUnit Table... 54 3.3.12 vdsReport Table... 56 3.3.13 vdsReportFormat Table... 56 3.3.14 vdsConfiguration Table... 57 3.3.15 vdsOfflineAuthData Table... 57
3.4 Encoding and Case-Sensitivity... 58
3.5 Domains and Organizational Units... 58
3.5.1 Domains... 58
3.5.1.1 Master Domain... 59
3.5.1.2 Identifying the Domain for a Login Attempt...59
3.5.2 Organizational Units... 61
3.6 Database User Accounts... 62
3.6.1 Permissions on the Tables... 62
3.6.2 Access to Another Schema... 62
3.6.2.1 Modify vdsControl Table... 63
3.7 Database Connection Handling... 64
3.7.1 Multiple Data Sources... 64
3.7.2 Max. Connections... 64
3.7.3 Connection Wait Time... 64
3.7.5 Enable Load Sharing... 65
3.7.6 Reconnect Intervals... 65
3.8 DPDBADMIN... 66
3.8.1 Modify Database Schema... 66
3.8.2 Check Database Modifications... 68
3.8.2.1 Prerequisite Information...68
3.8.2.2 Check the Database Structure...69
3.8.2.3 Command Line Syntax...69
3.8.3 Remove Database Modifications... 69
3.8.3.1 Prerequisite Information...70
3.8.3.2 Modify Database Structure...70
3.8.3.3 Command Line Syntax...70
4
Sensitive Data Encryption... 72
4.1 Encrypted Data... 72
4.2 Which Encryption Algorithms can be used?... 72
4.3 Exporting Encryption Settings... 73
4.4 Digipass TCL Command-Line Administration... 73
5
Set Up Active Directory Permissions... 74
5.1 Permissions Needed by the IDENTIKEY Server... 74
5.1.1 Giving Permissions to the IDENTIKEY Server... 74
5.2 Permissions Needed by Administrators... 75
5.2.1 Domain Administrators... 75
5.2.2 Delegated Administrators... 75
5.2.3 Reduced-Rights Administrators... 75
5.2.4 System Administrators... 76
5.3 Assign Administration Permissions to a User ... 77
5.4 Multiple Domains... 80
5.4.1 Scenario 1 – Each IDENTIKEY Server Handles One Domain... 80
5.4.2 Scenario 2 – One IDENTIKEY Server Handles All Domains... 81
5.4.3 Scenario 3 - Combination... 81
6
Backup and Recovery... 82
6.1 What Must be Backed Up... 82
6.1.1 Configuration Files... 82
6.1.2 SSL Certificates... 83
6.1.3 Audit Log Data... 83
6.1.3.1 Write to Text File...83
6.1.3.2 Write to ODBC Database...83
6.1.5 DPX files... 84
6.1.6 Data Store... 84
6.1.6.1 Data Source Settings...85
6.1.6.2 Backup Strategies... 85
6.1.6.3 Backup of PostgreSQL Embedded Database... 85
6.2 Recovery... 87
6.2.1 Active Directory... 87
6.2.2 ODBC Database... 88
6.2.2.1 Rebuild IDENTIKEY Server, Database Undamaged... 88
6.2.2.2 Restore Database, IDENTIKEY Server Undamaged... 89
6.2.2.3 Rebuild IDENTIKEY Server, Restore Database...91
6.2.2.4 Copy Database from Other IDENTIKEY Server...94
6.2.2.5 Rebuild IDENTIKEY Server, Copy Database...96
7
Field Listings... 98
7.1 User Properties... 98
7.2 User Attributes... 100
7.3 Digipass Properties... 102
7.4 Digipass Application Tab... 104
7.5 Policy Properties... 105
7.6 Client Properties... 115
7.7 Back-End Server Properties... 117
7.8 Reports Properties... 119
7.9 IDENTIKEY Server Properties... 121
7.10 Data Changes Requiring a Restart of IDENTIKEY Server... 122
7.10.1 Changes to the Data Store... 122
7.10.1.1 Automatic Re-Loading of Cached Data... 122
7.10.1.2 Cached Data List...122
7.10.2 Changes to Configuration Settings... 123
7.10.3 Changes to Date/Time... 123
8
Licensing... 124
8.1 How is Licensing Handled?... 124
8.2 Licensing Parameters... 125
8.2.1 Sample License File... 125
8.3 View License Information... 126
8.4 Obtain and Load a License Key... 126
9
Web Sites... 128
9.1 Customizing the Web Sites... 128
9.2 CGI Program... 128
9.2.1 Configuration Settings... 129
9.3 Form Fields... 130
9.3.1 Registration – Main Pages... 130
9.3.1.1 Registration – Challenge Page... 131
9.3.1.2 PIN Change... 132
9.3.1.3 Login Test – Main Page...133
9.3.1.4 Login Test – Challenge Page... 134
9.3.2 OTP Request Site... 135
9.3.2.1 Request Page... 135
9.4 Query String Variables... 136
9.4.1 Failure/Error Handling... 136
9.4.2 Query String Variable List... 137
9.4.3 Return Code Listing... 138
9.4.3.1 API Return Codes...138
9.4.3.2 CGI Errors...138 9.4.3.3 Internal Errors... 139
10 Login Options... 141
10.1 Login Permutations... 141 10.1.1 Login Methods... 141 10.1.2 Login Actions... 141 10.1.3 Login Variables... 141 10.1.4 Password Format... 142 10.1.5 Policy Settings... 14210.1.6 Response Only – Cleartext Combined Password Format...143
10.1.7 Response Only – CHAP/MS-CHAP/MS-CHAP2... 146
10.1.8 2-Step Challenge/Response – Cleartext Combined Password Format...146
10.1.9 Virtual Digipass... 148
11 IDENTIKEY Server Configuration Settings... 149
11.1 IDENTIKEY Server Configuration Wizard...149
11.2 Redeploy Administration Web Interface... 149
11.3 IDENTIKEY Server Configuration... 151
11.3.1 Starting the Configuration GUI...151
11.3.2 Starting the Configuration Wizard... 151
11.3.3 General Section... 152
11.3.3.1 Server Location...152
11.3.3.2 Administration Session Settings... 152
11.3.4.1 SOAP... 153 11.3.4.2 RADIUS... 154 11.3.4.3 SEAL... 154 11.3.5 Scenarios Section... 156 11.3.5.1 Authentication Scenario...156 11.3.5.2 EMV-CAP Scenario...156
11.3.5.3 Signature Validation Scenario...156
11.3.5.4 Provisioning Scenario... 156 11.3.5.5 Administration Scenario...157 11.3.5.6 Reporting Scenario...157 11.3.5.7 Audit Scenario... 157 11.3.5.8 Replication Scenario...157 11.3.5.9 Configuration Scenario... 157 11.3.6 Engines Section... 158 11.3.7 Storage Section... 158
11.3.7.1 ODBC Data Sources... 158
11.3.7.2 LDAP Data Sources...160
11.3.7.3 Encryption... 160
11.3.7.4 Advanced Configuration Settings...161
11.3.8 Auditing... 164 11.3.9 Replication Section... 165 11.3.9.1 Enable Replication...165 11.3.9.2 Source Server... 166 11.3.9.3 Destination Server...166 11.3.9.4 Queue... 166
11.3.10 Server Discovery Section... 167
11.3.11 Configuration File... 169
11.3.11.1 DNS Registration...169
11.4 Command Line Options... 170
11.4.1 Windows Service Control Manager... 170
11.4.2 Linux Runtime Configuration... 170
11.4.3 Running IDENTIKEY Server with Command Line Options... 170
11.4.3.1 Command Line Option flags...170
11.4.3.2 Windows... 171
11.4.3.3 Linux...171
11.5 IDENTIKEY Server Web Administration Configuration... 171
11.5.1 List... 171
11.5.1.1 Location... 171
11.5.1.2 IDENTIKEY Server Name... 172
11.5.2 Add IDENTIKEY Server ... 172
11.5.3 Server Status... 172
11.5.3.1 Replication ...172
11.5.3.2 Admin Session...172
11.6 Web Administration Setup Tool... 174
11.6.1 Overview... 174
11.6.2 Running the Application... 174
11.6.3 Available Commands... 175
11.6.4 Command Usage Examples... 176
11.6.4.1 Adding an IDENTIKEY Server and SSL Certificate...176
11.6.4.2 Adding an IDENTIKEY Server... 176
11.6.4.3 Using an SSL Certificate... 177
11.7 Message Delivery Component Configuration... 179
11.7.1 Required Information... 179
11.7.2 MDC Configuration GUI... 179
11.7.2.1 Modify Gateway Account Login Details... 179
11.7.2.2 Configure Internet Connection Details...179
11.7.2.3 Configure Tracing...180
11.7.2.4 Import HTTP Gateway settings... 181
11.7.2.5 Edit Advanced Settings...181
11.7.2.6 Export HTTP Gateway settings...182
11.7.2.7 Gateway Result Pages... 182
11.7.3 MDC Configuration File... 186
11.7.4 Configuration Settings... 188
11.8 Digipass TCL Command Line Utility... 191
11.8.1 Sample Configuration File... 191
12 IDENTIKEY Server Advanced Setup... 193
12.1 Create Organizational Structure... 193
12.1.1 Domains... 193
12.1.1.2 Create a New Domain...193
12.1.2 Organizational Units... 193
12.1.2.1 Create an Organizational Unit...194
12.1.3 Administrators... 194
12.1.3.1 Create a Delegated Administrator...194
12.1.3.2 Create a Global Administrator... 195
12.2 How To Set Up Virtual Digipass... 196
12.2.1 Pre-requisites... 196
12.2.2 Import Virtual Digipass records... 196
12.2.3 Set Up SMS Gateway... 196
12.2.4 Set Up Message Delivery Component... 196
12.2.5 Configure IDENTIKEY Server ... 197
12.2.6 Edit IDENTIKEY Server Policy... 197
12.2.6.1 Primary Virtual Digipass...197
12.2.6.2 Backup Virtual Digipass... 197
12.2.7 Test Virtual Digipass... 199
12.3.2 Linux... 200
12.4 Create Custom Report Definition... 201
12.4.1 Query Filters... 202
12.5 Use a Commercial SSL Certificate with IDENTIKEY Server... 206
12.5.1 Generate a Certificate Signing Request... 206
12.5.2 Certificate Chain... 206
12.5.3 Windows... 207
12.5.4 Linux... 208
12.6 Use a Self-Signed SSL Certificate with IDENTIKEY Server... 209
12.6.1 Windows... 209
12.6.2 Linux... 209
12.7 How to Set Up a Stand-Alone IDENTIKEY Server in RADIUS Environment... 211
12.7.1 Information required... 211
12.7.2 Instructions... 211
12.8 How to Set Up IDENTIKEY Server as RADIUS Proxy Target... 212
12.8.1 Information required... 212
12.8.2 Instructions... 212
12.9 How to Set Up IDENTIKEY Server as Intermediate Server... 214
12.9.2 Information required... 215
12.9.3 Instructions... 215
12.10 Add a New Domain to IDENTIKEY Server... 216
12.10.1 Solution 1: Install an Extra IDENTIKEY Server in the New Domain... 216
12.10.2 Solution 2: Configure New Domain for Existing IDENTIKEY Server... 216
12.11 How to Set Up IDENTIKEY Server Discovery... 217
12.11.1 Enable IDENTIKEY Server Discovery in DIGIPASS Windows Logon... 217
12.11.2 Register IDENTIKEY Server with DNS Server... 217
12.12 Change Server Component Location... 218
12.12.1 Administration Client Components... 218
12.12.2 IDENTIKEY Server Process... 218
12.13 Set Up a Hardware Security Module... 221
12.13.1 Hardware Security Module Setup... 221
12.13.1.1 Pre-Requisites... 221
12.13.1.2 Configuration... 221
12.13.2 IDENTIKEY Server Setup... 223
12.13.2.1 Pre-requisites... 223
12.13.2.2 Configuration... 224
13 Reporting... 225
13.1.1 What fields can be included in reports?... 225
13.1.2 How can these fields be grouped?... 225
13.1.3 How to define a Query... 225
13.1.3.1 Fields Available to Report Query Definition... 226
13.1.4 Report Permissions... 229 13.2 Types of Report ... 229 13.2.1 Standard Reports... 230 13.2.2 Custom Reports... 231 13.2.3 Formatting Templates... 231 13.3 Archiving Strategy... 231
14 Auditing... 232
14.1 Text File... 23214.1.1 Text File Name Variables... 232
14.1.2 Configure Auditing to Text File... 232
14.2 Windows Event Log... 234
14.3 ODBC Audit Message Database...235
14.3.1 Set up ODBC Database... 235
14.3.1.1 Create database...235
14.3.1.2 Create database schema... 235
14.3.1.3 Create Database Account(s)...236
14.3.1.4 Create DSN on IDENTIKEY Server machine...237
14.3.1.5 Create DSN on Audit Viewer machine...237
14.3.2 Configure IDENTIKEY Server... 237
14.3.3 Configure Audit Viewer... 237
14.4 Linux Syslog... 238
14.4.1 Configure the System Log... 239
14.4.2 Modify Configuration File... 239
14.4.3 Configure IDENTIKEY Server to Write Audit Messages to the Syslog... 239
14.4.4 Starting the Audit Viewer... 240
14.5 Live Connection - IDENTIKEY Server to Audit Viewer... 241
14.5.1 Configure IDENTIKEY Server... 241
14.5.2 Configure Audit Viewer... 241
15 Tracing... 242
15.1 Trace Message Types... 242
15.2 Trace Message Levels... 243
15.3 Trace Message Contents... 243
16 Digipass TCL Command-Line Administration... 244
16.1.3 Data Store Connection... 245
16.1.4 Configuration File... 245
16.2 Using DPADMINCMD – Basics... 246
16.2.1 Using an Interactive TCL Command Prompt... 246
16.2.2 Running a Script... 247 16.2.3 Help... 248 16.2.4 Command Parameters... 248 16.2.5 Result Output... 248 16.2.6 Error Handling... 249 16.2.7 International Characters... 249 16.2.8 Syntax Notes... 249 16.2.9 Sample Scripts... 250
17 Replication... 252
17.1 Concepts... 252 17.1.1 Replication Queue... 253 17.1.2 Record-level Replication... 253 17.1.3 Replication Process... 254 17.1.4 Connection Handling... 255 17.1.4.1 Component Record... 256 17.1.5 Monitoring Replication... 256 17.1.5.1 Auditing...25617.1.5.2 Administration Web Interface... 256
17.1.6 Forwarding Replication Entries... 257
17.2 Configuring Replication ... 258
17.2.1 Active Directory... 258
17.2.2 ODBC Database... 258
17.2.2.1 Configure Replication to a Second IDENTIKEY Server... 258
17.2.2.2 Configure Replication to a Third or Subsequent IDENTIKEY Server ... 261
17.2.2.3 Add Redundant Replication...263
18 Troubleshooting... 264
18.1 Troubleshooting Tools... 264
18.1.1 View Audit Information... 264
18.1.1.1 Windows Event Viewer... 264
18.1.1.2 Syslog... 264 18.1.1.3 Text file ... 264 18.1.1.4 ODBC Database... 265 18.1.2 Tracing... 265 18.2 How To Troubleshoot... 266 18.2.1 Connection Problems... 266
18.2.2 Dynamic Component Registration Problems... 266
18.2.3 Installation Check... 266
18.2.3.1 Windows Registry Entries...266
18.2.3.2 Check Permissions...267
18.2.3.3 Default Policy and Component Created...268
18.2.4 Administration Web Interface Connection...268
18.2.5 Message Delivery Component... 269
18.2.5.1 Enable Tracing...269
18.2.6 Open Port Numbers on Firewall... 269
18.2.6.1 Incoming Ports...269
18.2.6.2 Outgoing Ports...270
18.2.7 SOAP/SSL Certificates... 270
18.2.8 Data Changes in Active Directory Users and Computers Snap-In... 270
18.2.9 Updating PostgreSQL from 8.2 to 8.3.1... 271
18.2.10 HSM Connection Failure... 271
19 Audit Messages... 272
19.1 Audit Message Listing... 272
20 Error and Status Codes... 285
20.1 Error Codes... 285
20.2 DIGIPASS Authentication for Windows Logon Error Messages...291
20.3 Status Codes... 292
Index of Tables
Table 1: Custom Active Directory Object Classes... 18
Table 2: Custom Active Directory Object Attributes... 19
Table 3: Custom Active Directory Permission Property Sets... 23
Table 4: Saved Queries in Active Directory Users and Computers... 26
Table 5: Custom Active Directory Search criteria - Digipass...27
Table 6: Custom Active Directory Search criteria - Users... 29
Table 7: DPADadmin addschema Command Line Options...38
Table 8: DPADadmin checkschema Command Line Options... 38
Table 9: DPADadmin setupdomain Command Line Options...40
Table 10: DPADadmin setupaccess Command Line Options... 40
Table 11: ODBC Database Tables... 47
Table 12: vdsControl Table... 47
Table 13: vdsUser Table... 48
Table 14: vdsUserAttr Table...49
Table 15: vdsDigipass Table...49
Table 16: vdsDPApplication Table...50
Table 17: vdsDPSoftParams Table...50
Table 18: vdsPolicy Table...51
Table 19: vdsComponent Table... 53
Table 20: vdsBackEnd Table...53
Table 21: vdsDomain Table... 54
Table 22: vdsOrgUnit Table... 54
Table 23: vdsReport Table...56
Table 24: vdsReportFormat Table... 56
Table 25: vdsConfiguration Table... 57
Table 26: vdsOfflineAuthData Table...57
Table 27: Table Permissions Required...62
Table 28: Table Names in vdsControl...63
Table 29: DPDBADMIN addschema Command Line Options...67
Table 30: DPDBADMIN checkschema Command Line Options... 69
Table 31: DPDBADMIN dropschema Command Line Options... 70
Table 32: Encrypted Data Attributes - ODBC Database...72
Table 33: Encrypted Data Attributes - Active Directory...72
Table 35: User Attribute Fields...100
Table 36: Digipass Fields...102
Table 37: Digipass Application Fields...104
Table 38: Policy Fields...105
Table 39: Client Fields...115
Table 40: RADIUS Back-End Server Fields... 117
Table 41: Active Directory Back-End Server Fields...117
Table 42: eDirectory Back-End Server Fields... 118
Table 43: ADAM Back-End Server Fields... 118
Table 44: Report fields... 119
Table 45: IDENTIKEY Server Fields...121
Table 46: License Parameters for IDENTIKEY Server... 125
Table 47: Configuration Settings for CGI Program... 129
Table 48: Form Fields for Main Registration Page... 130
Table 49: Form Fields for Registration Challenge Page... 131
Table 50: Form Fields for Server PIN Change Page... 132
Table 51: Form Fields for Main Login Test Page... 133
Table 52: Form Fields for Login Test Challenge Page...134
Table 53: Form Fields for OTP Request Page... 135
Table 54: Query String Variable List...137
Table 55: API Return Codes... 138
Table 56: CGI Error Return Codes... 138
Table 57: Internal Error Codes... 139
Table 58: Login Permutations - Response Only Cleartext Combined (1)...143
Table 59: Login Permutations - Response Only Cleartext Combined (2)...144
Table 60: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP2...146
Table 61: Login Permutations – 2-Step Challenge/Response Cleartext Combined...147
Table 62: Login Permutations – Virtual Digipass... 148
Table 63: MDC Audit Message Variables...184
Table 64: Message Delivery Component Configuration Settings...188
Table 65: Audit Text File Name/Path Variables...232
Table 66: Required Audit Database Tables...235
Table 67: vdsAuditMessage Required Fields...236
Table 68: vdsAuditMsgField Required Fields...236
Table 69: Required Account Permissions...236
Table 72: Tracing Message Levels...243
Table 73: Tracing Message Contents...243
Table 74: DPADMINCMD Help Commands... 248
Table 75: Registry Entries...266
Table 76: Permissions Required... 268
Table 77: List of Incoming Ports Used by the IDENTIKEY Server... 269
Table 78: List of Outgoing Ports Used by the IDENTIKEY Server... 270
Table 79: Audit Messages List...272
Table 80: Error Code List...285
Table 81: Error Code List - DIGIPASS Authentication for Windows Logon... 291
1
Introduction
1.1
Available Guides
The following IDENTIKEY Server guides are available:
Product Guide
The Product Guide will introduce you to the features and concepts of IDENTIKEY Server and the various options you have for using it.
Getting Started Guide
The Getting Started Guide will lead you through a standard setup and testing of key IDENTIKEY Server features.
Windows Installation Guide
Use this guide when planning and working through an installation of IDENTIKEY Server in a Windows environment.
Linux Installation Guide
Use this guide when planning and working through an installation of IDENTIKEY Server in a Linux environment.
Administrator Reference
In-depth information required for administration of IDENTIKEY Server. This includes references such as data attribute lists, backup and recovery and utility commands.
Performance and Deployment Guide
Contains information on common deployment models and performance statistics.
Help Files
Context-sensitive help accompanies the Administration Web Interface and DIGIPASS Extension for Active Directory Users and Computers.
IDENTIKEY Server SDK Programmers Guide
In-depth information required to develop using the SDK.2
Active Directory Schema
2.1
Schema Extensions
The following tables document the changes required by IDENTIKEY Server to the Active Directory (AD) schema when AD is used as the data store.
2.1.1
Added Object Classes
Table 1: Custom Active Directory Object Classes
Attribute Type Location Explanation
vasco-UserExt Aux. Class User record Extra VASCO attributes are added to an Active Directory User record via an 'auxiliary class' vasco-UserExt on the User class.
vasco-DPToken Class Unassigned – Optional
Assigned – with User record
The vasco-DPToken class is used to store Digipass attributes. It is also a container, in which vasco-DPApplication records for that Digipass are stored. Upon assignment to a User, the Digipass record is stored in the same location as the User.
vasco-DPApplication
Class Within Digipass record This class is used to store Digipass Application attributes, such as Server PIN and expected OTP length. vasco-Policy Class Digipass Configuration
Container
Policy attributes. Attributes will commonly be shared via inheritance.
vasco-Component Class Digipass Configuration Container
Component attributes include the License Key for IDENTIKEY Server Components.
vasco-BackEndServer
Class Digipass Configuration Container
Information required for connection to back-end servers.
vasco-Report Class Digipass Configuration Container
Support reporting functionality. Use this class to control the report scope.
vasco-ReportFormat
Class Digipass Configuration Container
Support reporting functionality. This class contains the report format definition information.
vasco-Configuration
Class Digipass Configuration Container
Configuration settings for the IDENTIKEY Server.
vasco-OfflineData Class Digipass Configuration Container
Offline authentication data. This is included for future releases of IDENTIKEY Server.
2.1.2
Added Attributes
Table 2: Custom Active Directory Object Attributes
Name Class vasco-SerialNumber vasco-DPToken vasco-TokenType vasco-DPToken vasco-ApplicationNames vasco-DPToken vasco-ApplicationTypes vasco-DPToken vasco-LinkVascoDigipassToUserExt vasco-DPToken vasco-TokenAssignedDate vasco-DPToken vasco-GracePeriod vasco-DPToken vasco-EnableBVDP vasco-DPToken vasco-BVDPExpiryDate vasco-DPToken vasco-BVDPUsesLeft vasco-DPToken vasco-DirectAssignOnly vasco-DPToken vasco-AdditionalAttribute vasco-DPToken vasco-ActivationLocations vasco-DPToken vasco-ActivationCount vasco-DPToken vasco-LastActivationTime vasco-DPToken vasco-DPSoftStaticVector vasco-DPToken vasco-DPDescription vasco-DPToken vasco-SerialNumber vasco-DPApplication vasco-ApplicationName vasco-DPApplication vasco-ApplicationNumber vasco-DPApplication vasco-ApplicationType vasco-DPApplication vasco-DPBlob vasco-DPApplication vasco-Active vasco-DPApplication vasco-LinkUserExtToVascoDigipass vasco-UserExt vasco-LinkUserExtToUser vasco-UserExt vasco-StaticPassword vasco-UserExt vasco-LocalAuth vasco-UserExt vasco-BackEndServerAuth vasco-UserExt vasco-Disable vasco-UserExt vasco-Profile vasco-UserExt vasco-AdminPrivileges vasco-UserExt
vasco-ObjectScope vasco-UserExt vasco-OfflineAuthEnabledOverride vasco-UserExt vasco-OfflineData vasco-UserExt vasco-CreateTime Vasco-UserExt vasco-ModifyTime Vasco-UserExt vasco-ID vasco-BackEndServer vasco-Protocol vasco-BackEndServer vasco-Domain vasco-BackEndServer vasco-Priority vasco-BackEndServer vasco-Retries vasco-BackEndServer vasco-AcctIPAddress vasco-BackEndServer vasco-AcctPort vasco-BackEndServer vasco-AdditionalAttribute vasco-BackEndServer vasco-AuthIPAddress vasco-BackEndServer vasco-AuthPort vasco-BackEndServer vasco-AuthPortSSL vasco-BackEndServer vasco-SharedSecret vasco-BackEndServer vasco-Timeout vasco-BackEndServer Version-Number vasco-BackEndServer vasco-ID vasco-Component vasco-Location vasco-Component vasco-LinkComponentToPolicy vasco-Component vasco-Protocol vasco-Component vasco-ComponentType vasco-Component vasco-PublicKey vasco-Component vasco-AdditionalAttribute vasco-Component vasco-SharedSecret vasco-Component vasco-TCPPort vasco-Component vasco-LicenseKey vasco-Component Version-Number vasco-Component vasco-AdditionalAttribute vasco-AllowedApplType vasco-Policy vasco-AllowedDPTypes vasco-Policy vasco-ApplicationNames vasco-Policy vasco-AssignmentMode vasco-Policy
Name Class vasco-AssignSearchUpOUPath vasco-Policy vasco-Autolearn vasco-Policy vasco-BackEndAuth vasco-Policy vasco-BackupVDPRequestKeyword vasco-Policy vasco-BackupVDPRequestMethod vasco-Policy vasco-BVDPMaximumDays vasco-Policy vasco-BVDPMaximumUses vasco-Policy vasco-ChallengeRequestKeyword vasco-Policy vasco-ChallengeRequestMethod vasco-Policy vasco-CheckChallenge vasco-Policy vasco-ChgWinPwdEnabled vasco-Policy vasco-ChgWinPwdLength vasco-Policy vasco-ChkInactDays vasco-Policy vasco-ClientGroupList vasco-Policy vasco-ClientGroupMode vasco-Policy vasco-DCR vasco-Policy vasco-Description vasco-Policy vasco-Domain vasco-Policy vasco-DUR vasco-Policy vasco-EnableBVDP vasco-Policy vasco-EventWindow vasco-Policy vasco-GracePeriod vasco-Policy vasco-GroupCheckMode vasco-Policy vasco-GroupList vasco-Policy vasco-ID vasco-Policy vasco-IThreshold vasco-Policy vasco-ITimeWindow vasco-Policy vasco-LinkPolicyToChildPolicy vasco-Policy vasco-LinkPolicyToComponent vasco-Policy vasco-LinkPolicyToParentPolicy vasco-Policy vasco-LocalAuth vasco-Policy vasco-OfflineAuthEnabled vasco-Policy vasco-OfflineTimeInterval vasco-Policy vasco-OfflineMaxEvents vasco-Policy vasco-OneStepChalCheckDigit vasco-Policy
vasco-OneStepChalLength vasco-Policy vasco-OneStepChalResp vasco-Policy vasco-OnLineSG vasco-Policy vasco-PINChangeAllowed vasco-Policy vasco-PrimaryVDPRequestKeyword vasco-Policy vasco-PrimaryVDPRequestMethod vasco-Policy vasco-Protocol vasco-Policy vasco-SelfAssignSeparator vasco-Policy vasco-SThreshold vasco-Policy vasco-STimeWindow vasco-Policy vasco-StoredPasswordProxy vasco-Policy vasco-SyncWindow vasco-Policy vasco-2OTPSyncEnabled vasco-Policy vasco-UserLockThreshold vasco-Policy vasco-VDPDeliveryMethod vasco-Policy Version-Number vasco-Policy vasco-ID vasco-Report vasco-ReportName vasco-Report vasco-Description vasco-Report vasco-DataSource vasco-Report vasco-GroupLevel vasco-Report vasco-ReportType vasco-Report vasco-RunPerms vasco-Report vasco-ChangePerms vasco-Report vasco-TimeFreq vasco-Report vasco-QueryDef vasco-Report vasco-UserID vasco-Report Version-Number vasco-Report vasco-ID vasco-ReportFormat vasco-FormatName vasco-ReportFormat vasco-FormatDef vasco-ReportFormat Version-Number vasco-ReportFormat vasco-Name vasco-Configuration vasco-Value vasco-Configuration Version-Number vasco-Configuration
2.1.3
Added Permission Property Sets
Property sets have been created for typical groups of permissions required for administration tasks. Table 3: Custom Active Directory Permission Property Sets
Property Set Applicable Object Actions Allowed
Digipass Assignment Link Digipass Assign and unassign Digipass for Digipass User accounts.
Digipass Application Data Digipass Application Digipass record functions. Digipass User Account Information User Modify Digipass User information.
Digipass User Account to User Link User Link and unlink Digipass Users. This is also required when assigning Digipass to linked Digipass User records.
Digipass User Account Stored Password User Read and modify the stored password for a Digipass User.
2.2
Active Directory Auditing
Active Directory auditing may be configured to record access and modifications to custom objects used by the IDENTIKEY Server. If you currently have default auditing enabled, it might already include actions on custom objects.
See these Microsoft articles for information on turning on and configuring auditing: Windows 2003 - http://support.microsoft.com/?kbid=814595
Windows Vista & 2008 – http://technet.microsoft.com/en-us/library/cc731607.aspx
What Should I Audit?
This will depend on what you need to audit. For example, if you wanted to record all Digipass assignments in the domain, you might set up auditing in the Domain Root for Everyone, with the Digipass Assignment Link property set.
Please note that this type of auditing is specific to Active Directory. Any audit information generated by this method cannot be imported into the IDENTIKEY Server auditing system, and cannot be used to generate IDENTIKEY Server reports.
See the 2.1 Schema Extensions topic for more information on custom objects and permission property sets created for the IDENTIKEY Server.
2.2.1
Auditing Inside the Active Directory Users and Computers Extension
If you wish to produce audit files that can be imported into IDENTIKEY Server and can be used to generate IDENTIKEY Server reports, you can set up auditing from inside the Active Directory Users and Computers Extension (ADUCE). All message types are audited - Error, Warning, Information, Success, Failure.
To enable Auditing in the ADUCE:
1. On the Digipass Extension Auditing window click on the Auditing option button.
2. Browse to the location you want the audit file to be written to. The name of the file will be in the format ikey_aduce<year><month>.audit, where <year> is the current year and <month> is the current month. 3. Click OK.
2.3
Custom Search Options
The DIGIPASS Extension adds functionality to the Active Directory Users and Computers snap-in which allows searching for specific DIGIPASS and DIGIPASS User records throughout a domain, or within the limits of a delegated administrator's permissions. This functionality is especially useful where unassigned DIGIPASS have been allocated to various Organizational Units.
Note
To see the digipass-pool, digipass-reserve, and digipass configuration containers under the domain in the Active Directory Users and Computers snap-in the Advanced Features setting needs to be enabled. Go to View => Advanced Features and click on Advanced Features to toggle the setting on.
2.3.1
Saved Queries
On Windows Server 2003, Windows 2008, and Windows XP, the Microsoft Management Console (MMC) framework supports Saved Queries.
On Windows Server 2003 and Windows XP, a number of Saved Queries are installed automatically into the saved MMC console file that is opened using the Start -> Programs -> VASCO -> IDENTIKEY Server -> Active Directory Users and Computers shortcut.
In addition, several Query Definition Files are installed in the <installation directory>\Queries folder. These can be imported into your existing Active Directory Users and Computers console by right-clicking on the Saved Queries folder and selecting Import Query Definition....
The Saved Queries provided by the installation are designed to provide several common queries that may be useful, as listed below. They can be edited, copied or deleted as required. If you have made a mistake modifying one and wish to start again, you can reload the query by deleting it and importing it from the Query Definition File.
Query Name Description Query Definition File Users with Digipass All Users in the Domain who have one or more
Digipass assigned directly.
users-with-dp.xml
Users without Digipass All Users in the Domain who have no Digipass assigned, directly or via a Linked User.
users-without-dp.xml
Users with a DP User Account All Users in the Domain who have a Digipass User Account.
users-with-dp-user-account.xml
Users without a DP User Account
All Users in the Domain who do not have a Digipass User Account.
users-without-dp-user-account.xml
Assigned Digipass All Digipass in the Domain that are assigned. assigned-dp.xml Unassigned Digipass All Digipass in the Domain that are currently
unassigned, excluding any Reserved Digipass.
unassigned-dp.xml
Locked DP User Accounts All Users in the Domain whose Digipass User Account is Locked.
2.3.2
Using the Custom Search for DIGIPASS
To perform a search for DIGIPASS:
1. Right-click on the Organizational Unit in which to search, or the domain root. 2. Click on Find...
3. Select the Digipass object type from the Find: drop down list.
4. Use the Digipass tab to specify the search criteria. Almost all the Digipass search criteria can be set using the form on this tab.
5. If you are searching on any criteria that do not appear on the Digipass tab, use the Advanced tab: a. Click on the Advanced tab.
b. Click on Field and select the required attribute from the list. c. Enter the search Condition and Value, then click Add. d. Repeat with additional Fields.
6. Click Find Now to execute the search. Multiple criteria are applied using the logical AND – all criteria must be met for a Digipass to be found.
The available criteria are listed in the following table: Table 5: Custom Active Directory Search criteria - Digipass
Tab Field Name Usage
Digipass Serial Number Exact Serial Number (as seen in Digipass properties); Serial Number with wildcard*;
First Serial Number in range, when used with To field. (Serial Number) To Last Serial Number in range.
Digipass Type Digipass Type, eg. DP300. Wildcard* allowed.
Application Name Application Name, eg. GO3DEFAULT. Wildcard* allowed.
This will find Digipass that have an Active application of the specified name**.
Application Type Application Type: Response Only, Challenge/Response.
This will find Digipass that have an Active application of the specified type**.
Digipass Assignment Assignment status: Assigned, Unassigned. Reserved Reserved status: Reserved, Not Reserved. Description Free text.
Use this field to find Digipass records with the same text string within their Description field.
Advanced Application Name Conditions: Starts with, Ends with, Is (Exactly), Is Not. Values: Application Name (complete or partial)
This will find Digipass that have an Active application of the specified Application Name criteria**.
Application Type Conditions: Is (Exactly), Is Not.
Values: RO (Response Only), CR (Challenge/Response), SG (Signature). This will find Digipass that have an Active application of the specified Application Type criteria**.
Backup Virtual Digipass Enabled
Conditions: Less than or equal to, Greater than or equal to, Is (Exactly), Is Not, Not Present.
Values: 0 (Default), 1 (No), 2 (Yes - Permitted), 3 (Yes - Required), 4 (Yes – Time Limited).
Note that Digipass with 'Default' for this setting may either have 0 for this attribute or may not have the attribute present.
Digipass Type Conditions: Starts with, Ends with, Is (Exactly), Is Not. Values: Digipass Type (complete or partial)
Reserved Conditions: Is (Exactly), Is Not. Values: 0 (No), 1 (Yes). This attribute is always present.
Serial Number Conditions: Starts with, Ends with, Is (Exactly), Is Not.
Values: Serial Number, as seen in Digipass properties (complete or partial) User Assignment Link Conditions: Present, Not Present.
Values: N/A.
If this attribute is present, the Digipass is assigned; if not present, the Digipass is unassigned.
* Search criteria on DIGIPASS Application attributes ignore Inactive DIGIPASS Applications. ** For a wildcard, the * character is used.
Example
A search for DIGIPASS records run with only the following text entered into the Serial Number field, would return these results: 0097 No records returned
0097* All DIGIPASS with serial number starting with 0097 0097987654 DIGIPASS with serial number 0097987654 only *76 All DIGIPASS with serial number ending in 76
2.3.3
Using the Custom Search for Users
To perform a search for Users:
2. Click on Find...
3. Select the Users, Contacts, and Groups object type from the Find: drop down list. 4. If you have search criteria that are not related to DIGIPASS, specify them as usual. 5. To specify DIGIPASS related search criteria, use the Advanced tab:
a. Click on the Advanced tab.
b. Click on Field, select the User submenu and select the required attribute from the list. c. Enter the search Condition and Value, then click Add.
d. Repeat with additional Fields.
6. Click Find Now to execute the search. Multiple criteria are applied using the logical AND – all criteria must be met for a User to be found.
The available criteria are listed in the following table: Table 6: Custom Active Directory Search criteria - Users
Field Name Usage
Digipass Assignment Link Conditions: Present, Not Present. Values: N/A.
If this attribute is present, a Digipass is assigned to the User; if not present, no Digipass is assigned.
Digipass Back-End Authentication Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),
Is Not, Not Present.
Values: 0 (Default), 1 (None), 2 (If Needed), 3 (Always).
Note that Users with 'Default' for this setting may either have 0 for this attribute or may not have the attribute present.
Digipass Local Authentication Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),
Is Not, Not Present.
Values: 0 (Default), 1 (None), 2 (Digipass/Password), 3 (Digipass Only). Note that Users with 'Default' for this setting may either have 0 for this attribute or may not have the attribute present.
Digipass User Account Create Time Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),
Is Not, Present, Not Present.
Values: Number of seconds since 1st Jan 1970 00:00:00 that the Digipass User account was created.
If this attribute is present, the User has a Digipass User account; if not present, the User does not.
Digipass User Account Disabled Conditions: Is (Exactly), Is Not, Not Present. Values: 0 (No), 1 (Yes).
If this attribute is not present, the account is not disabled*.
Digipass User Account Lock Count Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),
Is Not, Not Present.
Values: current count of failed logins since last successful login. If this attribute is not present, it is treated as 0.
Digipass User Account Locked Conditions: Is (Exactly), Is Not, Not Present. Values: 0 (No), 1 (Yes).
If this attribute is not present, the account is not locked*.
Digipass User Account Modify Time Conditions: Less than or equal to, Greater than or equal to, Is (Exactly),
Is Not, Present, Not Present.
Values: Number of seconds since 1st Jan 1970 00:00:00 that the Digipass User account was last modified.
Digipass User Account Password This field does not have practical value as a search field, but is listed by Active Directory anyway.
Digipass User Attributes This field is not currently used. Digipass User to User Link Conditions: Present, Not Present.
Values: N/A.
If this attribute is present, The Digipass User account is linked to another Digipass User account; if not present, there is no link.
* If you specify Is Not 1, the results will include Users who do not have the attribute set, in addition to those who have the attribute set to 0.
Example
A search for DIGIPASS User accounts where the Local Authentication setting has a value other than Default would use the following criteria:
2.4
Active Directory Replication Issues
Active Directory replication is not instantaneous. Intra-site replication is usually quite fast but changes on one Domain Controller may still take several minutes to be replicated to other Domain Controllers. Inter-site replication may be quite slow – an hour or more between replications is common.
Replication occurs when more than one Domain Controller exists in a domain.
2.4.1
Old Data Used After Attribute Modified
The time period between replications becomes a problem where information is changed on one Domain Controller (for example, a Digipass User's Server PIN is reset), but old information is used on another Domain Controller before the changed information has been replicated to it.
There are a few scenarios where this may occur. These are listed below:
2.4.1.1 Single IDENTIKEY Server using more than one Domain Controller
A single IDENTIKEY Server may make a change to a record, have to switch to another Domain Controller, and read the same record – where the change has not yet been applied.
Example
A User logs in with an OTP, and the IDENTIKEY Server connects to DC-01 to retrieve and update the Digipass data. The connection to the DC-01 fails soon after login, before replication has occurred. The User needs to log in again, and the IDENTIKEY Server connects 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 succeeds, because DC-02 does not yet know that the OTP has been previously used.
Time DC-01 DC-02
8:32 Replication occurs
8:34 User logs in with OTP 10457920.
The IDENTIKEY Server records the use of the OTP in the Digipass record.
8:35 Connection to DC-01 is broken, and the IDENTIKEY Server switches to DC-02.
8:35 User retries login using same OTP
10457920. The login succeeds where it should have failed (OTP replay).
The IDENTIKEY Server records the use of the OTP in the Digipass record.
8:37 Replication occurs
Digipass record changes are replicated between DC-01 and DC-02.
The administrator may not be connected to the same Domain Controller (via the Administration Interfaces) as the IDENTIKEY Server.
Example
An administrator changes a User's Server PIN through the Active Directory Users and Computers extension, which is connected to DC-01. The IDENTIKEY Server connects to DC-03. The User attempts a login using the new PIN, which fails because DC-03 is not yet aware of the change of Server PIN.
Time DC-01 DC-03
9:02 Replication occurs
9:03 Administrator changes a User's Server PIN from 1234 to 9876.
9:04 User attempts to log in using new PIN (9876) and the login fails.
9:05 Replication occurs
Digipass record changes are replicated between DC-01 and DC-03.
The example timeline above shows the sequence of events.
2.4.1.3 Multiple IDENTIKEY Servers Using Different Domain Controllers
Multiple IDENTIKEY Servers may connect to different Domain Controllers in a domain or site.
Example
A User changes their own PIN during a login through one IDENTIKEY Server which connects to DC-01. The server on which the IDENTIKEY Server is installed becomes unavailable, and the User attempts another login via the IDENTIKEY Server on a backup server, which connects to DC-02. The login fails because DC-02 is not yet aware of the change of Server PIN.
Time DC-01 DC-02
11:54 Replication occurs
11:55 User changes their Server PIN from 1234
to 9876 during login.
The IDENTIKEY Server records the PIN change in the Digipass record.
11:57 User attempts to log in using new PIN (9876) and the login fails.
11:59 Replication occurs
Digipass record changes are replicated between DC-01 and DC-02.
The example timeline above shows the sequence of events.
Two administrators attempt to modify the same attribute on a single User account or Digipass record within the same replication interval. The later modification will overwrite the earlier when replication occurs.
2.4.2
Old Data Used Overwrites New Data
The problems above are exacerbated when the old information used on the second Domain Controller is updated based on the old information. As the updated record on the second Domain Controller now has a later modification date, the end result is that the changed information on the first Domain Controller is overwritten incorrectly.
Example
An administrator connects to DC-01 and sets a User's PIN from '1234' to '9876'. The User logs in through the IDENTIKEY Server, which connects to DC-02. The User enters the new Server PIN and his One Time Password. However, the PIN set on DC-01 has not yet been replicated to 02, so because the PIN entered does not match the old PIN still recorded in the Digipass record on DC-02, the login fails.
Because the Policy setting of Identification Threshold is in use, his login failure is written back to the Digipass record. When replication occurs, the Digipass record on DC-02 has the latest modification date – and is copied to DC-01, wiping out the original PIN setting made by the administrator. Both DC-01 and DC-02 now consider '1234' to be the correct Server PIN for the Digipass.
Time DC-01 DC-02
10:45 Replication
10:46 Administrator changes User's PIN from
9876 to 1234.
10:48 User login (with new PIN of 1234) fails.
IDENTIKEY Server writes failure information to Digipass record.
10:50 Replication
Active Directory finds last instance of the Digipass blob having been modified. Active Directory overwrites DC-01 Digipass record with DC-02 Digipass record.
The example timeline above shows how the problem can occur.
The problem shown in the example above may also occur in a Force PIN Change set by an administrator.
2.4.3
Factors Affecting Replication Issues
A number of factors determine the likelihood and severity of the Active Directory issues described: Redundancy and load-balancing settings for the IDENTIKEY Server
There are a number of IDENTIKEY Server configuration settings which may affect replication issues: Preferred Server
The IDENTIKEY Server will attempt to connect to the named Domain Controller, rather than simply polling the domain for an available Domain Controller.
setting. If this is enabled, the IDENTIKEY Server will not switch to any other Domain Controller, so it will never retrieve data older than its own.
Max. Bind Lifetime
The maximum bind lifetime controls how long the IDENTIKEY Server will stay connected to a Domain Controller before polling the domain for a Domain Controller connection.
Replication Interval
On Windows Server 2003 and Windows 2008, the intra-site replication interval is not configurable, but is set to approximately 15 seconds, as replication is much more efficient.
Inter-site replication is fully configurable on Windows Server 2003 and Windows 2008. The longer the replication interval, the more likelihood of these problems occurring. Number of Domain Controllers in the Site
Each Domain Controller regularly requires replication with all other local Domain Controllers. As this is done sequentially, it will affect the amount of time between replications.
2.4.4
Solutions and Mitigations
2.4.4.1 Digipass Cache
The Digipass cache collects Digipass records as they are modified, and keeps them in memory for a certain length of time. A newer entry from the cache is always used in preference to an older record from Active Directory. The cache age should be a little longer than the typical replication interval. The default is 10 minutes (600 seconds). This option will help in problems caused by a single IDENTIKEY Server accessing more than one Domain Controller in a domain – see 2.4.1.1 Single IDENTIKEY Server using more than one Domain Controller . It will also assist in problems caused by having multiple Authentication Servers accessing more than one Domain Controller in a domain, if IDENTIKEY Server replication is enabled between the servers. However, it will not affect the scenario of an Administration Interface being connected to a different Domain Controller to the IDENTIKEY Server.
If you calculate that your typical replication interval will be more than ten minutes, the cache age may be increased by modifying the Blob-Cache Max-Age setting in the configuration file (<install dir>\bin\identikeyconfig.xml):
<Blob-Cache>
<Max-Age type="unsigned" data="600"/> <Max-Size type="unsigned" data="0"/>
<Clean-Threshold type="unsigned" data="10"/> <Min-Clean-Interval type="unsigned" data="60"/> </Blob-Cache>
A large cache may slow down processing slightly for the IDENTIKEY Server, so monitor performance to check the impact caused after modifying the cache age.
Warning
If the IDENTIKEY Server is installed on a Member Server, this server must be closely time-synchronized with the Domain Controller(s). If the server is not time-time-synchronized, the Policy may select an older record when comparing records in the Digipass cache with those on the Domain Controller.
2.5
DPADadmin Utility
2.5.1
Extend Active Directory Schema
The addschema command is used to create all the Active Directory Schema extensions, if they are not already there. Each element will be checked individually to see if it is already there and if not, will be added.
This command is intended to be run manually by a domain administrator before the main IDENTIKEY Server installation is run, as recommended by Microsoft.
It may be necessary to go through an approval process in your company before running this command, as it involves changes to Active Directory Schema. You may also need to have another administrator run the command for you, possibly in another part of your network. This depends on your company’s structure and rules for Active Directory control.
Prerequisite Information
Schema Master MachineThis command may technically be run on any Windows XP, 2003, Vista or 2008 machine. However it needs to contact the Domain Controller which has the Schema Master role. There can be only one Domain Controller in the Forest with that role. It may be simplest to run the command directly on the Schema Master, to avoid any potential connectivity or permission issues.
Warning
Warning: If you are passing the credentials to the command in the parameters, and you are not running the command on the Schema Master, check that you do not have any shares on the Schema Master open. This will cause the command to fail.
Domain Administrator Account
In order to successfully update the Schema, you must know the username and password of a Domain Administrator account that is able to log into the Schema Master. You must either run the command while logged in as that user, or pass the credentials to the command in the parameters. The Domain Administrator must have permission to extend the Schema – they must be a member of the Schema Admins group in the Forest-Root-Domain (the first Forest-Root-Domain created in the Forest).
Schema Changes Allowed
By default, Active Directory does not permit Schema extensions to be made. There is a registry setting that must be changed to allow extensions. If this is not already set, DPADadmin will ask you whether it should change the setting itself or not. If you click on Yes, it will change the setting itself, make the extensions then change it back again.
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\NTDS\ Parameters\Schema Update Allowed registry key to 1, adding it as a value of type DWORD if it does not already exist. Alternatively, if the Schema Manager MMC snap-in is installed on the machine, this can be used to enable or disable Schema extensions. If you have disabled the Schema extensions after removing a previous installation in the Forest, reactivate them before using this command. This can be done using the Schema Manager MMC snap-in used to deactivate them.
Extend the Schema on the Schema Master
1. Log into the Schema Master as a member of the Schema Administrators group. 2. Copy dpadadmin.exe onto the Schema Master
3. Open a command prompt in the location to which it was copied. 4. Type:
dpadadmin addschema
5. If DPADadmin detects that Schema extensions are not currently permitted, it will prompt you whether to enable them or not. Enter y to enable them, or n to cancel.
The progress and success/failure of the command will be displayed in the command prompt window. If there was a failure, it can be run again after the problem has been rectified.
Extend the Schema on the IDENTIKEY Server
1. Open a command prompt and navigate to the installation’s bin directory by typing:
cd <install dir>\bin
2. Type:
dpadadmin addschema –master schema_master –u user_name –p password
3. See Command Line Syntax for more details regarding the required parameters.
4. If DPADadmin detects that Schema extensions are not allowed, it will prompt you to enable them. Enter y to enable them, or n to cancel.
The progress and success/failure of the command will be displayed in the command prompt window. If there was a failure, it can be run again after the problem has been rectified.
Active Directory Replication Interval
If Active Directory is running replication between multiple domain controllers, allow time for the schema changes to be replicated across the system. The DPADadmin checkschema command may be used to check this – see 2.5.2 Check Schema Extensions for more information.
Command Line Syntax
dpadadmin addschema [–master schema_master] [–u user_name [–p password]] [-q]
Option Description
-master Fully qualified name of the Domain Controller with the Schema Master role. This option may be omitted if the command is run directly on the Schema Master.
-u User name of a Domain Administrator in the Schema Administrators group. This option may be omitted if you are logged into the machine as that Domain Administrator when you run the command.
-p Password of the Domain Administrator. This option may be omitted if you are logged in as that Domain Administrator or if they have a blank password.
-q Quiet mode, will not output commentary text.
DPADadmin addschema Command Sample
dpadadmin addschema –master dc1.vasco.com –u schema_admin –p sa_password
2.5.2
Check Schema Extensions
The checkschema command can be used to check that the Active Directory schema has been extended to include VASCO objects and attributes.
2.5.2.1 Check the Database Structure
1. Open a command prompt and go to the installation’s bin directory by typing:
a. Open a command prompt and navigate to the installation’s bin directory by typing:
cd <install dir>\bin
2. Type
dpadadmin checkschema –u user_name –p password
3. See below for more details regarding the parameters.
The progress and success/failure of the command will be displayed in the command prompt window.
2.5.2.2 Command Line Syntax
dpadadmin checkschema [–u user_name [–p password]] [-m] [-d] [-q] [-v] [-l file_name]
Table 8: DPADadmin checkschema Command Line Options
Option Description
-u User name of a Domain Administrator in the Schema Administrators group. This option may be omitted if you are logged into the machine as that Domain Administrator when you run the
Option Description command.
-p Password of the Domain Administrator. This option may be omitted if you are logged in as that Domain Administrator or if they have a blank password.
-m Fully qualified name of the Domain Controller with the Schema Master role. This option may be omitted if the command is run directly on the Schema Master.
-d Specify the domain in which the schema check should be run. -q Quiet mode, will not output commentary text.
-v Verbose mode.
-l Log output to file file_name.
DPADadmin checkschema Command Sample
dpadadmin checkschema –u schema_admin –p sa_password
2.5.3
Set Up Digipass Containers in Domain
This command sets up the Digipass-Pool and Digipass-Reserve containers in the specified domain. It can optionally set up the Digipass-Configuration container also.
2.5.3.1 Prerequisite Information
Domain AdministratorYou must be logged into the machine as a Domain Admin in the target domain.
2.5.3.2 Set Up Digipass Containers
1. Log into the machine as a Domain Administrator in that Domain.
2. Copy dpadadmin.exe onto the machine and open a command prompt in the location to which it was copied. 3. Type:
dpadadmin setupdomain
The progress and success/failure of the command will be displayed in the command prompt window.
2.5.3.3 Command Syntax
Option Description
-config OPTIONAL. Specifies that this is the Digipass Configuration Domain, so the Digipass-Configuration container must be created.
-domain <FQDN> OPTIONAL. Specifies the FQDN of the domain to set up. If omitted, the domain to which the current machine belongs will be used.
-q OPTIONAL. Specifies that quiet mode should be used.
DPADadmin setupdomain Command Sample
dpadadmin setupdomain -config -q
2.5.4
Assign Digipass Permissions to a Group
This command assigns Digipass-specific permissions to a Windows group, applicable at the domain root and downwards. The permissions assigned are:
Full read access to everything in the domain Full control over vasco-DPToken objects Full control over vasco-DPApplication objects Full write access to vasco-UserExt auxiliary objects
2.5.4.1 Pre-requisites
You must be logged into the machine as a Domain Admin in the target domain.
2.5.4.2 Command Syntax
dpadadmin.exe setupaccess -group <group name> [-domain <FQDN>] [-q] [-c]
Table 10: DPADadmin setupaccess Command Line Options
Option Description
-group <group name> MANDATORY. Specify the name of the group to assign the permissions. Double-quotes are required if there are any spaces.
-domain <FQDN> OPTIONAL. Specify the fully-qualified domain name for the domain to which the group or user belongs. If omitted, the domain to which the current machine belongs will be used. -q OPTIONAL. Specify that quiet mode should be used.
DPADadmin setupaccess Command Sample
dpadadmin.exe setupaccess -group “RAS and IAS Servers” -q
2.5.5
Delete all Digipass-Related Data from Active Directory
Digipass-specific information is not removed from Active Directory when IDENTIKEY Server is uninstalled from a computer.
A custom VB script is available which will strip all information related to the IDENTIKEY Server from a domain. The data removed includes:
Digipass-Configuration container if present VASCO Records in container:
Policy Component BackendServer Report Reportformat Configuration
Offline authentication data Digipass-Pool container if present Digipass records in container Digipass-Reserve container if present Digipass records in container
All Digipass in the domain, including all Digipass Applications. All Digipass User Accounts
Each Digipass User account is deleted by searching for Active Directory Users with the vasco-CreateTime attribute set (indicating that a Digipass User account has been created for that User). All vasco-UserExt attributes on the Active Directory User are reset.
Note
The script must be run in each domain from which data is to be removed.
you will run the command.
2. Open cmd prompt, logged in as domain admin in the domain required. 3. Enter the following:
cscript dpDeleteAll.wsf [<domain>] [-v]
4. If the machine does not belong to the target domain, specify the domain name 5. If you want record-by-record progress display, specify -v (verbose mode).
Example
3
ODBC Database
3.1
Database Support
Note
An embedded database option is available in the Windows Basic installation program. This will install PostgreSQL 8.3.1 for you on the server. However, be aware that on Windows Server 2008 a PostgreSQL 8.2 database which is in use will NOT be overwritten by the new database version. However, IDENTIKEY Server supports other ODBC-compliant databases, should you prefer to use your own database.
IDENTIKEY Server makes use of a limited set of database features, in order to support as many RDBMS (Relational Database Management Systems) as possible:
Tables (relations) with the following datatypes: INTEGER (32-bit)
VARCHAR (up to 1024 characters; on Microsoft SQL Server this is NVARCHAR for Unicode support) LONGVARCHAR or TEXT (depending on the database type) is used for columns over 1024 characters if required by the database
TIMESTAMP (for some databases, this is DATETIME or DATE – this is not an automatically generated timestamp, but just a date/time field)
Primary Key constraints
Foreign Key constraints, using the default action (restrict) and cascade delete
ANSI Standard SQL DML (Data Manipulation Language) – select, insert, update, delete, without any vendor-specific syntax
Transactions with simple COMMIT and ROLLBACK (no 'save points' or equivalents)
In order for a database to be supported, there must be an ODBC level 3 driver that supports: Multi-threaded access using multiple concurrent connections
'Wide char' (Unicode) parameters for input and output The following databases have been specifically tested:
Oracle 10g and Oracle 11g
Microsoft SQL Server 2005 Full Enterprise Edition or Express IBM DB2 8.1 (on 32-bit platforms) and 9.1 (on 64-bit platforms) Sybase Adaptive Server Anywhere 10.0
3.1.1
Unicode Support
At a minimum, the database ODBC driver must allow the 'wide char' parameters to be used, as mentioned above. However, the underlying database does not necessarily need to be configured with Unicode support. The database only needs to be able to handle the characters that are actually used.
If you do want full Unicode support in the database, refer to the database vendor's instructions. Normally, a database has to be created with Unicode storage from the start. Depending upon the database type, some of the columns in the database need to be increased in size, to handle multi-byte UTF-8 encoded data. The database documentation should indicate whether VARCHAR columns are defined by number of characters or number of bytes.
3.2
Embedded Database
The embedded database option supplied with IDENTIKEY Server for Windows uses PostgreSQL 8.2. The database server is installed as a Service and a single database created. This database has full Unicode support.
The full PostgreSQL install package is used, so the database administation tools and documentation are available. The package is installed under the IDENTIKEY Server installation directory.
3.2.1
Service Account
Windows
A local Windows account called dppostgres is created on the installation machine. This account is given privileges to log on as a service and locally. If installed on a domain controller, this account will be a domain account. The privileges to log on locally may be removed manually after installation if preferred, without preventing PostgreSQL from running.
Note
The dppostgres account is not automatically deleted upon uninstallation of PostgreSQL.
The default password for dppostgres is p!ss&0rd. This can be changed using the standard Windows or Active Directory user management interface. If you do this, make sure that the Windows Service Control Manager is configured with the new password. The PostgreSQL service is PostgreSQL Database Server 8.2.
If you have changed the password when you uninstall and reinstall the product, either delete the dppostgres account or change its password back to the default password shown above before installing. Otherwise, re-installation of PostgreSQL will fail.
