Identikey Server Administrator Reference 3.1

Transcription

1 Identikey Server Administrator Reference 3.1

2 Disclaimer of Warranties and Limitations of Liabilities 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. Document Version: 1.3

3 Table of Contents Table of Contents 1 Introduction Available Guides Active Directory Schema Schema Extensions Added Object Classes Added Attributes Added Permission Property Sets Active Directory Auditing Auditing Inside the Active Directory Users and Computers Extension Custom Search Options Saved Queries Using the Custom Search for Digipass Using the Custom Search for Users Active Directory Replication Issues Old Data Used After Attribute Modified Single Identikey Server using more than one Domain Controller Administrator and Identikey Server using different Domain Controllers Multiple Identikey Servers Using Different Domain Controllers Two Administrators Modifying the Same Attribute Old Data Used Overwrites New Data Factors Affecting Replication Issues Solutions and Mitigations Digipass Cache DPADadmin Utility Extend Active Directory Schema Check Schema Extensions Check the Database Structure Command Line Syntax Set Up Digipass Containers in Domain Prerequisite Information Set Up Digipass Containers Command Syntax Assign Digipass Permissions to a Group Pre-requisites Command Syntax Delete all Digipass-Related Data from Active Directory Run Delete Script on a Domain Identikey Server Administrator Reference 3

4 Table of Contents 3 ODBC Database Database Support Unicode Support Embedded Database Service Account Database Administration Account Database Administration Changing the Digipass User's Password Connection Limitations Database Schema vdscontrol Table vdsuser Table vdsuserattr Table vdsdigipass Table vdsdpapplication Table vdsdpsoftparams Table vdspolicy Table vdscomponent Table vdsbackend Table vdsdomain Table vdsorgunit Table vdsreport Table vdsreportformat Table vdsconfiguration Table vdsofflineauthdata Table Encoding and Case-Sensitivity Domains and Organizational Units Domains Master Domain Identifying the Domain for a Login Attempt Organizational Units Database User Accounts Permissions on the Tables Access to Another Schema Modify vdscontrol Table Database Connection Handling Multiple Data Sources Max. Connections Connection Wait Time Idle Timeout Identikey Server Administrator Reference 4

5 Table of Contents Enable Load Sharing Reconnect Intervals DPDBADMIN Modify Database Schema Check Database Modifications Prerequisite Information Check the Database Structure Command Line Syntax Remove Database Modifications Prerequisite Information Modify Database Structure Command Line Syntax Sensitive Data Encryption Encrypted Data Which Encryption Algorithms can be used? Exporting Encryption Settings Digipass TCL Command-Line Administration Set Up Active Directory Permissions Permissions Needed by the Identikey Server Giving Permissions to the Identikey Server Permissions Needed by Administrators Domain Administrators Delegated Administrators Reduced-Rights Administrators System Administrators Assign Administration Permissions to a User Multiple Domains Scenario 1 Each Identikey Server Handles One Domain Scenario 2 One Identikey Server Handles All Domains Scenario 3 - Combination Backup and Recovery What Must be Backed Up Configuration Files SSL Certificates Audit Log Data Write to Text File Write to ODBC Database Write to Windows Event Log Write to Syslog Identikey Server Administrator Reference 5

6 Table of Contents DPX files Data Store Data Source Settings Backup Strategies Backup of PostgreSQL Embedded Database Recovery Active Directory ODBC Database Rebuild Identikey Server, Database Undamaged Restore Database, Identikey Server Undamaged Rebuild Identikey Server, Restore Database Copy Database from Other Identikey Server Rebuild Identikey Server, Copy Database Field Listings User Properties User Attributes Digipass Properties Digipass Application Tab Policy Properties Client Properties Back-End Server Properties Reports Properties Identikey Server Properties Data Changes Requiring a Restart of Identikey Server Changes to the Data Store Automatic Re-Loading of Cached Data Cached Data List Changes to Configuration Settings Licensing How is Licensing Handled? Licensing Parameters Sample License File View License Information Obtain and Load a License Key Re-Licensing Web Sites Customizing the Web Sites CGI Program Identikey Server Administrator Reference 6

7 Table of Contents Configuration Settings Form Fields Registration Main Pages Registration Challenge Page PIN Change Login Test Main Page Login Test Challenge Page OTP Request Site Request Page Query String Variables Failure/Error Handling Query String Variable List Return Code Listing API Return Codes CGI Errors Internal Errors Login Options Login Permutations Login Methods Login Actions Login Variables Password Format Policy Settings Response Only Cleartext Combined Password Format Response Only CHAP/MS-CHAP/MS-CHAP Step Challenge/Response Cleartext Combined Password Format Virtual Digipass Identikey Server Configuration Settings Identikey Server Configuration Wizard Redeploy Administration Web Interface Identikey Server Configuration Starting the Configuration GUI General Section Server Location Administration Session Settings Tracing Communicators Section SOAP RADIUS SEAL Identikey Server Administrator Reference 7

8 Table of Contents Scenarios Section Authentication Scenario Signature Validation Scenario Provisioning Scenario Administration Scenario Reporting Scenario Audit Scenario Replication Scenario Configuration Scenario Engines Section Storage Section ODBC Data Sources LDAP Data Sources Encryption Advanced Configuration Settings Auditing Replication Section Enable Replication Source Server Destination Server Queue Configuration File Windows - Example Configuration File Linux Example Configuration File Command Line Options Windows Service Control Manager Linux Runtime Configuration Running Identikey Server with Command Line Options Command Line Option flags Windows Linux Identikey Server Web Administration Configuration List Location Identikey Server Name Add Identikey Server Server Status Replication Admin Session Server Configuration Web Administration Setup Tool Overview Running the Application Available Commands Identikey Server Administrator Reference 8

9 Table of Contents Command Usage Examples Adding an Identikey Server and SSL Certificate Adding an Identikey Server Adding an SSL Certificate Message Delivery Component Configuration Required Information MDC Configuration GUI Modify Gateway Account Login Details Configure Internet Connection Details Configure Tracing Import HTTP Gateway settings Edit Advanced Settings Export HTTP Gateway settings Gateway Result Pages MDC Configuration File Configuration Settings Digipass TCL Command Line Utility Sample Configuration File Identikey Server Advanced Setup Create Organizational Structure Domains Create a New Domain Organizational Units Create an Organizational Unit Administrators Create a Delegated Administrator Create a Global Administrator How To Set Up Virtual Digipass Pre-requisites Import Virtual Digipass records Set Up SMS Gateway Set Up Message Delivery Component Configure Identikey Server Edit Identikey Server Policy Primary Virtual Digipass Backup Virtual Digipass Test Virtual Digipass Connect the Administration Web Interface to a New Identikey Server Windows Linux Create Custom Report Definition Query Filters Identikey Server Administrator Reference 9

10 Table of Contents 12.5 Install a Commercial SSL Certificate Windows Linux How to Set Up a Stand-Alone Identikey Server in RADIUS Environment Information required Instructions How to Set Up Identikey Server as RADIUS Proxy Target Information required Instructions How to Set Up Identikey Server as Intermediate Server Information required Instructions Add a New Domain to Identikey Server Solution 1: Install an Extra Identikey Server in the New Domain Solution 2: Configure New Domain for Existing Identikey Server Reporting Reporting Overview What fields can be included in reports? How can these fields be grouped? How to define a Query Fields Available to Report Query Definition Report Permissions Types of Report Standard Reports Custom Reports Formatting Templates Archiving Strategy Auditing Text File Text File Name Variables Configure Auditing to Text File Windows Event Log ODBC Audit Message Database Set up ODBC Database Create database Create database schema Create Database Account(s) Create DSN on Identikey Server machine Create DSN on Audit Viewer machine Identikey Server Administrator Reference 10

11 Table of Contents Configure Identikey Server Configure Audit Viewer Linux Syslog Configure the System Log Modify Configuration File Configure Identikey Server to Write Audit Messages to the Syslog Live Connection - Identikey Server to Audit Viewer Configure Identikey Server Configure Audit Viewer Tracing Trace Message Types Trace Message Levels Trace Message Contents Digipass TCL Command-Line Administration Introduction Knowledge Requirements Data Store Connection Configuration File Using DPADMINCMD Basics Using an Interactive TCL Command Prompt Running a Script Help Command Parameters Result Output Error Handling International Characters Syntax Notes Sample Scripts Replication Concepts Replication Queue Record-level Replication Replication Process Connection Handling Component Record Monitoring Replication Auditing Identikey Server Administrator Reference 11

12 Table of Contents Administration Web Interface Forwarding Replication Entries Configuring Replication Active Directory ODBC Database Configure Replication to a Second Identikey Server Configure Replication to a Third or Subsequent Identikey Server Add Redundant Replication Troubleshooting Troubleshooting Tools View Audit Information Windows Event Viewer Syslog Text file ODBC Database Tracing How To Troubleshoot Connection Problems Installation Check Windows Registry Entries Check Permissions Default Policy and Component Created Administration Web Interface Connection Message Delivery Component Enable Tracing Open Port Numbers on Firewall Incoming Ports Outgoing Ports SOAP/SSL Certificates Audit Messages Audit Message Listing Error and Status Codes Error Code Listing Status Code Listing Technical Support Support Contact Information Identikey Server Administrator Reference 12

13 Table of Contents Index of Tables Table 1: Custom Active Directory Object Classes Table 2: Custom Active Directory Object Attributes Table 3: Custom Active Directory Permission Property Sets Table 4: Saved Queries in Active Directory Users and Computers Table 5: Custom Active Directory Search criteria - Digipass...26 Table 6: Custom Active Directory Search criteria - Users Table 7: DPADadmin addschema Command Line Options...37 Table 8: DPADadmin checkschema Command Line Options Table 9: DPADadmin setupdomain Command Line Options...39 Table 10: DPADadmin setupaccess Command Line Options Table 11: ODBC Database Tables Table 12: vdscontrol Table...46 Table 13: vdsuser Table 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 Table 20: vdsbackend Table...52 Table 21: vdsdomain Table Table 22: vdsorgunit Table Table 23: vdsreport Table...54 Table 24: vdsreportformat Table...54 Table 25: vdsconfiguration Table 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 Table 31: DPDBADMIN dropschema Command Line Options Table 32: Encrypted Data Attributes - ODBC Database...70 Table 33: Encrypted Data Attributes - Active Directory...70 Table 34: User Fields...96 Identikey Server Administrator Reference 13

14 Table of Contents Table 35: User Attribute Fields...98 Table 36: Digipass Fields Table 37: Digipass Application Fields Table 38: Policy Fields Table 39: Client Fields Table 40: Back-End Server Fields Table 41: Report fields Table 42: Identikey Server Fields Table 43: License Parameters for Identikey Server Table 44: Configuration Settings for CGI Program Table 45: Form Fields for Main Registration Page Table 46: Form Fields for Registration Challenge Page Table 47: Form Fields for Server PIN Change Page Table 48: Form Fields for Main Login Test Page Table 49: Form Fields for Login Test Challenge Page Table 50: Form Fields for OTP Request Page Table 51: Query String Variable List Table 52: API Return Codes Table 53: CGI Error Return Codes Table 54: Internal Error Codes Table 55: Login Permutations - Response Only Cleartext Combined (1) Table 56: Login Permutations - Response Only Cleartext Combined (2) Table 57: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP Table 58: Login Permutations 2-Step Challenge/Response Cleartext Combined Table 59: Login Permutations Virtual Digipass Table 60: MDC Audit Message Variables Table 61: Message Delivery Component Configuration Settings Table 62: Audit Text File Name/Path Variables Table 63: Required Audit Database Tables Table 64: vdsauditmessage Required Fields Table 65: vdsauditmsgfield Required Fields Table 66: Required Account Permissions Table 67: Audit Message Types and Syslog Priority Table 68: Tracing Message Types Table 69: Tracing Message Levels Table 70: Tracing Message Contents Identikey Server Administrator Reference 14

15 Table of Contents Table 71: DPADMINCMD Help Commands Table 72: Registry Entries Table 73: Permissions Required Table 74: List of Incoming Ports Used by the Identikey Server Table 75: List of Outgoing Ports Used by the Identikey Server Table 76: Audit Messages List Table 77: Error Code List Table 78: Status Code List Identikey Server Administrator Reference 15

16 Introduction 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. Identikey Server Administrator Reference 16

17 Active Directory Schema 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 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 vasco- DPApplication 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. 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 vasco-component Class Digipass Configuration Container vasco- BackEndServer Class Digipass Configuration Container vasco-report Class Digipass Configuration Container vasco- ReportFormat vasco- Configuration Class Class Digipass Configuration Container Digipass Configuration Container vdsofflineauthdata Class Digipass Configuration Container Policy attributes. Attributes will commonly be shared via inheritance. Component attributes include the License Key for Identikey Server Components. Information required for connection to back-end servers. Support reporting functionality. Use this class to control the report scope. Support reporting functionality. This class contains the report format definition information. Configuration settings for the Identikey Server. Offline authentication data. This is included for future releases of Identikey Server. Identikey Server Administrator Reference 17

18 Active Directory Schema Added Attributes Table 2: Custom Active Directory Object Attributes Name Class vasco-serialnumber vasco-tokentype vasco-applicationnames vasco-applicationtypes vasco-linkvascodigipasstouserext vasco-tokenassigneddate vasco-graceperiod vasco-enablebvdp vasco-bvdpexpirydate vasco-bvdpusesleft vasco-directassignonly vasco-additionalattribute vasco-activationlocations vasco-activationcount vasco-lastactivationtime vasco-dpsoftstaticvector vasco-dpdescription vasco-serialnumber vasco-applicationname vasco-applicationnumber vasco-applicationtype vasco-dpblob vasco-active vasco-linkuserexttovascodigipass vasco-linkuserexttouser vasco-staticpassword vasco-localauth vasco-backendserverauth vasco-disable vasco-profile vasco-adminprivileges vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dptoken vasco-dpapplication vasco-dpapplication vasco-dpapplication vasco-dpapplication vasco-dpapplication vasco-dpapplication vasco-userext vasco-userext vasco-userext vasco-userext vasco-userext vasco-userext vasco-userext vasco-userext Identikey Server Administrator Reference 18

19 Active Directory Schema 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 Identikey Server Administrator Reference 19

20 Active Directory Schema 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 Identikey Server Administrator Reference 20

21 Active Directory Schema 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 Identikey Server Administrator Reference 21

22 Active Directory Schema 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. Identikey Server Administrator Reference 22

23 Active Directory Schema 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 Windows Vista & 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 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. Identikey Server Administrator Reference 23

24 Active Directory Schema 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 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. Identikey Server Administrator Reference 24

25 Active Directory Schema Table 4: Saved Queries in Active Directory Users and Computers Query Name Description Query Definition File Users with Digipass Users without Digipass Users with a DP User Account Users without a DP User Account All Users in the Domain who have one or more Digipass assigned directly. All Users in the Domain who have no Digipass assigned, directly or via a Linked User. All Users in the Domain who have a Digipass User Account. All Users in the Domain who do not have a Digipass User Account. users-with-dp.xml users-without-dp.xml users-with-dp-user-account.xml Assigned Digipass All Digipass in the Domain that are assigned. assigned-dp.xml Unassigned Digipass Locked DP User Accounts All Digipass in the Domain that are currently unassigned, excluding any Reserved Digipass. All Users in the Domain whose Digipass User Account is Locked. users-without-dp-user-account.xml unassigned-dp.xml locked-dp-user-accounts.xml Identikey Server Administrator Reference 25

26 Active Directory Schema 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 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 Digipass Type Application Name Application Type Digipass Assignment Reserved Description Last Serial Number in range. Digipass Type, eg. DP300. Wildcard* allowed. Application Name, eg. GO3DEFAULT. Wildcard* allowed. This will find Digipass that have an Active application of the specified name**. Application Type: Response Only, Challenge/Response. This will find Digipass that have an Active application of the specified type**. Assignment status: Assigned, Unassigned. Reserved status: Reserved, Not Reserved. Free text. Use this field to find Digipass records with the same text string within their Description field. Identikey Server Administrator Reference 26

27 Active Directory Schema 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 Backup Virtual Digipass Enabled Digipass Type Reserved Serial Number User Assignment Link 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**. 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. Conditions: Starts with, Ends with, Is (Exactly), Is Not. Values: Digipass Type (complete or partial) Conditions: Is (Exactly), Is Not. Values: 0 (No), 1 (Yes). This attribute is always present. Conditions: Starts with, Ends with, Is (Exactly), Is Not. Values: Serial Number, as seen in Digipass properties (complete or partial) 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 Digipass with serial number only *76 All Digipass with serial number ending in Using the Custom Search for Users To perform a search for Users: 1. Right-click on the Organizational Unit in which to search, or the domain root. Identikey Server Administrator Reference 27

28 Active Directory Schema 2. Click on Find 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 Digipass Assignment Link Digipass Back-End Authentication Digipass Local Authentication Digipass User Account Create Time Digipass User Account Disabled Digipass User Account Lock Count Usage 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. 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. 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. Conditions: Less than or equal to, Greater than or equal to, Is (Exactly), Is Not, Present, Not Present. Values: Number of seconds since 1 st Jan :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. Conditions: Is (Exactly), Is Not, Not Present. Values: 0 (No), 1 (Yes). If this attribute is not present, the account is not disabled*. 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. Identikey Server Administrator Reference 28

29 Active Directory Schema Field Name Usage Digipass User Account Locked Digipass User Account Modify Time Digipass User Account Password Digipass User Attributes Digipass User to User Link Conditions: Is (Exactly), Is Not, Not Present. Values: 0 (No), 1 (Yes). If this attribute is not present, the account is not locked*. Conditions: Less than or equal to, Greater than or equal to, Is (Exactly), Is Not, Present, Not Present. Values: Number of seconds since 1 st Jan :00:00 that the Digipass User account was last modified. This field does not have practical value as a search field, but is listed by Active Directory anyway. This field is not currently used. 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: Digipass Local Authentication Greater than or equal to 1 Identikey Server Administrator Reference 29

30 Active Directory Schema 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 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: 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 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 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 example timeline above shows the sequence of events. Identikey Server Administrator Reference 30

31 Active Directory Schema 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 :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 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. Identikey Server Administrator Reference 31

32 Active Directory Schema 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 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 DC-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 :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 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. Identikey Server Administrator Reference 32

33 Active Directory Schema 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 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 Solutions and Mitigations 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 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. Identikey Server Administrator Reference 33

34 Active Directory Schema Warning If the Identikey Server is installed on a Member Server, this server must be closely timesynchronized with the Domain Controller(s). If the server is not time-synchronized, the Policy may select an older record when comparing records in the Digipass cache with those on the Domain Controller. If the Identikey Server is installed on a Domain Controller, time-synchronization is assumed. Identikey Server Administrator Reference 34

35 Active Directory Schema 2.5 DPADadmin Utility 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 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. Identikey Server Administrator Reference 35

36 Active Directory Schema 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: 2. Type: cd <install dir>\bin 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 Check Schema Extensions for more information. Command Line Syntax dpadadmin addschema [ master schema_master] [ u user_name [ p password]] [-q] Identikey Server Administrator Reference 36

37 Active Directory Schema 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 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 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 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 Identikey Server Administrator Reference 37

38 Active Directory Schema 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 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 Prerequisite Information Domain Administrator You must be logged into the machine as a Domain Admin in the target domain 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 Command Syntax dpadadmin setupdomain [-config] [-domain <FQDN>] [-q] Identikey Server Administrator Reference 38

39 Active Directory Schema Table 9: DPADadmin setupdomain Command Line Options Option Description -config -domain <FQDN> OPTIONAL. Specifies that this is the Digipass Configuration Domain, so the Digipass-Configuration container must be created. 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 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 Pre-requisites You must be logged into the machine as a Domain Admin in the target domain Command Syntax dpadadmin.exe setupaccess -group <group name> [-domain <FQDN>] [-q] [-c] Table 10: DPADadmin setupaccess Command Line Options Option Description -group <group name> -domain <FQDN> MANDATORY. Specify the name of the group to assign the permissions. Double-quotes are required if there are any spaces. 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. -c OPTIONAL. Add the local computer to the group named. Identikey Server Administrator Reference 39

40 Active Directory Schema DPADadmin setupaccess Command Sample dpadadmin.exe setupaccess -group RAS and IAS Servers -q 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. Identikey Server Administrator Reference 40

41 Active Directory Schema 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 cscript dpdeleteall.vbs dm3.vasco.com -v Identikey Server Administrator Reference 41

42 ODBC Database 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 vendorspecific 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 Identikey Server Administrator Reference 42

43 ODBC Database PostgreSQL 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 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 re-installing. Otherwise, reinstallation of PostgreSQL will fail. Identikey Server Administrator Reference 43

44 ODBC Database 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 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 Database Administration below 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 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 node underneath and select Properties. Enter the new password, confirm it and click OK. Identikey Server Administrator Reference 44

45 ODBC Database 1. Run pgadmin III and connect as described above. 2. Expand the Login Roles node in the tree pane. 3. Right-click on the digipass node underneath and select Properties. 4. Enter the new Password and confirm it in Password (again). 5. Click on OK. 6. Open the Identikey Server Configuration utility: click on the Start Button and select Programs -> VASCO -> Identikey Server -> Identikey Server Configuration. 7. Click on the Storage section. 8. Click on the Identikey Server row in the ODBC Data Sources list and click the Edit... button. 9. Modify the Password field with the new password and click Test Connection. Identikey Server Configuration will test that it can connect to the database using the new password and inform you of the result. 10. If connection failed, make sure you have entered the password correctly and try again. If it still fails, cancel out of Identikey Server Configuration and try repeating the whole procedure from step Click OK. 12. Click OK to exit Identikey Server Configuration. When prompted to restart the Service, click Yes Connection Limitations The embedded database install leaves PostgreSQL with the default configuration, that connections to the database may only be made on the same machine. If you need to connect from another machine to the database, you need to update the configuration. In order to allow connection from another machine, you need to modify a PostgreSQL configuration file. Edit the configuration file with a text editor. This file can be found at: <install directory>\postgresql\data\pg_hba.conf (Windows) /opt/vasco/identikey/usr/local/pgsql/data/pg_hba.conf (Linux) At the bottom of this file, there is a list of rules for authenticating connections to the database, which by default will be: # TYPE DATABASE USER CIDR-ADDRESS METHOD # IPv4 local connections: host all all /32 md5 # IPv6 local connections: #host all all ::1/128 md5 Refer to the PostgreSQL documentation for more details. As an example, to permit access from IP address by the digipass user to the postgres database, add the following line directly below # Ipv4 local connections: host postgres digipass /32 md5 Identikey Server Administrator Reference 45

46 ODBC Database 3.3 Database Schema Digipass-related data is stored in a number of tables that are created using the DPDBADMIN command line utility: Table 11: ODBC Database Tables Table Name vdscontrol vdsuser vdsuserattr vdsdigipass vdsdpapplication vdsdpsoftparams vdspolicy vdscomponent vdsbackend vdsdomain vdsorgunit vdsreport vdsreportformat vdsconfiguration vdsofflineauthdata Notes This table is used to control various details about the database schema and connection. Contains Digipass User Account details. Authorization profiles/attributes (not used for all scenarios). Information about individual Digipass, including the Digipass User to which they are assigned. Data for Applications belonging to each Digipass, such as Server PIN and expected OTP length. Data required for Software Digipass Provisioning (the 'Static Vector' used to generate Activation Codes). Policy attributes. Attributes will commonly be shared via inheritance. Component attributes include the License Key for Identikey Servers. Back-End Server attributes. This includes RADIUS and LDAP server information. Domain list. Organizational Unit structure. Report definitions. Formatting templates for reports. Configuration settings for the Identikey Server. Offline authentication data. This is included for future releases of Identikey Server vdscontrol Table Table 12: vdscontrol Table Name Type Required? vdsname varchar(64) Yes vdsvalue varchar(512) vdsflags integer Primary Key: (vdsname) Foreign Keys: None Identikey Server Administrator Reference 46

47 ODBC Database vdsuser Table Table 13: vdsuser Table Name Type Required? vdsdomain varchar(255) Yes vdsuserid varchar(255) Yes vdsorgunit varchar(255) vdsusername varchar(64) vdsdescription varchar(1024) vdsphone varchar(64) vdsmobile varchar(64) vds varchar(64) vdsstaticpwd varchar(690)* vdslinkuserdomain varchar(255) vdslinkuserid varchar(255) vdslocalauth integer vdsbackendauth integer vdslockcount integer vdslocked integer vdsdisabled integer vdsprofiles** varchar(255) vdsadminprivileges varchar(255)* vdsofflineauthenabled integer vdscreatetime timestamp Yes vdsmodifytime timestamp Yes * This column contains binary data stored in base64-encoded format. ** This column is obsolete (replaced by the separate vdsuserattr table). Primary Key: (vdsdomain, vdsuserid) Foreign Keys: (vdsdomain) references vdsdomain (vdsdomain, vdsorgunit) references vdsorgunit (vdslinkuserdomain, vdslinkuserid) references vdsuser Identikey Server Administrator Reference 47

48 ODBC Database vdsuserattr Table Table 14: vdsuserattr Table Name Type Required? vdsdomain varchar(255) Yes vdsuserid varchar(255) Yes vdsattrgroup varchar(64) Yes vdsseqno integer Yes vdsname varchar(64) Yes vdsusagequal varchar(64) vdsvalue varchar(255) vdscreatetime timestamp Yes vdsmodifytime timestamp Yes Primary Key: (vdsdomain, vdsuserid, vdsattrgroup, vdsseqno) Foreign Keys: (vdsdomain, vdsuserid) references vdsuser (ON DELETE CASCADE) vdsdigipass Table Table 15: vdsdigipass Table Name Type Required? vdsserialno varchar(32) Yes vdsdomain varchar(255) Yes vdsorgunit varchar(255) vdsdptype varchar(32) vdsuserid varchar(255) vdsassigndate timestamp vdsgpexpires timestamp vdsbvdpenabled integer vdsbvdpexpires timestamp vdsbvdpusesleft integer vdsdirectassign integer vdsdpsoftparamsid varchar(64) vdsactivlocs varchar(1024) vdsactivcount integer Identikey Server Administrator Reference 48

49 ODBC Database Name Type Required? vdslastactivtime timestamp vdsdpdescription varchar(255) vdscreatetime timestamp Yes vdsmodifytime timestamp Yes Primary Key: (vdsserialno) Foreign Keys: (vdsdomain) references vdsdomain (vdsdomain, vdsorgunit) references vdsorgunit (vdsdomain, vdsuserid) references vdsuser (vdsdpsoftparamsid) references vdsdpsoftparams vdsdpapplication Table Table 16: vdsdpapplication Table Name Type Required? vdsserialno varchar(32) Yes vdsapplname varchar(32) Yes vdsapplno integer vdsappltype integer vdsactive integer vdsblob varchar(255) vdscreatetime timestamp Yes vdsmodifytime timestamp Yes Primary Key: (vdsserialno, vdsapplname) Foreign Keys: (vdsserialno) references vdsdigipass vdsdpsoftparams Table Table 17: vdsdpsoftparams Table Name Type Required? vdsdpsoftparamsid varchar(64) Yes Identikey Server Administrator Reference 49

50 ODBC Database Name Type Required? vdsstaticvector varchar(1024) Yes vdscreatetime timestamp Yes vdsmodifytime timestamp Yes Primary Key: (vdsdpsoftparamsid) Foreign Keys: None vdspolicy Table Table 18: vdspolicy Table Name Type Required? vdspolicyid varchar(60) Yes vdsdescription varchar(255) vdsparentpolicyid varchar(60) vdsdur integer vdsautolearn integer vdsspwdproxy integer vdsassignmode integer vdssearchupou integer vdsapplnames varchar(255) vdsappltype integer vdsdptypes varchar(255) vdsgraceperiod integer vdslocalauth integer vdsbackendauth integer vdsbackendprotocol varchar(32) vdsdefdomain varchar(255) vdsgrouplist varchar(1024) vdsgroupmode integer vdsoscr integer vdsosclength integer vdsoscchkdgt integer vdsbvdpenabled integer vdsbvdpmaxdays integer vdsbvdpmaxuses integer Identikey Server Administrator Reference 50

51 ODBC Database Name Type Required? vdschgpinallowed integer vdsselfassignsep varchar(8) vdscrmethod integer vdscrkeyword varchar(16) vdspvdprqstmeth integer vdspvdpkeyword varchar(16) vdsbvdprqstmeth integer vdsbvdpkeyword varchar(16) vdsitimewindow integer vdsstimewindow integer vdseventwindow integer vdssyncwindow integer vdsithreshold integer vdssthreshold integer vdscheckchal integer vdsonlinesg integer vdschkinactdays integer vdsotpsyncenabled integer vdsdcr integer vdschgwinpwdenabled integer vdschangewinpwdlength integer vdsclientgroupmode integer vdscreatetime timestamp Yes vdsmodifytime timestamp Yes vdslockthreshold integer Primary Key: (vdspolicyid) Foreign Keys: (vdsparentpolicyid) references vdspolicy vdscomponent Table Table 19: vdscomponent Table Name Type Required? vdscomponenttype varchar(60) Yes Identikey Server Administrator Reference 51

52 ODBC Database Name Type Required? vdslocation varchar(255) Yes vdspolicyid varchar(80) Yes vdsprotocolid varchar(32) vdstcpport integer vdssharedsecret varchar(690)* vdslicensekey varchar(1024) vdspubkey varchar(1024) vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes * This column contains binary data stored in base64-encoded format. Primary Key: (vdscomponenttype, vdslocation) Foreign Keys: (vdspolicyid) references vdspolicy vdsbackend Table Table 20: vdsbackend Table Name Type Required? vdsserverid varchar(80) Yes vdsprotocolid varchar(32) vdsdomain varchar(255) vdspriority integer vdsauthaddr varchar(128) vdsauthport integer vdsradacctaddr varchar(128) vdsradacctport integer vdsretries integer vdstimeout integer vdsradsharedsecret varchar(690)* vdsdirbasedn varchar(512) vdssecprincpldn varchar(512) vdssecprincplpwd varchar(32) vdsdirauth varchar(32) Identikey Server Administrator Reference 52

53 ODBC Database Name Type Required? vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes * This column contains binary data stored in base64-encoded format. Primary Key: (vdsserverid) Foreign Keys: None vdsdomain Table Table 21: vdsdomain Table Name Type Required? vdsdomain varchar(255) Yes vdsdescription varchar(1024) vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes Primary Key: (vdsdomain) Foreign Keys: None vdsorgunit Table Table 22: vdsorgunit Table Name Type Required? vdsdomain varchar(255) Yes vdsorgunit varchar(255) Yes vdsdescription varchar(1024) vdsparentorgunit varchar(255) vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes Primary Key: (vdsdomain, vdsorgunit) Foreign Keys: (vdsdomain) references vdsdomain (vdsdomain, vdsparentorgunit) references vdsorgunit Identikey Server Administrator Reference 53

54 ODBC Database vdsreport Table Table 23: vdsreport Table Name Type Required? vdsdomain varchar(255) Yes vdsreportid varchar(64) Yes vdsreportname varchar(64) Yes vdsreportdesc varchar(255) Yes vdsdatasource integer Yes vdsgrouplevel integer Yes vdsreporttype integer Yes vdsrunperms integer Yes vdschangeperms integer Yes vdstimefreq integer Yes vdsquerydef varchar(1024) Yes vdsuserid varchar(255) vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes Primary Key: (vdsdomain, vdsreportid) Foreign Keys: (vdsdomain) references vdsdomain (vdsdomain, vdsuserid) references vdsuser vdsreportformat Table Table 24: vdsreportformat Table Name Type Required? vdsdomain varchar(255) Yes vdsreportid varchar(64) Yes vdsfmtname varchar(64) Yes vdsfmtdef varchar(32768)* Yes vdscreatetime Timestamp Yes vdsmodifytime Timestamp Yes * This column contains binary data stored in base64-encoded format. Identikey Server Administrator Reference 54

55 ODBC Database Primary Key: (vdsdomain, vdsreportid, vdsfmtname) Foreign Keys: (vdsdomain, vdsreportid) references vdsreport vdsconfiguration Table Table 25: vdsconfiguration Table Name Type Required? vdsname varchar(512) yes vdsvalue varchar(512) vdscreatetime timestamp yes vdsmodifytime timestamp yes Primary Key: vdsname Foreign Keys: None vdsofflineauthdata Table Table 26: vdsofflineauthdata Table Name Type Required? vdscomponenttype varchar(60) yes vdslocation varchar(255) yes vdsdomain varchar(255) yes vdsuserid varchar(255) yes vdseventwindow integer vdseventcounter integer vdsstarttime timestamp vdsendtime timestamp vdsregenrequired integer vdscreatetime timestamp yes vdsmodifytime timestamp yes Primary Key: vdscomponenttype, vdslocation, vdsdomain, vdsuserid Foreign Keys: vdscomponenttype, vdslocation, vdsdomain, vdsuserid Identikey Server Administrator Reference 55

56 ODBC Database 3.4 Encoding and Case-Sensitivity When you create the database, depending on the database type, you may have the chance to select a collation sequence. The collation sequence determines both the sort order and the case-sensitivity of the database. If you do not have the chance to select the collation sequence, it is advisable to find out how it is already defined. The encoding used by the database is important when considering support for non-english languages. You must ensure that the database will be able to store the data in whatever languages may be used in your system. Case-sensitivity is of particular importance when looking up a Digipass User account. It determines whether the user must get the correct case for their UserId when logging in. For example, if your database collation sequence is case-sensitive, user JSmith would have to log in as exactly JSmith, not jsmith. If you want a case-insensitive User ID and domain lookup, and your database does not behave this way by default, you have two choices: Choose a case-insensitive collation sequence for the database. Use a configuration option in Identikey Server to convert User ID and Domain names to all upper or all lower case. Caution The configuration setting for case-sensitivity can be set up in the Identikey Server Configuration Wizard before data is entered into the database. This setting can be changed later using the Identikey Server Configuration utility. However, since the new setting value may invalidate existing Digipass User accounts and Domain records, additional work may be required. For example, if you have a User ID in upper or mixed case and you change the setting to convert to lower case, the Digipass User account with this User ID will need to be deleted and recreated. This setting is especially important for the Master Domain. If you plan to configure the Identikey Server to convert User IDs and Domains to upper case, change the name of the Master Domain before changing the case setting. See Master Domain for more information. The embedded database created by the installation program uses UTF-8 encoding. In addition, as this results in case-sensitive collation, the option to convert User IDs and domain names to lower case is set by default. 3.5 Domains and Organizational Units The concepts of Domain and Organizational Unit are present in Identikey Server for the purpose of grouping users. They closely match the concepts of the same names in Active Directory/LDAP, but they are not identical. Identikey Server Administrator Reference 56

