- Updated on 01 Oct 2024
- 9 Minutes to read
Print
Share
Dark
Light
PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Authenticator records can be manually imported from Authentication Server Framework to OneSpan Authentication Server using a DIGIPASS import file, i.e. a comma-separated text file (.csv).
For more information about the various migration paths, see Available migration paths for Data Migration Tool (DMT).
To import authenticator records from a DIGIPASS import file
Install the destination OneSpan Authentication Server instance.
Export the authenticator records from the Authentication Server Framework database to a DIGIPASS import file and prepare it accordingly (see DIGIPASS import file format).
Create the domain and organizational unit structure using OneSpan Authentication Server Administration Web Interface.
For more detailed information, refer to the OneSpan Authentication ServerAdministrator Guide.
Import the authenticator records and import/create the user accounts.
Import the authenticator records from the DIGIPASS import file previously created, using Data Migration Tool (DMT).
Create user records either manually or automatically in bulk using a user import file with OneSpan Authentication Server Administration Web Interface.
Assign the authenticators to user accounts either manually or automatically when creating them from a user import file with OneSpan Authentication Server Administration Web Interface.
You can do either:
Import the authenticator records from the DIGIPASS import file first, then import the user records from a user import file and automatically assign the users to the existing authenticators (by specifying the serial numbers in the user import file).
Import the user records from a user import file first, then import the authenticator records from the DIGIPASS import file and automatically assign the authenticators to the existing users (by specifying the user ids and domains in the DIGIPASS import file).
Create or import the user records and authenticator records separately (without referring from one to the other), then assign the authenticators to the users manually.
It's usually less error-prone to import or create the user accounts first and to import and assign the authenticator records afterward.
For more information about using user import files, refer to the OneSpan Authentication ServerAdministrator Guide, Section "Format of User Import File".
Prepare a DIGIPASS import file with custom keys
If you import from a DIGIPASS import file that has been encrypted with a custom key, you will have to use that same custom key in Data Migration Tool during the data migration process (see Prepare migration from a DIGIPASS import file (Authentication Server Framework)).
DIGIPASS import file format
Authenticator records must be imported from a comma-separated text file. The exact file format depends on whether the file contains regular authenticator records (see DIGIPASS import file contents (standard licensing)) or multi-device licensing (MDL) authenticator records (see DIGIPASS import file contents (multi-device licensing (MDL)).
DIGIPASS import file contents (standard licensing) | |||
Column Name | Data type | Required | Description |
|---|---|---|---|
Blob | Text (exactly 248 chars) | Yes | Encrypted data block that contains important parameter settings and secrets for an authenticator application. |
StaticVectorEx | Text (up to 4096 characters) | Yes | Specific to software authenticators. It is used to generate an encrypted authenticator secret (activation code) This is only present for new software authenticator parameters. |
ActivationCount | Unsigned number | No | Specific to software authenticators. This is directly connected to ActivationLocations. |
ActivationLocations | Text (up to 1024 characters) | No | Specific to software authenticators. This field will be stored in the vdsDPApplication table in the vdsActivLocs column. It specifies the client locations where the authenticator has been activated from via provisioning register commands (as space-separated hash values). This is directly connected to ActivationCount. |
Active | Boolean | No | Flags whether the authenticator application should be imported as active. If set to 0 (inactive), the authenticator application will be deactivated on import. Possible values:
Default value: 1 |
BackupVDPEnabled | Text | No | States whether backup Virtual Mobile Authenticator functionality is enabled for this authenticator. Possible values:
The value must exactly conform to one of the above examples. |
BackupVDPExpires | Date | No | Used with Yes - Time Limited option above. Expected format 'YYYY/MM/DD' |
BackupVDPUsesLeft | Unsigned number | No | Used with Yes - Permitted option above. |
Description | Text (up to 255 characters) | No | Descriptive text for the authenticator. May not contain any of the following characters: /\:;,|'"<>[]&@=+*?# |
DirectAssignOnly | Boolean | No | Flags the authenticator as unavailable for auto-assignment and bulk assignment processes. Possible values:
Default value: 0 |
Domain | Text | No | The domain to import the authenticator to. The domain must already exist. If UserID is specified, the respective user account must exist in the domain. Default value: master |
MessageVector | Text (26 characters) | No | The message vector is a string containing configuration settings for the message generation. This field is extracted during the initial DPX import process to the Authentication Server Framework database. This field is applicable (and required) for specific, pre-provisioned hardware authenticators with Secure Channel capabilities only! |
Number | Number | No | This field defines the application index number and will be stored in the vdsDPApplication table in the vdsApplNo column. It’s used for audit and trace messages and as reference when an operation was using a specific authenticator application. If defined in the DIGIPASS import file, this number should be unique across the applications for a particular authenticator. It is recommended to order the authenticator applications always in the same way, e.g. as they are defined in the static vector. Usually, the application order should be the same across authenticators of the same initial configuration (DPX). If this field is not supplied, DMT will automatically generate it based on the order of the authenticator applications found in the DIGIPASS import file. |
OrganizationalUnit | Text | No | The organizational unit to import the authenticator to. The organizational unit must already exist. The organizational unit name is sufficient. '//' should only be used to designate an organizational unit path, not included as part of an OU name. If the authenticator is assigned to a user in a different organizational unit, the authenticator record will be moved to the user's organizational unit. Default value: <empty> |
PayloadKeyBlob | Text (up to 256 characters) | No | Payload keys to protect the confidentiality and authenticity of the payload of a message. It is shared by the authenticator license and authenticator instance, it is however, defined separately for each one in the DIGIPASS import file. This field is applicable (and required) for specific, pre-provisioned hardware authenticators with Secure Channel capabilities only! |
UserID | Text | No | The user ID the authenticator is assigned to. Only required, if the authenticator is assigned. |
DIGIPASS import file contents (multi-device licensing (MDL)) | |||
Column Name | Data type | Required | Description |
|---|---|---|---|
Blob | Text (exactly 248 characters) | Yes | Encrypted data block that contains important parameter settings and secrets for an authenticator application. |
MessageVector | Text (26 characters) | Yes | The message vector is a string containing configuration settings for the message generation, including the activation process and the optional Secure Channel process. This field is extracted during the initial DPX import process to the Authentication Server Framework database. It is applicable for the following authenticator categories:
|
PayloadKeyBlob | Text (up to 256 characters) | Yes | Payload keys to protect the confidentiality and authenticity of the payload of a message. It is shared by the authenticator license and authenticator instance, it is however, defined separately for each one in the DIGIPASS import file. |
ProvisioningActivationCount | Number | Yes | The number of activations made by provisioning commands, meaning activations usually performed by the users themselves. If the exact number is unknown, set this value to 0. |
StaticVectorEx | Text (up to 4096 characters) | Yes | Specific to software authenticators. It is used to generate an encrypted authenticator secret (activation code) This is only present for new software authenticator parameters. |
SequenceNumberThreshold | Unsigned Number (1–99) | Only for authenticator license | Maximum number of authenticator instances that can be activated with the authenticator license. By design it is not possible to create more than 99 instances of a license. This field is mandatory for the authenticator license, for authenticator instances the value will be NULL. This value is configured by OneSpan at the time of order and extracted during the initial DPX import process to the Authentication Server Framework database. |
Activation vector | Text (up to 1024 characters) | No | A data string containing license-specific encrypted activation data necessary for the activation process. This field is extracted during the initial DPX import process to the Authentication Server Framework database. |
ActivationChallenge | Text (16 characters) | No | The challenge (numeric or hexadecimal) initially used to generate the Activation Message 1.The same challenge is used to validate the device code. If no challenge was initially used, this field can be omitted. If the activation challenge is required, but missing, subsequent activations of authenticator instances will fail! |
ActivationCount | Number | No | The number of activations made either by administration or provisioning commands. Applies to authentication licenses only. Is also encoded in the BLOB and cannot be reset (only during new activations). |
Active | Boolean | No | Flags whether the authenticator application should be imported as active. If set to 0 (inactive), the authenticator application will be deactivated on import. Possible values:
Default value: 1 |
Description | Text (up to 255 characters) | No | Descriptive text for the authenticator. May not contain any of the following characters: /\:;,|'"<>[]&@=+*?# |
DirectAssignOnly | Boolean | No | Flags the authenticator as unavailable for auto-assignment and bulk assignment processes. Possible values:
Default value: 0 |
Domain | Text | No | The domain to import the authenticator to. The domain must already exist. If UserID is specified, the respective user account must exist in the domain. Default value: master |
LastActivationTime | DateTime | No | This field is required when the authenticator license is assigned and activated. It is required to prevent reactivation. If it is not required, the field is left blank. This is set by provisioning commands and reset by certain administration commands, i.e. Delete User, Unassign Digipass, and Reset Activation. Expected format 'YYYY/MM/DD HH:MM:SS'. |
Number | Number | No | This field defines the application index number and will be stored in the vdsDPApplication table in the vdsApplNo column. It’s used for audit and trace messages and as reference when an operation was using a specific authenticator application. If defined in the DIGIPASS import file, this number should be unique across the applications for a particular authenticator. It is recommended to order the authenticator applications always in the same way, e.g. as they are defined in the static vector. Usually, the application order should be the same across authenticators of the same initial configuration (DPX). If this field is not supplied, DMT will automatically generate it based on the order of the authenticator applications found in the DIGIPASS import file. |
OrganizationalUnit | Text | No | The organizational unit to import the authenticator to. The organizational unit must already exist. The organizational unit name is sufficient. '//' should only be used to designate an organizational unit path, not included as part of an OU name. If the authenticator is assigned to a user in a different organizational unit, the authenticator record will be moved to the user's organizational unit. Default value: <empty> |
UserID | Text | No | The user ID the authenticator is assigned to. Only required, if the authenticator is assigned. |
For more information about individual fields, refer to the Authentication Server FrameworkProduct Guide.
For more information about the actual migration process, see Migrate data.
DIGIPASS import file migration restrictions
Several restrictions apply for the import of authenticator records via a DIGIPASS import file:
One authenticator application per line. If an authenticator has more than one authenticator application, it will take up multiple lines in the import file.
Headings should be included at the top of the file, using the exact field names provided in the table above.
Commas should not be added to any field, as this will be interpreted as the end of the data for that field and the beginning of data for the next field.
When migrating from Authentication Server Framework-based installations to OneSpan Authentication Server, multi-device licensing (MDL) authenticators can be migrated.
Only fully activated authenticator instances can be migrated.
Temporary data used for activation is not migrated and will be lost.
DIGIPASS import file examples
The Data Migration Tool setup includes working DIGIPASS import file samples for reference. You can find the sample files in the following folder:
%PROGRAMFILES%\VASCO\Data Migration Tool 3.26\samples (Windows)
/opt/vasco/dmt/samples (Linux)
Was this article helpful?
What's Next
- Prepare the Destination System
