Disclaimer of Warranties and Limitations of Liabilities
The Product is provided on an 'as is' basis, without any other warranties, or conditions, express or implied, including but not limited to warranties of merchantable quality, merchantability of fitness for a particular purpose, or those arising by law, statute, usage of trade or course of dealing. The entire risk as to the results and performance of the product is assumed by you. Neither we nor our dealers or suppliers shall have any liability to you or any other person or entity for any indirect, incidental, special or consequential damages whatsoever, including but not limited to loss of revenue or profit, lost or damaged data of other commercial or economic loss, even if we have been advised of the possibility of such damages or they are foreseeable; or for claims by a third party. Our maximum aggregate liability to you, and that of our dealers and suppliers shall not exceed the amount paid by you for the Product. The limitations in this section shall apply whether or not the alleged breach or default is a breach of a fundamental condition or term, or a fundamental breach. Some states/countries do not allow the exclusion or limitation or liability for consequential or incidental damages so the above limitation may not apply to you.
Copyright
Copyright © 2009 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.
RADIUS Documentation Disclaimer
The RADIUS documentation featured in this manual is focused on supplying required information pertaining to the RADIUS server and its operation in the Identikey Server environment. It is recommended that further information be gathered from your NAS/RAS vendor for information on the use of RADIUS.
Trademarks
VASCO®, Vacman®, IDENTIKEY®, aXs GUARD™, 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... 16
1.1 Available Guides... 16
2
Active Directory Schema... 17
2.1 Schema Extensions... 17
2.1.1 Added Object Classes... 17
2.1.2 Added Attributes... 18
2.1.3 Added Permission Property Sets... 22
2.2 Active Directory Auditing... 23
2.2.1 Auditing Inside the Active Directory Users and Computers Extension... 23
2.3 Custom Search Options... 24
2.3.1 Saved Queries... 24
2.3.2 Using the Custom Search for Digipass... 26
2.3.3 Using the Custom Search for Users... 27
2.4 Active Directory Replication Issues... 30
2.4.1 Old Data Used After Attribute Modified... 30
2.4.1.1 Single Identikey Server using more than one Domain Controller... 30
2.4.1.2 Administrator and Identikey Server using different Domain Controllers...31
2.4.1.3 Multiple Identikey Servers Using Different Domain Controllers... 31
2.4.1.4 Two Administrators Modifying the Same Attribute...32
2.4.2 Old Data Used Overwrites New Data... 32
2.4.3 Factors Affecting Replication Issues...32
2.4.4 Solutions and Mitigations... 33
2.4.4.1 Digipass Cache...33
2.5 DPADadmin Utility... 35
2.5.1 Extend Active Directory Schema... 35
2.5.2 Check Schema Extensions... 37
2.5.2.1 Check the Database Structure...37
2.5.2.2 Command Line Syntax...37
2.5.3 Set Up Digipass Containers in Domain... 38
2.5.3.1 Prerequisite Information...38
2.5.3.2 Set Up Digipass Containers...38
2.5.3.3 Command Syntax...38
2.5.4 Assign Digipass Permissions to a Group... 39
2.5.4.1 Pre-requisites... 39
2.5.4.2 Command Syntax...39
2.5.5 Delete all Digipass-Related Data from Active Directory... 40
3
ODBC Database... 42
3.1 Database Support... 42
3.1.1 Unicode Support... 43
3.2 Embedded Database... 43
3.2.1 Service Account... 43
3.2.2 Database Administration Account... 44
3.2.3 Database Administration... 44
3.2.3.2 Changing the Digipass User's Password... 44
3.2.4 Connection Limitations... 45 3.3 Database Schema... 46 3.3.1 vdsControl Table... 46 3.3.2 vdsUser Table... 47 3.3.3 vdsUserAttr Table... 48 3.3.4 vdsDigipass Table... 48 3.3.5 vdsDPApplication Table... 49 3.3.6 vdsDPSoftParams Table... 49 3.3.7 vdsPolicy Table... 50 3.3.8 vdsComponent Table... 51 3.3.9 vdsBackEnd Table... 52 3.3.10 vdsDomain Table... 53 3.3.11 vdsOrgUnit Table... 53 3.3.12 vdsReport Table... 54 3.3.13 vdsReportFormat Table... 54 3.3.14 vdsConfiguration Table... 55 3.3.15 vdsOfflineAuthData Table... 55
3.4 Encoding and Case-Sensitivity... 56
3.5 Domains and Organizational Units... 56
3.5.1 Domains... 57
3.5.1.1 Master Domain... 57
3.5.1.2 Identifying the Domain for a Login Attempt...58
3.5.2 Organizational Units... 59
3.6 Database User Accounts... 60
3.6.1 Permissions on the Tables... 60
3.6.2 Access to Another Schema... 60
3.6.2.1 Modify vdsControl Table... 61
3.7 Database Connection Handling... 62
3.7.1 Multiple Data Sources... 62
3.7.2 Max. Connections... 62
3.7.3 Connection Wait Time... 62
3.7.5 Enable Load Sharing... 63
3.7.6 Reconnect Intervals... 63
3.8 DPDBADMIN... 64
3.8.1 Modify Database Schema... 64
3.8.2 Check Database Modifications... 66
3.8.2.1 Prerequisite Information...66
3.8.2.2 Check the Database Structure...67
3.8.2.3 Command Line Syntax...67
3.8.3 Remove Database Modifications... 68
3.8.3.1 Prerequisite Information...68
3.8.3.2 Modify Database Structure...68
3.8.3.3 Command Line Syntax...68
4
Sensitive Data Encryption... 70
4.1.1 Encrypted Data... 70
4.1.2 Which Encryption Algorithms can be used?... 70
4.1.3 Exporting Encryption Settings... 71
4.1.4 Digipass TCL Command-Line Administration... 71
5
Set Up Active Directory Permissions... 72
5.1 Permissions Needed by the Identikey Server... 72
5.1.1 Giving Permissions to the Identikey Server...72
5.2 Permissions Needed by Administrators... 73
5.2.1 Domain Administrators... 73
5.2.2 Delegated Administrators... 73
5.2.3 Reduced-Rights Administrators... 73
5.2.4 System Administrators... 74
5.3 Assign Administration Permissions to a User ... 75
5.4 Multiple Domains... 77
5.4.1 Scenario 1 – Each Identikey Server Handles One Domain... 77
5.4.2 Scenario 2 – One Identikey Server Handles All Domains... 78
5.4.3 Scenario 3 - Combination... 78
6
Backup and Recovery... 79
6.1 What Must be Backed Up... 79
6.1.1 Configuration Files... 80
6.1.2 SSL Certificates... 80
6.1.3 Audit Log Data... 80
6.1.3.1 Write to Text File...80
6.1.3.2 Write to ODBC Database...80
6.1.3.3 Write to Windows Event Log... 81
6.1.5 DPX files... 81
6.1.6 Data Store... 82
6.1.6.1 Data Source Settings...82
6.1.6.2 Backup Strategies... 82
6.1.6.3 Backup of PostgreSQL Embedded Database... 83
6.2 Recovery... 84
6.2.1 Active Directory... 84
6.2.2 ODBC Database... 85
6.2.2.1 Rebuild Identikey Server, Database Undamaged...85
6.2.2.2 Restore Database, Identikey Server Undamaged...86
6.2.2.3 Rebuild Identikey Server, Restore Database... 89
6.2.2.4 Copy Database from Other Identikey Server... 92
6.2.2.5 Rebuild Identikey Server, Copy Database... 94
7
Field Listings... 96
7.1 User Properties... 96
7.2 User Attributes... 98
7.3 Digipass Properties... 100
7.4 Digipass Application Tab... 102
7.5 Policy Properties... 103
7.6 Client Properties... 113
7.7 Back-End Server Properties... 115
7.8 Reports Properties... 116
7.9 Identikey Server Properties... 118
7.10 Data Changes Requiring a Restart of Identikey Server... 119
7.10.1 Changes to the Data Store... 119
7.10.1.1 Automatic Re-Loading of Cached Data... 119
7.10.1.2 Cached Data List...119
7.10.2 Changes to Configuration Settings... 120
8
Licensing... 121
8.1 How is Licensing Handled?... 121
8.2 Licensing Parameters... 121
8.2.1 Sample License File... 122
8.3 View License Information... 122
8.4 Obtain and Load a License Key... 123
8.5 Re-Licensing... 124
9
Web Sites... 125
9.1 Customizing the Web Sites... 125
9.2.1 Configuration Settings... 126
9.3 Form Fields... 127
9.3.1 Registration – Main Pages... 127
9.3.1.1 Registration – Challenge Page... 128
9.3.1.2 PIN Change... 129
9.3.1.3 Login Test – Main Page...130
9.3.1.4 Login Test – Challenge Page... 131
9.3.2 OTP Request Site... 132
9.3.2.1 Request Page... 132
9.4 Query String Variables... 133
9.4.1 Failure/Error Handling... 133
9.4.2 Query String Variable List... 134
9.4.3 Return Code Listing... 135
9.4.3.1 API Return Codes...135
9.4.3.2 CGI Errors...135 9.4.3.3 Internal Errors... 136
10 Login Options... 138
10.1 Login Permutations... 138 10.1.1 Login Methods... 138 10.1.2 Login Actions... 138 10.1.3 Login Variables... 138 10.1.4 Password Format... 139 10.1.5 Policy Settings... 13910.1.6 Response Only – Cleartext Combined Password Format...140
10.1.7 Response Only – CHAP/MS-CHAP/MS-CHAP2... 142
10.1.8 2-Step Challenge/Response – Cleartext Combined Password Format...142
10.1.9 Virtual Digipass... 144
11 Identikey Server Configuration Settings... 145
11.1 Identikey Server Configuration Wizard... 145
11.2 Redeploy Administration Web Interface... 145
11.3 Identikey Server Configuration... 147
11.3.1 Starting the Configuration GUI...147
11.3.2 General Section... 147
11.3.2.1 Server Location...148
11.3.2.2 Administration Session Settings... 148
11.3.2.3 Tracing...148
11.3.3 Communicators Section... 148
11.3.3.1 SOAP... 148
11.3.3.2 RADIUS... 149
11.3.4 Scenarios Section... 150
11.3.4.1 Authentication Scenario...150
11.3.4.2 Signature Validation Scenario...150
11.3.4.3 Provisioning Scenario... 150 11.3.4.4 Administration Scenario...151 11.3.4.5 Reporting Scenario...151 11.3.4.6 Audit Scenario... 151 11.3.4.7 Replication Scenario...151 11.3.4.8 Configuration Scenario... 152 11.3.5 Engines Section... 152 11.3.6 Storage Section... 152
11.3.6.1 ODBC Data Sources... 152
11.3.6.2 LDAP Data Sources...154
11.3.6.3 Encryption... 154
11.3.6.4 Advanced Configuration Settings...155
11.3.7 Auditing... 158 11.3.8 Replication Section... 159 11.3.8.1 Enable Replication...160 11.3.8.2 Source Server... 160 11.3.8.3 Destination Server...160 11.3.8.4 Queue... 160 11.3.9 Configuration File... 161
11.3.9.1 Windows - Example Configuration File...161
11.3.9.2 Linux Example Configuration File...168
11.4 Command Line Options... 176
11.4.1 Windows Service Control Manager... 176
11.4.2 Linux Runtime Configuration... 176
11.4.3 Running Identikey Server with Command Line Options... 176
11.4.3.1 Command Line Option flags...176
11.4.3.2 Windows... 177
11.4.3.3 Linux...177
11.5 Identikey Server Web Administration Configuration... 177
11.5.1 List... 177
11.5.1.1 Location... 177
11.5.1.2 Identikey Server Name...178
11.5.2 Add Identikey Server ... 178
11.5.3 Server Status... 178
11.5.3.1 Replication ...178
11.5.3.2 Admin Session...178
11.5.4 Server Configuration... 178
11.6 Web Administration Setup Tool... 180
11.6.1 Overview... 180
11.6.2 Running the Application... 180
11.6.4 Command Usage Examples... 182
11.6.4.1 Adding an Identikey Server and SSL Certificate... 182
11.6.4.2 Adding an Identikey Server... 183
11.6.4.3 Adding an SSL Certificate... 183
11.7 Message Delivery Component Configuration... 185
11.7.1 Required Information... 185
11.7.2 MDC Configuration GUI... 185
11.7.2.1 Modify Gateway Account Login Details... 185
11.7.2.2 Configure Internet Connection Details...186
11.7.2.3 Configure Tracing...186
11.7.2.4 Import HTTP Gateway settings... 187
11.7.2.5 Edit Advanced Settings...187
11.7.2.6 Export HTTP Gateway settings...188
11.7.2.7 Gateway Result Pages... 188
11.7.3 MDC Configuration File... 192
11.7.4 Configuration Settings... 194
11.8 Digipass TCL Command Line Utility... 197
11.8.1 Sample Configuration File... 197
12 Identikey Server Advanced Setup... 199
12.1 Create Organizational Structure... 199
12.1.1 Domains... 199
12.1.1.2 Create a New Domain...199
12.1.2 Organizational Units... 200
12.1.2.1 Create an Organizational Unit...200
12.1.3 Administrators... 200
12.1.3.1 Create a Delegated Administrator...200
12.1.3.2 Create a Global Administrator... 201
12.2 How To Set Up Virtual Digipass... 202
12.2.1 Pre-requisites... 202
12.2.2 Import Virtual Digipass records... 202
12.2.3 Set Up SMS Gateway... 202
12.2.4 Set Up Message Delivery Component... 202
12.2.5 Configure Identikey Server ... 203
12.2.6 Edit Identikey Server Policy... 203
12.2.6.1 Primary Virtual Digipass...203
12.2.6.2 Backup Virtual Digipass... 204
12.2.7 Test Virtual Digipass... 205
12.3 Connect the Administration Web Interface to a New Identikey Server... 206
12.3.1 Windows... 206
12.3.2 Linux... 206
12.4 Create Custom Report Definition... 207
12.5 Install a Commercial SSL Certificate...212
12.5.1 Windows... 212
12.5.2 Linux... 213
12.6 How to Set Up a Stand-Alone Identikey Server in RADIUS Environment...214
12.6.1 Information required... 214
12.6.2 Instructions... 214
12.7 How to Set Up Identikey Server as RADIUS Proxy Target...215
12.7.1 Information required... 215
12.7.2 Instructions... 215
12.8 How to Set Up Identikey Server as Intermediate Server... 217
12.8.2 Information required... 218
12.8.3 Instructions... 218
12.9 Add a New Domain to Identikey Server... 220
12.9.1 Solution 1: Install an Extra Identikey Server in the New Domain... 220
12.9.2 Solution 2: Configure New Domain for Existing Identikey Server...220
13 Reporting... 221
13.1 Reporting Overview... 221
13.1.1 What fields can be included in reports?... 221
13.1.2 How can these fields be grouped?... 221
13.1.3 How to define a Query... 221
13.1.3.1 Fields Available to Report Query Definition... 222
13.1.4 Report Permissions... 225 13.2 Types of Report ... 225 13.2.1 Standard Reports... 226 13.2.2 Custom Reports... 227 13.2.3 Formatting Templates... 227 13.3 Archiving Strategy... 227
14 Auditing... 228
14.1 Text File... 22814.1.1 Text File Name Variables... 228
14.1.2 Configure Auditing to Text File... 229
14.2 Windows Event Log... 230
14.3 ODBC Audit Message Database...231
14.3.1 Set up ODBC Database... 231
14.3.1.1 Create database...231
14.3.1.2 Create database schema... 231
14.3.1.3 Create Database Account(s)...232
14.3.1.4 Create DSN on Identikey Server machine...233
14.3.2 Configure Identikey Server... 233
14.3.3 Configure Audit Viewer... 234
14.4 Linux Syslog... 234
14.4.1 Configure the System Log... 235
14.4.2 Modify Configuration File... 235
14.4.3 Configure Identikey Server to Write Audit Messages to the Syslog...236
14.5 Live Connection - Identikey Server to Audit Viewer... 237
14.5.1 Configure Identikey Server... 237
14.5.2 Configure Audit Viewer... 237
15 Tracing... 238
15.1 Trace Message Types... 238
15.2 Trace Message Levels... 239
15.3 Trace Message Contents... 239
16 Digipass TCL Command-Line Administration... 240
16.1 Introduction... 240
16.1.2 Knowledge Requirements... 241
16.1.3 Data Store Connection... 241
16.1.4 Configuration File... 241
16.2 Using DPADMINCMD – Basics... 242
16.2.1 Using an Interactive TCL Command Prompt... 242
16.2.2 Running a Script... 243 16.2.3 Help... 244 16.2.4 Command Parameters... 244 16.2.5 Result Output... 244 16.2.6 Error Handling... 245 16.2.7 International Characters... 245 16.2.8 Syntax Notes... 245 16.2.9 Sample Scripts... 246
17 Replication... 248
17.1 Concepts... 248 17.1.1 Replication Queue... 249 17.1.2 Record-level Replication... 249 17.1.3 Replication Process... 250 17.1.4 Connection Handling... 252 17.1.4.1 Component Record... 252 17.1.5 Monitoring Replication... 252 17.1.5.1 Auditing...25217.1.5.2 Administration Web Interface... 252
17.1.6 Forwarding Replication Entries... 253
17.2 Configuring Replication ... 254
17.2.1 Active Directory... 254
17.2.2 ODBC Database... 255
17.2.2.1 Configure Replication to a Second Identikey Server... 255
17.2.2.2 Configure Replication to a Third or Subsequent Identikey Server ...257
17.2.2.3 Add Redundant Replication...259
18 Troubleshooting... 260
18.1 Troubleshooting Tools... 260
18.1.1 View Audit Information... 260
18.1.1.1 Windows Event Viewer... 260
18.1.1.2 Syslog... 260 18.1.1.3 Text file ... 260 18.1.1.4 ODBC Database... 261 18.1.2 Tracing... 261 18.2 How To Troubleshoot... 262 18.2.1 Connection Problems... 262 18.2.2 Installation Check... 262
18.2.2.1 Windows Registry Entries...262
18.2.2.2 Check Permissions...263
18.2.2.3 Default Policy and Component Created...263
18.2.3 Administration Web Interface Connection...264
18.2.4 Message Delivery Component... 264
18.2.4.1 Enable Tracing...264
18.2.5 Open Port Numbers on Firewall... 264
18.2.5.1 Incoming Ports...265
18.2.5.2 Outgoing Ports...265
18.2.6 SOAP/SSL Certificates... 265
19 Audit Messages... 266
19.1 Audit Message Listing... 266
20 Error and Status Codes... 279
20.1 Error Code Listing... 279
20.2 Status Code Listing... 285
21 Technical Support... 292
Index of Tables
Table 1: Custom Active Directory Object Classes... 17
Table 2: Custom Active Directory Object Attributes... 18
Table 3: Custom Active Directory Permission Property Sets... 22
Table 4: Saved Queries in Active Directory Users and Computers... 25
Table 5: Custom Active Directory Search criteria - Digipass...26
Table 6: Custom Active Directory Search criteria - Users... 28
Table 7: DPADadmin addschema Command Line Options...37
Table 8: DPADadmin checkschema Command Line Options... 37
Table 9: DPADadmin setupdomain Command Line Options...39
Table 10: DPADadmin setupaccess Command Line Options... 39
Table 11: ODBC Database Tables... 46
Table 12: vdsControl Table... 46
Table 13: vdsUser Table... 47
Table 14: vdsUserAttr Table...48
Table 15: vdsDigipass Table...48
Table 16: vdsDPApplication Table...49
Table 17: vdsDPSoftParams Table...49
Table 18: vdsPolicy Table...50
Table 19: vdsComponent Table... 51
Table 20: vdsBackEnd Table...52
Table 21: vdsDomain Table... 53
Table 22: vdsOrgUnit Table... 53
Table 23: vdsReport Table...54
Table 24: vdsReportFormat Table... 54
Table 25: vdsConfiguration Table... 55
Table 26: vdsOfflineAuthData Table...55
Table 27: Table Permissions Required...60
Table 28: Table Names in vdsControl...61
Table 29: DPDBADMIN addschema Command Line Options...65
Table 30: DPDBADMIN checkschema Command Line Options... 67
Table 31: DPDBADMIN dropschema Command Line Options... 68
Table 32: Encrypted Data Attributes - ODBC Database...70
Table 33: Encrypted Data Attributes - Active Directory...70
Table 35: User Attribute Fields...98
Table 36: Digipass Fields...100
Table 37: Digipass Application Fields...102
Table 38: Policy Fields...103
Table 39: Client Fields...113
Table 40: Back-End Server Fields...115
Table 41: Report fields... 116
Table 42: Identikey Server Fields...118
Table 43: License Parameters for Identikey Server... 121
Table 44: Configuration Settings for CGI Program... 126
Table 45: Form Fields for Main Registration Page... 127
Table 46: Form Fields for Registration Challenge Page... 128
Table 47: Form Fields for Server PIN Change Page... 129
Table 48: Form Fields for Main Login Test Page... 130
Table 49: Form Fields for Login Test Challenge Page...131
Table 50: Form Fields for OTP Request Page... 132
Table 51: Query String Variable List...134
Table 52: API Return Codes... 135
Table 53: CGI Error Return Codes... 135
Table 54: Internal Error Codes... 136
Table 55: Login Permutations - Response Only Cleartext Combined (1)...140
Table 56: Login Permutations - Response Only Cleartext Combined (2)...141
Table 57: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP2...142
Table 58: Login Permutations – 2-Step Challenge/Response Cleartext Combined...143
Table 59: Login Permutations – Virtual Digipass... 144
Table 60: MDC Audit Message Variables...190
Table 61: Message Delivery Component Configuration Settings...194
Table 62: Audit Text File Name/Path Variables...228
Table 63: Required Audit Database Tables...231
Table 64: vdsAuditMessage Required Fields...232
Table 65: vdsAuditMsgField Required Fields...232
Table 66: Required Account Permissions...233
Table 67: Audit Message Types and Syslog Priority... 234
Table 68: Tracing Message Types... 238
Table 69: Tracing Message Levels...239
Table 71: DPADMINCMD Help Commands... 244
Table 72: Registry Entries...262
Table 73: Permissions Required... 263
Table 74: List of Incoming Ports Used by the Identikey Server... 265
Table 75: List of Outgoing Ports Used by the Identikey Server...265
Table 76: Audit Messages List...266
Table 77: Error Code List...279
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. vdsOfflineAuthData 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
Name Class 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-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 Version-Number vasco-Component vasco-AdditionalAttribute vasco-Policy vasco-AllowedApplType vasco-Policy vasco-AllowedDPTypes vasco-Policy vasco-ApplicationNames vasco-Policy vasco-AssignmentMode vasco-Policy vasco-AssignSearchUpOUPath vasco-Policy vasco-Autolearn vasco-Policy vasco-BackEndAuth vasco-Policy
Name Class 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-OfflineTimeIntervals vasco-Policy vasco-OfflineMaxEvents vasco-Policy vasco-OneStepChalCheckDigit vasco-Policy vasco-OneStepChalLength vasco-Policy vasco-OneStepChalResp vasco-Policy vasco-OnLineSG vasco-Policy
Name Class 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 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.
Table 4: Saved Queries in Active Directory Users and Computers
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.
Tab Field Name Usage
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.
Field Name Usage 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.
2.4.1.2 Administrator and Identikey Server using different Domain Controllers
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.
2.4.1.4 Two Administrators Modifying the Same Attribute
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.
Preferred Server Only
The Identikey Server may be restricted to connecting only to the Domain Controller named in the above 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 Machine
This 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.
If you would prefer to change the setting manually, log into the Schema Master and change the value of the 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]
Table 7: DPADadmin addschema Command Line Options
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 Administrator
You 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
Table 9: DPADadmin setupdomain Command Line Options
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
2.5.5.1 Run Delete Script on a Domain
1. Get dpDeleteAll.vbs file from the CD – \Windows\Utilities\DpDeleteAll directory. Copy to the computer where you will run the command.
2. Open cmd prompt, logged in as domain admin in the domain required. 3. Enter the following:
cscript dpDeleteAll.vbs [<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.2 for you on the server.
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
PostgreSQL 8.2.5
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.
Linux
During Linux Simple Installation a postgres daemon user account is created, which is assigned the correct permissions to run the PostgreSQL server. The PostgreSQL server is registered as a Linux daemon which runs under the postgres account.
3.2.2
Database Administration Account
A single database administrator account called digipass is created when the embedded database is installed, with password digipassword. It has full administration and access rights to the database.
This account is used by the Identikey Server to connect to the database. If you use an SQL or database administration tool to connect to the database, you can also use this account.
If you want to change the password, you can do this using the pgAdmin III utility. See 3.2.3 Database
Administration below.
3.2.3
Database Administration
Windows
The full set of PostgreSQL administration tools are installed with the embedded database. For a full description, refer to the PostgreSQL documentation that is installed with the product.
The main tool to use is pgAdmin III, which is a graphical administration interface. This can be launched by clicking on the Start Button and selecting Programs -> PostgreSQL 8.2 -> pgAdmin III.
To connect to the database, right-click on the Servers -> PostgreSQL Database Server 8.2 node in the tree pane and select the Connect option. You will be prompted for the password for the digipass user – the default after installation is digipassword.
After logging in, you can perform a range of database administration tasks. See the online help for more details on what can be done with the utility.
The 6 Backup and Recovery section includes instructions on the pg_dump, pg_restore and vacuumdb utilities.
Linux
For Linux the PostgreSQL command line utilities are installed. For a full description of the command line utilities refer to the PostgreSQL documentation installed with the product.
3.2.3.2 Changing the Digipass User's Password
After logging in as described above, expand the Login Roles node in the tree pane. Right-click on the digipass