57 ODBC Database Domains Domains are essentially separate sub-databases of Digipass User accounts and Digipass. All Digipass User accounts and Digipass must belong to a Domain. The Domain is used as a naming scope for the UserId it is allowed to have two different Digipass User accounts with the same UserId, so long as they are in different Domains Master Domain When Identikey Server is installed, a single Domain will be created in the database, the Master Domain. By default, all new Digipass User accounts and Digipass will be created in that Domain. A Domain must be chosen for a Digipass User account when it is created, as the Domain makes up part of the identification (primary key) for the account. A Digipass User account may not be moved to a different Domain. It must be deleted and recreated in the required Domain. Digipass, however, may be moved to the required Domain after import. The 'primary key' of the Digipass record consists only of its Serial Number, which cannot be duplicated in different Domains. A Digipass that is assigned to a Digipass User account must belong to the same Domain as the account. Therefore, you need to ensure that the correct numbers of Digipass are allocated to the different Domains. Administrators belonging to the Master Domain may be assigned administration privileges for all Domains in the database, or just their own Domain. Administrators belonging to any other Domain will have the assigned administration privileges for that Domain only. If you do not need to use the concept of Domains in your system, then you can leave all Digipass User accounts and Digipass in the Master Domain. You can designate a different Domain as the Master Domain using the Identikey Server Configuration Wizard. You can change it later using the Identikey Server Configuration utility, Storage section, Advanced Settings tab. Modify the Master Domain You might need to modify the domain used as the Master Domain if: You want new Digipass User accounts and Digipass records to be created in a different domain by default You want to change the name of the Master Domain The case used in the name of the Master Domain will not be compatible with Identikey Server configuration settings For instructions on changing the domain used as the Master Domain, see Master Domain in Advanced Configuration Settings. Identikey Server Administrator Reference 57

58 ODBC Database Identifying the Domain for a Login Attempt As the Domain is part of the naming scope for a Digipass User account, the Domain must be identified when a user attempts to log in. Image 1: Domain Identification Logic When Windows Back-End Authentication is used, the Domain of a Digipass User account must match the Domain of their corresponding Windows (Active Directory) user account. In this situation, the Use Windows User Name Resolution feature would typically be used, in case the same user logs in with different Windows user name formats (DOMAIN\userid, userid@domain.com, userid). You can enable this feature using the Identikey Server Configuration interface, Configure Advanced Settings screen. Without Windows name resolution, a simple rule is applied to identify the Domain of a user who is logging in: if the UserId is in the form userid@domain, and there is a Domain with the given domain name, that Domain will be used. In that case, the UserId will have part removed. Otherwise, the whole UserId will remain as userid@domain and no Domain will be identified. Identikey Server Administrator Reference 58

59 ODBC Database If a Domain cannot be identified via name resolution, the applicable Policy will be checked. If a Default Domain is specified in the Policy, it will be used for the login. If no Default Domain is specified in the Policy, the Master Domain will be used. The Master Domain is a configuration setting Organizational Units Within a Domain, Organizational Units can be used to group Digipass User accounts and Digipass. They are primarily used in Identikey Server to allocate unassigned Digipass to groups of users such as offices or departments and to provide delegated administration by user group. Organizational Units can be created as a hierarchy, in a similar way to Active Directory/LDAP. It is not permitted to create a circular chain in the hierarchy. Digipass User accounts and Digipass do not have to belong to an Organizational Unit. If you do not need to use the Organizational Unit feature, you can ignore it. Organizational Units are not used as a naming scope in the same way as Domains. It is permitted to move Digipass User accounts and Digipass between Organizational Units whenever required. However, a Digipass that is assigned to a Digipass User Account must belong to the same Organizational Unit, as well as the same Domain. Upon assignment, or upon moving the Digipass User Account, the Digipass is moved automatically. It is not permitted to move an assigned Digipass instead, you must move the Digipass User Account, which may have other Digipass assigned also. Organizational Units have no effect on the authentication process, with the exception of Auto- and Self-Assignment the Digipass to be assigned must be in the same Organizational Unit as the Digipass User Account. However, if you enable the 'Search up Organizational Unit Hierarchy' Policy setting, the Digipass may be located higher up the Organizational Unit structure, provided it is still in the same Domain. Identikey Server Administrator Reference 59

60 ODBC Database 3.6 Database User Accounts It is important to consider which database user accounts will be utilized when installing, running and administering Identikey Server. There are a few main roles that need to be considered: Schema creator. A database user account is needed to create the tables used by Identikey Server. Typically this would be either a fully privileged DBA account, or the account that will own the schema. Schema owner. This may be the same as the schema creator. If not, the schema creator can transfer ownership of the new tables after they have been created. Identikey Server account. This may be the same as the schema creator or owner, but you may prefer to use an account with less privileges. A few elements need to be taken into account when setting up these database user accounts Permissions on the Tables The following permissions are required by the Identikey Server account: Table 27: Table Permissions Required Table Permissions Required vdscontrol SELECT, INSERT*, UPDATE * All other tables SELECT, INSERT, UPDATE, DELETE Access to Another Schema Depending on the database type, there may be a problem with the Identikey Server database user account accessing the tables from another schema/user account. Identikey Server will access the tables according to the table names that are defined in the vdscontrol table. If the tables are not accessible to the Identikey Server account without qualifying the table name (eg. schema.table), there are a few ways to solve the problem: Set the default schema or database. Some databases allow you to specify which schema or database a database user account will use by default when they log in. This may be a setting in the database itself or the ODBC data source Create views. You can create a view in the Identikey Server account's own schema for each table, that provides access to the table. The view names should match the table names. However, be careful that your database type permits the necessary INSERT, UPDATE and DELETE operations on the views (see the table above). Some database types provide only limited support for those operations or disallow them all. * The Identikey Server does not need INSERT and UPDATE permission on the vdscontrol table itself. However, when the Identikey Server Configuration Wizard and the Identikey Server Configuration utility are used to configure Storage Advanced Settings, the same database user account is used as the Identikey Server, and at this time the INSERT and UPDATE permissions are needed. Identikey Server Administrator Reference 60

61 ODBC Database Modify the vdscontrol table. Provided that all applicable database user accounts need the schema qualifier in front of the table names, you can safely modify the vdscontrol table entries to add the schema qualifier (see below). If you have just one Identikey Server account, this will be safe. Another possible solution is to create a vdscontrol table in each applicable database user account's schema, that contains the necessary schema qualifier. However this is not recommended, as it is complex to set up and there are other settings in the vdscontrol table other than the table names. It would be easy to end up with different settings in each table Modify vdscontrol Table There are two parts to this solution. Firstly, to make sure that the vdscontrol table itself can be accessed; secondly, to update the remaining table names using the vdscontrol table. The Identikey Server component uses a configuration setting in its configuration file identikeyconfig.xml to identify the vdscontrol table name: VASCO->Storage->ODBC->Data-Sources->Data-Sourcesnn->Control-Table where nn is 01 for the first data source, 02 for the next, and so on. Each data source must be configured separately. Modification of the vdscontrol table entries that define the table names must be performed using your database's SQL utility. The following entries in vdscontrol are used to define the table names: Table 28: Table Names in vdscontrol Table vdsuser vdsuserattr vdsdigipass vdsdpapplication vdsdpsoftparams vdspolicy vdscomponent vdsbackend vdsdomain vdsorgunit vdsreport vdsreportformat vdsconfiguration VdsOfflineAuthData vdsname user_table user_attr_table dp_table dpappl_table dpsoft_params_table policy_table comp_table backend_table domain_table org_table report_table report_format_table configuration_table offlineauthdata_table Identikey Server Administrator Reference 61

62 ODBC Database 3.7 Database Connection Handling The Identikey Server can be configured with a few settings that control the connection to the database. These settings can be found in the Identikey Server Configuration utility Multiple Data Sources It is possible to make more than one database available to the Identikey Server by creating additional databases and corresponding ODBC data sources. The additional database(s) can be used for redundancy and/or simple load sharing. If this is done, it is critical that the second and subsequent databases are synchronized with the first database. You will have to use the methods available to your database type, according to the database vendor's instructions. Typical methods include mirroring, shadow databases and instantaneous replication. Simply by configuring a second data source, if all connections to the main data source fail and cannot be reopened, the Identikey Server will open connections to the second data source. Similarly, a third data source can be used when the first and second are both unavailable Max. Connections There is a configurable limit on the number of connections to the data source that the Identikey Server will have open at one time. This will prevent too many connections being opened to the database in case of peak load. However, each request uses a connection for its duration, so the number of connections effectively limits the number of requests that can be concurrently executed. It may improve performance to increase this setting, when there are a lot of concurrent requests provided that the database is able to handle the increased load. The effect of this setting depends on the characteristics of your ODBC driver and database. Some ODBC drivers may not open a separate connection to the database for each connection that is made to it; they may set up a 'pool' of connections to the database or they may even just maintain a single connection Connection Wait Time When the Identikey Server already has the maximum number of connections open and a new request arrives, it will wait a configurable amount of time for a connection to become available (unless the Enable Load Sharing option is used, see below). You may want to reduce this waiting time, to reduce the impact of an overload of requests. Alternatively you may want to increase the waiting time, to make it less likely that a request will be rejected due to a temporary 'spike' of requests. Identikey Server Administrator Reference 62

63 ODBC Database Idle Timeout After a period of peak load, there may be a large number of connections open to the database. The Idle Timeout setting can be used to configure how quickly the connections are closed after being idle for a period of time. It may reduce the load on the database to close these connections quickly. Alternatively, if the load is very irregular but is often high, you may prefer to keep idle connections open for longer Enable Load Sharing A simple form of load sharing can be implemented if you make a second database available to the Identikey Server. In fact, any number of databases can be added to the list of data sources, and the load can be shared across all of them. If you have more than one database available and the Enable Load Sharing option is used, the Identikey Server will open connections to the second database when it would exceed the maximum number of connections it is allowed to have to the first database. Similarly, it will open connections to the third database when it has reached the maximum for the second, and so on. In general, connections to the first database will be used when available, in preference to connections to any other database Reconnect Intervals After the first data source has become unavailable, the Identikey Server will attempt at intervals to reconnect, even if it has successfully failed over to a second data source. It will always use the first data source in preference to the others. The Min. Reconnect Interval and Max. Reconnect Interval settings control the minimum and maximum intervals between retries respectively. The interval will start at the minimum and increase in steps until the maximum is reached. After that, the interval will stay at the maximum. Identikey Server Administrator Reference 63

64 ODBC Database 3.8 DPDBADMIN Modify Database Schema The addschema command is used to create all required tables in an existing database, if they are not already there. Each table 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 an administrator before Identikey Server is installed. It may be necessary to go through an approval process in your company before running this command. You may also need to have a database administrator run the command for you. This depends on your company s structure and rules for control of the database. This command may also be used to create the tables required for auditing to an ODBC database. Prerequisite Information Database Administrator Account In order to successfully modify the database structure, you will need the username and password of a database administrator account that is able to make changes to the database schema for example, creating tables. You must pass these credentials to the command in the parameters. Database Name You will need the ODBC Data Source Name of the database (as registered with Windows or Linux as an ODBC Data Source). Master Domain Name You can specify the name of the Master Domain (see Master Domain) when you add the database schema. However if you do not do it at that time, the Configuration Wizard can change it. UserID/Domain Name Conversion The Case Conversion option for UserIDs and Domain names may be specified (see 3.4 Encoding and Case- Sensitivity for more information) during the database schema modification. Alternatively, the setting may be modified using the Configuration Wizard. This should, however, be finalised before User data is entered into the data store. Modify the Database Structure 1. Follow the instructions for the installation that you have: 2. Type: a. For Windows, open a command prompt and navigate to the installation s bin directory by typing: cd <install dir>\bin dpdbadmin addschema u user_name p password -d dsn Identikey Server Administrator Reference 64

65 ODBC Database 3. See below for more details regarding the required parameters. 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. Command Line Syntax dpdbadmin addschema -d dsn [ u user_name] [ p password] [-domain domain_name] [-case case_conversion] [-vdsuser alternatename] [-vdsuserattr alternatename] [-vdsdomain alternatename] [-vdscontrol alternatename] [-vdsdigipass alternatename] [-vdsdpapplication alternatename] [-vdspolicy alternatename] [vdsbackend alternatename] [-vdscomponent alternatename] [-vdsorgunit alternatename] [-vdsdpsoftparams alternatename] [-vdsreport alternatename] [-vdsreportformat alternatename] [-audit] [-noserver] [-nouser] [-utf8factor factor] [-q] [-v] [-l file_name] Table 29: DPDBADMIN addschema Command Line Options Option Description -d ODBC Data Source Name (DSN) -u User name of a database administrator (if required). -p Password of the database administrator. This option may be omitted if they have a blank password. -domain -case vdsuser vdsuserattr vdsdomain vdscontrol vdsdigipass vdsdpapplication vdspolicy vdsbackend vdscomponent vdsorgunit vdsdpsoftparams vdsreport vdsreportformat vdsconfiguration vdsofflineauthdata -audit -noserver Specify the Master Domain to be used. If not specified, it will be master. The Domain will be created if it does not already exist. Specify to convert User IDs and domain names to either upper or lower case. The value must be either upper or lower. Alternative name for the Digipass User table to be created. Alternative name for the Digipass User Attribute table to be created. Alternative name for the Domain table to be created. Alternative name for the Control table to be created. Alternative name for the Digipass table to be created. Alternative name for the Digipass Application table to be created. Alternative name for the Policy table to be created. Alternative name for the Back-end Server table to be created. Alternative name for the Component table to be created. Alternative name for the Organizational Unit table to be created. Alternative name for the DPSoft Parameters table to be created. Alternative name for the Report Definition table to be created. Alternative name for the Report Format table to be created. Alternative name for the Configuration table to be created. Alternative name for the Offline Authentication Data table to be created. Create the Audit tables. Do not create the main tables used by the Identikey Server. This should only be used with the -audit Identikey Server Administrator Reference 65

66 ODBC Database Option Description -nouser -utf8factor option, when you only want to create the auditing tables. Do not create Digipass User table. This option is not currently supported. On certain databases (such as Oracle and DB2), column sizes are specified in bytes, not characters, by default. When UTF-8 encoding is used to store data, for full Unicode support, one character may be represented as more than one byte. Normally 2 or 3 characters are used, depending on the language, but some characters require 4. If your data will include a lot of non-english characters, you can increase the size of certain columns by a factor to allow for the extra bytes. The value of the parameter should be 2, 3 or 4. Typically, 3 is sufficient. The columns affected by this are the User Name (not User ID) and various Description fields. On other databases, column sizes are specified in characters, and this parameter is not needed. -q Quiet mode, will not output commentary text. -v Verbose mode. -l Log output to file file_name. DPDBADMIN addschema Command Sample dpdbadmin addschema u DBAdmin p pwd3498 -d UserDb -domain mydomain -case lower This command will modify the database structure of the ODBC database with the data source name of UserDb. It uses a database administrator account with the User ID of DBAdmin and password pwd3498. A non-default Master Domain will be used, called mydomain. It specifies to convert domain names and User IDs to lower case. dpdbadmin addschema u DBAdmin p pwd3498 -d AuditDb -audit -noserver This command will create only the auditing tables in the ODBC database with the data source name of AuditDb. It uses a database administrator account with the User ID of DBAdmin and password pwd Check Database Modifications The checkschema command is called from the Identikey Server Configuration Wizard to check that all required database changes have been applied. Each table and field is checked individually to see if it exists within the database, but it will not be added if it does not exist Prerequisite Information Database User Account Ensure that you know the username and password of a database user account for the database to be checked. It is suggested to use the Identikey Server database user account, as the database tables are required by that account, Database Name You will need the Data Source Name of the database (as registered with Windows or Linux as an ODBC Data Source). Identikey Server Administrator Reference 66

67 ODBC Database Check the Database Structure 1. Open a command prompt and go to the installation s bin directory by typing: a. For Windows, open a command prompt and navigate to the installation s bin directory by typing: cd <install dir>\bin b. For Linux go to the location in which the ODBC data source was created. 2. Type dpdbadmin checkschema u user_name p password -d dsn 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 Command Line Syntax dpdbadmin checkschema -d dsn [ u user_name] [ p password] [-audit] [-noserver] [-vdscontrol alternatename] [-q] [-v] [-l file_name] Table 30: DPDBADMIN checkschema Command Line Options Option Description -d ODBC Data Source Name (DSN) -u User name of a database user account (if required). -p Password of the database account. This option may be omitted if they have a blank password. -audit -noserver vdscontrol Check the Audit tables. Do not check the main tables used by the Identikey Server. This should only be used with the -audit option, when you only want to check the auditing tables. Alternative name for the Control table. -q Quiet mode, will not output commentary text. -v Verbose mode. -l Log output to file file_name. DPDBADMIN checkschema Command Sample dpdbadmin checkschema u DBAdmin p pwd3498 -d UserDb Remove Database Modifications This command removes from a database the tables added by the addschema command. It may be necessary to go through an approval process in your company before running this command. You may also need to have a database administrator run the command for you. Identikey Server Administrator Reference 67

68 ODBC Database Prerequisite Information Database Administrator Account In order to successfully modify the database structure, you will need the username and password of a database administrator account that is able to make changes to the database structure for example, dropping tables. You must pass these credentials to the utility in the parameters of the command. Database Name You will need the Data Source Name of the database (as registered with Windows or Linux as an ODBC Data Source). This DSN must be registered on the computer from which the command line utility wil be run Modify Database Structure 1. Open a command prompt and navigate to the installation s bin directory by typing: 2. Type: a. For Windows, open a command prompt and navigate to the installation s bin directory by typing: cd <install dir>\bin b. For Linux go to the location in which the ODBC data source was created. dpdbadmin dropschema u user_name p password -d dsn 3. See below for more details regarding the required parameters. 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 Command Line Syntax dpdbadmin dropschema -d dsn [ u user_name] [ p password] [-audit] [-noserver] [-nouser] [-vdscontrol alternatename] [-q] [-v] [-l file_name] Table 31: DPDBADMIN dropschema Command Line Options Option Description -d ODBC Data Source Name (DSN) -u User name of a database administrator. -p Password of the database administrator. This option may be omitted if they have a blank password. -audit -noserver -nouser Drop the Audit tables. Do not drop the main tables used by the Identikey Server. This should only be used with the -audit option, when you only want to drop the auditing tables. Do not delete Digipass User table. This option is not currently supported. -q Quiet mode, will not output commentary text. Identikey Server Administrator Reference 68

69 ODBC Database Option Description -v Verbose mode. -l Log output to file file_name. DPDBADMIN checkschema Command Sample dpdbadmin dropschema u DBAdmin p pwd3498 -d UserDb Identikey Server Administrator Reference 69

70 Sensitive Data Encryption 4 Sensitive Data Encryption Sensitive data is encrypted by Identikey Server using an embedded key. If needed, this encryption may be strengthened by adding a custom key using the Identikey Server Configuration utility. The embedded and custom keys are subjected to a logical XOR process to produce a new key derived from both. You may also choose a different encryption algorithm (Cipher) if you prefer. All Identikey Servers MUST share the same encryption settings. Note Encryption settings must be set before importing any Digipass. If you change the settings at a later date, all Digipass records will become invalidated, and require deleting and re-importing Encrypted Data Table 32: Encrypted Data Attributes - ODBC Database Column Table vdsstaticpwd vdsadminprivileges vdssharedsecret vdssharedsecret vdsuser vdsuser vdscomponent vdsbackend Table 33: Encrypted Data Attributes - Active Directory Column vasco-staticpassword vasco-adminprivileges vasco-sharedsecret vasco-sharedsecret Table vasco-userext vasco-userext vasco-component vasco-backendserver Which Encryption Algorithms can be used? 3DES (default) 3DES with 3 keys AES Identikey Server Administrator Reference 70

71 Sensitive Data Encryption Exporting Encryption Settings Encryption settings may be exported to a password-protected text file from the Identikey Server Configuration utility. This file must then be loaded to other Identikey Servers see Encryption for instructions. If using Active Directory as the data store for Identikey Server, the Digipass Extension for Active Directory Users and Computers snap-in may be used to export the settings: 1. Open Active Directory Users and Computers. 2. Right-click on the Users container and select the Digipass Extension Encryption Settings option. 3. In the Configure Encryption Settings dialog, click the Import... button. 4. Browse to the encryption settings file. 5. Click on OK. 6. Enter the required password. 7. Click on OK Digipass TCL Command-Line Administration If using Active Directory as the data store for Identikey Server, the customized encryption settings must be loaded into Digipass TCL Command-Line Administration if you use it to import Digipass. 1. Open the file <installation directory>\bin\dpadmincmd.xml in a text editor (or XML editing tool). 2. Open the file <installation directory>\bin\identikeyconfig.xml in a text editor (or XML editing tool). 3. Copy and paste the whole VASCO -> Encryption section from Identikey Server, overwriting the same section in dpadmincmd.xml. 4. Save dpadmincmd.xml and exit the editors. Identikey Server Administrator Reference 71

72 Set Up Active Directory Permissions 5 Set Up Active Directory Permissions 5.1 Permissions Needed by the Identikey Server The Identikey Server Service runs under the 'Local System' account rather than as a named user account. Therefore, when connecting to Active Directory, the Identikey Server connects as the computer account, not a user account. The permissions that it has within Active Directory are the permissions of the computer account. An important exception to this occurs if you install the Identikey Server onto a Domain Controller. Any Service running as 'Local System' on a Domain Controller has all possible permissions to that Domain. In this case, no additional setup of permissions is required. Therefore, the rest of this section applies to the case where the Identikey Server is not on the Domain Controller. During installation, the computer account is added to the built-in 'RAS and IAS Servers' group in the Domain, as it will require the permissions assigned by default to this group. In order to function correctly, the Identikey Server requires the following permissions in Active Directory, that are not granted to 'RAS and IAS Servers' by default: Read access to the Digipass Configuration Container Read access to all User accounts (or at least, all who might need to be authenticated by the Identikey Server) Write access to the new attributes that are added to the User class for Identikey Server (these are in the auxiliary class vasco-userext) Full control over all Digipass (vasco-dptoken) and Digipass Application (vasco-dpapplication) objects Create and delete permission for Digipass (vasco-dptoken) objects in Organizational Units and containers (specifically the Digipass-Pool and Users containers) Giving Permissions to the Identikey Server During installation, these additional permissions are granted to the 'RAS and IAS Servers' group automatically. There is also a manual way to grant these permissions, by running the 'setupaccess' command at the command prompt: dpadadmin.exe setupaccess -group RAS and IAS Servers See 2.5 DPADadmin Utility for more information on the setupaccess command. As mentioned above, this is not necessary if the Identikey Server is installed onto a Domain Controller. Identikey Server Administrator Reference 72

73 Set Up Active Directory Permissions 5.2 Permissions Needed by Administrators Domain Administrators Domain Administrators already have all required permissions within their Domain Delegated Administrators The term 'Delegated Administrators' is used here to refer to administrators who have been delegated control over an Organizational Unit. Generally speaking, they have administrative control over the user and computer accounts within their Organizational Unit. See the Digipass Records topic in the Product Guide for more information on possible approaches to delegating Digipass administration. By default, these administrators will be able to view the Digipass User Account data for their users and the Digipass that are located within their Organizational Unit. However, they will not be able to modify any of that data or assign Digipass. If you wish to delegate responsibility for all Digipass-related administration within an Organizational Unit, the following additional permissions are required by the Delegated Administrator: Within the scope of the Organizational Unit, Write permission to the new attributes that are added to the User class for Identikey Server (these are in the auxiliary class vasco-userext) you can add Write permissions for each individual Property Set or if appropriate, grant 'Write All Properties' permission Within the scope of the Organizational Unit, Full Control over all Digipass (vasco-dptoken) and Digipass Application (vasco-dpapplication) objects Create and Delete permission for Digipass (vasco-dptoken) objects within the Organizational Unit If the Delegated Administrator should be allowed to assign Digipass from the Digipass Pool to their users, they need: the Delete Digipass objects permission in the Digipass-Pool container Write All Properties permission on Digipass objects in the Digipass-Pool container If the Delegated Administrator should be allowed to move unassigned Digipass back to the Digipass-Pool, they need Create Digipass objects permission in the Digipass-Pool container Reduced-Rights Administrators The term 'Reduced-Rights Administrator' is used here to refer to administrators who are granted permissions to perform only selected Digipass-related administration tasks. They may be granted these permissions within the scope of the whole Domain, or only within an Organizational Unit. Identikey Server Administrator Reference 73

74 Set Up Active Directory Permissions An example is a Helpdesk operator who is permitted to troubleshoot Digipass operations, but not to assign/unassign Digipass to/from users. By default, all users have read access to everything in the Active Directory. The modification permissions that can be granted to this kind of administrator are: Write permission for any of three Property Sets on the Digipass User Account fields: Digipass User Account Information all attributes except those covered by the other two Property Sets, including Authorization Profiles/Attributes Digipass User Account Link the link attribute used to share a Digipass between two user accounts Digipass User Account Stored Password the Stored Password attribute Write permission for any individual properties on Digipass objects, except for one Property Set that is defined to control the Digipass assignment link Write permission for any individual properties on Digipass Application objects, except for one Property Set that is defined to include the Digipass 'blob' that is required for any administrative operation such as Reset PIN, Test, Set Event Counter, etc. Create and delete permission on Digipass and Digipass Application objects If the administrator should be allowed to move Digipass, they need: the Delete Digipass objects and Create Digipass objects permissions in the relevant Domain and/or Organizational Unit Write All Properties permission on Digipass objects Note This can be necessary for assigning Digipass to users, because a move from one location to another is controlled by permissions to delete from the source and create in the destination System Administrators The term 'System Administrator' is used here to refer to an administrator who will be responsible for management of records which affect the configuration and running of the Identikey Server, rather than Digipass User Accounts and Digipass. They need permissions within the Digipass Configuration Container to create, modify and delete these objects: Component (vasco-component) Policy (vasco-policy) Report (vasco-report) Report Format (vasco-reportformat) Back-End Server (vasco-backendserver) Identikey Server Administrator Reference 74

75 Set Up Active Directory Permissions Server Configuration (vasco-configuration) In practice, System Administrators can typically be given full control over the Digipass-Configuration container. If you wish to grant more limited permissions, this can be handled with the standard Active Directory permissions on these objects within the scope of the container. 5.3 Assign Administration Permissions to a User Note This example assumes that the administrator's User account has read permissions for all User records already. To grant permissions to manage Digipass records, you will need to follow these steps: 1. Right-click on the Organizational Unit in which to assign permissions. in the Active Directory Users and Computers extension. 2. Select Delegate Control... from the right-click menu. The Delegate Control Wizard will be displayed. 3. Select the User or Windows Group to assign permissions. 4. Click on OK. 5. Select the Delegate Common Tasks option button. 6. Select Create, Delete and Manage Digipass from the list. 7. Click on Next. 8. Click on Finish. If you wish to grant permissions to modify Digipass User Account properties, you will need to follow these steps: 9. Select View -> Advanced Features from the main menu. 10. Right-click on the Organizational Unit in which to assign permissions. 11. Select Properties from the right-click menu. 12. Click on the Security tab. 13. Click on the Advanced button. The Advanced Security Settings window will be displayed. 14. Click on Add Type the username of the User to assign the permissions to and click OK. 16. Click on the Properties tab. 17. Select User Objects from the Apply onto drop down list. Identikey Server Administrator Reference 75

76 Set Up Active Directory Permissions 18. Select the required permissions from: Write Digipass User Account Information Write Digipass User Account Link Write Digipass User Account Stored Password 19. Click on OK. 20. Click on OK. 21. Click on OK. If the administrator requires permissions to take Digipass out of the Digipass-Pool for assignment, you will need to follow these steps: 22. Right-click on the Digipass Pool. 23. Select Properties from the right-click menu. 24. Click on the Security tab. 25. Click on the Advanced button. The Advanced Security Settings window will be displayed. 26. Click on Add Select the User account. 28. Click on OK. 29. Click on the Object tab. 30. Select Child objects only from the Apply onto drop down list. 31. Tick the Allow box for: Delete Digipass Objects Create Digipass Objects (if you wish to allow the administrator to move Digipass records into the Digipass Pool) 32. Click on OK. 33. Click on Add Select the User account. 35. Click on OK. 36. Click on the Object tab. 37. Select Digipass objects from the Apply onto drop down list. 38. Tick the Allow box for Write All Properties. 39. Click on OK. 40. Click on OK. 41. Click on OK. Identikey Server Administrator Reference 76

77 Set Up Active Directory Permissions 5.4 Multiple Domains When using the Identikey Server with multiple domains, extra steps must be followed to ensure that both the Identikey Server and administrators have permissions sufficient to access required data. The main issues are: The Digipass Configuration Container is only in one Domain. All Identikey Servers need read access to this container, even when they are in a different Domain. Cross-Domain access for administrators is a less likely requirement however. If a Identikey Server handles users and Digipass in more than one Domain, they need to be granted the necessary permissions in all the necessary Domains. In this manual, we will handle cross-domain permissions using a combination of Domain Local and Domain Global groups. It is also possible in a 'native' mode Domain to use Universal groups, but this is not covered in the instructions below. Three possible scenarios for multiple domain setup are outlined below: Scenario 1 Each Identikey Server Handles One Domain Each Identikey Server handles only the domain in which it is a member. Install the Identikey Server in each domain (the result will be at least as many Identikey Servers as domains). Give each Identikey Server access to the Digipass Configuration Domain: Domain Global Group(s) For each domain (apart from the Digipass Configuration Domain) - 1. Create a Domain Global group 2. Add the Identikey Server(s) to the Domain Global group (check which machines are in the 'RAS and IAS Servers' group to ensure the correct additions) Domain Local group In the Digipass Configuration Domain - 3. Create or use an existing Domain Local group. 4. Give the Domain Local group full read access to the Digipass Configuration Container. 5. Add the Domain Global Group from each other domain to the Domain Local group. Identikey Server Administrator Reference 77

78 Set Up Active Directory Permissions Scenario 2 One Identikey Server Handles All Domains Identikey Servers in one domain handle all domains. The Digipass Configuration Container should be located in the domain to which the Identikey Servers belong. Give the necessary access to User and Digipass data: Domain Global group In the RADIUS server Domain - 1. Create a Domain Global group. 2. Add the Identikey Servers to the Domain Global group (check which machines are in the 'RAS and IAS Servers' group to ensure the correct additions). Domain Local groups For each other Domain - 3. Create a Domain Local group. 4. Give the Domain Local group the required permissions (run the setupaccess command - See 2.5 DPADadmin Utility for more information). 5. Add the Domain Global group from the Identikey Server Domain to the Domain Local group Scenario 3 - Combination This scenario represents more complex setups, where a combination of steps from Scenarios 1 and 2 will be required. Use the steps given in the first two scenarios as a guide for what you will need to do for the combination scenario. Identikey Server Administrator Reference 78

79 Backup and Recovery 6 Backup and Recovery This section explores the measures that Administrators can undertake in backing up and recovering Identikey Server datafiles in the event of a system failure. Note This section does not cover backup of executables and system files. In the event of a catastrophic failure these can be restored or reinstalled from the original distribution media (and any subsequent service packs/patches). Once the Identikey Server is installed and operational, backups should be made of important files and data. Any time changes are made to the system configuration, backups may need to be performed again. User and Digipass data should be backed up on a frequent, regular basis. 6.1 What Must be Backed Up Configuration files for Identikey Server, Virtual Digipass Message Delivery Component and Digipass TCL Command Line Administration. SSL certificate(s) Audit Log data Data store DPX files (except for demo Digipass) Any scripts that have been written for Digipass TCL Command Line Administration, if they may be needed in the future. Important Note The Identikey Server installation includes a DPX directory containing sample DPX files for demo Digipass. These do not need to be backed up. However, if Identikey Server uses an ODBC database and you have copied the DPX files for your real Digipass into that directory, ensure you still have the original files. If you no longer have the DPX file(s) stored elsewhere, it is very important that you take a backup. Identikey Server Administrator Reference 79

80 Backup and Recovery Configuration Files The configuration files for the Identikey Server, Virtual Digipass Message Delivery Component and Digipass TCL Command Line Administration can be copied from: the Bin directory in Windows (by default in Windows C:\Program Files\VASCO\Identikey Server\Bin) to a secure location. <installation directory>/etc/vasco/ in Linux The files to be copied are: identikeyconfig.xml for all Identikey Servers mdcconfig.xml a backup of one working file is sufficient. dpadmincmd.xml Tip Save the files above with an extension that describes the server from which the file(s) were backed up. This makes it easier and quicker to locate the correct file during recovery SSL Certificates Any SSL certificates used with the Identikey Server should be backed up. If you are using a certificate generated by Identikey Server's Configuration Wizard, this will be named either ikeycerts.pem or ikeypvk.pem Audit Log Data If your organization requires that the Audit Log data be archived, the method required will depend on the audit settings. You may need to archive periodically, to avoid too much disk space being used or to keep the database from growing too large and slow Write to Text File Ensure you make copies of all files contained in the directory into which the audit log files are written. By default this will be <install dir>\log (Windows) or <install dir>/var/vasco (Linux), however it may have been configured to another location. Check the audit configuration settings if you are unsure Write to ODBC Database Back up the database using the database's backup utility. If you are using the audit tables in the embedded database, they will be included in the backup of the data store and will not require a separate backup. Identikey Server Administrator Reference 80

81 Backup and Recovery Write to Windows Event Log By default, Event Log entries are written to the Application log. However, you can configure the entries to be written to another log. Check the audit configuration if you are unsure. Important Note The Event Log may be configured with a maximum size. When this size is reached, the oldest entries may be overwritten by new ones. To check this, view the Properties of the log in the Event Viewer. If older entries will be overwritten, you will need to archive them before that occurs. To archive an Event Log: 1. Select Start -> Programs -> Control Panel. 2. Double-click on Administrative Tools. 3. Double-click on Event Viewer. 4. Right-click on Application (or the correct log, if not Application). 5. Click on Save log file as Select a path and enter a filename. 7. Select a file format from the Type drop down list. 8. Click on the Save button. Note The Audit Log data is not required for system recovery purposes Write to Syslog In Linux, audit data can be written to the Syslog. See 14.4 Linux Syslog for information on configuring Linux and Identikey Server correctly DPX files The DPX files are normally provided on secure media, which can be stored securely as a backup. If you prefer another method of archive, copy the files to your preferred location. It is important to keep the DPX file transport keys secure and preferably in a separate location to the DPX files themselves. Identikey Server Administrator Reference 81

