Post-upgrade tasks and considerations

Correcting mismatching SQL string types (Oracle Database)

When you upgrade OneSpan Authentication Server, it is often necessary to update the database schema. This is either done explicitly via the dpdbadmin command-line utility if you update your database manually, or automatically by the Configuration Wizard (which implicitly uses dpdbadmin).

The dpdbadmin addschema and dpdbadmin checkschema commands automatically verify the SQL string types of the existing database columns to determine the data type used for SQL string binding. For Oracle Database, this is either VARCHAR2 or NVARCHAR2.

The dpdbadmin addschema command stores this information in the vdsControl table in the database. The OneSpan Authentication Server service reads that information when it starts:

vdsControl.vdsName = string_type

vdsControl.vdsValue = char if the column type is VARCHAR2, wchar if the column type is NVARCHAR2

In some environments, the database column types may be mixed, meaning that some columns use VARCHAR2 and some use NVARCHAR2. This can occur due to historical changes and previous upgrades, for instance if you changed NLS_CHARACTERSET to AL32UTF8 before an upgrade of OneSpan Authentication Server.

If dpdbadmin detects such mixed column types, it will issue a warning, and string_type is not set in the vdsControl table. To prevent performance issues due to different string type binding, we highly recommend to change the type of all string columns to the suggested default type.

To correct mixed column types

  1. Determine the default type as suggested in the warning that is issued by the dpdbadmin command.

  2. Verify and change the data type of the affected string/varchar columns using a database management application, e.g. Oracle SQL Developer.

    For a complete reference of the ODBC database scheme, refer to the OneSpan Authentication Server Administrator Reference.

  3. Run the dpdbadmin addschema command again.

    This will ensure that the database schema update is complete and string_type is correctly set in the vdsControl table.

Once the value for string_type is correctly set in the vdsControl table, it will not be updated or modified again by later executions of dpdbadmin.

Migrating server data

Upgrading OneSpan Authentication Serverwill most likely involve a database schema update. Therefore, as soon as the server has been upgraded, server data from the previous installation such as authenticator and user data needs to be migrated to match the new schema.

To ensure that authentication services remain available at all times, data is migrated using two complementary mechanisms:

  • On-the-fly data migration

    On-the-fly data migration means that data is migrated on demand whenever OneSpan Authentication Server receives a request (e.g. an authentication request) and accesses server data records. Only data records required to process the request are migrated, whereas data records which are newly created or have already been migrated will not be processed (a second time).

    On-the-fly data migration is only triggered upon updating or reading a data record; it is not initiated by queries (listing several data records).

  • Task-based data migration

    In addition, to systematically migrate all server data from the old installation, you need to start or schedule a data migration task using the Administration Web Interface. The data migration task runs in the background and migrates all database records one-by-one to the new schema, except for server data which has already been migrated.

    In environments with multiple OneSpan Authentication Server instances, the data migration task can run on only one OneSpan Authentication Server instance. The migrated server data is then replicated to all other databases that are used.

    As with other tasks in the Administration Web Interface, you can schedule, run, and disable the task to fit your user load and performance requirements.

Each server data record is migrated only once, either on-the-fly or by the data migration task.

When upgrading multiple OneSpan Authentication Server instances, the data migration task must be run after ALL server instances have been upgraded.

When upgrading multiple OneSpan Authentication Server instances configured to replicate data changes between them, the data migration task must be run after ALL server instances have been upgraded and when replication between all instances is enabled again.

Starting the data migration task before all server instances have been upgraded will result in a failure of the Installation Wizard with an "Invalid upgrade path found" error message when attempting to upgrade remaining server instances afterward!

To start a data migration task

  1. Log on to the Administration Web Interface.

  2. Do one of the following:

    • Navigate to SERVERS > Migrate Data.

      The Migrate Data menu item will be available only if data migration is required.

    • In the Home tab, in the OneSpan Authentication Server status section, click Migrate Data.

      The data migration task status will be displayed only if a data migration task is running or ready to be scheduled after an OneSpan Authentication Server upgrade, and if you have the View Task administrative privilege.

    The Migrate Data - Schedule Task page is displayed.

  3. Specify if and how you want to be notified upon task completion.

    Possible options are None, Email, and SMS.

  4. Specify if you want to schedule the task:

    • Select No if you want to run the task immediately.
    • Select Yes if you want to schedule the task to run at a later time.

    The task will run in the background.

  5. If you want to schedule the task, define the time and date on which you wish to run the task.

  6. Click MIGRATE.

    The Migrate Data - Summary page is displayed.

  7. Click FINISH to create the task.

You can view the progress of the data migration task in the task list of the Administration Web Interface.

Setting the audit indexing level

When upgrading OneSpan Authentication Server, indexing levels for the vdsAuditMsg table are not modified. If you intend to work with the User Dashboard, view recent user and authenticator activity, and use reporting, we recommend that you set the level of indexing for the vdsAuditMsg table to 1, to enhance authentication and audit/report performance. To do so, use the ODBC Database Command-Line Utility (dpdbadmin).

For more information about the different levels of indexing and instructions to set the level, refer to the OneSpan Authentication Server Administrator Guide and the OneSpan Authentication Server Administrator Reference. For further indexing recommendations, e.g. for high-availability deployment models, refer to the OneSpan Authentication Server Performance and Deployment Guide.

Adapting MariaDB settings

If upgrading OneSpan Authentication Server involves an upgrade of the embedded MariaDB database server, custom database settings from the previous installation will not be transferred to the upgraded database. Therefore, after an upgrade of MariaDB, always verify the database settings in my.ini, located in %PROGRAMFILES%\VASCO\MariaDB10.11\data, and adapt the settings as needed.