3.3 Database Schema
3.3.1 vdsControl Table
Table 12: vdsControl Table
Name Type Required?
vdsName varchar(64) Yes
vdsValue varchar(512)
vdsFlags integer
Primary Key: (vdsName) Foreign Keys: None
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)
vdsEmail 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
3.3.3 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)
3.3.4 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
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
3.3.5 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
3.3.6 vdsDPSoftParams Table
Table 17: vdsDPSoftParams Table
Name Type Required?
vdsDPSoftParamsID varchar(64) Yes
vdsSVFileName varchar(64) Yes
vdsStaticVector varchar(1024) Yes
Name Type Required?
vdsCreateTime timestamp Yes
vdsModifyTime timestamp Yes
Primary Key: (vdsDPSoftParamsID) Foreign Keys: None
3.3.7 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
vdsChgPinAllowed integer
vdsSelfAssignSep varchar(8)
Primary Key: (vdsPolicyId) Foreign Keys:
(vdsParentPolicyId) references vdsPolicy
3.3.8 vdsComponent Table
Table 19: vdsComponent Table
Name Type Required?
vdsComponentType varchar(60) Yes
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
3.3.9 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
vdsAuthPortSSL 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)
vdsCreateTime Timestamp Yes
vdsModifyTime Timestamp Yes
* This column contains binary data stored in base64-encoded format.
Primary Key: (vdsServerId) Foreign Keys: None
3.3.10 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
3.3.11 vdsOrgUnit Table
Table 22: vdsOrgUnit Table
Name Type Required?
vdsDomain varchar(255) Yes
vdsOrgUnit varchar(255) Yes
Name Type Required?
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
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
3.3.13 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.
Primary Key: (vdsDomain, vdsReportID, vdsFmtName) Foreign Keys:
(vdsDomain, vdsReportID) references vdsReport
3.3.14 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
3.3.15 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
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 re-created.
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 3.5.1.1 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.
3.5.1 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.
3.5.1.1 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 11.3.7.4 Advanced Configuration Settings.
3.5.1.2 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, [email protected], 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 the @domain part removed. Otherwise, the whole UserId will remain as userid@domain and no Domain will be identified.
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.
3.5.2 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.
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.
3.6.1 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
3.6.2 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.
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.
3.6.2.1 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 vdsName
vdsUser user_table
vdsUserAttr user_attr_table
vdsDigipass dp_table
vdsDPApplication dpappl_table
vdsDPSoftParams dpsoft_params_table
vdsPolicy policy_table
vdsComponent comp_table
vdsBackEnd backend_table
vdsDomain domain_table
vdsOrgUnit org_table
vdsReport report_table
vdsReportFormat report_format_table
vdsConfiguration configuration_table
VdsOfflineAuthData offlineauthdata_table
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.
3.7.1 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.
3.7.2 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.
3.7.3 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.
3.7.4 Idle Timeout
After a period of peak load, there may be a large number of connections open to the database. The Idle Timeout
After a period of peak load, there may be a large number of connections open to the database. The Idle Timeout