82 Backup and Recovery Data Store Data Source Settings If you have performed some adjustments to the ODBC Data Source (DSN) that are important to keep, make sure that you have a readout of the settings Backup Strategies Warm Backup A 'warm' backup of the disk containing the database used by the Identikey Server via a RAID hardware configuration or server mirroring is a favorable backup method. It is both entirely up to date and incurs no downtime if a single disk failure occurs. This method requires either software RAID, or for better performance a hardware RAID configuration. Another technique that achieves the same effect is the 'shadow database'. However, it is still recommended to take a cold backup at intervals, as there is a possibility that a database corruption could be mirrored/shadowed under some circumstances. Cold Backup A 'cold' backup of the database allows administrators to implement a duplicate database as a safeguard on a regular basis. Generally speaking there are two methods that can be used to perform a cold backup: Backup Utility The first option is to use the vendor-specific backup utility that allows the contents of the database to backed up to a file or device while the system is running. Such a utility is provided with the embedded database PostgreSQL (see below). Shut Down and Copy the Database File The second option involves stopping the database server and any connecting server processes and copying the database files. However, this is only possible where the database vendor recommends this approach. Normally this is only appropriate if the database is contained in a single operating system file. Replicated Copy If replication has been configured between databases, a replicated copy can be used as a backup. However, it is still recommended to take a cold backup at intervals. Identikey Server Administrator Reference 82

83 Backup and Recovery Backup of PostgreSQL Embedded Database The PostgreSQL database available with the Identikey Server installation may be backed up while operational by completing these steps: 1. Open command prompt in <install directory>\postgresql\bin (Windows) or <install dir>/usr/local/pgsql/bin (Linux). 2. If using Windows, enter the following command: pg_dump -f "<path\filename>" -Fc -Z9 -U <DB admin userid> [-v] postgres If using a Linux distribution, enter the following command: vds_chroot <install dir> pg_dump -f "<path/filename>" -Fc -Z9 -U <DB admin userid> [-v] postgres where: <install dir> is the Identikey Server installation directory by default, this will be /opt/vasco/identikey <path\filename> is the absolute path and file name of the file to which data will be backed up. <DB admin userid> is the database administrator account name. When installed, this is set to digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the backup is run. 3. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. This command may also be run via a batch file in order to automatically take a backup at regular intervals. In order to remove the interactive prompt for the password, you can add a line to a PostgreSQL configuration file to allow local logins for a database administrator account without a password. Edit the file <install directory>\postgresql\data\pg_hba.conf (Windows) or <install dir>/usr/local/pgsql/data/pg_hba.conf (Linux) with a text editor. At the bottom of this file, there is a list of rules for authenticating connections to the database, which by default will be: # TYPE DATABASE USER CIDR-ADDRESS METHOD # IPv4 local connections: host all all /32 md5 # IPv6 local connections: #host all all ::1/128 md5 Add the following line directly below # Ipv4 local connections: host postgres digipass /32 trust Backup Administrator Account You may prefer to create a second database administrator account that only has permission to back up the database. Identikey Server Administrator Reference 83

84 Backup and Recovery 6.2 Recovery Active Directory Assumptions: Steps: Active Directory itself is still valid and operational. Up-to-date backups of the configuration files for the Identikey Server are available. 1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same Domain as before. 2. Retrieve your backup copy of the identikeyconfig.xml file. 3. Reinstall Identikey Server on the server. The same settings as those chosen in the previous installation should be selected. Before you restart the machine, carry out the following: 4. Restore the backup copy of the configuration file identikeyconfig.xml to <install directory>\bin. 5. Restore any customized files for the web sites (see 9.1 Customizing the Web Sites for more information). After restarting the machine: 6. Check that you can view Digipass-specific information in the Administration Web Interface and the Digipass Extension for Active Directory Users and Computers. Identikey Server Administrator Reference 84

85 Backup and Recovery ODBC Database Rebuild Identikey Server, Database Undamaged 1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same Domain as before. 2. Retrieve your backup copies of the file and any other files from the Bin directory that were backed up. 3. Reinstall Identikey Server on the server. The same settings as those chosen in the previous installation should be selected. Do not run the Configuration Wizard. 4. Restore the backup copy of the configuration file identikeyconfig.xml into the <install directory>\bin directory. Restore the backup copies of any other files that were backed up from the Bin directory at the same time. 5. Start up the Identikey Server Service. Identikey Server Administrator Reference 85

86 Backup and Recovery Restore Database, Identikey Server Undamaged This procedure should be followed where a database has been damaged and no current, valid database exists on another server. The database is restored from an earlier backup. Windows 1. Stop the Identikey Server Service. 2. Restore database from backup. If you are using the embedded PostgreSQL database: a. Open a command prompt in <install directory>\postgresql\bin. b. Enter the following command and hit ENTER: pg_restore -d postgres -c -U <DB admin userid> [-v] "<path\filename>" where: <path\filename> is the absolute path and file name of the file to restore from <DB admin userid> is the database administrator account name. The database administrator account created during installation is digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. c. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. d. Enter the following command and hit ENTER: vacuumdb -z -d postgres -U <DB admin userid> [-v] where: <DB admin userid> is the database administrator account name. The database administrator account created during installation is "digipass". -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. e. You will normally be prompted for the password of the database administrator account. This step forces the database to recalculate optimization statistics, because all the data has been removed and reloaded. Identikey Server Administrator Reference 86

87 Backup and Recovery 3. Delete the replication queue files for all destination servers. This can be done by deleting all files in the <install directory>\repldata directory (Note: if you have re-configured replication to store its files in a different directory, delete the files in that directory instead). 4. Restart the Identikey Server Service. Follow the Copy Database from Other Identikey Server procedure below on all other Identikey Servers in the system. It is essential to resynchronize all the databases in the system. Linux 1. Stop the Identikey Server Daemon. 2. Restore database from backup. If you are using the embedded PostgreSQL database: a. Enter the following command: vds_chroot <install dir> /opt/vasco/identikey/usr/local/pgsql/bin/pg_restore -d postgres -c -U <DB admin userid> [-v] "<path/filename>" where: <install dir> is the directory in which Identikey Server is installed <path/filename> is the absolute path and file name of the file to restore from <DB admin userid> is the database administrator account name. The database administrator account created during installation is digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. b. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. c. Enter the following command: vds_chroot <install dir> /opt/vasco/identikey/usr/local/pgsql/bin/vacuumdb -z -d postgres -U <DB admin userid> [-v] where: <install dir> is the directory in which Identikey Server is installed <DB admin userid> is the database administrator account name. The database administrator account created during installation is "digipass". -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. d. You will normally be prompted for the password of the database administrator account. This step forces the database to recalculate optimization statistics, because all the data has been removed and reloaded. 3. Delete the replication queue files for all destination servers. This can be done by deleting all files in the <install directory>\repldata directory (Note: if you have re-configured replication to store its files in a different directory, delete the files in that directory instead). 4. Restart the Identikey Server Daemon. Identikey Server Administrator Reference 87

88 Backup and Recovery Follow the Copy Database from Other Identikey Server procedure below on all other Identikey Servers in the system. It is essential to resynchronize all the databases in the system. Identikey Server Administrator Reference 88

89 Backup and Recovery Rebuild Identikey Server, Restore Database This procedure is required where both the Identikey Server and its database have been lost. Configuration files and the database will be restored from backups. Windows 1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same Domain as before. 2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were backed up. 3. Reinstall Identikey Server on the server. The same settings as those chosen in the previous installation should be selected. Do not run the Configuration Wizard. 4. Restore the backup copy of the configuration file identikeyconfig.xml into the <install directory>\bin directory. Restore the backup copies of any other files that were backed up from the Bin directory at the same time. 5. Stop the Identikey Server Service. 6. Restore database from backup. If you are using the embedded PostgreSQL database: a. Open a command prompt in <install directory>\postgresql\bin. b. Enter the following command and hit ENTER: pg_restore -d postgres -c -U <DB admin userid> [-v] "<path\filename>" where: <path\filename> is the absolute path and file name of the file to restore from <DB admin userid> is the database administrator account name. The database administrator account created during installation is digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. c. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. d. Enter the following command and hit ENTER: Identikey Server Administrator Reference 89

90 Backup and Recovery vacuumdb -z -d postgres -U <DB admin userid> [-v] where: <DB admin userid> is the database administrator account name. The database administrator account created during installation is digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. This step forces the database to recalculate optimization statistics, because all the data has been removed and reloaded. e. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. 7. Start the Identikey Server Service. 8. Follow the Copy Database from Other Identikey Server procedure below on all other Identikey Servers in the system. It is essential to resynchronize all the databases in the system. Linux 1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same Domain as before. 2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were backed up. 3. Reinstall Identikey Server on the server. The same settings as those chosen in the previous installation should be selected. Do not run the Configuration Wizard. 4. Restore the backup copy of the configuration file identikeyconfig.xml into the <install directory>/bin directory. Restore the backup copies of any other files that were backed up from the Bin directory at the same time. 5. Stop the Identikey Server Daemon. 6. Restore database from backup. If you are using the embedded PostgreSQL database: a. Enter the following command: vds_chroot <install dir> /opt/vasco/identikey/usr/local/pgsql/bin/pg_restore -d postgres -c -U <DB admin userid> [-v] "<path/filename>" where: <install dir> is the directory in which Identikey Server is installed <path/filename> is the absolute path and file name of the file to restore from <DB admin userid> is the database administrator account name. The database administrator account created during installation is digipass. -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. b. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. c. Enter the following command: Identikey Server Administrator Reference 90

91 Backup and Recovery vds_chroot <install dir> /opt/vasco/identikey/usr/local/pgsql/bin/vacuumdb -z -d postgres -U <DB admin userid> [-v] where: <install dir> is the directory in which Identikey Server is installed <DB admin userid> is the database administrator account name. The database administrator account created during installation is "digipass". -v is an optional 'verbose mode' parameter. Use this if you wish to see output as the database is restored. This step forces the database to recalculate optimization statistics, because all the data has been removed and reloaded. d. You will normally be prompted for the password of the database administrator account. When installed, this is set to digipassword. 7. Start the Identikey Server Daemon. 8. Follow the Copy Database from Other Identikey Server procedure below on all other Identikey Servers in the system. It is essential to resynchronize all the databases in the system. Identikey Server Administrator Reference 91

92 Backup and Recovery Copy Database from Other Identikey Server This procedure will be required where multiple Identikey Servers are synchronizing with each other, where one database has become unsynchronized or unstable. It must be replaced with a 'safe' database one containing upto-date, uncorrupted data. The instructions below assume a simple two-identikey Server pair where one Identikey Server (SVR-2) is using a database that has become unstable, and the other (SVR-1) is using a 'safe' database. To replace the database: 1. Identify the Identikey Server with the 'safe' database. For these steps, it will be referred to as SVR Stop the Identikey Server Service on SVR-1 and SVR Take a complete copy of the database used by the Identikey Server on SVR-1. If you are using the embedded PostgreSQL database, see Backup of PostgreSQL Embedded Database for instructions. 4. Delete the replication queue files for SVR-2 which is on SVR-1: a. On SVR-1, run the Identikey Server Configuration utility and change to the Destination Servers tab of the Replication section. b. Find the Destination Server row that represents SVR-2 and note the Display Name. c. Change to the Queue tab and check the File Path value. This will normally be <install directory>\repldata, but may have been re-configured. d. In that directory, delete all files with filename starting <Display Name>. 5. The Identikey Server Service on SVR-1 may be restarted now if needed it will build up a new replication queue until it can connect to SVR Completely overwrite the database used by the Identikey Server on SVR-2 with the copy from SVR-1. If you are using the embedded PostgreSQL database, see Step 2 of Restore Database, Identikey Server Undamaged. Identikey Server Administrator Reference 92

93 Backup and Recovery 7. Delete the replication queue file on SVR-2 for all other Identikey Servers. This can be done by deleting all files in the <install directory>\repldata directory (Note: if you have re-configured replication to store its files in a different directory, delete the files in that directory instead). 8. Restart the Identikey Server Service on SVR-2. Warning If the Identikey Server with the 'bad' database (SVR-2) was synchronizing with another Identikey Server, you must copy over the other database as well. Follow the steps above for any Identikey Servers with which SVR-2 was synchronizing. Identikey Server Administrator Reference 93

94 Backup and Recovery Rebuild Identikey Server, Copy Database This procedure will be required where multiple Identikey Servers are synchronizing with each other and one Identikey Server, together with its database, is lost. The instructions below assume one functional Identikey Server (SVR-1) with an up-to-date database, and a server on which an Identikey Server must be rebuilt (SVR-2) and its database copied from the other Identikey Server. 1. Rebuild the server with your operating system SOE, using the same IP address as before, in the same Domain as before. 2. Retrieve your backup copies of the identikeyconfig.xml file and any other files from the Bin directory that were backed up. 3. Reinstall Identikey Server on the server. The same settings as those chosen in the previous installation should be selected. Do not run the Configuration Wizard. 4. Restore the backup copy of the configuration file identikeyconfig.xml into the <install directory>\bin directory. Restore the backup copies of any other files that were backed up from the Bin directory at the same time. 5. On SVR-1, stop the Identikey Server service. 6. Take a complete copy of the database used by the Identikey Server on SVR-1. If you are using the embedded PostgreSQL database, see Backup of PostgreSQL Embedded Database for instructions. 7. Delete the replication queue file for SVR-2 which is on SVR-1. a. On SVR-1, run the Identikey Server Configuration utility and change to the Destination Servers tab of the Replication section. b. Find the Destination Server row that represents SVR-2 and note the Display Name. c. Change to the Queue tab and check the File Path value. This will normally be <install directory>\repldata, but may have been re-configured. Identikey Server Administrator Reference 94

95 Backup and Recovery d. In that directory, delete all files with filename starting <Display Name>. 8. The Identikey Server Service on SVR-1 may be restarted now if needed it will build up a new replication queue until it can connect to SVR Completely overwrite the database used by the Identikey Server on SVR-2 with the copy from SVR-1. If you are using the embedded PostgreSQL database, see Step 2 of Restore Database, Identikey Server Undamaged. 10. Delete the replication queue file on SVR-2 for all other Identikey Servers. This can be done by deleting all files in the <install directory>\repldata directory (Note: if you have re-configured replication to store its files in a different directory, delete the files in that directory instead). 11. Restart the Identikey Server Service on SVR-2. Warning If the Identikey Server with the 'bad' database (SVR-2) was synchronizing with another Identikey Server, you must copy over the other database as well. Follow the steps above for any Identikey Servers with which SVR-2 was synchronizing. Identikey Server Administrator Reference 95

96 Field Listings 7 Field Listings 7.1 User Properties Table 34: User Fields Field Name Static Password Local Authentication Back-End Authentication Description The static password. This may be used for static password checking by the Identikey Server or may be a record of a password in a Back-End System. In view mode, the system will only show whether a password is set or not. The Set Password and Reset Password commands are used to change this, although it can also be entered when creating the Digipass User account. Specifies whether authentication requests for the User account will be handled by the Identikey Server using Local Authentication (see the Authenticating Users section in the Product Guide for more details on Local Authentication and Back-End Authentication). Normally, this field will be Default, meaning that the Policy applicable to the authentication request determines the setting. This field on the Digipass User account is used to override the Policy setting for special cases. When Local Authentication is used, there are two factors that determine whether Digipass authentication is used any Policy restrictions on Digipass Types and/or Applications that can be used and whether the Digipass User account has any assigned Digipass that meet the restrictions. For example, if the Policy requires a DP300 and the User just has a DP700, they cannot use Digipass authentication under that Policy. This setting also affects the Provisioning Registration process (see the Software Digipass Provisioning section in the Product Guide). Options: Default None Digipass/Password Digipass Only Use the setting of the effective Policy. The Identikey Server will not carry out Local Authentication for this User account. They may be handled using Back-End Authentication, or not handled at all by the Identikey Server. The Identikey Server will always carry out Local Authentication for this User, using Digipass authentication if possible, otherwise the static password. Back-End Authentication may also be utilized. The Identikey Server will always carry out Local Authentication for this User, using Digipass authentication. If Digipass authentication is not possible, the user cannot log in. Back-End Authentication may also be utilized. Specifies whether authentication requests for the User account will be handled by the Identikey Server using Back-End Authentication (see the Authenticating Users section in the Product Guide for more details on Local Authentication and Back-End Authentication). Normally, this field will be Default, meaning that the Policy applicable to the authentication request determines the setting. This field on the Digipass User account is used to override the Policy setting for special cases. Identikey Server Administrator Reference 96

97 Field Listings Field Name Disabled Locked Linked User Account Created On Last Modified On Domain Organizational Unit Description This setting also affects the Provisioning Registration process (see the Software Digipass Provisioning section in the Product Guide). Options: Default None If Needed Always Use the setting of the effective Policy. Back-End Authentication will not be used. The Identikey Server will utilize Back-End Authentication but only in certain cases: Dynamic User Registration Self-Assignment Password Autolearn Requesting a Challenge or Virtual Digipass OTP, when the Request Method includes a Password Static password authentication, when verifying a Virtual Digipass password-otp combination or during the Grace Period Provisioning Registration The Identikey Server will utilize Back-End Authentication for every authentication and Provisioning Registration request. Specifies whether a Digipass User account is enabled or disabled. If disabled, all requests for the User will be rejected by the Identikey Server. The Disable and Enable commands are used to change this, although it can also be changed when creating or editing the Digipass User account. Specifies whether a Digipass User account is locked or not. If locked, all requests for the User will be rejected by the Identikey Server. The Locked indicator is normally set automatically when the User exceeds a certain number of failed authentication attempts. The User Lock Threshold is set in the Policy. The Unlock command is used to change this, although it can also be changed when editing the Digipass User account. It is possible to share Digipass between different User accounts, by linking User accounts together. This feature is intended for the case where one person, such as an administrator, has multiple User accounts. If their accounts are linked, there is no need to give more than one Digipass to that person. This feature is used by assigning the Digipass to one User account, then linking all the other User accounts for the person to the one that has the Digipass. Read only. The Link and Unlink commands must be used to change this. If a User is linked to another User, their Linked User Account field will show the UserId and Domain of the linked User, for example: testuser [vasco.com] The date and time that the Digipass User account was created. Read-only. The date and time that the Digipass User account was last modified. Read-only. The Domain to which the User belongs. Read only. This cannot be changed. The Organizational Unit in which the User is located. This is optional as the User does not have to be located in an Organizational Unit. Identikey Server Administrator Reference 97

98 Field Listings Field Name User Name Address Phone No. Mobile No. Description Assigned Digipass list Administrative Privileges Description Read only. The Move command must be used to change this. The full name of the User. The address of the User. The telephone number of the User. The mobile phone number of the User. This will be used for Virtual Digipass logins. Any descriptive text or notes. This lists all Digipass that are assigned to the User. For each Digipass, the list of active Applications is given with the Application Type indicated in brackets(). For example: RESP_ONLY(RO), CHALLENGE(CR) In this example line, the Digipass with Serial Number has two active Applications: one Response Only Application RESP_ONLY and one Challenge/Response Application CHALLENGE. Other Digipass properties are shown in this list for more information, see the Digipass Properties table. If the User does not have any Digipass assigned directly, but is linked to another User to use their Digipass (see Linked User Account), the linked User's Digipass list is shown with the Serial Numbers in square brackets (eg. [ ]). Read-only. The Assign Digipass and Unassign Digipass commands much be used to change this. This lists all the administrative privileges for which the User has permission. 7.2 User Attributes Table 35: User Attribute Fields Field Name Attribute Group Name Usage Description Attribute Groups provide a way to add different attributes to the User account for different client components. A SOAP client application may request a certain Attribute Group it will only be given the user's attributes for the matching Attribute Group. A different application may request the same Attribute Group or a different one. An IIS Module (for example, in Digipass Pack for IIS Basic Authentication) may also request an Attribute Group. The Attribute Group entered in the Configuration GUI for the IIS Module will be requested. If the Identikey Server Data Store is shared with Digipass Plug-In for SBR, the SBR Plug-In may retrieve other Attribute Groups. The name of the attribute. This must match the name of an attribute expected by the client component. For the Digipass Pack for IIS Basic Authentication, this would be either User- Name or Password. Specifies the usage of the User attribute. This is an optional setting. Identikey Server Administrator Reference 98

99 Field Listings Field Name Description Value Options: Basic Check Profile Return Designates an attribute used by the Digipass Pack for IIS Basic Authentication. Note: Not currently in use with Identikey Server. Used to specify a RADIUS check attribute. Note: Not currently in use with Identikey Server. Used to specify the name of a RADIUS Profile. Note: Not currently in use with Identikey Server. Used to specify a RADIUS return attribute. This value of the attribute. For the Digipass Pack for IIS Basic Authentication, this would be a User ID or password. Identikey Server Administrator Reference 99

100 Field Listings 7.3 Digipass Properties Table 36: Digipass Fields Domain Field Name Organizational Unit Digipass Type Description Reserve for Individual Assignment Assigned to User Date Assigned Grace Period End BVDP Mode Description The Domain to which the Digipass belongs. Read only. The Move command must be used to change this. The Organizational Unit in which the Digipass is located. This is optional as the Digipass does not have to be located in an Organizational Unit. Read only. The Move command must be used to change this. The type of Digipass represented by the Digipass record (eg. DP300). A custom text description of the Digipass. This can be used to search for specific attributes of a Digipass, eg. color, company logo. When used, this option prevents the Digipass from being assigned using the Auto-Assignment feature or by Provisioning Registration. It also prevents it from being assigned by an administrator who uses the 'Assign next available...' option in the assignment wizard. User ID of the Digipass User account that the Digipass is assigned to, if it is assigned. This User account must be in the same Domain as the Digipass. Read-only. The Assign command must be used to change this. The date and time when the Digipass was assigned to its current User. Read-only. The date on which the Grace Period will expire, or did expire, for this Digipass. If the date shows today's date or before, the Grace Period has already expired. If it is blank, there is no Grace Period. Specifies whether and how the Backup Virtual Digipass feature can be used for this Digipass. Note that in order for the Backup Virtual Digipass feature to function, it must also be activated in the DPX file for the Digipass. Normally, this field will be Default, meaning that the Policy applicable to the authentication request determines the setting. This field on the Digipass record is used to override the Policy setting for special cases. Options: Default No Yes - Permitted Yes Time Limited Yes - Required Use the setting of the effective Policy. Backup Virtual Digipass is not permitted. Backup Virtual Digipass is permitted, but not mandatory. The Enabled Until date is not applicable when using this option, but the Uses Remaining count is. Backup Virtual Digipass is permitted, but not mandatory. Both the Enabled Until date and the Uses Remaining count will be in effect. Backup Virtual Digipass is mandatory. This may be useful if the User may have lost the Digipass, to prevent it from being used until they have found it again. The Enabled Until date is not applicable when using this Identikey Server Administrator Reference 100

101 Field Listings Field Name Enabled Until Uses Remaining Static Vector ID Last Activation Activation Locations Activation Count Created On Last Modified On Description option, but the Uses Remaining count is. The date on which the Backup Virtual Digipass feature may no longer be used, provided that the effective Enable Backup VDP setting is Yes Time Limited (it is ignored otherwise). If this date is blank, it will be set automatically the first time that the User requests a Backup Virtual Digipass OTP, using the Backup Virtual Digipass Time Limit defined in the Policy. Once this date has expired, it requires administrator intervention either to extend it or to reset it to blank for the next time that the User needs to use Backup Virtual Digipass. The remaining number of times that the Backup Virtual Digipass feature may be used for this Digipass. Once this number has reached zero, Backup Virtual Digipass can no longer be used with this Digipass, unless the administrator increases it or resets it to blank. If this number is blank and there is a Backup Virtual Digipass Max. Uses/User defined in the Policy, it will be set automatically the first time that the User requests a Backup Virtual Digipass OTP, based on the Max. Uses/User. The presence of a value here indicates that a Digipass is a Software Digipass capable of Provisioning. Its specific value is not of use to an administrator normally. It represents a lookup key of a database record used in the Provisioning process (DPSoft Parameters) that stores the Static Vector value. The date and time at which the last Provisioning Registration operation took place using this Digipass, when an Activation Code was generated for it. There is a configurable minimum interval of time between Registration operations for a Digipass. See the Software Digipass Provisioning section in the Product Guide for more details. This value is reset to blank by the Reset Activation command. This is typically only used for Digipass for Web, to keep track of the number of different locations at which a particular User has activated it. The value is a comma-separated list of hash values, where each hash value represents one location. There is a configurable maximum number of activation locations for a Digipass. See the Software Digipass Provisioning section in the Product Guide for more details. This value is reset to blank by the Reset Activation command. The total number of Provisioning Registration operations that have taken place using this Digipass, when an Activation Code was generated for it. This includes Registration operations for which the corresponding Activate operation was not completed successfully. There is a configurable maximum number of activation attempts for a Digipass. See the Software Digipass Provisioning section in the Product Guide for more details. This value is reset to 0 by the Reset Activation command. The date and time that the Digipass was created. Read-only. The date and time that the Digipass was last modified. Read-only. Identikey Server Administrator Reference 101

102 Field Listings 7.4 Digipass Application Tab Table 37: Digipass Application Fields Field Name Application Name Application Type Status Application Info Created On Last Modified On Description A name for the Digipass Application. This is taken from the DPX file (always upper case). Readonly. The type of Digipass Application: RO Response Only CR Challenge/Response SG Signature MM Multi-Mode Read-only. This field indicates whether the Application is active or not. If it is not active, it cannot be used for authentication, provisioning or signature validation. Read-only. The Activate Application and Deactivate Application commands much be used to change this. This list indicates various internal settings of the Digipass Application. They are not edited directly but some are updated as side-effects of Digipass operations such as verification of One Time Passwords. Others represent programming parameters and never change. The date and time that the Digipass Application was created. Read-only. The date and time that the Digipass Application was last modified. Read-only. Identikey Server Administrator Reference 102

103 Field Listings 7.5 Policy Properties Note Changes to Policy settings will not take effect immediately on all Identikey Servers unless Replication is used to synchronize the Identikey Servers. Where Replication is not used, changes to Policy settings will take effect when each Identikey Server is restarted, once the Policy change is available to it in its data store. Alternatively, if there is no restart, the cache of Policy settings will refresh from the data store after approximately every 15 minutes. Table 38: Policy Fields Field Name Description Inherits from Policy Local Authentication Description This description can be entered to record the purpose of the Policy. Contains the Name of the Policy from which settings will be inherited, referred to as the 'parent Policy'. Settings are inherited individually, depending on the value in the Policy field; they inherit the parent Policy value in the following cases: Choice lists/radio buttons if the selected value is Default Text fields if the field is blank Numeric fields if the field is blank (not 0) List fields if the list is empty The Show Effective Policy Settings... button can be used to display the result of inheriting settings combined with settings on the current Policy. Specifies whether authentication requests using the Policy will be handled by the Identikey Server using Local Authentication (see the Authenticating Users section in the Product Guide for more details on Local Authentication and Back-End Authentication). When Local Authentication is used, there are two factors that determine whether Digipass authentication is used any Policy restrictions on Digipass Types and/or Applications that can be used and whether the Digipass User account has any assigned Digipass that meet the restrictions. For example, if the Policy requires a DP300 and the User just has a DP700, they cannot use Digipass authentication under that Policy. This setting also affects the Provisioning Registration process (see the Software Digipass Provisioning section in the Product Guide). Options: Default None Digipass/Password Digipass Only Use the setting of the parent Policy. The Identikey Server will not carry out Local Authentication under this Policy. They may be handled using Back-End Authentication, or not handled at all by the Identikey Server. The Identikey Server will always carry out Local Authentication under this Policy, using Digipass authentication if possible, otherwise the static password. Back-End Authentication may also be utilized. The Identikey Server will always carry out Local Authentication Identikey Server Administrator Reference 103

104 Field Listings Field Name Back-End Authentication Back-End Protocol Created On Last Modified On Dynamic User Registration Description under this Policy, using Digipass authentication. If Digipass authentication is not possible, the user cannot log in. Back-End Authentication may also be utilized. Specifies whether authentication requests using the Policy will be handled by the Identikey Server using Back-End Authentication (see the Authenticating Users section in the Product Guide for more details on Local Authentication and Back-End Authentication). This setting also affects the Provisioning Registration process (see the Software Digipass Provisioning section in the Product Guide). Options: Default None If Needed Always Use the setting of the parent Policy. Back-End Authentication will not be used. The Identikey Server will utilize Back-End Authentication but only in certain cases: Dynamic User Registration Self-Assignment Password Autolearn Requesting a Challenge or Virtual Digipass OTP, when the Request Method includes a Password Static password authentication, when verifying a Virtual Digipass password-otp combination or during the Grace Period Provisioning Registration The Identikey Server will utilize Back-End Authentication for every authentication and Provisioning Registration request. Specifies the protocol to be used for Back-End Authentication. If you have your own Back-End Authentication Engines, they will have Protocol names to identify them. The name for the required Engine must be defined in the Back-End Protocol for the Policy. The following standard options are available: Windows RADIUS e-directory ADAM Active Directory Authentication using the Windows operating system (this is only available when the Identikey Server runs on Windows). Authentication using a RADIUS server. Authentication using Novell's e-directory. Authentication using a Microsoft ADAM server. Authentication using Microsoft's Active Directory. The date and time that the Policy was created. Read-only. The date and time that the Policy was last modified. Read-only. Specifies whether the Dynamic User Registration (DUR) feature is enabled for the Policy. If this feature is used, when the Identikey Server receives an authentication request for a User for the first time and Back-End Authentication is successful, it will create a Digipass User account automatically. If DUR is used in conjunction with Auto-Assignment, a Digipass will be assigned to the new User account immediately. Identikey Server Administrator Reference 104

105 Field Listings Field Name Password Autolearn Stored Password Proxy Default Domain User Lock Threshold Windows Group Check Description This setting also determines whether the Provisioning Registration process is allowed to perform DUR or not. Specifies whether the Password Autolearn feature is enabled for the Policy. This feature enables the Identikey Server to update the password stored in the Digipass User account when Back-End Authentication is successful. This setting also determines whether the Provisioning Registration process will update the password after successful Back-End Authentication or not. Specifies whether the Stored Password Proxy feature is enabled for the Policy. This feature can be used in conjunction with the Back-End Authentication Always setting and the Password Autolearn feature. With this combination, even though a Back-End Authentication check is done every login, it is done using the password stored in the Digipass User account. Therefore the User does not have to enter it during their login, unless it has changed in the Back-End System. This mode of operation is referred to as Password Replacement. The default Domain in which the Identikey Server should look for and create Digipass User accounts, if a Domain is not specified by the user credentials. The process of resolving the User ID and Domain name is described in the User ID and Domain Resolution section in the Product Guide and in Identifying the Domain for a Login Attempt of this document. This indicates the number of consecutive failed login attempts that will cause a Digipass User account to become Locked. For example, if the User Lock Threshold is 3, the account will become Locked on the third failed login attempt. Unlocking the account requires administrator action. Note that not all kinds of login failure will result in locking. For example, if the UserId is incorrect or the account is Disabled, the failure would not count towards the lock threshold. Locking is used mainly for incorrect OTPs and static passwords. The locking mechanism is also used for Provisioning and Signature Validation. Specifies whether and how the Windows Group Check feature is to be used. This feature is typically used for a staged deployment of Digipass when the Auto-Assignment method is used. It can also be used when only some Users are required to use Digipass or when only some Users will be permitted access and they have to use Digipass. Options: Default No check Pass requests for users not in listed groups back to host system Reject requests for users not in listed group Use only Back-End Authentication for users not in listed groups Use the setting of the parent Policy. Do not use the Windows Group Check feature. Use the Windows Group Check so that any Users who are not in one of the listed groups are ignored by the Identikey Server. Use of this setting for Provisioning or Signature Validation will have the same effect as the Reject... setting. Use the Windows Group Check so that any Users who are not in one of the listed groups are rejected by the Identikey Server. Use Back-End Authentication only for any Users who are not in one of the listed groups. Use of this setting for Provisioning or Signature Validation Identikey Server Administrator Reference 105

106 Field Listings Group List Field Name Assignment Mode Grace Period Serial No. Separator Search Upwards in Org. Unit hierarchy Description will have the same effect as the Reject... setting. This lists the names of the Windows Groups to be checked according to the Windows Group Check radio button setting. There are some important limitations of this check: Certain built-in Active Directory groups such as Domain Users and Everyone will not be checked. The check is intended to be used with a new group created specifically for this purpose. Nested group membership will not be detected by the check. There is no Domain qualifier for a group. The named group must be created in each Domain where User accounts exist that need to be added to the group. A local machine group can be used also. Specifies the method of automated Digipass Assignment that will be used for this Policy, if any. There are two methods, Auto-Assignment and Self-Assignment. Auto-Assignment is used in conjunction with Dynamic User Registration (DUR). When DUR occurs, the next available Digipass is assigned to the new Digipass User account. A Grace Period is set for the Digipass according to the Grace Period setting in the Policy. Self-Assignment is typically used with DUR also, but if the Digipass User accounts are created first by the administrator, DUR is not necessary. In the Self-Assignment mode, a User is able to assign themselves a Digipass by entering the Serial Number, a valid OTP from the Digipass and their static password. There is no Grace Period associated with Self- Assignment, because the User has to use the Digipass to perform Self-Assignment. In both cases, any Applicable Digipass restrictions for the Policy apply. For example, it will not be permitted to self-assign a DP300 if the Policy restricts Digipass Types to DPGO3 and DPGO1. In addition, if the User already has a Digipass assigned that meets the Policy restrictions, they will not be able to self-assign another Digipass. This setting is not applicable to Provisioning or Signature Validation. Options: Default Auto-Assignment Self-Assignment Neither Use the setting of the parent Policy. Use the Auto-Assignment method. Use the Self-Assignment method. Do not use either method of automated assignment. Default time period (in days) to give Users between Auto-Assignment of a Digipass and the date they must start using their Digipass to login. Before that time they can still use a static password (unless the Local Authentication setting is Digipass Only). However, the first time that an OTP is used to log in, the Grace Period is ended at that point if it has not already ended. This setting does not affect manual assignment by an administrator or Provisioning. The character (or short sequence of characters) that will be included at the end of the Digipass Serial Number during a Self-Assignment login. It allows the Identikey Server to easily recognize that a Self-Assignment attempt is being made and extract the Serial Number from the credentials. This controls the search scope for an available Digipass for Auto-Assignment or Provisioning Registration, or for a specific Digipass for Self-Assignment. This setting does not affect manual assignment by an administrator. Identikey Server Administrator Reference 106

107 Field Listings Field Name Application Names Application Type Digipass Types Allow PIN change 1-Step Challenge/Response Permitted Options: Default No Yes Description Use the setting of the parent Policy. The search scope is only the Organizational Unit in which the User account belongs. If the User does not belong to an Organizational Unit, the search will look for Digipass that also do not belong to an Organizational Unit. The search will start in the User account's Organizational Unit, but if necessary it will then move upwards through the Organizational Unit hierarchy until it reaches the top. See the Location of Digipass Records topic in the Product Guide for more information. The Policy can specify a restriction on which Digipass Applications may be used when it is effective. If the list is empty, there is no restriction. If there are one or more entries, they will indicate the Application Names that are permitted. The Policy can restrict which Digipass Application Type (eg. Response Only, Challenge/Response) may be used when it is effective. Options: Default No Restriction Response Only Challenge/Response Signature Multi-Mode Use the setting of the parent Policy. Digipass Application Type is not restricted. Only Digipass Applications of Type RO (Response Only) or MM (Multi-Mode) may be used. Only Digipass Applications of Type CR (Challenge/Response) or MM (Multi-Mode) may be used. Only Digipass Applications of Type SG (Signature) or MM (Multi- Mode) may be used. Only Digipass Applications of Type or MM (Multi-Mode) may be used. The Policy can specify a restriction on which Digipass Types may be used when it is effective. If the list is empty, there is no restriction. If there are one or more entries, they will indicate the Digipass Types that are permitted. Specifies whether Digipass Users will be allowed to change their Server PIN during authentication requests to which the current Policy applies. Normally this setting is enabled, but it can be used to prevent PIN changes if required. Controls whether 1-step Challenge/Response logins will be enabled for the current Policy and, if so, where the challenge should originate. In order to enable 1-step Challenge/Response, you also need to set the Challenge Check Mode (see below). Note that 1-step Challenge/Response is not applicable in a RADIUS environment. Options: Default No 1-step Challenge/Response may not be used. Identikey Server Administrator Reference 107

108 Field Listings Field Name 1-Step Challenge/Response Challenge Length 1-Step Challenge/Response Add Check Digit 2-Step Challenge/Response Request Method 2-Step Challenge/Response Request Keyword Primary Virtual Digipass Request Method Primary Virtual Digipass Request Keyword Yes Server Challenge Yes Any Challenge Description 1-step Challenge/Response may be used provided that the Identikey Server that verifies the response generated the challenge. 1-step Challenge/Response may be used with any random challenge. Specifies the length of the challenge (excluding a check digit) which should be generated for 1-step Challenge/Response logins. A check digit may be added to the generated challenge. This allows the Digipass to identify invalid Challenges more quickly. The method by which a User has to request a 2-step Challenge/Response login. This is the only mode of Challenge/Response available in a RADIUS environment. The 'request' is made in the password field during login. The request will fail if the User does not have a Challenge/Response-capable Digipass assigned. This includes Digipass Applications of Type CR, SG and MM. Options: Default None Keyword Password KeywordPassword PasswordKeyword Use the setting of the parent Policy. Do not use 2-step Challenge/Response. Use the Request Keyword. This is permitted to be blank. Use the static password. Use the Request Keyword followed by the static password. No separator characters or whitespace should be between them. Use the static password followed by the Request Keyword. No separator characters or whitespace should be between them. Defines the Keyword that a User must enter to request a 2-step Challenge/Response login, if a method using a Keyword is selected in the Request Method. This is permitted to be blank. The method by which a User has to request a Primary Virtual Digipass login. The 'request' is made in the password field during login. The request will be ignored if the User does not have a Primary Virtual Digipass assigned. Options: Default None Keyword Password KeywordPassword PasswordKeyword Use the setting of the parent Policy. Do not use Primary Virtual Digipass. Use the Request Keyword. This is permitted to be blank. Use the static password. Use the Request Keyword followed by the static password. No separator characters or whitespace should be between them. Use the static password followed by the Request Keyword. No separator characters or whitespace should be between them. Defines the Keyword that a User must enter to request a Primary Virtual Digipass login, if a method using a Keyword is selected in the Request Method. This is permitted to be blank. Identikey Server Administrator Reference 108

109 Field Listings Field Name Backup Virtual Digipass Enable Backup VDP Backup Virtual Digipass Time Limit Backup Virtual Digipass Max. Uses/User Backup Virtual Digipass Request Method Description Specifies whether and how the Backup Virtual Digipass feature can be used when this Policy is effective. Note that in order for the Backup Virtual Digipass feature to function, it must also be activated in the DPX file for the Digipass. Options: Default No Yes - Permitted Yes Time Limited Yes - Required Use the setting of the parent Policy. Backup Virtual Digipass is not permitted. Backup Virtual Digipass is permitted, but not mandatory. The Time Limit is not applicable when using this option, but the Max. Uses/User limit is. Backup Virtual Digipass is permitted, but not mandatory. Both the Time Limit and the Max. Uses/User limit will be in effect. Backup Virtual Digipass is mandatory. The Time Limit is not applicable when using this option, but the Max. Uses/User limit is. When the Enable Backup VDP setting is Yes Time Limited, the Time Limit setting indicates the number of days for which the Backup Virtual Digipass feature may be used by a User, once they start using it. The Backup Virtual Digipass Enabled Until setting on the Digipass record will be set automatically the first time that the User requests a Backup Virtual Digipass OTP, using the Time Limit defined in the Policy. Once this date has expired, it requires administrator intervention either to extend it or to reset it to blank for the next time that the User needs to use Backup Virtual Digipass. Note that if a User has more than one Digipass capable of Backup Virtual Digipass, they will have a separate limit for each one. The maximum number of uses of the Backup Virtual Digipass feature permitted for each User, if they do not have a specific limit set for them. If the Backup Virtual Digipass Uses Remaining on the Digipass record is blank and there is a Max. Uses/User limit defined in the Policy, the Uses Remaining will be set automatically the first time that the User requests a Backup Virtual Digipass OTP. Once the Uses Remaining has reached zero, Backup Virtual Digipass can no longer be used with this Digipass, unless the administrator increases it or resets it to blank. Note that if a User has more than one Digipass capable of Backup Virtual Digipass, they will have a separate limit for each one. The method by which a User has to request a Backup Virtual Digipass login. The 'request' is made in the password field during login. The request will be ignored if the User does not have a Digipass assigned that is activated for the Backup Virtual Digipass feature, or if other Policy or Digipass settings do not permit Backup Virtual Digipass use. Options: Default None Keyword Use the setting of the parent Policy. Do not use Backup Virtual Digipass. Use the Request Keyword. This is permitted to be blank. Identikey Server Administrator Reference 109

110 Field Listings Field Name Backup Virtual Digipass Request Keyword Identification Time Window Signature Time Window Initial Time Window Event Window Identification Threshold Signature Threshold Password KeywordPassword PasswordKeyword Description Use the static password. Use the Request Keyword followed by the static password. No separator characters or whitespace should be between them. Use the static password followed by the Request Keyword. No separator characters or whitespace should be between them. Defines the Keyword that a User must enter to request a Backup Virtual Digipass login, if a method using a Keyword is selected in the Request Method. This is permitted to be blank. Controls the maximum number of time steps' variation allowable between a Digipass and the Identikey Server during login. This only applies to time-based Digipass Applications when verifying a One Time Password. The Dynamic Time Window option may be used to allow more variation according to the length of time since the last successful login. If this setting is not specified at all, there is an inbuilt default value of 20. Controls the maximum number of time steps' variation allowable between a Digipass and the Identikey Server during Digital Signature verification. This only applies to time-based Digipass Applications when validating a signature, but even then it may be used or not according to the Online Signature Level setting. If this setting is not specified at all, there is an inbuilt default value of 24. Controls the maximum allowed time variation allowable between a Digipass and the Identikey Server, the first time that the Digipass is used. The time is specified in hours. This Initial Time Window is also used directly after a Reset Application operation, which can be used if it appears that the internal clock in the Digipass has drifted too much since the last successful login. This only applies to time-based Digipass Applications when verifying a One Time Password. In either case, after the first successful login, the Initial Time Window is no longer active. If this setting is not specified at all, there is an inbuilt default value of 6. Controls the maximum number of events' variation allowable between a Digipass and the Identikey Server during login. This only applies to event-based Digipass Applications. It always applies when verifying a One Time Password but for Signature validation, it depends on the Online Signature Level setting whether the Event Window is used or not. If this setting is not specified at all, there is an inbuilt default value of 20. Specifies the number of consecutive failed authentication attempts allowed before the Digipass Application is locked from future authentication attempts. Once the Digipass Application is locked, the Reset Appl Lock command is required to unlock it for further authentication. This locking mechanism is separate from the User Lock Threshold and is normally not necessary. It only applies when a single Digipass Application can be used for a login, either because the User only has one Digipass with one Application, or because the Policy restrictions narrow the list down to one Digipass Application. If Policy restrictions are used in this way, the Identification Threshold can be used to lock a User out of one kind of login (eg. a VPN) while still permitting them to use another kind (eg. a web application). If this setting is not specified at all, this feature is not used. Specifies the number of consecutive failed Signature validation attempts allowed before the Identikey Server Administrator Reference 110

111 Field Listings Field Name Max. Days Since Last Use Challenge Check Mode Online Signature Level Description Digipass Application is set to be locked from future signature validation attempts. Once the Digipass Application is locked, the Reset Appl Lock command is required to unlock it for further signature validation. This locking mechanism is separate from the User Lock Threshold and is normally not necessary. It only applies when a single Digipass Application can be used for a signature validation, either because the User only has one Digipass with one signature-capable Application, or because the Policy restrictions narrow the list down to one Digipass Application. If Policy restrictions are used in this way, the Signature Threshold can be used to lock a User out of one kind of signature validation while still permitting them to use another kind. If this setting is not specified at all, this feature is not used. This setting specifies the maximum number of days for which a Digipass Application can go unused for authentication or signature validation. After this limit, authentication and signature validation will be rejected until an admnistrator performs a Reset Application operation. If this setting is not specified at all, this feature is not used. This setting is for advanced control over time-based Challenge/Response authentication. The value 1 should be used for standard RADIUS Challenge/Response. This is the inbuilt default value if the setting is not specified at all. 0 No check is made. This is necessary for 1-step Challenge/Response. 1 The challenge presented for verification must be the last one that was generated specifically for that Digipass. This is the normal mode of operation in 2-step Challenge/Response. 2 The challenge presented for verification is ignored; the last one that was generated specifically for that Digipass is used. 3 Only one verification is permitted per time step. This option only applies to time-based Challenge/Response. This is a method of avoiding a potential replay of a captured response if the same challenge comes up again in the same time step. 4 If the same challenge and response are presented for verification twice in a row during the same time step, they are rejected. This is an advanced method of avoiding a potential replay of a capture challenge/response. This setting is for advanced control of Signature validation. The value 0 can be used for Digipass Applications that are neither time- nor event-based. This is the inbuilt default value if the setting is not specified at all. 0 The signature is validated in offline mode. This is useful when the signatures may not be validated in the same sequence as they were generated by the user. It is also useful when there may be some delay after the signature is generated by the user, before the signature is validated. For time-based Digipass Applications: This mode is typically used with a large time step. When this mode is used, no clock synchronization occurs Identikey Server Administrator Reference 111

112 Field Listings Field Name Description between the Digipass and the Identikey Server. The Identikey Server will not reject an older signature than the most recently validated signature, provided it is still within the Signature Time Window. For event-based Digipass Applications: When this mode is used, the Identikey Server will not reject an older signature than the most recently validated signature, provided it is still within the Event Window. 1 The signature is validated in online mode. This is useful when the signatures are expected or required to be validated immediately after they are generated. For time-based Digipass Applications: This mode is typically used with a small time step. When this mode is used, clock synchronization occurs between the Digipass and the Identikey Server. The Identikey Server will reject an older signature than the most recently validated signature. A newer signature must be within the Signature Time Window. This mode will allow more than one signature to be validated in the same time step, provided that the same exact signature is not repeated twice in a row. For event-based Digipass Applications: When this mode is used, the Identikey Server will reject an older signature than the most recently validated signature. A newer signature must be within the Event Window. 2 The signature is validated in strict online mode. This is useful for time-based signatures when you want to prevent more than one signature from the same time step from being validated. Otherwise, this mode is the same as online mode. 3 The signature is validated using the Deferred Event Count. This mode only applies to event-based signatures. For each signature validation request, the Deferred Event Count must be supplied as a parameter. Identikey Server Administrator Reference 112

113 Field Listings 7.6 Client Properties Note Changes to Client records (add, change, delete) will not take effect immediately on all Identikey Servers unless Replication is used to synchronize the Identikey Servers. Where Replication is not used, changes to Client records will take effect when each Identikey Server is restarted, once the Client change is available to it in its data store. Alternatively, if there is no restart, the cache of Client records will refresh from the data store after approximately every 15 minutes. Table 39: Client Fields Field Name Client Type Location Protocol Policy Shared Secret Description The type of Client component represented by the record. For SOAP clients, the type needs to match the Component Type parameter passed in the SOAP requests. Each application can identify itself as a different type of Client. In addition there are some standard 0ptions: Administration Program RADIUS Client Citrix Web Interface Outlook Web Access IIS6 Module The IP address or name of the machine represented by the record. For all Client types except RADIUS Clients, this must be the source IP address of requests originating from that Client. For a RADIUS Client, it must be the NAS-IP-Address or NAS-Identifier values sent in the RADIUS requests. A RADIUS Client of Location default can be used to accept RADIUS requests from all IP addresses, using the same Shared Secret. However, where a RADIUS Client record with the exact Location exists, its Shared Secret will be used in preference to the default RADIUS Client's Shared Secret. The protocol by which requests will be received from the Client. SOAP RADIUS SEAL The standard SOAP protocol over HTTPS. This is used by programs using the SOAP interface from the Identikey Server SDK and the Web Administration Interface. The standard RADIUS protocol. This is used by various remote network access hardware and software systems. It can also be used as a simple authentication programming interface. A proprietary TCP/IP based protocol used by Identikey Server and VACMAN Middleware 3.x. It is used by the IIS6 Module, Digipass TCL Command-Line Administration and for Replication between Identikey Servers. The name of the Policy that should be used for authentication, Provisioning and signature validation requests from the Component. The RADIUS Shared Secret between the Identikey Server and the RADIUS Client. Identikey Server Administrator Reference 113

114 Field Listings Field Name Description Confirm Shared Secret Allows confirmation of a new shared secret. Created On Last Modified On License Key The date and time that the Client was created. Read-only. The date and time that the Client was last modified. Read-only. For each SEAL authentication Clients (IIS Modules), a License Key is required. This consists of a set of parameters followed by a signature. See 8 Licensing for more information. Identikey Server Administrator Reference 114

115 Field Listings 7.7 Back-End Server Properties Note Changes to Back-End Server records (add, change, delete) will not take effect immediately on all Identikey Servers unless Replication is used to synchronize the Identikey Servers. Where Replication is not used, changes to Back-End Server records will take effect when each Identikey Server is restarted, once the Back-End Server change is available to it in its data store. Alternatively, if there is no restart, the cache of Back-End Server records will refresh from the data store after approximately every 15 minutes. Table 40: Back-End Server Fields Field Name Description Protocol Domain Priority Authentication IP Authentication Port Accounting IP Accounting Port Shared Secret Confirm Shared Secret Timeout No. of Retries Base Search DN Security Principle DN Back-End Authentication Protocol. RADIUS, Active Directory, ADAM and e-directory are currently supported. This field provides the ability to assign particular Back-End Servers to a given Domain. This is optional. The priority in the case that there are multiple Back-End Servers. The highest priority server is tried first, then the next highest, etc. IP Address on which the RADIUS Server receives authentication requests. UDP Port on which the RADIUS Server receives authentication requests. IP Address on which the RADIUS Server receives accounting requests. UDP Port on which the RADIUS Server receives accounting requests. Shared secret between the Identikey Server and the RADIUS Server. Allows confirmation of a new shared secret. Number of seconds to wait for a response from the RADIUS Server before either retrying or trying another RADIUS Server. Number of times to retry if no response is received from the RADIUS Server. The DN where the search for user accounts starts. The DN of the security principle used to access the directory. Security Principle Password the password of the security principle. Created On Last Modified On Date/time of creation. Date/time of last modification. Identikey Server Administrator Reference 115

116 Field Listings 7.8 Reports Properties Table 41: Report fields Field Name Report Name Domain Name Report Type Description Data Source Grouping Level Description The name the report was given when it was created. The domain the report was created in. The report Type. List Analysis Report Detailed Analysis Report Distribution Analysis Report Trend Analysis Report List analysis reports list items that match the predefined criteria The Detailed Analysis Report shows detail of the events specified in the report definition Distribution analysis reports break down the values of certain items over other items. Trend analysis reports express a trend/evolution over a requested period of time for a set of reported items. The system therefore makes sub counts at a regular interval of the amount of times an item has occurred The description of the report that was entered when the report was created. Where the data in the report comes from. The sources can be: Users Users + Audit Digipass Digipass + Audit Audit The User data will be used to generate the report The User data and audit data will be used to generate the report Digipass data will be used to generate the report Digipass data and audit data will be used to generate the report. Only Audit data will be used to generate the report. The grouping level will be used to group the information on the report into the format you require. The grouping levels are: Client Domain Organizational Unit The report information will be grouped for each client The report information will be grouped for each Domain The report information will be grouped for each Organizational Unit Identikey Server Administrator Reference 116

117 Field Listings Time Frequency Created On Updated On User Digipass The report information will be grouped for each client The report information will be grouped for each Digipass For Trend Analysis reports. This type of report shows trends over a time period, taking sub counts at certain time periods. Use this field to specify the sub-count time frequency Date the report was created Date the report definition was last modified Identikey Server Administrator Reference 117

118 Field Listings 7.9 Identikey Server Properties Note Changes to Identikey Server records (add, change, delete) will not take effect immediately on all Identikey Servers unless Replication is used to synchronize the Identikey Servers. Where Replication is not used, changes to Identikey Server records will take effect when each Identikey Server is restarted, once the Identikey Server change is available to it in its data store. Alternatively, if there is no restart, the cache of Identikey Server records will refresh from the data store after approximately every 15 minutes. Table 42: Identikey Server Fields Field Name Location Policy Created On Last Modified On License Key Description The IP address of the Identikey Server represented by the record. The name of the Policy that should be used for administration logon requests from the Component, including live connections from the Audit Viewer. This Policy is used if there is no specific Administration Program Client record for the location of the administration logon. The date and time that the Client was created. Read-only. The date and time that the Client was last modified. Read-only. For each Identikey Server, a License Key is required. This consists of a set of parameters followed by a signature. See 8 Licensing for more information. Identikey Server Administrator Reference 118

119 Field Listings 7.10 Data Changes Requiring a Restart of Identikey Server Changes to the Data Store No data changes made in the Web Administration Interface, Digipass TCL Command-Line Administration or a SOAP administration client require a restart of the Identikey Server to take effect straight away. As this administration is carried out through the Identikey Server, the Identikey Server can immediately update any cached data. In addition, when multiple Identikey Servers are replicating database changes to each other, they update their cached data as changes are replicated. However, modifications listed in the Cached Data List topic below will not take effect until the Identikey Server is restarted, or until the caches re-load the data automatically, in the following cases: Multiple Identikey Servers are sharing a database. In this case, only the Identikey Server with which the data change is made will update its caches. Multiple Identikey Servers with their own database each are used, but they are not synchronized using Identikey Server Replication. Direct modifications are made to the database, for example with an SQL tool or using the VASCO Data Migration Tool. Note that direct modifications to the database are not replicated to any other Identikey Servers the same modifications must be made to each Identikey Server's database (or the whole database re-copied). Where multiple Identikey Servers are in use, with multiple databases, user-configured synchronization between the databases must be considered. A Identikey Server will not know about a data change made in another Identikey Server's database until that change has been copied to its own database Automatic Re-Loading of Cached Data In the Identikey Server, all cached data is periodically re-loaded from the data store. This time period, around 15 minutes, is tracked for each entry separately. Therefore, even without a restart, data changes will typically take effect within a matter of minutes (unless synchronization between databases is slower) Cached Data List The following data modifications relate to cached data: Creation, editing and deletion of Policy records Creation, editing and deletion of Client records Creation, editing and deletion of Back-End Server records Identikey Server Administrator Reference 119

120 Field Listings Creation, editing and deletion of Identikey Server records Creation, editing and deletion of Domain records Changes to Configuration Settings Configuration settings are modified using the Identikey Server Configuration utility, the Web Administration, SOAP commands, TCL commands. or can be modified directly in the XML file. Configuration changes done using the Identikey Server Configuration utility or directly in the XML file require a restart. The Identikey Server Configuration utility automatically prompts to restart the Service upon exiting. However if you modify the file directly, you will need to restart the Identikey Server Service using the Windows Service Control Manager. Configuration changes done using Web Administration, or the SOAP or TCL commands do not require a restart. Each Identikey Server has separate configuration settings. Changes to settings for one Identikey Server will not be automatically applied to other Identikey Servers. Storage Advanced Settings The settings edited using Advanced Settings tab in the Storage section are not replicated to other Identikey Servers. Normally these settings should be the same on all Identikey Servers, so you need to make sure they are applied to each one. As they are stored in the database itself, if you copy a database from one Identikey Server to another, these settings will be copied also. Identikey Server Administrator Reference 120

121 Licensing 8 Licensing 8.1 How is Licensing Handled? Identikey Server requires a License Key for each Identikey Server component. The License Key is stored in the Identikey Server record in the data store. It is tied to the location (IP address) where the Identikey Server is installed the Identikey Server will 'listen' on this IP address for SOAP and RADIUS requests. A License Key must be obtained from This will generate a License Key and allow you to download it in a text file. The License Key can then be loaded from the file into the data store. This process normally occurs in the Identikey Server Configuration Wizard, but may also be carried out later using the Web Administration Interface. The Identikey Server will not authenticate a user without a valid License Key, except to permit administration and reporting. Signature Validation and Provisioning will not be carried out without a valid License Key. Certain Client modules such as the IIS 6 Module for Citrix Web Interface also require a License Key to be loaded into their Client component record. The Identikey Servers to which they connect will otherwise reject all authentication requests from them. SOAP and RADIUS clients do not require a License Key in their Client component record. However, the Identikey Server License Key requires parameters to enable the use of SOAP and RADIUS. Certain types of request processing need to be enabled by parameters in the Identikey Server License Key: Authentication, Signature Validation and Provisioning. If you acquire new functionality, you will need to obtain new License Keys for all your Identikey Servers. This can be done using the Web Administration Interface. Evaluation Licenses An evaluation license allows you to utilize full functionality until the evaluation period runs out. At the end of this period, you will need to either uninstall the product or buy a permanent license. Contact your VASCO supplier's representative to acquire the licences you will need. For your convenience, the evaluation serial number is provided for you in the evaluation license activation web page. However, you still need to obtain and load a License Key. Client module licenses can also be evaluation (time-limited) licenses. 8.2 Licensing Parameters Table 43: License Parameters for Identikey Server Parameter Product Value The name of the VASCO product, eg. Identikey Server. Identikey Server Administrator Reference 121

122 Licensing Parameter Component Version Location Company Username SerialNo Generated Expires SOAP RADIUS Authentication Signature Provisioning Value The type of Component licensed, eg. Identikey Server. Current version number of the licensed VASCO product. The IP address for the machine represented by the Component record. The name of your company. Your name. The serial number for the VASCO product. The date and time that the license file was generated. Used for evaluation license only expiry date. Enable SOAP request processing. Enable RADIUS request processing. Enable Authentication request processing. Enable Signature Validation request processing. Enable Provisioning request processing Sample License File VASCO PRODUCT LICENCE Product=Identikey Server Component=Identikey Server Version=3.1 Expires=2009/06/19 02:40:32 GMT Location=test.vasco.com Company=VASCO Data Security Username=Mr Demo User SerialNo=0A2B4C6D8E Generated=2009/05/20 02:40:32 GMT SOAP=Yes Authentication=Yes Signature=Yes SIGNATURE :302C02147A487891E0745D 6866E0Af8DDB7D6AF092BFCD DbFCE5B500 D F0489DB159B END LICENCE View License Information To view the license information for a specific component: Identikey Server Administrator Reference 122

123 Licensing 1. Log into the Web Administration Interface. 2. For a Client component, click on the Clients tab. The Client List will be displayed. 3. For an Identikey Server component, click on the System tab. The Identikey Server List will be displayed. 4. Click on the required component record's link to view its property pages. 5. Click on the License tab. 8.4 Obtain and Load a License Key Note An active internet connection is required to obtain a License Key. 1. Follow the steps in 8.3 View License Information to view the License property tab for the required component. 2. Click on the Get License Key button. A browser window will be opened, with the VASCO license activation page loaded. Some details of the component will be entered automatically for you. 3. Enter any other required information into the web page. 4. When the License Key has been generated, right-click on the link where it says 'Right-click and save the file to disk'. Select the option to save the link save it with a.dat extension, for example as license.dat. The license file will also be ed to you. 5. A download of your License Key file should begin. Keep note of where you save the file, and its name. 6. Once the download is complete, go back to the Web Administration Interface and the License property tab. 7. Click on the Load License Key button. 8. Browse to the download location and select the License Key file. 9. Click on Upload to load the License Key from the file into the component record. 10. If you have new functionality enabled in the license, you will need to restart the Identikey Server in order for the new functionality to become available. In addition, the new functionality may need to be enabled in other Identikey Servers in your system. If so, you will need to follow this procedure for each one. Identikey Server Administrator Reference 123

124 Licensing 8.5 Re-Licensing You will need to obtain and load new License Keys for your Identikey Server components in the following situations: You need to change from an evaluation license to a permanent license. You need to enable new functionality. The Identikey Server's IP address is going to change or has changed. You are performing an Identikey Server upgrade where the minor or major versions are increasing (for example, from 3.0 to 3.1 or 4.0). See 8.4 Obtain and Load a License Key above for instructions on obtaining a new License Key in the first two cases. Identikey Server Administrator Reference 124

125 Web Sites 9 Web Sites 9.1 Customizing the Web Sites The User Self Management Web Site and OTP Request Site can be customized by modifying the pages provided with the installation. You may wish to: change the colors and graphics to match your corporate colors/logos integrate the pages into a larger web site translate or customize the text Any cosmetic part of the web pages may be modified. Completely new web pages may be used, provided that the correct form fields are posted to the CGI program, and query string variables are interpreted correctly. Server scripting languages such as PHP or ASP, or any other way of generating HTML, can be used. This section provides the instructions and reference material that you require to customize the site. It is assumed that the reader has some web development knowledge. 9.2 CGI Program A CGI script is used for the User Self Management Web Site and OTP Request Site. The CGI program carries out the following actions: Read and validate the input. This input is gathered from: Configuration settings from the registry Form variables posted Send an authorisation request to the RADIUS Server (if used, and provided that there were no validation errors) and interpret the response. Requests are sent to the Server using the RADIUS protocol. A component identifier Self-Mgt Site will indicate in the Audit Console which audit messages relate to requests from the User Self- Management Web Site. (OTP Request Site only) Send a request to the Message Delivery Component to send an OTP to the User's mobile phone via text message. Output the HTML to direct the user to the page that will indicate success or failure, or display a challenge. This is achieved by returning the HTML for a basic please wait page with a meta-refresh instruction to go directly to the appropriate page. The meta-refresh will happen immediately, but on a slow link you may notice the intermediate page. The CGI program cannot be customized. Its behaviour is controlled by the configuration settings and the posted form variables. The configuration settings are listed below; the posted form variables are specified in the Customizing the Web Site section. Identikey Server Administrator Reference 125

126 Web Sites Configuration Settings Various configuration settings are used by the CGI program to locate the RADIUS server(s) and to enable tracing. These can be modified using the Start->Programs menu option User CGI Configuration. The configuration settings are stored in the Windows Registry, at the path: HKEY_LOCAL_MACHINE\Software\VASCO\User CGI Table 44: Configuration Settings for CGI Program Trace-Mask Name Type Value Default Number (DWORD) Used to enable internal tracing levels. In general, just use these values: 0 = no tracing FFFFFFFF (hexadecimal) = full tracing Trace-File String Full path and filename of output file for internal tracing. NB: the file will be created if it is missing, but not the directory. Source-IP-Address String Source IP address to bind to when sending API requests, if any (only required if there are multiple IP addresses on the machine).eg <No default> <Blank> Server1-IP-Address String IP address of primary RADIUS Server. eg Server1-Port Number (DWORD) API port of primary RAIUS Server (in general, this should not be changed from the default). Server2-IP-Address String IP address of backup RADIUS Server, or blank if there is no backup. Server2-Port Number (DWORD) API port of backup RAIUS Server (in general, this should not be changed from the default) <Blank> Identikey Server Administrator Reference 126

127 Web Sites 9.3 Form Fields Registration Main Pages User Registration (UR), Digipass Assignment (DA) and Password Synchronization (PS) are all implemented using a single invocation of the CGI program. This permits them to be carried out either separately or in any combination. You can choose to separate them in your customized web site or keep them together as you prefer. If Challenge/Response or a Virtual Digipass is used, the user will enter their User ID, static password and Serial Number into the main page without a Digipass Response. They will be directed to a challenge page, which is specified in the next topic, in which they should enter either a Response to the challenge or the OTP sent to their mobile phone. The following table applies only to the main page. The following posted form fields must be used on the main page, according to the particular function and other conditions specified below: Table 45: Form Fields for Main Registration Page Form Field Name Visible Label (Default) Value(s) Required? UR PS DA dpcgi_operation <hidden> register for User Registration, Digipass Assignment or Password Synchronization. dpcgi_success_page <hidden> Relative or absolute URL of web page to go to if the function is successful. dpcgi_fail_page <hidden> Relative or absolute URL of web page to go to if the function fails. dpcgi_challenge_page <hidden> Relative or absolute URL of web page to go to if a challenge is returned for the user. Y Y Y Y Y Y Y Y Y (4) (1) dpcgi_userid UserId UserID in the Identikey Server. Y Y Y dpcgi_password Password Static password. Y Y Y dpcgi_serialno Serial Number Digipass serial number. Y dpcgi_response Digipass Response Digipass response (without static PIN if there is one). (5) (2) dpcgi_newpin New PIN New static PIN (for Go 1/Go 3). (3) dpcgi_confirmpin Confirm New PIN Confirm the new static PIN. (3) dpcgi_usecombinedpwd <hidden> True to send the password, serial number, response and PIN to the Identikey Server in one attribute. False to send the contents of the password field (1) If any users may self-assign a Challenge/Response Digipass, provide this form field. Identikey Server Administrator Reference 127

128 Web Sites (2) If any users may self-assign a Response Only Digipass, provide this form field. (3) If any users may self-assign a Response Only Digipass which uses a static PIN at the beginning of the response (eg. Go 1/Go 3), where the Digipass are initialized with no initial static PIN, they have to enter a new PIN the first time they use the Digipass. If they are self-assigning the Digipass, that means that they have to enter the new PIN and confirm it during the self-assignment process. They can do this by adding the new PIN twice at the end of the Digipass Response, however it may be more user-friendly to provide these two separate form fields. (4) If any users have a Challenge/Response application or a Primary Virtual Digipass, include this field. (5) If any users have a Response Only application, include this field Registration Challenge Page The Registration challenge page will be used for Digipass Challenge/Response or Virtual Digipass. The user enters their response to the challenge, to complete the registration process. The following posted form fields must be used on the challenge page: Table 46: Form Fields for Registration Challenge Page Form Field Name Visible Label (Default) Value(s) Required? dpcgi_operation <hidden> register for User Registration, Digipass Assignment or Password Synchronization. dpcgi_success_page <hidden> Relative or absolute URL of web page to go to if the function is successful. dpcgi_fail_page <hidden> Relative or absolute URL of web page to go to if the function fails. dpcgi_userid UserId UserID in the Identikey Server. Y dpcgi_response Digipass Response Digipass response or Virtual Digipass OTP. Y dpcgi_challenge Challenge Digipass challenge returned to the user. Y Y Y Y Note If you make dpcgi_challenge a visible form field, ensure that it is not modifiable. An alternative is to make it a hidden form field, while also displaying the challenge in HTML text rather than as a form field. Identikey Server Administrator Reference 128

129 Web Sites PIN Change The PIN Change function is only applicable for Digipass Response Only where the Server PIN is entered at the start of the response (eg. Go 1/Go 3). The following posted form fields must be used on the PIN Change page: Table 47: Form Fields for Server PIN Change Page Form Field Name Visible Label (Default) Value(s) Required? dpcgi_operation <hidden> changepin for PIN Change. Y dpcgi_success_page <hidden> Relative or absolute URL of web page to go to if the function is successful. dpcgi_fail_page <hidden> Relative or absolute URL of web page to go to if the function fails. dpcgi_userid UserId UserID in the Identikey Server. Y dpcgi_response Digipass Response Digipass response (without static PIN if there is one). Y dpcgi_currentpin Current PIN Current static PIN to be changed. (6) dpcgi_newpin New PIN New static PIN. Y dpcgi_confirmpin Confirm New PIN Confirm the new static PIN. Y (6) If the Digipass has had its Server PIN reset by the administrator because the user has forgotten it, there is no current Server PIN to enter here. In all other cases, the current Server PIN must be provided to permit the PIN change. Y Y Identikey Server Administrator Reference 129

130 Web Sites Login Test Main Page If a Challenge/Response application or Primary Virtual Digipass is used, the user will enter just their UserId (and maybe password) into the main page without a Digipass Response. If using the Backup Virtual Digipass, they will need to enter the trigger specified in server settings (password and/or a Keyword) into the password field. They will be directed to a challenge page, specified in the next topic. The following table applies only to the main page. The following posted form fields must be used on the main page: Table 48: Form Fields for Main Login Test Page Form Field Name Visible Label (Default) Value(s) Required? dpcgi_operation <hidden> testlogin for Login Test. Y dpcgi_success_page <hidden> Relative or absolute URL of web page to go to if the function is successful. dpcgi_fail_page <hidden> Relative or absolute URL of web page to go to if the function fails. dpcgi_challenge_page <hidden> Relative or absolute URL of web page to go to if a challenge is returned for the user. dpcgi_userid UserId UserID in the Identikey Server. Y dpcgi_response Digipass Response Digipass response (with static PIN if there is one). (8) (7) If any users have a Challenge/Response Digipass, a Primary Digipass or use the Backup Virtual Digipass feature, provide this form field. (8) If any users have a Response Only Digipass, provide this form field. Y Y (7) Identikey Server Administrator Reference 130

131 Web Sites Login Test Challenge Page The user enters their response to the challenge or the OTP sent to their mobile phone to complete the login test. The following posted form fields must be used on the challenge page: Table 49: Form Fields for Login Test Challenge Page Form Field Name Visible Label (Default) Value(s) Required? dpcgi_operation <hidden> testlogin for Login Test. Y dpcgi_success_page <hidden> Relative or absolute URL of web page to go to if the function is successful. dpcgi_fail_page <hidden> Relative or absolute URL of web page to go to if the function fails. dpcgi_userid UserID User ID in the Identikey Server. Y dpcgi_response Digipass Response Digipass response. Y dpcgi_challenge Challenge Digipass challenge returned to the user. Y Y Y Note If you make dpcgi_challenge a visible form field, make sure that it is not modifiable. An alternative is to make it a hidden form field, while also displaying the challenge in HTML text rather than as a form field. Identikey Server Administrator Reference 131

132 Web Sites OTP Request Site Request Page The request page must contain the following fields: Table 50: Form Fields for OTP Request Page Name Type Username text Visible Password Password Visible dpcgi_operation VDPrequest Hidden dpcgi_vdp_success_page Name of OTP was sent Page Hidden dpcgi_vdp_fail_page Name of OTP not sent Page Hidden dpcgi_vdp_wrongtoken_page Name of Not a Virtual Digipass Page Hidden Identikey Server Administrator Reference 132

133 Web Sites 9.4 Query String Variables The query string variables that are passed to the web pages by the CGI program are mainly concerned with status and error reporting. There is also a variable that is used to pass a challenge to the pages that display one Failure/Error Handling There are three main groups of failures that can occur, which should be handled in a different manner. In all cases there is a numeric error code, however in some cases there is an auxiliary code and message such as the return code and message from the Identikey Server. The main error codes will be assigned in three separate ranges, so that the web pages can identify which category of error is returned. API return codes these are returned by the VASCO API used to make the authentication request to the Server. In some cases there will be an auxiliary code and message. CGI errors these errors are detected by the CGI program, mainly when the web pages are not providing or enforcing the posted form fields correctly. These will not generally have an auxiliary code and message, but it is possible. Internal errors these are technical errors that should not occur. In some cases there will be an auxiliary code and message. The intention of using this code-based scheme is to allow translation and customization of the messages. The main error code will be translated into a message by the web pages themselves. The pages can also translate the auxiliary code into a message, for the Identikey Server codes, but normally, the pages would not know how to translate it into a message, and should display the auxiliary message as provided. Identikey Server Administrator Reference 133

134 Web Sites Query String Variable List The following table indicates which variables are used for the User Self Management Web Site and the required conditions: Table 51: Query String Variable List Variable Value Condition Used by Site result 0 Successful authentication request Both challenge serialno auxcode auxmsg <API return code, numeric> Unsuccessful authentication request Both <error code, numeric> CGI or internal error occurred Both <challenge returned by API, string> <Digipass Serial Number assigned> <VACMAN Controller return code, numeric> <additional error code for CGI or internal error, numeric> <Message for VACMAN Controller return code, string> <message for CGI or internal error, string> Challenge returned by API Successful Auto- or Self- Assignment Unsuccessful authentication request due to Controller rejecting password CGI or internal error occurred, where another error code is relevant Unsuccessful authentication request due to Controller rejecting password CGI or internal error occurred, where an error message is relevant User Self Management Web Site only User Self Management Web Site only Both Both Both Both Examples: success: /vmsite/success.html?result=0 invalid Digipass response due to code replay: /vmsite/fail.html?result=1000&auxcode=2&auxmsg=code+replay+attempt challenge: /vmsite/challenge.html?challenge= Identikey Server Administrator Reference 134

135 Web Sites Return Code Listing In the following tables, the Message is the one that is provided by the standard web pages that we install API Return Codes The following codes are the ones that in normal cases might be returned: Table 52: API Return Codes Code Message Auxiliary Code/ Message? Notes -1 Error during request to Server N We are unable to distinguish the error from the client side of the API the administrator would have to look at the Audit Console CGI Errors Table 53: CGI Error Return Codes Code Message Auxiliary Code/ Message? -100 Only the POST method is permitted N -101 No dpcgi_operation was posted N -102 An invalid dpcgi_operation was posted N -103 dpcgi_challenge_page cannot be used for this operation N -104 dpcgi_password cannot be used for this operation N -105 dpcgi_serialno cannot be used for this operation N -106 dpcgi_currentpin cannot be used for this operation N -107 dpcgi_newpin cannot be used for this operation N -108 dpcgi_confirmpin cannot be used for this operation N -109 dpcgi_challenge cannot be used for this operation N -110 dpcgi_success_page must be entered for this operation N -111 dpcgi_fail_page must be entered for this operation N -112 dpcgi_userid must be entered for this operation N -113 dpcgi_password must be entered for this operation N -114 dpcgi_response must be entered for this operation N -115 dpcgi_newpin must be entered for this operation N Identikey Server Administrator Reference 135

136 Web Sites Internal Errors Code Message Auxiliary Code/ Message? -116 dpcgi_confirmpin must be entered for this operation N -117 A Digipass Response is required to assign a Digipass N -118 A New PIN can only be set when assigning a Digipass N -119 Enter the new PIN in the New PIN and Confirm New PIN fields N -120 The New PIN and Confirm New PIN fields have different values N -121 A challenge was returned, but there is no dpcgi_challenge_page N -122 Unknown parameter N -123 The Content-Length passed in was invalid N -124 dpcgi_serialno must be entered for this operation N -131 Wrong token page is forbidden N Table 54: Internal Error Codes Code Message Auxiliary Code/ Message? Cannot read Trace-Mask configuration setting Y Cannot read Trace-File configuration setting Y Cannot open Trace-File Y Cannot read Source-IP-Address configuration setting Y Cannot read Server1-IP-Address configuration setting Y Cannot read Server1-Port configuration setting Y Cannot read Server2-IP-Address configuration setting Y Cannot read Server2-Port configuration setting Y Invalid configuration setting Source-IP-Address Y Invalid configuration setting Server1-IP-Address Y Invalid configuration setting Server1-Port Y Invalid configuration setting Server2-IP-Address Y Invalid configuration setting Server2-Port Y Cannot read HTTP request data N Request to Server not completed Y Cannot read Self-Management Site registry key Y Identikey Server Administrator Reference 136

137 Web Sites Code Message Auxiliary Code/ Message? The specified Source-IP-Address is not on this machine N Cannot read Trace-Header configuration setting Y Invalid configuration setting Trace-Header Y The Trace file name must not contains quotes ' or ". N No File found in the trace file <trace file name> N Error reading Server 1 Secret - return code was <return code> N Error reading Server 2 Secret - return code was <return code> N Error reading No of Retries - return code was <return code> N Error reading Timeout - return code was <return code> N Error writing Protocol - return code was <return code> N The Shared Secret and Confirm Shared Secret do not match. N Identikey Server Administrator Reference 137

138 Login Options 10 Login Options 10.1 Login Permutations The information required to be entered during a login will vary according to the configuration settings of the relevant Policy, the login method, and any actions to be performed during the login. This section refers to authentication processing only, not Signature Validation or Provisioning Login Methods The login methods specified are: Response Only Challenge/Response: 1-Step Challenge/Response: a random challenge is presented on the login page before the User ID is known. This is supported for SOAP clients and form-based IIS Modules. 2-Step Challenge/Response: a challenge is generated after the user submits their User ID with a request to be given a challenge. The user then logs in with the response to the challenge in a second step. This is supported for all kinds of authentication client. Virtual Digipass - Primary or Backup Login Actions A User may be allowed to do these things during a login: Set their Server PIN on first use or after a PIN reset. Change their Server PIN. Inform the Identikey Server that their static password for the Back-End System eg. Windows - has been modified. Perform a Self-Assignment for a Digipass in their possession Login Variables The variables which a User may need to enter, in order to do one of the above functions are listed below. The code or word used to designate each variable in the following tables is included in brackets. One Time Password (OTP) Password (Password) Identikey Server Administrator Reference 138

139 Login Options Server PIN (PIN) Serial Number of their Digipass (Serial No) Serial Number Separator (Sep.) Request Keyword (Keyword) Password Format In a SOAP authentication request, there are two Password Formats that can be used: Cleartext Combined Using this format, all the login variables listed above must be entered into a single password field. This format applies when the login screen or web page cannot be extended with additional entry fields. Cleartext Separate Using this format, the login variables are entered in separate fields. In RADIUS authentication requests, the PAP password protocol corresponds to the Cleartext Combined password format. The CHAP, MS-CHAP and MS-CHAP2 password protocols are handled as different password formats (as the password is hashed in various ways according to the protocol). In general, these hash-based password formats are not capable of combining different login variables, unless all the variables are already known to the Identikey Server. In administrative logons and IIS Module authentication requests, the Cleartext Combined password format is always used Policy Settings The Policy settings which will affect the variables required in logins are: Stored Password Proxy If this attribute is set to Enabled, each User's password must be kept up to date in the Identikey Server. This is typically achieved by enabling Password Autolearn. Password Autolearn If the Identikey Server is informed of a User's password change, the new password will only be recorded by the Identikey Server if Password Autolearn is enabled in the relevant Policy Serial Number Separator If a Serial Number Separator is specified, the User may enter their Digipass serial number exactly as it appears on the back of their Digipass (or in the documentation provided to the User), including dashes. If a Serial Number Separator is not specified, the Digipass serial number must be padded to 10 characters, with all nonnumerical characters removed. Back-End Authentication Identikey Server Administrator Reference 139

140 Login Options In the following login permutations tables, 'Back-End Authentication Required' means that the Back-End Authentication setting is set to Always or If Needed. Note Back-End Authentication is required for Self-Assignment and Password Autolearn logins Response Only Cleartext Combined Password Format The following two tables apply to the following cases: SOAP using Cleartext Combined password format Administration logins RADIUS using PAP IIS Modules The first table applies in these cases when: EITHER the Stored Password Proxy feature is enabled OR Back-End Authentication is not enabled Table 55: Login Permutations - Response Only Cleartext Combined (1) Login Type Existing PIN? Separator? Password Field Contents Server PIN Required Normal login Yes N/A PIN+OTP Set PIN No N/A OTP+NewPIN+NewPIN Change PIN Yes N/A PIN+OTP+NewPIN+NewPIN Changed Password Yes N/A Password+PIN+OTP Set PIN and Changed Password No N/A Password+OTP+NewPIN+NewPIN Change PIN and Changed Password Yes N/A Password+PIN+OTP+NewPIN+NewPIN Self-Assignment 1 Yes Yes SerialNo+Sep.+Password+PIN+OTP No Server Normal login N/A N/A OTP No SerialNo+Password+PIN+OTP No Yes SerialNo+Sep.+Password+OTP+NewPIN+NewPIN No SerialNo+Password+OTP+NewPIN+NewPIN 1 If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to 10 characters with preceding zeroes. Note that Back-End Authentication is required for successful Self-Assignment. Identikey Server Administrator Reference 140

141 Login Options Login Type Existing PIN? Separator? Password Field Contents PIN Required Changed Password N/A N/A Password+OTP Self-Assignment N/A Yes SerialNo+Sep.+Password+OTP The second table applies in these cases when: The Stored Password Proxy feature is not enabled AND Back-End Authentication is enabled Table 56: Login Permutations - Response Only Cleartext Combined (2) No SerialNo+Password+OTP Login Type Existing PIN? Separator? Password Field Contents Server PIN Required No Server PIN Required Normal login Yes N/A Password+PIN+OTP Set PIN No N/A Password+OTP+NewPIN+NewPIN Change PIN Yes N/A Password+PIN+OTP+NewPIN+NewPIN Changed Password Yes N/A Password+PIN+OTP Set PIN and Changed Password No N/A Password+OTP+NewPIN+NewPIN Change PIN and Changed Password Yes N/A Password+PIN+OTP+NewPIN+NewPIN Self-Assignment 2 Yes Yes SerialNo+Sep.+Password+PIN+OTP No SerialNo+Password+PIN+OTP No Yes SerialNo+Sep.+Password+OTP+NewPIN+NewPIN No SerialNo+Password+OTP+NewPIN+NewPIN Normal login N/A N/A Password+OTP Changed Password N/A N/A Password+OTP Self-Assignment N/A Yes SerialNo+Sep.+Password+OTP No SerialNo+Password+OTP Examples Self-Assignment of a GO 1 Digipass with no existing Server PIN and Serial Number Separator set to '::' ::pA192ss Self-Assignment of a GO 3 Digipass with no Server PIN required and no Serial Number Separator set PA192ss If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to 10 characters with preceding zeroes. Note that Back-End Authentication is required for successful Self-Assignment. Identikey Server Administrator Reference 141

142 Login Options Response Only CHAP/MS-CHAP/MS-CHAP2 The following table applies to the following case only: RADIUS using CHAP, MS-CHAP or MS-CHAP2 EITHER the Stored Password Proxy feature is enabled OR Back-End Authentication is not enabled Table 57: Login Permutations - Response Only CHAP/MS-CHAP/MS-CHAP2 Login Type Server PIN Required? Normal login Yes PIN+OTP Password Field Contents No OTP Step Challenge/Response Cleartext Combined Password Format The following table applies to the following cases: SOAP using Cleartext Combined password format Administration logins RADIUS using PAP IIS Modules Challenge/Response in RADIUS is only supported for PAP. The column Stored Password Proxy Off AND Back-End Auth. Required contains Yes when: The Stored Password Proxy feature is not enabled AND Back-End Authentication is enabled In most cases, this does not affect 2-Step Challenge/Response; just when a Keyword only is used. Identikey Server Administrator Reference 142

143 Login Options Table 58: Login Permutations 2-Step Challenge/Response Cleartext Combined Login Type Serial Number Separator? Request Method 2-Step Challenge/Response Stored Password Proxy Off AND Back- End Auth. Required 3 Pre-Challenge Response Normal login N/A Keyword Yes Keyword Password+OTP No Keyword OTP Password N/A Password OTP Keyword-Password N/A Keyword+Password OTP Password-Keyword N/A Password+Keyword OTP Changed Password N/A Keyword N/A Keyword Password+OTP Password N/A Password OTP Keyword-Password N/A Keyword+Password OTP Password-Keyword N/A Password+Keyword OTP Self-Assignment 4 Yes N/A N/A SerialNo+Sep.+Password OTP No N/A N/A SerialNo+Password OTP 3 Back-End Authentication is required for Self-Assignment and Password Autolearn logins. 4 If a Serial Number Separator is not set, the serial number must have all non-numerical characters removed and be padded to 10 characters with preceding zeroes. Identikey Server Administrator Reference 143

144 Login Options Virtual Digipass The 2-step Virtual Digipass login is possible when using a SOAP client, the RADIUS Access-Challenge mechanism or an IIS Module in form-based authentication mode. The static password is required in either the first or the second step, but not both. However, many RADIUS environments and IIS Module 'basic authentication' do not support the 2-step login process. If the 2-step login process is not possible, two separate 1-step logins are required. The second login must include the Password as well as the OTP, but it is not necessary to provide the Password in the first login, if only a Keyword is used. Using the Cleartext Combined password format, all inputs in the table below are entered into the Password field. Using the Cleartext Separate password format, the Keyword and/or Password are always entered into the Static Password field, while the OTP is entered into the OTP field. Table 59: Login Permutations Virtual Digipass Login Type Normal login Changed Password Request Method 2-step login Two 1-step logins Step 1 Step 2 Step 1 Step 2 Keyword Keyword Password+OTP Keyword Password+OTP Password Password OTP Password Password+OTP Keyword-Password Keyword+Password OTP Keyword+Password Password+OTP Password-Keyword Password+Keyword OTP Password+Keyword Password+OTP Keyword Keyword Password+OTP Keyword Password+OTP Password Password OTP Password Password+OTP Keyword-Password Keyword+Password OTP Keyword+Password Password+OTP Password-Keyword Password+Keyword OTP Password+Keyword Password+OTP Identikey Server Administrator Reference 144

145 Identikey Server Configuration Settings 11 Identikey Server Configuration Settings 11.1 Identikey Server Configuration Wizard The Identikey Server Configuration Wizard runs in two different modes: First Time Mode After the Identikey Server is installed, the Configuration Wizard needs to be run in First Time mode. This ensures that all necessary configuration to get the Identikey Server operational is accomplished as easily as possible. This mode creates the Identikey Server configuration file and initializes the data store with default data and the first administrator account. Afterwards, configuration settings can be managed using the Identikey Server Configuration utility. The data store can be managed using the Web Administration Interface and Digipass TCL Command-Line Administration. The Configuration Wizard starts up in First Time mode if the Identikey Server configuration file is not present. Maintenance Mode If the Identikey Server configuration file is present, the Configuration Wizard will start up in Maintenance mode. In Maintenance mode, an operations menu is available to carry out certain maintenance tasks that cannot be carried out with the day-to-day administration tools. These tasks are: Re-run Installation Wizard Change Server location Back Up Audit Messages - Back up Audit Message files or databases Rescue administrator - create a new administrator account Rescue Administration Client - create or modify an Administration Program client Install SSL server certificate Restore Default Policies and Reports 11.2 Redeploy Administration Web Interface After running the Configuration Wizard or making changes to SSL certificate settings, the Administration Web Interface must be redeployed: 1. Open a command line window. 2. Navigate to the <install directory>\webadmin directory. 3. Delete the existing certificate from the keystore using the following command: Identikey Server Administrator Reference 145

146 Identikey Server Configuration Settings java -jar admintool.jar certificate delete <keystore location> <keystore password> where <keystore location> is the location and file name of the keystore and <keystore password> is the password on the keystore. For example: java -jar admintool.jar certificate delete c:\program Files\VASCO\Identikey 3.1\webadmin\keystore.jks password1 4. Add the new certificate that has been generated: java -jar admintool.jar certificate add <keystore location> <keystore password> <new certificate> where <keystore location> is the location and file name of the keystore, <keystore password> is the password on the keystore and <new certificate> is the certificate that was generated after re-running the configuration wizard. For example: java -jar admintool.jar certificate add c:\program Files\VASCO\Identikey 3.1\webadmin\ keystore.jks password1 c:\program Files\VASCO\Identikey 3.1\bin\ikeycerts.pem 5. Restart the web server application. Identikey Server Administrator Reference 146

147 Identikey Server Configuration Settings 11.3 Identikey Server Configuration A Graphical User Interface (GUI) is available for use in configuring the Identikey Server. There are several sections in Identikey Server Configuration, which can be reached by clicking on the corresponding image on the left hand side. When settings are changed, click on the Apply or OK button to write them to the configuration file. Clicking OK also closes Identikey Server Configuration. Note A restart of the Identikey Server service or daemon is required after any change to Identikey Server configuration settings. When exiting the Configuration Wizard, you will be prompted to allow an automatic restart of the service. The Administration Web Interface must also be redeployed if any changes are made to the SSL certificate settings. This includes running the Configuration Wizard. See 11.2 Redeploy Administration Web Interface for instructions Starting the Configuration GUI Windows To start the Identikey Server Configuration, click on the Start Button and select Programs -> VASCO ->Identikey Server -> Identikey Server Configuration. Linux To start the Identikey Server Configuration in graphical interface mode, open a command prompt and enter: vds_chroot <install dir> /usr/sbin/ikconfigwizardgui To start the Identikey Server Configuration GUI in console mode, open a command prompt and enter: vds_chroot <install dir> /usr/sbin/ikconfigwizardconsole General Section This section contains a few general settings Identikey Server Administrator Reference 147

148 Identikey Server Configuration Settings Server Location The Server Location setting contains the licensed IP address for the Identikey Server. The Identikey Server uses this IP address to listen for SOAP and RADIUS requests. There must be a Identikey Server component record with this Location, containing a valid License Key. The setting is carried forward to the Communication Protocols pages Administration Session Settings The following settings control the number and lifetime of administration sessions for this Identikey Server: Max Concurrent Sessions: the maximum number of concurrent administration sessions permitted. If this is set to 0, concurrent sessions will be unlimited. Max Session Time (seconds): the maximum allowed length of an administration session. There is no way to extend a session beyond this limit. Idle Timeout (seconds): the maximum length of time of inactivity allowed during a session, before the session it automatically terminated by the Identikey Server Tracing To enable or disable tracing by Identikey Server: 1. Select a Tracing option. 2. Enter a path and filename for the tracing file into the File field. The file path entered must be the full absolute path. Note If the File field is left blank or the path does not exist, the Identikey Server will not output tracing. If the file does exist, tracing will be appended to the file. If the path is valid but the file does not exist, it will be created Communicators Section This section contains settings for the Communicator modules (see the Structure of Identikey Server section in the Product Guide) SOAP The SOAP Communicator settings are: Identikey Server Administrator Reference 148

149 Identikey Server Configuration Settings Enable SOAP: whether to listen for and process SOAP requests or not. Note that the Identikey Server's License Key must enable SOAP for it to be enabled. IP Address: the IP address on which to listen for SOAP requests. This is read-only, as it must be the same as the licensed IP address for the Identikey Server. It can be changed in the General section using the Server Location setting (see Server Location). Port: the port number on which to listen for SOAP requests. DPX File Upload Location: the directory in which DPX files uploaded using the SOAP administration interface will be stored by the Identikey Server. This is used by the Web Administration Interface. Server Certificate: the details for the SSL server certificate. The Certificate File address must be the address of a.pem file. Client Certificate: the details for the SSL client certificate. CA certificate store is the absolute address to the file that contains the approved CA list. See the SOAP SSL section in the Product Guide. Require Client Certificate indicates whether the client certificate is required to during SSL processing. See the SOAP SSL section in the Product Guide for further information. The valid values are: Never Optional Required Required - Signed Address Only Re-Verify on re-negotiation - see the SOAP SSL section in the Product Guide for more details RADIUS The RADIUS Communicator settings are: Enable RADIUS: whether to listen for and process RADIUS requests or not. Note that the Identikey Server's License Key must enable RADIUS for it to be enabled. IP Address: the IP address on which to listen for RADIUS requests. This is read-only, as it must be the same as the licensed IP address for the Identikey Server. It can be changed in the General section using the Server Location setting (see Server Location). Authentication Port: the port number on which to listen for RADIUS Access-Requests. You may specify more than one port, using a comma-separated list. Accounting Port: the port number on which to listen for RADIUS Accounting-Requests. You may specify more than one port, using a comma-separated list SEAL The SEAL Communicator settings are: Identikey Server Administrator Reference 149

150 Identikey Server Configuration Settings Enable SEAL: whether to listen for and process SEAL requests or not. Note that SEAL does not need to be enabled in the Identikey Server's License Key. Caution Replication updates from other Identikey Servers are received by the SEAL Communicator. If you disable it, this Identikey Server will not be able to receive Replication updates. Digipass TCL Command-Line Administration also uses SEAL to connect to the Identikey Server. IP Address: the IP address on which to listen for SEAL requests. This does not have to be the same as the licensed IP address for the Identikey Server. Port: the port number on which to listen for SEAL requests. DPX File Upload Location: the directory in which DPX files uploaded using the SEAL administration interface will be stored by the Identikey Server. This is used by the Web Administration Interface. Require administration client component registration: whether to use strict client component checking for SEAL administration logons or not. If this option is enabled, there must be an Administration Program client component record for every Location at which Digipass TCL Command-Line Administration runs and for every Location at which an Audit Viewer sets up a Live Connection to an Identikey Server Scenarios Section This section contains settings for the Scenario modules (see the Structure of Identikey Server section in the Product Guide). Some Scenario modules do not have specific settings except to enable or disable them, while others do have further settings Authentication Scenario The only setting for this Scenario is to enable or disable it. Note that the Identikey Server's License Key must enable Authentication for it to be enabled Signature Validation Scenario The only setting for this Scenario is to enable or disable it. Note that the Identikey Server's License Key must enable Signature for it to be enabled Provisioning Scenario This Scenario has the following settings: Enable Provisioning: whether to process Provisioning requests or not. Note that the Identikey Server's License Key must enable Provisioning for it to be enabled. Identikey Server Administrator Reference 150

151 Identikey Server Configuration Settings Min Intervals: the minimum length of time in minutes between activation attempts for a particular Digipass. Max Attempts: the total number of activation attempts (successful or unsuccessful) per Digipass. Max Locations: the maximum number of different locations at which a particular Digipass can be activated. This only applies where the location is specified as part of Provisioning (Digipass for Web) Administration Scenario The only setting for this Scenario is to enable or disable it. Note that no License Key is required for administration to be enabled Reporting Scenario This Scenario has the following settings: Enable Reporting: whether to process Reporting requests or not. Note that no License Key is required for reporting to be enabled. Source: the type of audit data source to use for report generation. UTF8 File and ODBC Database are the supported options. If UTF8 File is selected, the following settings are required: File Path: the full absolute path to the directory in which the audit text files can be found. Note that the search for audit files is not recursive - all files must be in this exact directory. Extension: the file extension that identifies which files in the File Path are audit files to be read. For example,.audit. If ODBC Database is selected, the following settings are required: DSN: the ODBC Data Source Name for the audit database. Username: the username with which to log into the audit database, if required. Password: the password to log into the audit database, if required Audit Scenario The only setting for this Scenario is to enable or disable it. Note that no License Key is required for the Audit Scenario to be enabled. When this Scenario is disabled, live connections from the Audit Viewer are not possible to this Identikey Server Replication Scenario The only setting for this Scenario is to enable or disable it. Note that no License Key is required for administration to be enabled. Identikey Server Administrator Reference 151

152 Identikey Server Configuration Settings When this Scenario is disabled, Replication updates sent to this Identikey Server will not be processed Configuration Scenario This scenario allows configuration settings to be edited from the Administration Web Interface. The scenario may be enabled or disabled. No other settings are required Engines Section This section allows you to set up custom Back-End Authentication Engine plug-in modules (see the Structure of Identikey Server section in the Product Guide and the Identikey Server SDK Guide). Click on the Add... button if you wish to add a new plug-in engine. The Add Plugin Engine window will be displayed. Select an engine and click on Edit... to change the settings for that engine. The Edit Plugin Window will be displayed. Both windows contain the same information. Add or edit the details as follows: 1. Enter a Display Name for the engine (this will just be used in the Engines list). 2. Enter a Library Path, indicating where the engine is kept. 3. Enter a Protocol to be used when the engine is connecting to Identikey Server. 4. Enter Custom Fields - the Name and Value of fields used to pass parameters into the back-end engine. They are entirely user-defined and the name and value are passed into the back-end engine as a string. To test the connection to the plug-in engine, select an engine and click Test. Enter the domain name, User Id and Password and click Authenticate Storage Section This section contains settings to configure the Identikey Server data store ODBC Data Sources The database(s) used to store data required by Identikey Server are listed in this tab. You may wish to add another database to this list if load-balancing or fail-over mechanisms need to be implemented. 1. Click on the Add... button if you wish to add a new database or Edit... if you wish to modify the settings for an existing database. 2. The Add New ODBC Data Source window will be displayed. 3. Enter a Display Name for the data source (this will just be used in data source list). 4. Enter the name (DSN) of the ODBC data source. Identikey Server Administrator Reference 152

153 Identikey Server Configuration Settings 5. Enter the Username and Password of a database administrator account with permissions to read, update, create and delete data used by Identikey Server (see 3.6 Database User Accounts). 6. Click on the Test Connection button. If the information has been entered correctly, the test should be successful. 7. Enter the minimum time the Identikey Server should wait before trying to reconnect to this data source (in seconds), after the connection has broken, into the Min Reconnect Interval (s). 8. Enter the maximum time the Identikey Server should wait before retrying the connection to this data source into the Max Reconnect Interval (s). 9. Click on the OK button to close the window. Identikey Server Administrator Reference 153

154 Identikey Server Configuration Settings LDAP Data Sources Encryption Active Directory domains to which the Identikey Server can connect are listed in this tab. 1. Click on the Add... button if you wish to add a new domain or Edit... if you wish to modify the settings for an existing domain. 2. The Add LDAP Domain window will be displayed. 3. Enter the Fully Qualified Domain Name for the domain. 4. If required, enter the name of a server in the domain in the Preferred Server field. If a Preferred Server is specified, the Identikey Server will attempt to connect to it rather than the first available server in the domain. 5. If the Identikey Server should only connect to the Preferred Server, tick the Preferred Server Only checkbox. 6. To use an encrypted connection, tick the Encrypt Remote Connections checkbox. 7. Enter a port number to use for unencrypted connections in the Unencrypted Port field. 8. If the Encrypt Remote Connections checkbox is ticked, enter a port number to use for encrypted connections in the Encrypted Port field. 9. Enter an integer in the Max. Bind Lifetime field. 10. Click on the OK button to close the window. See 4 Sensitive Data Encryption for more information on encryption in the Identikey Server data store. All Identikey Servers must share the same encryption settings. To modify encryption settings for the first Identikey Server: 1. If required, enter a custom encryption key in the Storage Key field. This must consist of 32 hex digits. The Storage Key is used to derive a unique encryption key for your installation. Caution If you change from having no Storage Key to having a Storage Key specified, all Digipass records already in the data store will be invalidated. They will need to be deleted and re-imported. However, Passwords and Shared Secrets in the data store will still be valid (they will be converted to the new Storage Key when they are next updated). If you change from one Storage Key to a different Storage Key, all Digipass records, Passwords and Shared Secrets in the data store will be invalidated, and will have to be re-entered. 2. If required, select an encryption algorithm from the Cipher Name drop down list. The available algorithms are aes256 (AES), des_ede (Triple DES) and des_ede3 (Triple DES with 3 keys). Identikey Server Administrator Reference 154

155 Identikey Server Configuration Settings If you have any other Identikey Servers, you need to export the new encryption settings and import them into the other Identikey Servers. 3. Click on Export Browse to a directory in which to create an encryption settings file. 5. Enter a file name to export the settings to. 6. Click on OK. 7. Enter a password to protect the Storage Key. 8. Click on OK. For each other Identikey Server, launch the Identikey Server Configuration utility and open the Encryption tab: 9. Click on Import Browse to the encryption settings file. 11. Click on OK. 12. Enter the required password. 13. Click on OK Advanced Configuration Settings This tab contains settings related to database connection management, as well as User ID and Domain handling. While the top two settings are stored in the Identikey Server configuration file, the other settings are stored inside the database itself, in the Control table. Each database has its own Control table, so those settings may need to be modified in more than one database. See 3.7 Database Connection Handling for more details about the connection management settings. Data Source-Independent Connection Settings The following settings are not specific to a data source, but relate to the handling of connections to all data sources: Connection Wait Time (ms): the time in milliseconds to wait for a database connection to become available when processing a command, before giving up and failing the request. Enable Load Sharing: whether to use the extra data sources (after the first one) when the first one is busy (enabled), or only when it cannot be contacted (disabled). Data Source-Specific Connection Settings The following settings are specific to each data source and can be configured differently in each if required. Use the Data Source Connection drop-down to view and edit the settings for each data source. Max Connections: the maximum number of connections to establish to this data source. Idle Timeout (seconds): the maximum time for which a connection can be idle before it is closed. Identikey Server Administrator Reference 155

156 Identikey Server Configuration Settings User ID and Domain Settings The following settings are stored in the Control table and are therefore configured in each data source separately. However, they should normally be the same in each data source. You will have to make sure that they are configured in each data source, as there is no automatic replication of these settings. User ID Conversion / Case Use Windows User Name Resolution Master Domain They are explained in more detail below: User ID Conversion The case in which the Identikey Server will save and retrieve User IDs will depend on: The capabilities and settings of the database used as the data store for the Identikey Server. Your database may require case sensitivity in queries, or may store all data in lower or upper case. Configuration settings for the Identikey Server. The Identikey Server may be configured to save and retrieve User IDs and domain names in: Lower case Upper case No conversion data is saved or searched on exactly as entered. The default configuration setting for the Identikey Server when using an embedded database is Convert to Lower. When using another ODBC database, the default is No Conversion. Caution Before changing the configuration setting, you need to make sure that existing User IDs and Domain names will not be invalidated by the new setting, or that they are deleted before the setting is changed. For example, if the current setting is No Conversion and you change to Convert to Lower, a User ID TestUser would become invalid. This Digipass User account must be deleted before changing the Case Conversion setting. Typically, this setting should be changed shortly after installation, so you do not have to deal with a lot of existing Digipass User account and Domain records. If you want to move from Convert to Lower to Convert to Upper, or vice versa, it will be necessary to make the change in two steps, via No Conversion. While the setting is No Conversion, upper or lower case User IDs and Domains can be created and deleted as necessary. This is especially important for the Master Domain name. The default Master Domain master will become invalid if you change to Convert to Upper. Therefore, you will need to create a new Domain with an upper case name and make it the Master Domain, while the Case Conversion Identikey Server Administrator Reference 156

157 Identikey Server Configuration Settings setting is No Conversion. See Master Domain below for instructions to change the Master Domain. To modify the Case Conversion setting for the Identikey Server: 1. Select a data source from the list. 2. If you wish the Identikey Server to convert User IDs to upper or lower case, select Convert to Upper or Convert to Lower from the Case drop down list. To leave User IDs and domains as they are entered, select No Conversion. 3. Click on OK. 4. The same setting must be applied in each database for each Identikey Server. This setting change is not replicated automatically to other databases. Windows User Name Resolution Identikey Server can use Windows functions to identify User IDs as Windows User accounts. This may be required if Windows is used as the back-end authenticator for Identikey Server. 1. Select a data source from the list. 2. To have the Identikey Server look up a User ID with Windows to find the SAM-Account-Name for the account and Fully Qualified Domain Name, tick the Use Windows User Name Resolution checkbox. 3. Click on OK. 4. The same setting must be applied in each database for each Identikey Server. This setting change is not replicated automatically to other databases. Master Domain The Master Domain is used as a default Domain as well as having special significance for administrative access. For more details, see Master Domain. To modify the domain used as the Master Domain: 1. If the new Master Domain does not already have a Domain record, create the new Domain using the Web Administration Interface. 2. Make sure there is an administrator account in the new Master Domain that has Set Administrative Privileges permission. 3. In the Advanced Settings tab of the Storage section in Identikey Server Configuration, select a data source from the list. 4. Modify the name in the Master Domain field. Identikey Server Administrator Reference 157

158 Identikey Server Configuration Settings Caution Ensure that the name of the Master Domain is set to the correct case, as required by the Case Conversion setting. For example, if the Case Conversion setting is Convert to Lower, the Master Domain name must be all lower case. 5. Click on OK. 6. The same setting must be applied in each database for each Identikey Server. This setting change is not replicated automatically to other databases. 7. Click Apply or OK to make sure all changes are committed. 8. Login to the Web Administration Interface as the administrator account identified in step 2. Give this account any privileges that it requires that are missing. You will need to log off and on again as this account for the new privileges to take effect. 9. Delete the original 'master' domain if no longer required. Note All User accounts must be deleted from a domain before the domain record can be deleted Auditing To view or edit auditing settings, use the Auditing section. For more information about setting up auditing, see 14 Auditing. Enable or Disable an Audit Method Use the checkbox next to the Display Name of the required Audit Method in the list. Add an Audit Method 1. Click on the Add... button. 2. Select a Plug-in type from the drop down list. 3. Click on OK. The Plugin window will be displayed. 4. Enter a name to use for display purposes in the Display Name field. 5. Tick the Reject audit message if this method fails checkbox if you want the Identikey Server to return an error if it fails to record an auditing message. 6. Tick the Record audit message if no other audit method has recorded it checkbox if messages should only be logged by this auditing plug-in if they have not been previously logged by any other plug-in. Identikey Server Administrator Reference 158

159 Identikey Server Configuration Settings 7. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 8. Enter the Text file settings. Enter the address of the log file Check the Always keep file open checkbox if required. Check the Use GMT/UTC checkbox if required. Check the Allow multiple lines in file checkbox if multiple lines of messages are required, instead of one long line of concatenated messages. 9. Click on OK. Edit an Audit Method 1. Select an auditing plug-in from the Methods list. 2. Click on the Edit... button. The Plug-In window will be displayed. 3. Make the required changes. 4. Click on OK. 5. Click on Apply. Delete an Audit Method 1. Select an auditing plug-in from the Methods list. 2. Click on the Delete button. The record will be deleted Replication Section This section contains settings related to the sending of Replication updates to other Identikey Servers. Note For more information about setting up replication on your system, see 17 Replication. Identikey Server Administrator Reference 159

160 Identikey Server Configuration Settings Enable Replication To configure the current Identikey Server to replicate data to other Identikey Servers: 1. Click on Edit Source Server 2. Tick the Enable Replication checkbox. Define a source server to be replicated: 1. Enter the IP address of the source server. 2. Enter the minimum number of seconds the system should wait before trying to reconnect to this server. 3. Enter the maximum number of seconds the system should wait before trying to reconnect to this server Destination Server Queue 1. Click on the Create button under the Destination Servers heading. 2. Enter a display name for the destination Identikey Server. 3. Enter the IP address and port to use in connecting to the Identikey Server. This must normally correspond to the IP Address and Port settings in the SEAL Communicator section of the destination Identikey Server's configuration. However, if Network Address Translation is active between the two Identikey Servers, be careful to select the correct IP address and port that will reach the Identikey Server. 4. Click on OK. The replication queue files hold data that is yet to be replicated on to other Identikey Servers. 1. If you wish to change the location of the replication queue files, modify the File Path field. This directory must already exist. 2. Set a Max File Size (Mb) for each queue file (there is one per Destination Server). If the file reaches this size, replication queue entries will no longer be writeable to the file, and the Identikey Server will cease processing requests that result in a database update. 3. The maximum number of retries specifies how many times the Identikey Server should attempt to resend entries in the replication queue that failed at the destination server. Enter a number in the Max Retries field. 4. The retry interval specifies how long the Identikey Server should wait before attempting to resend entries in the replication queue that failed at the destination server. Enter a number of seconds in the Retry Interval field. Identikey Server Administrator Reference 160

161 Identikey Server Configuration Settings Configuration File Identikey Server Configuration writes to an XML file named identikeyconfig.xml in the install/bin directory for Windows, or the chroot envrionment in Linux. It is possible to edit this file directly instead of using Identikey Server Configuration, but is not recommended. For Windows you will need to restart the Identikey Server Service using the Windows Service Control Manager after editing and saving the file, before the changes will take effect. To enter the chroot environment in Linux enter: vds_chroot <IK installation directory> /bin/bash <IK installation directory> is /opt/vasco/identikey by default. Note The configuration file is UTF-8 encoded do not put any non-utf-8 characters into the file. The XML tag names in the configuration file are case-sensitive Windows - Example Configuration File <?xml version="1.0"?> <VASCO> <Server-Config> <Server-Location type="string" data=" "/> </Server-Config> <Tracing> <Trace-Header type="unsigned" data="15"/> <Trace-Mask type="unsigned" data="0x "/> <Trace-File type="string" data="c:\program Files\VASCO\Identikey 3.1\log\ikeyserver.trace"/> </Tracing> <Encryption> <Storage-Key type="string" data=""/> <Cipher-Name type="string" data="des_ede"/> <Cipher-Module type="string" data=""/> <Enable-Engine type="bool" data="false"/> <Engine-Module type="string" data=""/> <Engine-Parameters/> </Encryption> <Storage> <Storage-Engine type="string" data="odbc"/> <ODBC> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikstorageodbc.dll"/> <Load-Balancing type="bool" data="false"/> Identikey Server Administrator Reference 161

162 Identikey Server Configuration Settings <Connection-Timeout type="unsigned" data="5000"/> <Domain-Cache> <Max-Age type="unsigned" data="900"/> <Max-Size type="unsigned" data="200"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </Domain-Cache> <Data-Sources> <Data-Source00> <Display-Name type="string" data="identikey Server"/> <DSN type="string" data="identikey Server"/> <Username type="string" data="digipass"/> <Password type="string" data="ktzbok2utco4nbhxhvucwdy="/> <Control-Table type="string" data="vdscontrol"/> <Min-Reconnect-Interval type="unsigned" data="0"/> <Max-Reconnect-Interval type="unsigned" data="10"/> </Data-Source00> </Data-Sources> </ODBC> <LDAP> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikstorageldap.dll"/> <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> <Domains> <Default-Domain> <Name type="string" data=""/> <Encrypt-Remote-Connections type="bool" data="false"/> <Preferred-Server type="string" data=""/> <Username type="string" data=""/> <Password type="string" data=""/> <Encrypted-Port type="unsigned" data="636"/> <Unencrypted-Port type="unsigned" data="389"/> <Preferred-Server-Only type="bool" data="false"/> <Max-Bind-LifeTime type="unsigned" data="10"/> <Configuration-Container type="string" data="digipass-configuration"/> </Default-Domain> </Domains> </LDAP> </Storage> <VDPClient> <MDC-IP type="string" data=" "/> <MDC-Port type="unsigned" data="20007"/> <Virtual-DP-Message type="string" data="your One Time Password is [OTP]"/> </VDPClient> <Replication> Identikey Server Administrator Reference 162

163 Identikey Server Configuration Settings <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikreplication.dll"/> <Enabled type="bool" data="false"/> <Repl-Server type="string" data=" "/> <Allow-Loopback type="bool" data="true"/> <Connection-Timeout type="unsigned" data="60"/> <Min-Reconnect-Interval type="unsigned" data="1"/> <Max-Reconnect-Interval type="unsigned" data="60"/> <Dead-Item-Cleanup-Threshold type="unsigned" data="60"/> <Queue> <File-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\repldata\"/> <Max-Retry-Count type="unsigned" data="3"/> <Retry-Interval type="unsigned" data="60"/> <Max-File-Size type="unsigned" data="100"/> </Queue> <Server-List/> </Replication> <Audit> <Libraries> <ODBC type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\dpauditodbc.dll"/> <live type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\dpauditlive.dll"/> </Libraries> <Plugins> <Profile00> <Enabled type="bool" data="true"/> <Type type="string" data="utf8file"/> <Display-Name type="string" data="text File"/> <Fail-On-Error type="bool" data="false"/> <Unhandled-Only type="bool" data="false"/> <Error type="bool" data="true"/> <Warning type="bool" data="true"/> <Info type="bool" data="true"/> <Success type="bool" data="true"/> <Failure type="bool" data="true"/> <Plugincfg> <Log-File type="string" data="c:\program Files\VASCO\Identikey 3.1\log\ikeyserver{year}{month}. audit"/> <Keep-Open type="bool" data="true"/> <Use-GMT type="bool" data="false"/> <Allow-Newlines type="bool" data="false"/> </Plugincfg> </Profile00> <Profile01> <Enabled type="bool" data="true"/> <Type type="string" data="eventlog"/> <Display-Name type="string" data="event Log (errors only)"/> <Fail-On-Error type="bool" data="false"/> <Unhandled-Only type="bool" data="false"/> <Error type="bool" data="true"/> <Warning type="bool" data="false"/> Identikey Server Administrator Reference 163

164 Identikey Server Configuration Settings <Info type="bool" data="false"/> <Success type="bool" data="false"/> <Failure type="bool" data="false"/> <Plugincfg> <Location type="string" data="application"/> </Plugincfg> </Profile01> <Profile02> <Enabled type="bool" data="true"/> <Type type="string" data="eventlog"/> <Display-Name type="string" data="event Log (fall-back)"/> <Fail-On-Error type="bool" data="true"/> <Unhandled-Only type="bool" data="true"/> <Error type="bool" data="true"/> <Warning type="bool" data="true"/> <Info type="bool" data="true"/> <Success type="bool" data="true"/> <Failure type="bool" data="true"/> <Plugincfg> <Location type="string" data="application"/> </Plugincfg> </Profile02> <Profile03> <Enabled type="bool" data="true"/> <Type type="string" data="live"/> <Display-Name type="string" data="live Audit Viewer"/> <Fail-On-Error type="bool" data="false"/> <Unhandled-Only type="bool" data="false"/> <Error type="bool" data="true"/> <Warning type="bool" data="true"/> <Info type="bool" data="true"/> <Success type="bool" data="true"/> <Failure type="bool" data="true"/> <Plugincfg> <IP-Address type="string" data=" "/> <Server-Port type="unsigned" data="20006"/> <Auth-Timeout type="unsigned" data="60"/> <Max-Connections type="unsigned" data="3"/> </Plugincfg> </Profile03> </Plugins> </Audit> <Component-Cache> <Max-Age type="unsigned" data="900"/> <Max-Size type="unsigned" data="1000"/> <Clean-Threshold type="unsigned" data="800"/> <Min-Clean-Interval type="unsigned" data="60"/> </Component-Cache> <Configuration-Cache> Identikey Server Administrator Reference 164

165 Identikey Server Configuration Settings <Max-Age type="unsigned" data="900"/> <Max-Size type="unsigned" data="200"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </Configuration-Cache> <Policy-Cache> <Max-Age type="unsigned" data="900"/> <Max-Size type="unsigned" data="200"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </Policy-Cache> <Challenge-Cache> <Max-Age type="unsigned" data="60"/> <Max-Size type="unsigned" data="1200"/> <Clean-Threshold type="unsigned" data="1000"/> <Min-Clean-Interval type="unsigned" data="5"/> </Challenge-Cache> <BackEnd-Cache> <Max-Age type="unsigned" data="900"/> <Max-Size type="unsigned" data="200"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </BackEnd-Cache> <DPX-Cache> <Max-Age type="unsigned" data="86400"/> <Max-Size type="unsigned" data="200"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </DPX-Cache> <Admin-Session-Cache> <Max-Concurrent-Sessions type="unsigned" data="20"/> <Max-Session-Time type="unsigned" data="86400"/> <Session-Timeout type="unsigned" data="900"/> </Admin-Session-Cache> <Report-Cache> <Max-Age type="unsigned" data="86400"/> <Max-Size type="unsigned" data="400"/> <Clean-Threshold type="unsigned" data="100"/> <Min-Clean-Interval type="unsigned" data="60"/> </Report-Cache> <Task-Manager> <Max-Workers type="unsigned" data="30"/> </Task-Manager> <BackEndAuthenticators> <Windows> <Enabled type="bool" data="true"/> </Windows> <RADIUS> <Enabled type="bool" data="true"/> Identikey Server Administrator Reference 165

166 Identikey Server Configuration Settings <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikcommradius.dll"/> </RADIUS> <Novell-e-Directory> <Enabled type="bool" data="true"/> <Plugin-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\"/> <BackEnd-Server-Status> <Min-Retry-Interval type="unsigned" data="60"/> <Max-Retry-Interval type="unsigned" data="900"/> </BackEnd-Server-Status> </Novell-e-Directory> <Microsoft-AD> <Enabled type="bool" data="true"/> <Plugin-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\"/> <BackEnd-Server-Status> <Min-Retry-Interval type="unsigned" data="60"/> <Max-Retry-Interval type="unsigned" data="900"/> </BackEnd-Server-Status> </Microsoft-AD> <Microsoft-ADAM> <Enabled type="bool" data="true"/> <BackEnd-Server-Status> <Min-Retry-Interval type="unsigned" data="60"/> <Max-Retry-Interval type="unsigned" data="900"/> </BackEnd-Server-Status> </Microsoft-ADAM> </BackEndAuthenticators> <Communicators> <SealCommunicator> <Enabled type="bool" data="true"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikcommseal.dll"/> <DPX-Upload-Location type="string" data="c:\program Files\VASCO\Identikey 3.1\dpx\"/> <IP-Address type="string" data=" "/> <IP-Port type="unsigned" data="20003"/> <Require-Client-Component type="bool" data="false"/> </SealCommunicator> <SoapCommunicator> <Enabled type="bool" data="true"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikcommsoap.dll"/> <DPX-Upload-Location type="string" data="c:\program Files\VASCO\Identikey 3.1\dpx\"/> <IP-Port type="unsigned" data="8888"/> <SSL> <Enabled type="bool" data="true"/> <Server-Certificate type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikeypvk.pem"/> <Private-Key-Password type="string" data="lnzvb2cyvfwb"/> <CA-Certificate-Store type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikeycerts.pem"/> <Client-Authentication-Method type="string" data="none"/> <Reverify-Client-On-Reconnect type="bool" data="false"/> </SSL> Identikey Server Administrator Reference 166

167 Identikey Server Configuration Settings </SoapCommunicator> <RadiusCommunicator> <Enabled type="bool" data="true"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikcommradius.dll"/> <Authentication-Port type="string" data="1812"/> <Accounting-Port type="string" data="1813"/> <Request-Cache> <Max-Age type="unsigned" data="5"/> <Max-Size type="unsigned" data="0"/> <Clean-Threshold type="unsigned" data="200"/> <Min-Clean-Interval type="unsigned" data="30"/> </Request-Cache> <Proxy-Cache> <Max-Age type="unsigned" data="600"/> <Max-Size type="unsigned" data="0"/> <Clean-Threshold type="unsigned" data="200"/> <Min-Clean-Interval type="unsigned" data="30"/> </Proxy-Cache> <BackEnd-Server-Status> <Min-Retry-Interval type="unsigned" data="60"/> <Max-Retry-Interval type="unsigned" data="900"/> <Unavailability-Threshold type="unsigned" data="2"/> </BackEnd-Server-Status> </RadiusCommunicator> </Communicators> <Scenarios> <ScenarioModule00> <Enabled type="bool" data="true"/> <Display-Name type="string" data="authentication Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenauth.dll"/> </ScenarioModule00> <ScenarioModule01> <Enabled type="bool" data="true"/> <Display-Name type="string" data="signature Validation Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscensign.dll"/> </ScenarioModule01> <ScenarioModule02> <Enabled type="bool" data="true"/> <Display-Name type="string" data="provisioning Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenprovision.dll"/> <Reactivation> <Min-Time-Before-Reactivation type="unsigned" data="1440"/> <Max-Nbr-Attempts type="unsigned" data="3"/> <Max-Nbr-Locations type="unsigned" data="5"/> </Reactivation> </ScenarioModule02> <ScenarioModule03> <Enabled type="bool" data="true"/> <Display-Name type="string" data="administration Scenario"/> Identikey Server Administrator Reference 167

168 Identikey Server Configuration Settings <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenadmin.dll"/> </ScenarioModule03> <ScenarioModule04> <Enabled type="bool" data="true"/> <Display-Name type="string" data="reporting Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenreport.dll"/> <Report-Location type="string" data="c:\program Files\VASCO\Identikey 3.1\reports\"/> <Audit> <Plug-ins> <Plugin01 type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\dpauditodbc.dll"/> </Plug-ins> <Source type="string" data="utf8file"/> <ODBC> <DSN type="string" data="identikey Server"/> <Username type="string" data="digipass"/> <Password type="string" data="p42kafzf5xlp_noo7hzj9co="/> </ODBC> <UTF8> <Path type="string" data="c:\program Files\VASCO\Identikey 3.1\log\"/> <Extension type="string" data=".audit"/> </UTF8> </Audit> </ScenarioModule04> <ScenarioModule05> <Enabled type="bool" data="true"/> <Display-Name type="string" data="audit Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenaudit.dll"/> </ScenarioModule05> <ScenarioModule06> <Enabled type="bool" data="true"/> <Display-Name type="string" data="replication Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenrepl.dll"/> </ScenarioModule06> <ScenarioModule07> <Enabled type="bool" data="true"/> <Display-Name type="string" data="configuration Scenario"/> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\ikscenconfig.dll"/> <Config-File type="string" data="c:\program Files\VASCO\Identikey 3.1\bin\identikeyconfig.xml"/> <Audit-Path type="string" data="c:\program Files\VASCO\Identikey 3.1\log\"/> </ScenarioModule07> </Scenarios> </VASCO> Linux Example Configuration File <?xml version="1.0"?> - <VASCO> - <Server-Config> Identikey Server Administrator Reference 168

169 Identikey Server Configuration Settings <Server-Location type="string" data=" " /> </Server-Config> <ProductInfo /> - <Tracing> <Trace-Header type="unsigned" data="47" /> <Trace-Mask type="unsigned" data="0x3fffffff" /> <Trace-File type="string" data="/var/vasco/identikey/ikeyserver.trace" /> </Tracing> - <Encryption> <Storage-Key type="string" data="" /> <Cipher-Name type="string" data="des_ede" /> <Cipher-Module type="string" data="" /> <Enable-Engine type="bool" data="false" /> <Engine-Module type="string" data="" /> <Engine-Parameters /> </Encryption> <Storage> <Storage-Engine type="string" data="odbc" /> <ODBC> <Library-Path type="string" data="/usr/lib/libikstorageodbc.so" /> <Load-Balancing type="bool" data="false" /> <Connection-Timeout type="unsigned" data="5000" /> - <Domain-Cache> <Max-Age type="unsigned" data="900" /> <Max-Size type="unsigned" data="200" /> <Clean-Threshold type="unsigned" data="100" /> <Min-Clean-Interval type="unsigned" data="60" /> </Domain-Cache> - <Data-Sources> - <Data-Source00> <Display-Name type="string" data="identikey Server" /> <DSN type="string" data="identikey server" /> <Username type="string" data="digipass" /> <Password type="string" data="hxrzkau8hisqpkpelzwat4k=" /> <Control-Table type="string" data="vdscontrol" /> <Min-Reconnect-Interval type="unsigned" data="0" /> <Max-Reconnect-Interval type="unsigned" data="10" /> </Data-Source00> </Data-Sources> </ODBC> </Storage> - <VDPClient> <MDC-IP type="string" data=" " /> <MDC-Port type="unsigned" data="20007" /> </VDPClient> - <Replication> <Library-Path type="string" data="/usr/lib/libikreplication.so" /> <Enabled type="bool" data="false" /> <Repl-Server type="string" data=" " /> Identikey Server Administrator Reference 169

170 Identikey Server Configuration Settings <Allow-Loopback type="bool" data="true" /> <Connection-Timeout type="unsigned" data="60" /> <Min-Reconnect-Interval type="unsigned" data="1" /> <Max-Reconnect-Interval type="unsigned" data="60" /> <Dead-Item-Cleanup-Threshold type="unsigned" data="60" /> - <Queue> <File-Path type="string" data="/var/vasco/repldata/" /> <Max-Retry-Count type="unsigned" data="3" /> <Retry-Interval type="unsigned" data="60" /> <Max-File-Size type="unsigned" data="100" /> </Queue> <Server-List /> </Replication> - <Audit> - <Libraries> <ODBC type="string" data="/usr/lib/libdpauditodbc.so" /> <live type="string" data="/usr/lib/libdpauditlive.so" /> </Libraries> - <Plugins> - <Profile00> <Enabled type="bool" data="true" /> <Type type="string" data="utf8file" /> <Display-Name type="string" data="text File" /> <Fail-On-Error type="bool" data="false" /> <Unhandled-Only type="bool" data="false" /> <Error type="bool" data="true" /> <Warning type="bool" data="true" /> <Info type="bool" data="true" /> <Success type="bool" data="true" /> <Failure type="bool" data="true" /> - <Plugincfg> <Log-File type="string" data="/var/vasco/identikey/ikeyserver{year}{month}.audit" /> <Keep-Open type="bool" data="true" /> <Use-GMT type="bool" data="false" /> <Allow-Newlines type="bool" data="false" /> </Plugincfg> </Profile00> - <Profile01> <Enabled type="bool" data="true" /> <Type type="string" data="syslog" /> <Display-Name type="string" data="linux Syslog (errors only)" /> <Fail-On-Error type="bool" data="false" /> <Unhandled-Only type="bool" data="false" /> <Error type="bool" data="true" /> <Warning type="bool" data="false" /> <Info type="bool" data="false" /> <Success type="bool" data="false" /> <Failure type="bool" data="false" /> - <Plugincfg> Identikey Server Administrator Reference 170

171 Identikey Server Configuration Settings <Syslog-Facility type="string" data="local0" /> </Plugincfg> </Profile01> - <Profile02> <Enabled type="bool" data="true" /> <Type type="string" data="syslog" /> <Display-Name type="string" data="linux Syslog (fall-back)" /> <Fail-On-Error type="bool" data="true" /> <Unhandled-Only type="bool" data="true" /> <Error type="bool" data="true" /> <Warning type="bool" data="true" /> <Info type="bool" data="true" /> <Success type="bool" data="true" /> <Failure type="bool" data="true" /> - <Plugincfg> <Syslog-Facility type="string" data="local0" /> </Plugincfg> </Profile02> - <Profile03> <Enabled type="bool" data="true" /> <Type type="string" data="live" /> <Display-Name type="string" data="live Audit Viewer" /> <Fail-On-Error type="bool" data="false" /> <Unhandled-Only type="bool" data="false" /> <Error type="bool" data="true" /> <Warning type="bool" data="true" /> <Info type="bool" data="true" /> <Success type="bool" data="true" /> <Failure type="bool" data="true" /> - <Plugincfg> <IP-Address type="string" data=" " /> <Server-Port type="unsigned" data="20006" /> <Auth-Timeout type="unsigned" data="60" /> <Max-Connections type="unsigned" data="3" /> </Plugincfg> </Profile03> <Profile04> <Display-Name type="string" data="odbc" /> <Type type="string" data="odbc" /> <Fail-On-Error type="bool" data="false" /> <Unhandled-Only type="bool" data="false" /> <Error type="bool" data="true" /> <Warning type="bool" data="true" /> <Info type="bool" data="true" /> <Success type="bool" data="true" /> <Failure type="bool" data="true" /> <Plugincfg> <DSN type="string" data="identikey server" /> <Username type="string" data="digipass" /> Identikey Server Administrator Reference 171

172 Identikey Server Configuration Settings <Password type="string" data="vsmkx1jrs9xhufpvdctsd_y=" /> </Plugincfg> <Enabled type="bool" data="true" /> </Profile04> </Plugins> </Audit> <Component-Cache> <Max-Age type="unsigned" data="900" /> <Max-Size type="unsigned" data="1000" /> <Clean-Threshold type="unsigned" data="800" /> <Min-Clean-Interval type="unsigned" data="60" /> </Component-Cache> -<Policy-Cache> <Max-Age type="unsigned" data="900" /> <Max-Size type="unsigned" data="200" /> <Clean-Threshold type="unsigned" data="100" /> <Min-Clean-Interval type="unsigned" data="60" /> </Policy-Cache> <Challenge-Cache> <Max-Age type="unsigned" data="60" /> <Max-Size type="unsigned" data="1200" /> <Clean-Threshold type="unsigned" data="1000" /> <Min-Clean-Interval type="unsigned" data="5" /> </Challenge-Cache> <BackEnd-Cache> <Max-Age type="unsigned" data="900" /> <Max-Size type="unsigned" data="200" /> <Clean-Threshold type="unsigned" data="100" /> <Min-Clean-Interval type="unsigned" data="60" /> </BackEnd-Cache> <DPX-Cache> <Max-Age type="unsigned" data="86400" /> <Max-Size type="unsigned" data="200" /> <Clean-Threshold type="unsigned" data="100" /> <Min-Clean-Interval type="unsigned" data="60" /> </DPX-Cache> <Admin-Session-Cache> <Max-Concurrent-Sessions type="unsigned" data="10" /> <Max-Session-Time type="unsigned" data="86400" /> <Session-Timeout type="unsigned" data="3600" /> </Admin-Session-Cache> <Report-Cache> <Max-Age type="unsigned" data="86400" /> <Max-Size type="unsigned" data="400" /> <Clean-Threshold type="unsigned" data="100" /> <Min-Clean-Interval type="unsigned" data="60" /> </Report-Cache> <Task-Manager> <Max-Workers type="unsigned" data="30" /> Identikey Server Administrator Reference 172

173 Identikey Server Configuration Settings </Task-Manager> <BackEndAuthenticators> <RADIUS> <Enabled type="bool" data="true" /> <Library-Path type="string" data="/usr/lib/libikcommradius.so" /> </RADIUS> <Engines /> </BackEndAuthenticators> - <Communicators> - <SealCommunicator> <Enabled type="bool" data="false" /> <Library-Path type="string" data="/usr/lib/libikcommseal.so" /> <IP-Address type="string" data=" " /> <IP-Port type="unsigned" data="20003" /> <Require-Client-Component type="bool" data="false" /> </SealCommunicator> - <SoapCommunicator> <Enabled type="bool" data="true" /> <Library-Path type="string" data="/usr/lib/libikcommsoap.so" /> <DPX-Upload-Location type="string" data="/usr/share/vasco/identikey/dpx/" /> <IP-Port type="unsigned" data="8888" /> <SSL> <Enabled type="bool" data="false" /> <Server-Certificate type="string" data="/etc/vasco/ikeypvk.pem" /> <Private-Key-Password type="string" data="loeh9$q5yoa0" /> <CA-Certificate-Store type="string" data="/etc/vasco/ikeycerts.pem" /> <Client-Authentication-Method type="string" data="none" /> <Reverify-Client-On-Reconnect type="bool" data="false" /> </SSL> </SoapCommunicator> <RadiusCommunicator> <Enabled type="bool" data="true" /> <Library-Path type="string" data="/usr/lib/libikcommradius.so" /> <Authentication-Port type="string" data="1812" /> <Accounting-Port type="string" data="1813" /> <Request-Cache> <Max-Age type="unsigned" data="5" /> <Max-Size type="unsigned" data="0" /> <Clean-Threshold type="unsigned" data="200" /> <Min-Clean-Interval type="unsigned" data="30" /> </Request-Cache> <Proxy-Cache> <Max-Age type="unsigned" data=" " /> <Max-Size type="unsigned" data="0" /> <Clean-Threshold type="unsigned" data="200" /> <Min-Clean-Interval type="unsigned" data="30" /> </Proxy-Cache> </RadiusCommunicator> </Communicators> Identikey Server Administrator Reference 173

174 Identikey Server Configuration Settings <Scenarios> <ScenarioModule00> <Enabled type="bool" data="true" /> <Display-Name type="string" data="authentication Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenauth.so" /> </ScenarioModule00> <ScenarioModule01> <Enabled type="bool" data="true" /> <Display-Name type="string" data="signature Validation Scenario" /> <Library-Path type="string" data="/usr/lib/libikscensign.so" /> </ScenarioModule01> <ScenarioModule02> <Enabled type="bool" data="true" /> <Display-Name type="string" data="provisioning Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenprovision.so" /> - <Reactivation> <Min-Time-Before-Reactivation type="unsigned" data="1440" /> <Max-Nbr-Attempts type="unsigned" data="3" /> <Max-Nbr-Locations type="unsigned" data="5" /> </Reactivation> </ScenarioModule02> <ScenarioModule03> <Enabled type="bool" data="true" /> <Display-Name type="string" data="administration Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenadmin.so" /> </ScenarioModule03> <ScenarioModule04> <Enabled type="bool" data="true" /> <Display-Name type="string" data="reporting Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenreport.so" /> <Report-Location type="string" data="/usr/share/vasco/identikey/reports/" /> <Audit> <Plug-ins> <Plugin01 type="string" data="/usr/lib/libdpauditodbc.so" /> </Plug-ins> <Source type="string" data="utf8file" /> <ODBC> <Username type="string" data="test" /> <Password type="string" data="o9jfpkmqsce8tkqkdq1h8zs=" /> <DSN type="string" data="postgres" /> </ODBC> <UTF8> <Path type="string" data="/var/vasco/identikey/" /> <Extension type="string" data=".audit" /> </UTF8> </Audit> </ScenarioModule04> <ScenarioModule05> <Enabled type="bool" data="true" /> Identikey Server Administrator Reference 174

175 Identikey Server Configuration Settings <Display-Name type="string" data="audit Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenaudit.so" /> </ScenarioModule05> <ScenarioModule06> <Enabled type="bool" data="true" /> <Display-Name type="string" data="replication Scenario" /> <Library-Path type="string" data="/usr/lib/libikscenrepl.so" /> </ScenarioModule06> </Scenarios> </VASCO> Identikey Server Administrator Reference 175

176 Identikey Server Configuration Settings 11.4 Command Line Options The Identikey Server is started via a single executable file named ikeyserver.exe (Windows) or ikeyserver (Linux). This command is rarely executed by the Administrator as it is automatically executed when the server on which Identikey Server has been installed is started up. The Identikey Server is started via an operating system specific framework used to start and stop services (Windows) or daemons (Linux). Command line options can be used to override the Identikey Server configuration file and run Identikey Server with a custom configuration file Windows Service Control Manager Under Windows the Identikey Server is started using the Windows Service Control Manager (SCM). The SCM allows services to be started, stopped, and paused. The SCM also allows the passing of command line parameters. The SCM is accessed via the Services icon on the control panel. Command line parameters may be passed to the Identikey Server service by double-clicking on the Identikey Server service in the services window and then entering the parameters in the Start Parameters field under the General tab Linux Runtime Configuration Under Linux the Identikey Server is started as a Daemon by the invocation of a Linux shell script that is run automatically as part of the Linux runtime configuration framework. All runtime configuration scripts allow daemons to be started, stopped and paused. Command line parameters may be specified by modifying the runtime confugration script for the intended daemon Running Identikey Server with Command Line Options Command Line Option flags Issuing the command 'ikeyserver help' either in a Windows command line instance or under a Linux shell prompt will display the following: Flags: -d, --debug Run Identikey Server in debug mode -h, --help Display this help message -c, --config=config_filename Optional argument used to override the configuration file which is used by the Identikey Server. Identikey Server Administrator Reference 176

177 Identikey Server Configuration Settings Note The Configuration GUI will only modify the default configuration file. If the Identikey Server has been started using an alternate configuration file, its configuration settings can only be altered by editing the file in a text editor Windows To run Identikey Server with command line options Identikey Server will have to be run in debug mode. This allows the Identikey Server executable to be run from the Windows command line. To run Identikey Server in debug mode, follow the instructions above in Windows Service Control Manager pass the command line parameter -d to the Windows service Linux Under Linux it is not mandatory that the Identikey Server is run under the debug mode when it is invoked from the command line Identikey Server Web Administration Configuration Configuration may be performed via the Identikey Server Web Administration. Click on the System tab for a drop down menu. Use the Web Administration Online Help for detailed on each page List Select the List menu item to display a list of Identikey Servers Location The Location setting contains the licensed IP address for the Identikey Server. The Identikey Server uses this IP address to listen for SOAP and RADIUS requests. There must be an Identikey Server component record with this Location, containing a valid License Key. The component location is carried forward to the Communication Protocols pages. Click the Location to change the IP address for the Identikey Server and the base policy. Click Edit on the Summary tab to change the policy ID. Click the License tab to change the license details. Identikey Server Administrator Reference 177

178 Identikey Server Configuration Settings Identikey Server Name Clicking on the Identikey Server Name will allow changes to the following settings: Policy User Digipass Challenge Virtual Digipass Digipass Control Parameters Add Identikey Server Use this tab to add another Identikey Server Server Status Replication Use this tab to get the Replication Status of nominated Identikey Servers Admin Session Use this tab to manage Administration sessions Server Configuration The tabs shown when you click on Server Configuration correspond to the headings in General Section The tabs comprise: General Audit Amend the Audit Settings. Storage Communicators Replication Identikey Server Administrator Reference 178

179 Identikey Server Configuration Settings Scenarios Identikey Server Administrator Reference 179

180 Identikey Server Configuration Settings 11.6 Web Administration Setup Tool Overview The Web Administration Setup Tool is a Java application that allows the management of Identikey Server connections and SSL certificate usage in the Administration Web Interface. Java Runtime Environment is required in order to run this tool. The Web Administration Setup Tool stores its information using the Java preferences API. On Windows, it uses the Windows registry. On Linux, it uses the running user's file system, and is stored in the java/.userprefs directory. User Account The user that runs the web server application should be the same user running the Web Administration Setup Tool under Linux, otherwise changes will not be reconciled in the Administration Web Interface. Note Any changes made with the Web Administration Setup Tool will not take effect until the Administration Web Interface and the web server application have been restarted Running the Application Windows 1. Open a command prompt. 2. Navigate to the directory in which the Java executable is located. 3. Enter the following command: java -jar admintool.jar Linux 1. Open a command prompt. 2. Enter the following commands: vds_chroot <install dir> /bin/bash java -jar admintool.jar Identikey Server Administrator Reference 180

181 Identikey Server Configuration Settings Note The vds_chroot command will enter you into the chroot environment. This is necessary for all Setup Tool commands. To exit the chroot environment, enter: exit Available Commands The commands should be in the following format: java -jar admintool.jar <command> [options] The following commands are available: Setup Tool Command autoadd <name> <url> <certificate archive> <password> <connection limit> <connection timeout> server list server add <name> <url> <connection_timeout> <connection limit> server delete <name> server default <name> server localaddress <name> <local address> certificate list certificate list <certificate archive> <passphrase> certificate add <certificate archive> <passphrase> <certificate file> <name> certificate delete <certificate archive> <passphrase> <name> certificate delete <certificate archive> <passphrase> Explanation Creates a new Identikey Server connection for the Administration Web Interface. If a certificate archive and password is specified, the Identikey Server's SSL certificate will be added to it. If no certificate archive is specified, it will be added to the existing keystore. A connection limit (number of concurrent connections to allow) and connection timeout may also be specified. List the available Identikey SOAP servers Add a new Identikey Server connection. A connection limit (number of concurrent connections to allow) and connection timeout may also be specified. Remove an existing Identikey Server Set the specified Identikey SOAP server as the default Specify a local IP address to specify when connecting to the provided server name. Displays the list of certificate alias which are in the used certificate archive Displays the list of certificate alias which are in the specifiedcertificate archive (opened using the specified passphrase) Installs the certificate into an existing or new certificate archive using the provided passphrase and alias the certificate using the provided name. Removes the certificate with the specified alias from the provided Removes the certificate with the default alias "IdentikeyServer" certificate archive using the provided password. Identikey Server Administrator Reference 181

182 Identikey Server Configuration Settings Setup Tool Command autoadd <name> <url> <certificate archive> <passphrase> Explanation Combines the functionality of the server add and certificate add commands and automates the retrieval of the certificate from the Identikey Server Command Usage Examples Adding an Identikey Server and SSL Certificate The following command will add an Identikey Server and add the Identikey Server's certificate to the keystore: java -jar admintool.jar autoadd <name> <url> <keystore location> <keystore password> where <name> is the display name of the Identikey Server, <url> is the address and port number of the Identikey Server, <keystore location> is the location and file name of the keystore and <keystore password> is the password on the keystore. Example java -jar admintool.jar autoadd IKServer1 etc/vasco/keystore.jks password1 will create a new Identikey Server record which will be displayed in the Web Administration application using the name IKServer1 and will connect to the Identikey SOAP communicator using http using SSL - at address and port It will add the Identikey Server's SSL certificate to the keystore specified. NOTE Protocol strings must be provided (http or https for SSL connections). Server creation can be verified by running the following command: java -jar admintool.jar server list which will display the current list of servers. NOTE The server name and url must both be unique. Attempting to add another server with a different name and the same url will fail. Adding a server with the same name and different url will overwrite the existing entry for the Identikey Server of that name. Identikey Server Administrator Reference 182

183 Identikey Server Configuration Settings Adding an Identikey Server The following command will add an Identikey Server only, without adding a certificate to the keystore: java -jar admintool.jar server add <name> <url> where <name> is the display name of the Identikey Server and <url> is the address and port number of the Identikey Server. Example java -jar admintool.jar server add IKServer1 will create a new Identikey Server record which will be displayed in the Web Administration application using the name IKServer1 and will connect to the Identikey SOAP communicator using http at address and port Adding an SSL Certificate To connect to an Identikey Server which is using an SSL connection, the server's certificate must be added to the Web Administration application's certificate archive. If this is not done while adding an Identikey Server using the autoadd command, it can be done by executing the The certificate used by the Identikey Server is usually created with the filename ikeycerts.pem and located in : Windows - <install dir>\vasco\identikey Server\bin Linux - <install dir>/etc/vasco To add this certificate to the Web Administration application's certificate archive, run the following command: java -jar admintool.jar certificate add <archive location> <password> <certificate location> where <archive location> is the file path and name of the certificate archive, <password> is the certificate archive password and <certificate location> is the file path and name of the SSL certificate to add to the certificate archive. Example or java -jar admintool.jar certificate add /etc/vasco/keystore.jks password1 /etc/vasco/ikeycerts.pem java -jar admintool.jar certificate add <install dir>\vasco\identikey Server\bin\keystore.jks password1 <install dir>\vasco\identikey Server\bin\ikeycerts.pem will add the ikeycerts.pem certificate to the specified certificate archive keystore.jks, using the certificate archive password password1. Identikey Server Administrator Reference 183

184 Identikey Server Configuration Settings NOTE Ensure that the connection url to the server is updated - https should be used rather than http. Identikey Server Administrator Reference 184

185 Identikey Server Configuration Settings 11.7 Message Delivery Component Configuration Required Information To configure gateway settings you will need: Gateway details: OR Protocol to use in connecting to the gateway. An address string and port to use in connecting to the gateway. The path and filename of a certificate file, if required. The required Query String. The Query Method (GET or POST) required by the gateway. A customized configuration file ordered from your VASCO supplier. This will need to be imported using the Configuration GUI. Username and password for the gateway account MDC Configuration GUI A Graphical User Interface (GUI) is available for use in configuring the MDC in Windows installations. To open the MDC Configuration GUI, click on the Start Button and select Programs -> VASCO -> Identikey Server -> Virtual Digipass MDC Configuration. Note The MDC must be restarted after any change is made in the Configuration GUI or configuration file. If using the MDC on a Linux system, the configuration file can be found in etc/vasco/mdcconfig.xml Modify Gateway Account Login Details The MDC needs a Username and password for the gateway in order to send text messages through it. Modify the Username if needed and change the Password and Confirm Password fields if required. The Password and Confirm Password fields must contain identical data. Identikey Server Administrator Reference 185

186 Identikey Server Configuration Settings Configure Internet Connection Details Enable or disable the use of an HTTP Proxy and enter details if required. 1. Enable or disable the use of the HTTP Proxy by ticking or clearing the Use HTTP Proxy checkbox. 2. If required, enter an IP address, port and timeout for the HTTP Proxy. 3. Enter a maximum number of internet connections to allow in the Max. Connections field Configure Tracing The MDC makes use of a trace file to record information about events that occur on the system, for use in troubleshooting. This could include generic information, changing conditions, or problems and errors that have been encountered. The level of tracing that the MDC employs depends on its configuration settings. Caution Enabling Full Tracing should only be done for troubleshooting purposes. There are no limits set on the size of the tracing file, so if the option is left on too long on a high-load system the file may dramatically slow down or crash Windows, due to excessive I/O or filling up the hard drive. This is not highly likely for MDC, but should be considered. Because there are no size limitations set on the trace file, it is not recommended that you have tracing permanently enabled. If your system is set up with Basic Tracing always enabled, ensure that the file size does not cause problems by deleting or archiving it whenever it gets too large. Basic tracing includes: Critical error/warning messages [CRITC] Major error/warning messages [MAJOR] Minor error/warning messages [MINOR] Configuration messages [CONFG] Full tracing includes: Critical error/warning messages [CRITC] Major error/warning messages [MAJOR] Minor error/warning messages [MINOR] Configuration messages [CONFG] Informational messages [INFOR] Data tracing messages [DATA] Identikey Server Administrator Reference 186

187 Identikey Server Configuration Settings Debugging messages (useful for support purposes) [DEBUG] Security messages, messages that may contain security sensitive data [SECUR] Turn Tracing On or Off 1. Select a Tracing option. 2. If you have selected Basic Tracing or Full Tracing, enter a path and filename for the tracing file into the File Name field. The file path entered must be the full absolute path. Note If the File Name field is left blank or the file path does not exist, the MDC will not output tracing. If the file does exist, tracing will be appended to the file. If it does not exist, it will be created Import HTTP Gateway settings Import a customized configuration file ordered from your VASCO supplier, containing the configuration details for your gateway needed by the MDC. 1. Click on the Gateway Settings tab. 2. Enter a name for the gateway. 3. Click on Import Settings. 4. Select a file from the Browse window. 5. Click on OK. The import progress will be displayed. 6. Click on OK Edit Advanced Settings 1. Click on the Gateway Settings tab. 2. Ensure that the Edit Advanced Settings checkbox is ticked. 3. Select a protocol to use in connecting to the gateway from the Protocol drop down list (typically HTTP). 4. Enter an address string to use in connecting to the gateway in the Address field. 5. Enter a port in the Port field (typically 80 for HTTP connections). 6. Enter the path and filename of a certificate file if required. 7. Modify the Query String field if required. Identikey Server Administrator Reference 187

188 Identikey Server Configuration Settings Example Query String: username=[acc_user]&password=[acc_pwd]&device=[otp_dest]&network=tgsm&message=[otp_msg] 8. Select a Query Method according to what the gateway requires (typically POST) Export HTTP Gateway settings Once you have entered the necessary gateway configuration information into the Configuration GUI, you may wish to export the settings into a file for backup purposes or to transfer to another server. 1. Click on the Gateway Settings tab. 2. Ensure that the Edit Advanced Settings checkbox is ticked. 3. Click on Export Settings. 4. Select a directory from the Browse window. 5. Enter a filename. 6. Click on OK. The export progress will be displayed Gateway Result Pages A result page is returned by the gateway service when a text message is submitted by the GET or POST methods. This page would normally be a HTML formatted page containing specific error codes and/or additional messages for success/failure. Three types of result messages are generally categorized as: Information Success of message delivery (the message has been accepted by the server) Warning The submission/delivery failed, but it is most likely a specific error only affecting this User. The User s login will fail on the first step. Possible causes are: Error Phone number invalid Temporary gateway failure Error(s) occurred while attempting delivery. This means that the delivery failed for a particular User, but the error might be affecting all Users. In this case, the User s login will fail immediately. Possible such errors are: Account data incorrect (Account User or password wrong) Identikey Server Administrator Reference 188

189 Identikey Server Configuration Settings Account credit expired (for a pre-paid gateway account) Communication error with gateway (network error) Other permanent gateway errors Audit Console Logging A gateway result page can be recognized by key words and phrases, and an alternate message created for logging to the audit console whenever the result is received. Variables can be extracted from the result page and used in the log message to provide extra information. Result Page Rules The result page rule patterns use the following syntax: <FixedText1> [Var-Name1] <FixedText2> [] <FixedText3> [Var-Name2] Where the template is constructed in the following way: <FixedTextx>: a character string which must be matched in the page returned by the gateway. Note that multiple <FixedTextx> can appear in a single template, but they must not be overlapping. Matching is casesensitive. []: Omits a variable part of the result page between two <FixedText> segments, when matching a template. This can be useful to ignore arbitrary data or time/date data in the returned web page. [Var-Namex]: Describes a segment of the result page between two <FixedText> segments or at the end of the result page, which will be written to a variable. Usually this will be data that can provide more detailed information why a particular message submission has failed. The variable name inside the [] brackets can then be used as part of the audit message template to create a meaningful message. Example If the server returns the following result page <b>submission successful at 10:00, 11/11/02, status: 00 - message delivery in progress.</b> for successful transmission, or <b> Submission unsuccessful at 10:05, 11/11/02, status: 47 number too short </b> for an unsuccessful submission, then the following result page rules can be configured: Message Rule Name: Message Rule Pattern: Variables retrieved: Message Rule Name: Message Rule Pattern: Variables retrieved: Message Rule Name: Message Rule Pattern: Success successful at [DateTime], status: [Status] [Message]</b> DateTimeStatusMessage Warning unsuccessful at [DateTime], status: 47 [Message]</b> DateTimeMessage Error unsuccessful at [DateTime], status: [status] [Message]</b> Identikey Server Administrator Reference 189

190 Identikey Server Configuration Settings Variables retrieved: DateTimeStatusMessage No Match Available If no Rule matches a Result page returned, an error will be logged to the Audit Console, reporting that the result page returned from the gateway could not be matched. Ordering Rules The order of the result page template in the configuration data can be used to match more specific messages first and finally catch any other message, which the gateway might send. Audit message template Once a result page template a matched, a corresponding audit message is constructed with the variables retrieved from the result page rule. The message template will use the following syntax: <FixedText1> [VAR-Name1] <FixedText3> [Var-Name2] <FixedTextx>: a character string which will appear literally in the constructed audit message. [Var-Namex]: Variable which is derived from the matched variables from the corresponding result page template. The following variables are predefined and can be used in the audit message template: Table 60: MDC Audit Message Variables [otp_dest] [otp_msg] [acc_user] [acc_pwd] [Username] Examples of variable use: The destination address (a mobile phone number) the OTP was sent to. The message that was submitted. This variable will also contain the OTP, so should not be used for the construction of audit messages. Account name for the gateway.not recommended for use in audit messages. Account password for the gateway.not recommended for use in audit messages. the User ID of the User requesting the OTP Insufficient credit on account [acc_user] when sending to [username] Message not sent to User "[Username]"/[otp_dest]. Gateway reported: [message] Modify a Gateway Result Message Rule Ensure that the Edit Advanced Settings checkbox on the Gateway Settings tab is ticked. 1. Click on the Gateway Results tab. 2. Select a Rule to modify. 3. Click on Edit. 4. Make any required changes. 5. Click on OK. Identikey Server Administrator Reference 190

191 Identikey Server Configuration Settings Add a Gateway Result Message Rule 1. Click on the Gateway Results tab. 2. Click on Add. 3. Enter a descriptive name for the Rule in the Description field. 4. Enter the full text or a partial match of the text displayed by the gateway in the Matching Pattern field. 5. Select an Audit Message Level for the Rule. Each level of message will be displayed with a different color background in the Audit Console. Info normal Warning yellow Error red 6. Enter the message text you wish the User to see into the Message Text field. 7. Click on OK. Identikey Server Administrator Reference 191

192 Identikey Server Configuration Settings MDC Configuration File The MDC Configuration GUI writes to an.xml file named MDCConfig.xml in the install\bin (Windows) or etc/vasco (Linux) directory. It is possible to edit this file directly instead of using the MDC Configuration GUI. Example Configuration File <?xml version="1.0"?> <VASCO> <Tracing> <Trace-Header type="unsigned" data="31"/> <Trace-Mask type="unsigned" data="0x "/> <Trace-File type="string" data="c:\program Files\VASCO\Identikey 3.0\Log\mdc.trace"/> </Tracing> <Gateway> <Description type="string" data="default"/> <HTTPMethod type="string" data="post"/> <URL type="string" data=" <HTTPQuery type="string" data="username=[acc_user]&password=[acc_pwd]&device=[otp_dest]&network=tgsm&am p;message=[otp_msg]"/> <Timeout type="unsigned" data="5"/> <ProxyIP type="string" data=""/> <ProxyPort type="unsigned" data="0"/> <MaxConnections type="unsigned" data="10"/> <Port type="unsigned" data="443"/> <Protocol type="string" data="https"/> <CertFile type="string" data="c:\program Files\VASCO\Identikey 3.0\Bin\curl-ca-bundle.crt"/> </Gateway> <Gateway-Acct> <Username type="string" data="user"/> <Password type="string" data="pass"/> </Gateway-Acct> <!-- These results are for the first gateway --> <Result01> <Name type="string" data="success Message"/> <Pagematch type="string" data="message has been sent[]sent to [number]."/> <MsgType type="unsigned" data="0"/> <Message type="string" data="message successfully sent to [username]/[number]"/> </Result01> <Result02> <Name type="string" data="failure Message"/> <Pagematch type="string" data="<font color=red><b>[message]</b>"/> <MsgType type="unsigned" data="1"/> <Message type="string" data="message not sent to user '[username]'/[otp_dest]. Gateway reported: [message]"/> </Result02> <Result03> <Name type="string" data="malformed Query string"/> Identikey Server Administrator Reference 192

193 Identikey Server Configuration Settings <Pagematch type="string" data="(404)"/> <MsgType type="unsigned" data="2"/> <Message type="string" data="query string is incorrect. 404 Page not found."/> </Result03> </VASCO> Caution The configuration file is UTF8 encoded. Non-UTF8 encoded characters should not be added to the configuration file, or it will not load. Identikey Server Administrator Reference 193

194 Identikey Server Configuration Settings Configuration Settings The table below lists the options, their default values, and a brief explanation of each. Table 61: Message Delivery Component Configuration Settings Option Name Config. GUI Field Default Value Notes General tab Gateway/ ProxyIP Gateway/ ProxyPort Gateway/ Timeout Gateway/ MaxConnections Tracing/ TraceFile Tracing/ TraceMask Gateway-Acnt/ Username Gateway-Acnt/ Password Gateway Settings tab Gateway/ Description Gateway/ HTTPMethod Gateway/ URL Proxy IP <Empty> IP address of the HTTP proxy used by the MDC to contact the HTTP gateway. This can be used when the firewall settings do not allow a direct connection.empty - no proxy being used. Data type: String with valid IP4 address Port <None> Port number to contact the HTTP proxy on.must be supplied if the ProxyIP setting is used. Data type: Integer with valid Port address ( ) Proxy Timeout 30 Time in seconds that the MDC will wait on a response from the HTTP/gateway. Data type: integer Max Connections 10 Maximum allowed number of concurrent connections to the HTTP gateway. Data type: Integer (1-100) File Name <None> The file that tracing output should be written to using the absolute path and file name. Data type: String Tracing 0 The tracemask specifies how much tracing is done. 0 no tracing 1 basic tracing 2 full tracing Data type: Integer (General tab)username (General tab)password & Confirm Password Gateway Name <required parameter> <required parameter> Sets the account Username the HTTP gateway. The given value will be used as content for the variable [acc_user] in the query string. Data type: String Sets the account password the HTTP gateway. The given value will be used as content for the variable [acc_pwd] in the query string. Data type: String This is an informational field, naming or describing the HTTP gateway. It can be set to provide a description for a particular service, but is ignored by the MDC. Data type: String Query Method POST Designates either the GET or POST method for use in transferring account and message data to the HTTP/HTTPS gateway. Data type: String ( GET or POST ) Protocol and Address <required parameter> Required parameter.sets the URL to the HTTP gateway. The address should not contain any variables, but is should contain the protocol Identikey Server Administrator Reference 194

195 Identikey Server Configuration Settings Option Name Config. GUI Field Default Value Notes Gateway/ HTTPQuery Gateway/ CertFile Gateway Results tab Results/ Resultnn/ Name Results/ Resultnn/ Pagematch Results/ Resultnn/ MsgType Query String Certificate File <required parameter>.\curl-cabundle.crt identifier. Note: the protocol identifier of can be used to SSL-encrypt the link between the MDC and the HTTP gateway. In this case it is required to specify a filename where the server certificates can be found. Data type: String Required parameter.defines the query string which will be submitted to the http server, either using POST or GET (as specified by HttpGw- Method). This string must contain all required variables that are expected by the HTTP gateway. Contained in the query string must be the following parameters which will be set by the MDC before submitting the query: [acc_user] specifies the account name for the gateway which will be used to submit the information [acc_pwd]password for the gateway account specified by the [Username] parameters [otp_msg]specifies the part of the query string, where the OTP message will be substituted [otp_dest]specifies the part of the query string, where the destination for the OTP (usually the mobile phone number) will be substituted.the query string should also incorporate any other parameters which might be expected by the gateway. Example:<Query type= string data= UN=[Username]&PW=[password]&TY=T&NB=[destination]&M E=[message]&FL=F&ON=FromVM&TM=Y /> Data type: String When using the HTTPS protocol, the server certificate file is used to authenticate the message gateway and to derive the data encryption keys. It can contain either one or multiple server certificates.the file needs to be PEM-encoded,X.509 compliant certificate.it can be created by exporting the required Root CA from any browser (eg. Internet Explorer) using the base-64 format - equivalent to PEM. Data type: String Description <Empty> Name of this entry, as displayed by the MDC Configuration GUI. This field has no functional meaning. Data type: String Matching Pattern Audit Message Level <required parameter> Result Page Template to match the result page returned by the HTTP service. If this template is matched, the corresponding audit message is composed and returned to the Identikey Server Audit message. Data type: String 2 Type of message to appear in the audit log: 0 INFO informational message (login on) 1 WARNING warning message (login fails) 2 ERROR error message (login fails) Data type: Integer (0-2) Identikey Server Administrator Reference 195

196 Identikey Server Configuration Settings Option Name Config. GUI Field Default Value Notes Results/ Resultnn/ Message Message Text <required parameter> Audit Message Template for the message to be compiled and sent back to the Identikey Server. The message is returned as Information, Warning or Error, depending on the MsgType parameter in the same section. Includes [variable] options. Data type: String Identikey Server Administrator Reference 196

197 Identikey Server Configuration Settings 11.8 Digipass TCL Command Line Utility The Digipass Command Line Utility uses an xml file to store necessary configuration settings. This file can be found at <install directory>\bin\dpadmincmd.xml (Windows) or /etc/vasco/dpadmincmd.xml (Linux). If the TCL Command Line Utility is being used on the server machine, the xml file will be created by the wizard. If the TCL Command Line Utility is not being used on the server machine, you will have to create the XML file using the template provided at <install directory>\bin\dpadmincmd.tmpl (Windows) or /etc/vasco/dpadmincmd.tmpl (Linux), and replace: the trace file the local address connection 00 - the IP address of the remote server Sample Configuration File <VASCO> <Silent-Mode type="bool" data="false" /> <Tracing> <Trace-Header type="unsigned" data="15" /> <Trace-Mask type="unsigned" data="0x " /> <Trace-File type="string" data="c:\program Files\VASCO\Identikey 3.0\log\dpadmincmd.trace" /> </Tracing> <AAL3> <Library-Path type="string" data="c:\program Files\VASCO\Identikey 3.0\bin\ikaal3seal.dll" /> <SEAL> <Local-Address type="string" data=" " /> <Connection-List> <Connection00> <Address type="string" data=" " /> Port type="unsigned" data="20003" /> <Server-Type type="string" data="primary" /> <Nr-Connections type="unsigned" data="5" /> </Connection00> </Connection-List> </SEAL> Identikey Server Administrator Reference 197

198 Identikey Server Configuration Settings </AAL3> <Audit> <Plugins /> </Audit> </VASCO> Identikey Server Administrator Reference 198

199 Identikey Server Advanced Setup 12 Identikey Server Advanced Setup 12.1 Create Organizational Structure The creation of the organizational structure is only applicable where Identikey Server uses an ODBC database as its data store. If it uses Active Directory, it will utilise the existing Active Directory organizational structure Domains Domains can be used to divide administration between specific organizational divisions, where some administrators should only have access to a single group of users rather than all. They may mirror actual domains in the corporate network. Master Domain Identikey Server installation creates a master domain named Master by default in the data store. This domain can be used to allow global administration and store unallocated Digipass records. Any administrators whose Digipass User record is in the Master Domain may act as global administrators Create a New Domain Pre-requisites The global administrator account used for this process must have at least these privileges: Admin Logon Access Data in all domains Create domain View domain Instructions 1. Log on to the Administration Web Interface with a global administrator account. 2. Click on Organization-> Add domain 3. Enter a Domain name. 4. If desired, enter a description for the domain. 5. Click on Create. Identikey Server Administrator Reference 199

200 Identikey Server Advanced Setup Organizational Units Create an Organizational Unit Org units in IK3.1 are mainly used to organize users and Digipass. To create an org unit in a domain: 1. Open the Administration Web Interface. 2. Click on Organization->List 3. Locate the domain in which to place the organizational unit. 4. View details of the selected domain 5. Click on Add Org. Unit 6. Enter a name for the organizational unit. 7. Select a parent organizational unit, if applicable. This will locate the new organizational unit as a child of the selected one. 8. If desired, enter a description for the new organizational unit. 9. Click on Create Administrators There are two basic types of administrators. Global administrators Global administrators are not restricted by domain, and can read and/or write data regardless of the domain to which it belongs. Delegated administrators This type of administrator is restricted to administration of data in the domain in which the account is located Create a Delegated Administrator This task implies defining and assigning for each of the newly added domains an admin user who will perform user and Digipass administration. In case of delegated administration, administration will be performed by a domain specific administrator. A domain specific admin user will be part of his domain. For each domain, an administrator has to be created and administrative rights assigned. To create an admin user: Identikey Server Administrator Reference 200

201 Identikey Server Advanced Setup 1. Open the Administration Web Interface. 2. Go to Users -> Create 3. Enter a User ID and domain for the administrator. They will be restricted to User and Digipass administration in this domain. 4. Click on Create. 5. Click on the Click here to manage link. 6. Click on Admin Privileges. 7. Click on Edit. 8. Assign the necessary user and Digipass admin privileges by selecting the privilege name and clicking the > button. 9. When complete, click on Save Create a Global Administrator Global administrator accounts are created in the master domain, and the administrative privileges assigned them apply throughout all domains. To create a global administrator: 1. Open the Administration Web Interface. 2. Click on Users -> Create 3. Enter a User ID for the administrator. 4. Enter the name of the master domain (default master domain is Master). 5. Click on Create. 6. Click on the Click here to manage link. 7. Click on Admin Privileges. 8. Click on Edit. 9. Assign the necessary user and Digipass admin privileges by selecting the privilege name and clicking the > button. 10. When complete, click on Save. Identikey Server Administrator Reference 201

202 Identikey Server Advanced Setup 12.2 How To Set Up Virtual Digipass Pre-requisites Reading It is recommended that you read the following topics before starting this process: Types of Digipass topic in the Introduction section of the Product Guide Virtual Digipass Implementation Considerations topic in the Digipass section of the Product Guide Select Virtual Digipass Options There are three basic options available when implementing Virtual Digipass with Identikey Server: Primary Virtual Digipass only Backup Virtual Digipass, in conjunction with hardware or software Digipass Combination of Primary and Backup Virtual Digipass Import Virtual Digipass records You will receive Primary Virtual Digipass records in a.dpx file, with a DPX File Key, as you would receive with normal Digipass records. Import them as you would normal Digipass records. Backup Virtual Digipass do not have records of their own. Information on Backup Virtual Digipass is contained in the record for the Digipass which is being supplemented by the Backup Virtual Digipass Set Up SMS Gateway MDC Access If required, configure an ID and password for the Message Delivery Component to use when passing text messages to the SMS Gateway Set Up Message Delivery Component Installation See the relevant Installation Guide (Windows or Linux) for instructions on installing the Message Delivery Component. Identikey Server Administrator Reference 202

203 Identikey Server Advanced Setup MDC Configuration For instructions on configuring the Message Delivery Component to work with Identikey Server and the SMS Gateway, see 11.7 Message Delivery Component Configuration Configure Identikey Server If the Message Delivery Component is installed on a different machine to the Identikey Server, the Identikey Server must be configured with the connection details. To do this, open the configuration file - identikeyconfig.xml - and find the VDPClient details. Edit the MDC-IPAddress and MDC-Port settings Edit Identikey Server Policy You may need to read the Policy information in the Product Guide before following these instructions Primary Virtual Digipass Set Up Policy 1. Open the Administration Web Interface. 2. Click on Policy -> List. 3. Select the Policy in which you wish to enable the use of Virtual Digipass. 4. Click on the Virtual Digipass tab. 5. Click Edit. 6. Find the Primary Virtual Digipass section. 7. Select one of the following options as the Request Method:: Keyword User enters the Request Keyword into the password field. Password - User enters their static password only into the password field. KeywordPassword User enters the Request Keyword, followed by their static password, into the password field. PasswordKeyword - User enters their static password, followed by the Request Keyword, into the password field. 8. If you have selected an option which includes the use of a Request Keyword, enter it in the PVDP Request Keyword field. 9. Click on Save. Identikey Server Administrator Reference 203

204 Identikey Server Advanced Setup Backup Virtual Digipass Permitted, Not Mandatory 1. Open the Administration Web Interface. 2. Click on Policy -> List. 3. Select the Policy in which you wish to enable the use of Virtual Digipass. 4. Click Edit. 5. Click on the Virtual Digipass tab. 6. Find the Backup Virtual Digipass section. 7. Select Yes Permitted from the Enable Backup VDP drop down list. 8. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual Digipass. 9. Click on Save. Permitted, Not Mandatory, Time-Limited 1. Open the Administration Web Interface. 2. Click on Policy -> List. 3. Select the Policy in which you wish to enable the use of Virtual Digipass. 4. Click Edit. 5. Click on the Virtual Digipass tab. 6. Find the Backup Virtual Digipass section. 7. Select Yes Time Limited from the Enable Backup VDP drop down list. 8. Enter a time limit (in days) into the Time Limit field. At the end of this time period calculated from their first use - the User will no longer be permitted to use a Backup Virtual Digipass. 9. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual Digipass. Mandatory 1. Open the Administration Web Interface. 2. Click on Policy -> List. 3. Select the Policy in which you wish to enable the use of Virtual Digipass. 4. Click Edit. 5. Click on the Virtual Digipass tab. 6. Find the Backup Virtual Digipass section. 7. Select Yes Required from the Enable Backup VDP drop down list. Identikey Server Administrator Reference 204

205 Identikey Server Advanced Setup 8. If desired, enter a maximum number of uses. This will be calculated for each person using a Backup Virtual Digipass. 9. Click on Save. Backup Virtual Digipass may also be enabled for individual Users, via each Digipass record. This over Test Virtual Digipass Primary Virtual Digipass To test a Primary Virtual Digipass: 1. Open the Administration Web Interface. 2. Click on Digipass -> List. 3. Click on the Virtual Digipass to be tested. 4. From the Application Type tab click on the Test VDP button. 5. Enter the mobile phone number to which the VDP should be sent. 6. Click on Generate. The Administration Web Interface will attempt to send an OTP to the Message Delivery Component, which will attempt to forward it to the SMS Gateway. The success or failure of these attempts will be displayed. 7. If the OTP was received by your mobile phone, enter it into the OTP field and click on Verify. The success or failure of the verification attempt will be displayed. Backup Virtual Digipass To test a Backup Virtual Digipass: 1. Open the Administration Web Interface. 2. Click on Digipass -> List. 3. Click on the Digipass belonging to the Backup Virtual Digipass to be tested. 4. From the Application Type tab click on the Test BVDP button. 5. Enter the mobile phone number to which the OTP should be sent. 6. Click on Generate. The Administration Web Interface will attempt to send an OTP to the Message Delivery Component, which will attempt to forward it to the SMS Gateway. The success or failure of these attempts will be displayed. 7. If the OTP was received by your mobile phone, enter it into the OTP field and click on Verify. The success or failure of the verification attempt will be displayed. Identikey Server Administrator Reference 205

206 Identikey Server Advanced Setup 12.3 Connect the Administration Web Interface to a New Identikey Server Note The Identikey Server to which the Administration Web Interface will be connecting needs to have a Client Component record of type Administration Program in its data store for the machine on which the Administration Web Interface is running Windows Linux 1. Open a command line window. 2. Navigate to the <install directory>\webadmin directory. 3. If you are using the default keystore and keystore password, enter the following command: java -jar admintool.jar autoadd <name> <url> where <name> is the display name for the server and <url> is its location. For example: java -jar admintool.jar autoadd Belgium 4. If you have moved the keystore from its default location, or entered a custom keystore password during installation, enter the following command: java -jar admintool.jar autoadd <name> <url> <keystore location> <keystore password> where <name> is the display name for the server, <url> is the server location, <keystore location> is the path and filename for the keystore, and <keystore password> is the password set for the keystore. 1. Enter the chroot environment: vds_chroot <installation directory> /bin/bash 2. Navigate to <install directory>/webadmin on the machine where the webadmin is running. 3. If you are using the default keystore and keystore password, enter the following command: java -jar admintool.jar autoadd <name> <url> where <name> is the display name for the server and <url> is its location. For example: java -jar admintool.jar autoadd Belgium Identikey Server Administrator Reference 206

207 Identikey Server Advanced Setup 4. If you have moved the keystore from its default location, or entered a custom keystore password during installation, enter the following command: java -jar admintool.jar autoadd <name> <url> <keystore location> <keystore password> where <name> is the display name for the server, <url> is the server location, <keystore location> is the path and filename for the keystore, and <keystore password> is the password set for the keystore Create Custom Report Definition Before attempting to create a custom report definition, it is recommended that you read the Reporting section of the Product Guide. 1. Open the Administration Web Interface. 2. Click on the Reports tab and select Define report from the drop-down list. 3. Type a name for the report definition. 4. Select the type of report definition required: List Analysis Report a list of all items that match the criteria specified in the report definition Detailed Analysis Report - detail of selected events Distribution Analysis Report - counts of events and/or objects Trend Analysis Report trends in event or object numbers over a specified period of time 5. Enter a description for the report definition something which will help you and/or other administrators know what data will be found in the report. 6. Select a grouping level: Client connections requested and/or approved by machines with Client Component records 7. Click on Next Data from Audit sources only Domain Digipass and Digipass User information Data from data store (eg. list of Digipass Users by Domain) or Audit sources (eg. rejected authentication requests) Organizational Unit Digipass and Digipass User information Data from data store (eg. list of Digipass Users by Organizational Unit) or Audit sources (eg. rejected authentication requests) User Digipass and Digipass User information Data from data store (eg. list of Digipass Users with Digipass assigned) or Audit sources (eg. rejected authentication requests) Digipass Digipass information Data from data store (eg. list of unassigned Digipass) or Audit sources Identikey Server Administrator Reference 207

208 Identikey Server Advanced Setup 8. Enter a name for the new query. 9. Click on Add New. 10. Select the name of a field, the condition, and the value on which to filter. Example To report on rejected authentication requests, select Audit:Code from the Field drop down list, select Equals from the Condition drop down list, and enter I in the Value field. 11. Click on Next. 12. If desired, add more queries. 13. Click on Next. 14. Select Usage and Update permissions. Usage permissions control which administrators may view a report Update permissions control which administrators may modify a report definition. 15. Click on Next. 16. To use the standard XML template, Select the Use the default XML template only option button. Or to use a custom template, select the Add new template in addition to default XML template option button and enter the location of the template and a name to use in referring to it. 17. Click on Save. 18. Click on Finish Query Filters The tables below list the fields on which a report query may be filtered, and the data type required for each. User field list User:User ID User:Domain Display name Type Value(s) required User:Organizational Unit User:User Name User: User:Phone User:Mobile User:Description User:Has Digipass User:Local Authentication User:Backend Authentication String String String String String String String String Number Number Number User:Disabled Checkbox 0 or 1 User:Lock Count Number Identikey Server Administrator Reference 208

209 Identikey Server Advanced Setup User:Locked Checkbox 0 or 1 User:Status String User:Profiles String User:Link String Domain Link String User:Created time Date User:Modified time Date The fields specified in the user field list can be referred to in the XSLT templates. Digipass field list Display name Type Digipass:Serial Number String Digipass:Domain String Digipass:Digipass Type String Digipass:Application Names String Digipass:Application Types String Digipass:Status String Digipass:User ID String Digipass:Assigned Date Digipass:Grace Period End Date Digipass:Backup VDP Enabled CheckBox Digipass:Backup VDP Expires Date Digipass:Backup VDP Uses Left Number Digipass:Created time Date Digipass:Modified time Date The fields specified in this Digipass field list can be referred to in the XSLT templates. Audit field list DisplayName Type Audit:Source Audit:Type code Audit:Type String Number String Audit:Code String See Audit Messages for a list of possible codes and messages used by the Audit System. Audit:Description String See Audit Messages for a list of possible codes and Identikey Server Administrator Reference 209

210 Identikey Server Advanced Setup Audit:Category Audit:TimeStamp Audit:AMID Audit:Reason Audit:Area Audit:Operation Audit:Error Code Audit:Error Message Audit:Error Details Audit:Source Location Audit:Server Location Audit:Client Location Audit:Version Audit:Data Source Audit:Data Source Location Audit:Configuration Details Audit:Outcome Audit:Reason Audit:Characteristics Audit:Credentials Audit:Session ID Audit:Application Audit:Request ID Audit:Password Protocol Audit:Input Details Audit:Action Audit:Output Details Audit:Policy ID Audit:From Audit:To String Date String String String String Number String String String String String String String String String String String String String String String String String String String String String String String messages used by the Audit System. Audit:Message String See Audit Messages for a list of possible codes and messages used by the Audit System. Audit:Quota Number Identikey Server Administrator Reference 210

211 Identikey Server Advanced Setup Audit:Object Audit:Command Audit:Downtime Audit:Fields Audit:Request Type String String Number String String Identikey Server Administrator Reference 211

212 Identikey Server Advanced Setup 12.5 Install a Commercial SSL Certificate Before installing a commercial SSL certificate, you will need to: obtain the.pem files required for the certificate note the location of the certificate files know the password for the keystore Windows Install Certificate 1. Run the Identikey Server Configuration Wizard. 2. Select Install SSL Certificate and click on Next. 3. Select Install my own SSL Certificate and click on Next. 4. Browse to the certificate file and click on Open. 5. Enter the password for the SSL certificate. 6. Browse to the trusted certificates file and click on Open. 7. Click on Next. 8. Click on Proceed. Configure Administration Web Interface to Use Certificate 1. Open a command line window. 2. Navigate to the <install directory>\webadmin directory. 3. Enter the following command: java -jar admintool.jar autoadd <name> <url> <keystore location> <keystore password> where <name> is the display name of the Identikey Server, <url> is the address and port number of the Identikey Server, <keystore location> is the location and file name of the keystore and <keystore password> is the password on the keystore. For example: java -jar admintool.jar autoadd IKServer1 c:\program Files\VASCO\Identikey 3.1\webadmin\keystore.jks password1 Identikey Server Administrator Reference 212

213 Identikey Server Advanced Setup Linux Install Certificate 1. Run the Identikey Server Configuration Wizard. 2. Select Install SSL Certificate and click on Next. 3. Select Install my own SSL Certificate and click on Next. 4. Browse to the certificate file and click on Open. 5. Enter the password for the SSL certificate. 6. Browse to the trusted certificates file and click on Open. 7. Click on Next. 8. Click on Proceed. Configure Administration Web Interface to Use Certificate 1. Navigate to the usr/share/vasco directory. 2. Enter the following command: java -jar admintool.jar autoadd <name> <url> <keystore location> <keystore password> where <name> is the display name of the Identikey Server, <url> is the address and port number of the Identikey Server, <keystore location> is the location and file name of the keystore and <keystore password> is the password on the keystore. For example: java -jar admintool.jar autoadd IKServer1 etc/vasco/keystore.jks password1 Identikey Server Administrator Reference 213

214 Identikey Server Advanced Setup 12.6 How to Set Up a Stand-Alone Identikey Server in RADIUS Environment You may wish to use this topology if: RADIUS attributes are not required One of the supported password protocols will be in use: PAP, CHAP, MS-CHAPv1, or MS-CHAPv Information required IP address of the RADIUS client Shared secret used by the RADIUS client - or select a secret to use now if the RADIUS client isn't yet equipped with a shared secret Instructions Administration Web Interface 1. Click on Clients -> Register 2. Enter this data: Client Type: Select RADIUS Client Location: Enter the IP address of the RADIUS client Policy ID: Select the policy you want to use for this RADIUS client Protocol ID: Select RADIUS Shared Secret: Enter the shared secret used by the RADIUS client 3. Click on Create. RADIUS Client Configuration 4. Configure your RADIUS client to send authentication request to the Identikey server (the IP/port of the RADIUS communicator can be found in the Identikey Server Configuration utility). Identikey Server Administrator Reference 214

215 Identikey Server Advanced Setup 12.7 How to Set Up Identikey Server as RADIUS Proxy Target You may wish to use this topology if: The RADIUS server supports the proxying of authentication while returning attributes itself The RADIUS server can forward the authentication request using one of the supported password protocols is used: PAP, CHAP, MS-CHAPv1, MS-CHAPv2 The RADIUS server supports an Access-Challenge response from Identikey Server, if required. The Access- Challenge mechanism is used for Challenge/Response and Virtual Digipass, although it is still possible to use Virtual Digipass without that mechanism. If the RADIUS server is capable, this scenario allows Identikey Server to operate in an environment that uses certificate-based EAP protocols such as PEAP and EAP-TTLS. To make this work, the RADIUS server decrypts the user credentials into a simpler protocol before forwarding the request to Identikey Server Information required IP address of the RADIUS server Shared secret used by the RADIUS server Instructions Administration Web Interface 1. Click on Clients -> Register 2. Enter this data: Identikey Server Administrator Reference 215

216 Identikey Server Advanced Setup Client Type: Select RADIUS Client Location: Enter the IP address of the RADIUS client Policy ID: Select the policy you want to use for this RADIUS client Protocol ID: Select RADIUS Shared Secret: Enter the shared secret used by the RADIUS client 3. Click on Create. RADIUS Client Configuration 4. Configure your RADIUS client to send authentication request to the Identikey server (the IP/port of the RADIUS communicator can be found in the Identikey Server Configuration utility). Identikey Server Administrator Reference 216

217 Identikey Server Advanced Setup 12.8 How to Set Up Identikey Server as Intermediate Server When used as an intermediate authentication server, Identikey Server can be set up in two basic modes OTPonly, where Identikey Server keeps a record of a User's static password and relays it to the Back-End Server, and OTP-Password, where the User enters an OTP and their password, which is not stored by Identikey Server but is relayed to the Back-End Server for authentication. OTP Only OTP and Password Identikey Server Administrator Reference 217

218 Identikey Server Advanced Setup Information required IP address of the RADIUS client Shared secret used by the RADIUS client IP address of the RADIUS server Shared secret used by the RADIUS server Instructions Administration Web Interface 1. Click on Clients -> Register 2. Enter this data: Client Type: Select RADIUS Client Location: Enter the IP address of the RADIUS client Policy ID: Select the policy you want to use for this RADIUS client Protocol ID: Select RADIUS Shared Secret: Enter the shared secret used by the RADIUS client 3. Click on Create. 4. Configure the RADIUS client to send authentication requests to the Identikey Server The IP/port of the RADIUS communicator can be found using the Identikey Server Configuration utility. 5. Go to Back-end->Register RADIUS Back-End Backend server ID: an identifier for the RADIUS server Domain name: master if the RADIUS Server should process auth request from all domains, else a specific domain Priority: use this if you want to define multiple back-end servers for failover reasons - the one with the highest priority will be used first Authentication IP Address: The IP address that the RADIUS Server is using for authentication requests Authentication port: The Port that the RADIUS Server is using for authentication requests Accounting IP Address: The IP address that the RADIUS Server is using for accounting requests Accounting port: The Port that the RADIUS Server is using for accounting requests Shared Secret: the shared secret of the RADIUS Server Timeout: timeout on the connection to the RADIUS Server Retries: Number of retries before abandoning attempts to send an authentication request to the RADIUS Server Identikey Server Administrator Reference 218

219 Identikey Server Advanced Setup 6. Click on Create Identikey Server Administrator Reference 219

220 Identikey Server Advanced Setup 12.9 Add a New Domain to Identikey Server These topic will lead you through the processes required to set up Identikey Server authentication in a new domain, where Identikey Server is already set up in another domain Solution 1: Install an Extra Identikey Server in the New Domain. Follow the regular installation process to install an Identikey Server on the new domain. Note Ensure that your license covers the new Identikey Server Solution 2: Configure New Domain for Existing Identikey Server 1. Check that the schema in the new domain contains the schema extensions required by Identikey Server. See Check Schema Extensions for more information. 2. Set up the Digipass-Pool and Digipass-Reserve containers in the new domain. See Set Up Digipass Containers in Domain for detailed information. 3. Ensure that trusts are configured correctly between the domains to allow Identikey Server access to data in the new domain. 4. Read 5 Set Up Active Directory Permissions for information on the Active Directory permissions that might need to be set in order to administer the Digipass Users and Digipass in that domain. 5. Add the domain to Identikey Server's configuration settings. See LDAP Data Sources for more information. 6. Optionally, install the Digipass Extension for Active Directory Users & Computers on a machine in the new domain which has the Active Directory Users & Computers tool installed. Identikey Server Administrator Reference 220

221 Reporting 13 Reporting 13.1 Reporting Overview What fields can be included in reports? Fields from the following sources can be used in a report: Users Digipass Audit Data Users + Audit Digipass + Audit How can these fields be grouped? These fields can be grouped based on the following based on the following fields: Client Domain Organizational Unit User Digipass The information on the report will be grouped based on the field defined above How to define a Query Queries consist of: a Datafield, which is a field from the database, an Operator, which is the operation to be performed on the datafield, a Value, which is the value the datafield will be compared against. A value is not necessary with all operators. To define a query you must select a datafield and an operator. Operators can be selected from the following: ISBLANK NOTBLANK Identikey Server Administrator Reference 221

222 Reporting EQUALS NOTEQUALS STARTS INCLUDES ENDS NOTSTARTS NOTENDS NOTINCLUDES > >= < <= BETWEEN NOTBETWEEN ISYES ISNO A value is not required for every operator. Sample structures are as follows: Datafield Operator Datafield Operator Value Datafield Operator Value Value for example CLIENTTYPE ISBLANK for example CLIENTTYPE INCLUDES 'W' for example CLIENTTYPE INCLUDES 'W' 'A Fields Available to Report Query Definition As mentioned above, queries can be defined from User, Digipass and Audit data fields. The fields listed below are available for selection when defining a query. User fields Name Type Description Userid String User Id Domain String User Domain Org_unit String User Organisational Unit Username String Username Identikey Server Administrator Reference 222

223 Reporting Name Type Description String User Phone String User Phone No Mobile Number User Mobile No Desc String User Description Has_dp Number User Has Digipass Digipass String User Digipass serial number Local_auth Number User Local Authentication Backend_auth Number User Back-End Authentication Disabled Y/N User Disabled Lock_count Number User Lock Count Locked Y/N User Locked Status String User Status Profiles String User Profiles Link_userid String User Link Link_domain String Domain Link Created Modified Digipass Fields Name Type Description Serial_no String DP Serial No Domain String DP Domain Org_unit String DP Organisational Unit Dp_type String DP Type Appl_names String DP Application Names Apply_types String DP Application Types Status String DP Status Userid String DP User ID Assigned Date DP Assign Date Grace_period_end Date DP Grace Period End Date Bvdp_enabled Y/N Backup Virtual DP Enabled Bvdp_expires Date BVDP Expiration Date Bvdp_uses_left Number BVDP Uses Left Identikey Server Administrator Reference 223

224 Reporting Name Type Description Reserve Number DP Reserved Description String Digipass Description Created Date DP Creation Date Modified Date DP Modification Date Audit Fields Name Type Description Source String Audit Source Msg_type Number Audit Message Type Type_name String Audit Type Name Code String Audit Code Desc String Audit Description Category String Audit Category Timestamp Date Audit TimeStamp Amid String Audit Amid Reason String Audit Reason Area String Area Operation String Operation Error_Code Number Error Code Error_Message String Error Message Error_Stack String Error Details Audit_Location String Source Location Server_Location String Server Location Client_Location String Client Location Version String Version Data_Source_Type String Data Source Data_Source_Location String Data Source Location Configuration_Details String Configuration Details Outcome String Outcome Reason String Reason Characteristics String Characteristics Credential_Type String Credentials Session_ID String Session ID Identikey Server Administrator Reference 224

225 Reporting Name Type Description Application_Name String Application Name Request_ID String Request ID Password_Protocol String Password Protocol Input_Details String Input Details Action String Action Output_Details String Output Details Policy_ID String Policy ID From_Location String From To_Location String To Info_Message String Message Quota Number Quota Object String Object Command String Command Downtime Number Downtime Field_Details String Fields Packet_Type String Request Type Note Two or more values after the operator will be interpreted as if the word 'and' was between them Report Permissions You can define Usage Permissions and Update Permissions for reports. Usage Permissions defines who is allowed to use the report. Update Permissions defines who is allowed to change the report definition. Both Usage and Update permissions can have the following values: Private - only the owner can run this report Domain - all administrators in this domain can run this report Public - all administrators in all the domains can run this report Types of Report There are four report types. All report templates are based on these report types: Identikey Server Administrator Reference 225

226 Reporting List Analysis Report Detailed Analysis Report Distribution Analysis Report Trend Analysis Report Standard Reports. The Identikey Server reporting package will come with standard reports. Standard reports are provided for the most common administration tasks. The standard reports can be grouped by their use: Reports produced by the Helpdesk to help with troubleshooting functional problems Detailed authentication report User authentication history report Detailed Digipass registration report Detailed activity summary report Detailed Signature Validation report Detailed Provisioning report Signature Validation history report Reports produced by System administrators to help with troubleshooting system problems Failed Operations summary report Succeeded Operations summary report Reports produced by Administrators for Accounting information Authentication activity by user report Authentication activity by client report Provisioning activity by user report Provisioning activity by client report Transaction Signing Activity by User Application report Transaction Signing Activity by Client report Reports produced by Administrators for System auditing information Administration activity summary report Digipass availability by type report Digipass deployment trend report Digipass deployment by type report Identikey Server Administrator Reference 226

227 Reporting Authentication trend report Transaction Signing Activity Trend Provisioning activity trend report Account lock trend report Digipass assignment activity summary report Custom Reports Custom reports can be defined to fulfil requirements not met by the standard reports. Custom reports are based on the standard report types with a report query defined to suit your organization's requirements Formatting Templates Report data is always generated into XML, then an XSLT transformation is applied to give the output. The XSLT transformation requires a formatting template. Each report definition requires at least one template so that it can be produced in the format required. Each report definition can have more than one Formatting Template. The template to be used can be selected when running the report Archiving Strategy Large amounts of data means that reports take a long time to run. Have an archiving strategy in place that moves out data over a certain age. Make a decision about what data you will require in your reports, and for how long you need to keep it live on the Data Source. Archived data cannot be reported upon. Identikey Server Administrator Reference 227

228 Auditing 14 Auditing 14.1 Text File Setting up auditing in the Identikey Server requires three basic steps: 1. Set up audit message destination. If this will be a text file or the Windows Event Log, no configuration is required. 2. Configure auditing in the Identikey Server to send audit messages to the correct destination. 3. Configure Audit Viewer to retrieve, filter and display audit messages Text File Name Variables A number of variables may be included in the name or path of an audit text file.time/date variables will influence how often a new text file is created. Table 62: Audit Text File Name/Path Variables Variable Notes {year} Current year in format 'YYYY' eg {month} Current month in format 'MM' eg. November becomes 11 {mday} Current day of the month in format 'DD' eg. 06 {yday} Current day of the year in format 'DDD' this will be a number between 1 and 366 {week} Current week of the year in format 'WW' eg. The 6 th week of the year will be 06 {source} The name of the program from which the audit message was received by the Audit System eg. Authentication Server Example Entering the following into the Log File field in the Identikey Server Configuration: c:\audit Files\{source}\audit-{year}-{month}-{mday}.audit would cause: A directory named Identikey Server to be created in the Audit Files directory A new audit text file to be created daily A file named audit audit to be created on the 6 th November 2006 Identikey Server Administrator Reference 228

229 Auditing Configure Auditing to Text File 1. Open the Identikey Server Configuration utility. 2. Click on the Auditing icon. 3. Click on the Add... button. 4. Select Text File from the list box. 5. Click on OK. The Add Text File Method window will be displayed. 6. Enter a name to use for display purposes in the Display Name field. 7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will be returned by the Identikey Server if an audit message cannot be written with this method. 8. Tick the Record audit message if no other audit method has recorded it checkbox if required. 9. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 10. Enter the location and a name for the text file. See Text File Name Variables for more information. 11. To speed up the auditing process, tick the Always keep file open checkbox. This will mean that the file is locked while the Identikey Server is running. 12. Tick the Use GMT/UTC checkbox to record dates and times in GMT/UTC. Otherwise, they will be recorded in local time. The text file will indicate the time zone used. 13. Click on OK. 14. Click on Apply. Identikey Server Administrator Reference 229

230 Auditing 14.2 Windows Event Log 1. Open the Identikey Server Configuration utility. 2. Click on the Auditing icon. 3. Click on the Add... button. 4. Select Event Log from the list box. 5. Click on OK. The Add Event Log Method window will be displayed. 6. Enter a name to use for display purposes in the Display Name field. 7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will be returned by the Identikey Server if an audit message cannot be written with this method. 8. Tick the Record audit message if no other audit method has recorded it checkbox if required. 9. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 10. Select a log type or enter a new log type to be created in the Log Type drop down list. 11. Click on OK. 12. Click on Apply. Identikey Server Administrator Reference 230

231 Auditing 14.3 ODBC Audit Message Database Set up ODBC Database Create database See 3.1 Database Support for information on the ODBC databases supported by Identikey Server Create database schema Two tables are required in the database. These can be created by the DPDBadmin utility using the -audit parameter (see Modify Database Schema), or manually. Table 63: Required Audit Database Tables Table Name vdsauditmessage vdsauditmsgfield Purpose Basic audit message, including mandatory fields Contains extra (non-mandatory) audit message fields which may be included in an audit message Image 2: Audit Database Table Relationships Identikey Server Administrator Reference 231

232 Auditing vdsauditmessage Table This table will contain one record per audit message generated, with non-mandatory information held in the vdsauditmsgfield table. Table 64: vdsauditmessage Required Fields Column Name Data Type Primary Key Allow NULL Details vdstimestamp timestamp* Yes No Date/time of event. vdsamid varchar(32) Yes No 32 hex digit Audit Message ID (without 0x prefix). vdssource varchar(64) No Source component name. vdstype integer No Numeric type. vdscode varchar(8) No Message code eg. I vdsdesc varchar(255) No Standard description for audit message. vdscategory varchar(32) No Name of category eg. Authentication. * For some databases, this is DATETIME (SQL Server, Sybase Enterprise) or DATE (Oracle) this is not an automatically generated timestamp, but just a date/time field. Millisecond precision or greater is required. vdsauditmsgfield Table This table may contain several records for a single audit message. Table 65: vdsauditmsgfield Required Fields Column Name Data Type Primary Key Allow NULL Details vdstimestamp timestamp* Yes No Date/time of event. vdsamid varchar(32) Yes No 32 hex digit AMID (without 0x prefix). vdsfieldid integer Yes No Integer (dataset) ID of optional field. vdsfieldvalue varchar(1024) No Yes Value of optional field, represented as string. * For some databases, this is DATETIME (SQL Server, Sybase Enterprise) or DATE (Oracle) this is not an automatically generated timestamp, but just a date/time field. Millisecond precision or greater is required Create Database Account(s) Create at least one database account. These permissions are required for the Identikey Server and Audit Viewer: Identikey Server Administrator Reference 232

233 Auditing Table 66: Required Account Permissions Program Table Permission(s) required Identikey Server All Write Audit Viewer All Read Create DSN on Identikey Server machine Create a Data Source Name for the database on the machine on which the Identikey Server is installed Create DSN on Audit Viewer machine Create a Data Source Name for the database on the machine on which the Audit Viewer is installed Configure Identikey Server 1. Open the Identikey Server Configuration utility. 2. Click on the Auditing icon. 3. Click on the Add... button. 4. Select ODBC Database from the list box. 5. Click on OK. The Add ODBC Audit Method window will be displayed. 6. Enter a name to use for display purposes in the Display Name field. 7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will be returned by the Identikey Server if an audit message cannot be written with this method. 8. Tick the Record audit message if no other audit method has recorded it checkbox if required. 9. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 10. Enter the DSN for the database. 11. Enter the username and password of the database account to be used by the Identikey Server (if required). 12. Click on OK. 13. Click on Apply. Identikey Server Administrator Reference 233

234 Auditing Configure Audit Viewer Note A Data Source Name must be configured on the Audit Viewer computer for the database. 1. Select New Audit Source -> ODBC Database from the File menu. 2. Enter a display name to be used for the database within the Audit Viewer. 3. Enter the Data Source Name for the database. 4. Enter the User ID and password of an administrator account for the database. 5. Tick the Store User ID and Password checkbox to save login details in the Audit Viewer. 6. Click on OK Linux Syslog For Linux systems, auditing data will be written to the Syslog. The Syslog requires the Audit Messages to have the following attributes : Priority Facility Timestamp Source Hostname Source Application name Event payload The values in the attributes on the Audit Message determine where the message gets written to, and whether it appears on the Syslog or not. Audit Message type to Syslog Priority Mapping The table below defines the mapping of Audit Message Type to Syslog Priority. You can use the Syslog Priority to direct the Audit Message Types to any log file, pipe, or remote syslog service. Table 67: Audit Message Types and Syslog Priority Message Type Success Fail Info Syslog Priority LOG_NOTICE LOG_NOTICE LOG_INFO Identikey Server Administrator Reference 234

235 Auditing Warning Error LOG_WARNING LOG_ERR Configure the System Log The host's syslog daemon needs to be configured to additionally point to the chroot location in order to pick up the identikey syslog audit events. This configuration will depend on the environment and how it is set up. Ubuntu Edit /etc/default/syslogd, adding option -a /opt/vasco/identikey/dev/log to the SYSLOGD parameter. RedHat 5 1. Edit /etc/sysconfig/syslog, adding option -a /opt/vasco/identikey/dev/log to the SYSLOGD_OPTIONS parameter. 2. For standard SELinux environments, the Syslog daemon may not have the correct permissions necessary to create the additional socket within the chroot. To resolve this, run the following command: SuSE cat <<EOF >>/etc/selinux/targeted/contexts/files/file_contexts && restorecon -F /opt/vasco/identikey/dev /opt/vasco/identikey/dev -d system_u:object_r:device_t:s0 /opt/vasco/identikey/dev/log -s system_u:object_r:devlog_t:s0 EOF 1. Run the following command: echo SYSLOGD_ADDITIONAL_SOCKET=\"/opt/vasco/identikey/dev/log\" >> /etc/sysconfig/syslog && SuSEconfig && /etc/init.d/syslog restart Modify Configuration File You may need to amend the syslog configuration file, to define the location to which specific audit logs should be written. For example, if the Identikey Server Syslog configuration has the audit Log Type set to local0, the syslog configuration file will need to define where to write this type of log message to. Check the ownership and permissions of the log file so that Syslog has permissions to write to it. Having changed the syslog configuration files, you will need to restart the host's syslog daemon. Identikey Server Administrator Reference 235

236 Auditing Configure Identikey Server to Write Audit Messages to the Syslog 1. Open the Identikey Server Configuration utility. 2. Click on the Auditing icon. 3. Click on the Add... button. 4. Select System Log from the list box. 5. Click on OK. The Add System Log Audit Method window will be displayed. 6. Enter a name to use for display purposes in the Display Name field. 7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will be returned by the Identikey Server if an audit message cannot be written with this method. 8. Tick the Record audit message if no other audit method has recorded it checkbox if required. 9. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 10. Select a log type or enter a new log type to be created in the Log Type drop down list. 11. Click on OK. 12. Click on Apply. Identikey Server Administrator Reference 236

237 Auditing 14.5 Live Connection - Identikey Server to Audit Viewer Configure Identikey Server 1. Open the Identikey Server Configuration GUI. 2. Click on the Auditing icon. 3. Click on the Add... button. 4. Select Live Connection from the list box. 5. Click on OK. The Add Live Connection Method window will be displayed. 6. Enter a name to use for display purposes in the Display Name field. 7. If this audit method must succeed, tick the Reject audit message if this method fails checkbox. An error will be returned by the Identikey Server if an audit message cannot be written with this method. 8. Tick the Only record message if no previous method has recorded it checkbox if required. 9. Select one or more audit message types to be logged by this plug-in: Error Warning Information Success Failure 10. Enter the IP address and port number on which the Identikey Server will listen for auditing connections. 11. Enter the maximum number of concurrent connections to allow. 12. Click on OK. 13. Click on Apply Configure Audit Viewer 1. Select New Audit Source -> Server from the File menu. 2. Enter a display name to be used for the messages within the Audit Viewer. 3. Enter the IP address of the Identikey Server. 4. Enter the port on which the Identikey Server will listen for auditing connections. 5. Click on OK. Identikey Server Administrator Reference 237

238 Tracing 15 Tracing The level of tracing for the Identikey Server can be configured using the Identikey Server Configuration GUI. Tracing messages will be recorded to a text file Trace Message Types Table 68: Tracing Message Types Message Type Code Notes Examples [CRITC] Critical error/warning [MAJOR] Major error/warning [MAJOR] > Failed to execute command. Error <Action denied:the static password was incorrect> [MINOR] Minor error/warning [MINOR]> Cannot get License Key from Component record [CONFG] Configuration/initialization [CONFG] > ODBC Database audit plugin is successfully loaded [CONFG] > Component cache configured as: max age : 900 max size : 1000 clean threshold : 800 min clean interval : 60 [ALERT] Alerts [ALERT] > disconnecting from server. [INFO] Informational messages [INFO ] > Audit: {Info} {Initialization} {I } {The Digipass Authentication library has been initialized successfully.} [INFO ] > Creating Digipass object. [VINFO] Verbose informational messages [VINFO] > Event log source is <Identikey Server 3 {Application}> [VINFO][ODBCConnection::OpenConnection] > Established connection to ODBC database [DATA] Data tracing [DATA ] > Prepared SQL statement "SELECT vdsdomain, vdsdescription, vdscreatetime, vdsmodifytime FROM vdsdomain ORDER BY vdsdomain" [TEMP] Temporary data values [TEMP ] > Updated list is <APPLI 1> [RESRC] Resource usage [RESRC] > Socket <0> Bound to < : 20006> [DEBUG] Debugging (useful for support purposes) [DEBUG] > Registering Binary <D:\Program Files\VASCO\Identikey Server 3\Bin\dpaudit.dll> with Event log <Application> for Source < Identikey Server 3 {Application}> [DEBUG] > Committed transaction Identikey Server Administrator Reference 238

239 Tracing Message Type Code [SECUR] Notes Security messages, messages that may contain security sensitive data Examples 15.2 Trace Message Levels There are two tracing levels available when configuring tracing from the Identikey Server Configuration GUI Basic and Full. This can be customised further if required by directly editing the configuration file. The message types recorded by each level are shown in the table below. Table 69: Tracing Message Levels Basic Full CRITC MAJOR MINOR CONFG ALERT INFO CRITC MAJOR MINOR CONFG ALERT INFO VINFO DATA TEMP RESRC DEBUG SECUR 15.3 Trace Message Contents Basic and Full tracing levels output different amounts of information in trace messages. Table 70: Tracing Message Contents Basic Full Trace Level [date_time] [thread ID] [level code] message Message Contents [date_time] [thread ID] [level code] [internal function name] message Identikey Server Administrator Reference 239

240 Digipass TCL Command-Line Administration 16 Digipass TCL Command-Line Administration 16.1 Introduction Digipass TCL Command-Line Administration (DPCLA) allows interactive command-line and scripted administration of Digipass related data. It has a number of possible uses: Interactive command-line administration Scripted administration Complex bulk administration tasks Reporting on the data in the data store The DPCLA consists of the following components: DPADMINCMD This is a command-line program that can be used interactively or called from within a batch file, script or other program. This provides a command shell based on the TCL interpreter. VASCO TCL Extension Library The main functionality is provided by the VASCO extensions to TCL. This provides a set of additional commands in a vasco namespace. The extension library is used by DPADMINCMD, which loads the namespace automatically. However, if you have your own TCL environment already, you can load the extension library directly into it, without having to use DPADMINCMD. In that case, you will need to use the namespace qualifier. Other scripting environments such as Python, Perl and VBScript also have modules available that enable them to use TCL, allowing the VASCO extensions to be used in a variety of environments. TCL Runtime The Identikey Server installation program also installs the TCL 8.4 runtime environment, which is necessary to run DPADMINCMD. Caution Windows command-line functions may be run from within the Digipass TCL Command-Line Administration. A new Windows command-line console may also be opened. Identikey Server Administrator Reference 240

241 Digipass TCL Command-Line Administration Knowledge Requirements Digipass TCL Command-Line Administration is an extension of the TCL 8.4 scripting language, and administrators will require a basic competence in TCL in order to use the command-line utility. However, for simple usage, no great knowledge of TCL is required. For an introduction to TCL, see Other pages on the web site may also provide useful background on TCL and its capabilities. For a more comprehensive tutorial, see (but note that we install version 8.4, so there may be minor differences in 8.5) Data Store Connection DPCLA makes a connection to the data store in a similar way to the Administration Web Interface. This connection requires an administrative login Configuration File. Digipass TCL Command-Line Administration requires a configuration file (dpacmincmd.xml file) to be present before it can run correctly. This file can be created by the Digipass TCL Command-Line Administration installation wizard, or created using a template. See 11.8Digipass TCL Command Line Utility for more details. Identikey Server Administrator Reference 241

242 Digipass TCL Command-Line Administration 16.2 Using DPADMINCMD Basics You can use TCL interactively with a command prompt or you can use it to run a script Using an Interactive TCL Command Prompt Using DPADMINCMD to open an interactive TCL command prompt can be done as follows: Windows 1. Open a Windows command prompt in the <install directory>\bin directory. 2. Enter the following command: Linux dpadmincmd 1. Enter the chroot environment: vds_chroot <install directory> /bin/bash 2. Enter the following command: dpadmincmd A command prompt will be opened, at which you can enter TCL commands. DPADMINCMD automatically loads the VASCO TCL extensions, so that they can be used without needing to specify the VASCO 'namespace'. Digipass TCL Command-Line Administration Version Copyright (C) VASCO Data Security Inc All rights reserved % Before any data administration commands will work, you need to perform an administrative logon to the Identikey Server. % logon {userid admin password password} 1 % If the logon is successful, the output indicates a session number. Otherwise, an error message will be displayed. Once there has been a successful logon, you can enter other commands, for example: % user query {userid admin} {domain master userid admin has_dp Unassigned status 0 created {2006/05/11 11:05:32} modified {2006/05/11 11:05:32}} % To log off, use the logoff command; to exit, use the exit command. Identikey Server Administrator Reference 242

243 Digipass TCL Command-Line Administration Running a Script Using DPADMINCMD to run a script requires an administration logon to be specified with command-line parameters, unless the script itself contains a logon command. For a logon requiring credentials, the -u (userid) and -p (password) parameters are required. 1. If using Windows, open a command prompt in the <install directory>\bin directory. If using Linux, enter the chroot environment: vds_chroot <install directory> /bin/bash 2. Enter the following command for an implicit logon and press Enter: dpadmincmd -i scriptname 3. Or, enter the following command for an explicit logon and press Enter: dpadmincmd -u userid -p password scriptname The scriptname parameter can be a file name or path and file name. If your script requires parameters, enter these after the scriptname. Example dpadmincmd -i myscript.tcl param1 param2 The script file must contain a sequence of TCL commands. DPADMINCMD will first perform the logon, and if successful, will execute each command in the script in sequence. The TCL language allows you to write simple sequential scripts or add more complex control flow, functions and so on. The script does not need to use the logoff or exit commands explicitly. DPADMINCMD will logoff the session if necessary at exit time. Character Substitution When using a non-printing ASCII character substitution (eg. \t for a horizontal tab) in a string, enclose the string in double quotes. If the string is enclosed in { }, the string will be displayed exactly as entered. eg. Error: \t Component does not exist. \n \t \t Please check the Component name. will be displayed as: Error: Component does not exist. Please check the Component name. Whereas {Error: \t Component does not exist. \n \t \t Please check the Component name.} will be displayed as: Error: \t Component does not exist. \n \t \t Please check the Component name. Identikey Server Administrator Reference 243

244 Digipass TCL Command-Line Administration Help To access help from the command prompt, use these commands: Table 71: DPADMINCMD Help Commands Command help help <command> help <command> <subcommand> Notes Provides basic information about DPADMINCMD, including a list of all commands available. Provides information about the specific command, including required parameters, optional parameters and available subcommands. Provides information about the specific subcommand, including required and optional parameters Command Parameters Some notes on command parameters in TCL: Parameters are given in list form: {field1 value1 field2 value2...} Parameter values that include whitespace require double quotes or { }, for example {field1 value 1 field2 {value 2}...} Commands may be substituted for parameters using square brackets, where the command will return the type of parameter(s) required. eg. foreach i [user query {domain master} {domain userid has_dp}] { puts $i } In this example, a query returns a list of Users with Digipass assigned, which is used in the foreach command Result Output Results are typically returned in list form, with pairs of field names and values, eg: {domain master userid user0001 has_dp Assigned} Some commands do not return field information, only a simple message, eg: Created Component. Queries return a list of list results, with only the requested fields displayed. These may be formatted for better readability by wrapping the query in another command, eg: foreach i [user query {domain master} {domain userid has_dp}] { puts $i } The result from the example above will display each user record in the master domain on a separate line, and only display the requested fields (domain, userid and has_dp), eg: domain master userid admin has_dp Assigned domain master userid user0001 has_dp Unassigned Identikey Server Administrator Reference 244

245 Digipass TCL Command-Line Administration Error Handling When an error occurs in a VASCO TCL Extension command, information about the error will be written to the standard TCL error variables. This allows error handling in scripts, and allows a user to obtain information about the last error received when using an interactive command line. For example, if this command was entered: % user get {userid doesnotexist} and a User with the ID of doesnotexist could not be found, then this error would be returned: Error code: <-13> Error message: <The object specified was not found.> Information about that error could be retrieved from standard TCL error variables using these commands: Returns: And -13 Returns: % puts $errorcode % puts $errorinfo Error code: <-13> Error message: <The object specified was not found.> while executing "user get {userid doesnotexist} International Characters DPADMINCMD supports international characters, but your console window must be able to support the characters or they will not display correctly. The Lucida Console font is typically used Syntax Notes The following points should be remembered for basic interactive and scripted usage: Result values that include whitespace, including date/time values, are given { } by TCL Comments in scripts are preceded with a # A backslash character at the end of a line indicates that the command is continued on the next line. Identikey Server Administrator Reference 245

246 Digipass TCL Command-Line Administration Sample Scripts Below are some sample scripts which perform basic tasks. They range in complexity to provide an example of what can be done, and the techniques required. Check if a Component Record exists This script checks for the existence of a RADIUS Client Component record with a specific IP address. If a Component record of that type and location does not exist, a message will be displayed onscreen. # Check if a specified RADIUS Client Component exists if [catch {component get {comp_type "RADIUS Client" location }} result] { puts "Component does not exist: $result" } Create a Record if it doesn't exist This script builds on the previous sample to check for the existence of a RADIUS Client Component record and, if one does not currently exist, to create one. It requires a location parameter to be passed to the script when it is run from DPADMINCMD. # Get IP-address location from command-line argument set loc [lindex $argv 0] # Create the component if it does not exist if [catch "component get {comp_type {RADIUS Client} location $loc}" result] { if [catch "component create {comp_type {RADIUS Client} \ location $loc \ policy_id {Identikey Server 3 Local Authentication} \ shared_secret default \ protocol RADIUS}" result] { puts "Error creating component: $result" } else { puts "Created component" } } else { puts "Component already exists" } To run this script from DPADMINCMD, you would need to use the following syntax: dpadmincmd -i scriptname loc Bulk User Administration This script collects all Digipass User records belonging to the domain named Domain1 and unlocks any which were locked. # Get all the users of the domain Domain1 if [catch {user query {domain Domain1}} users] { Identikey Server Administrator Reference 246

247 Digipass TCL Command-Line Administration puts "Unable to retrieve users: $users" } else { # Loop for each user foreach user $users { # Get the user information into an array for easier access array set userinfo $user # Check if the locked information is present as it may not return a # value is the user is not locked if [info exists userinfo(locked)] { # If the user is locked, try to unlock it if [string equal $userinfo(locked) yes] { if [catch "user update {userid $userinfo(userid) domain Domain1 locked no}" result] { puts "Error unlocking $userinfo(userid): $result" } else { puts "Unlocked $userinfo(userid)" } } } } } # Clear-out the current user information array set userinfo [list] Identikey Server Administrator Reference 247

248 Replication 17 Replication 17.1 Concepts Replication can be configured to allow multiple Identikey Servers to keep their data synchronized. Active Directory Active Directory has its own replication, which will replicate data between Domain Controllers. In some circumstances, however, Active Directory replication can be slow enough to cause problems in Identikey Server authentications. Due to these problems, each Identikey Server using Active Directory as its data store has a Digipass Cache. Digipass records used in recent authentication requests are kept in the cache for a set amount of time, and checked against Active Directory records. See 2.4 Active Directory Replication Issues for more information on the Digipass Cache. Where Identikey Servers use Active Directory as their data store, this Digipass Cache can be replicated between Identikey Servers. This ensures that authentication data is as up-to-date as possible. Identikey Server Administrator Reference 248

249 Replication ODBC Databases Where multiple Identikey Servers use different ODBC databases as their data stores, replication ensures that each database is up to date with the latest data changes Replication Queue The replication queue for each Identikey Server which is configured as a replication destination is written to two files a data and an index file in <install directory>\repldata. The files are named using the destination Identikey Server name. Check the Identikey Server Configuration for the destination server to check the configured name Record-level Replication The replication method used by Identikey Server involves replication of entire records, rather than individual record attributes. This means that data clashes can occur when a single record is updated at the same time from different sources. If this occurs, the later change will be the one chosen and written to the database. Superseded changes are ignored. Identikey Server Administrator Reference 249