Upgrading OneSpan Authentication Server and migrating server data

The upgrade mechanism of OneSpan Authentication Server ensures that you can upgrade to the most recent OneSpan Authentication Server version with minimum server downtime and minimum impact on the availability of your authentication services.

During a rolling upgrade, i.e. when upgrading multiple OneSpan Authentication Server instances in environments where authentication services can absolutely not be taken offline, authentication services remain available throughout the upgrade process. For more information about rolling upgrade and the various scenarios, refer to the OneSpan Authentication Server Administrator Guide.

The upgrade process involves the following steps:

  1. Upgrading OneSpan Authentication Server software.
  2. Updating static server configuration.
  3. (OPTIONAL) Migrating from software security module (SSM) to hardware security module (HSM).
  4. Migrating server data.

While steps 1 to 3 require individual servers to be down, authentication services are available during server data migration in step 4, and are also available on other server instances during a rolling upgrade.

Upgrading OneSpan Authentication Server software and updating static server configuration

During OneSpan Authentication Server software upgrade and static configuration update, the installed product components and all static server settings are updated. At this point, authentication requests cannot be processed on the server instance that is being upgraded.

OneSpan Authentication Server data stored in the storage subsystem, such as authenticator or user data, will be migrated in a separate step, to avoid prolonged server downtime. For more information, see Migrating server data.

Migrating from software security module (SSM) to hardware security module (HSM)

When configuring OneSpan Authentication Server in the course of an upgrade, if an SSM is configured for this OneSpan Authentication Server instance and if the data storage used is an ODBC database, you can migrate to a hardware security module (HSM).

The migration from an SSM to an HSM deployment cannot be reverted. Migrating back to an SSM deployment is not possible.

For more information about the HSM migration process, see HSM migration. For instructions to migrate to an HSM and information about supported HSM models, refer to the OneSpan Authentication Server Installation Guide for Windows or the OneSpan Authentication Server Installation Guide for Linux.

Migrating server data

Upgrading OneSpan Authentication Server will 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.

Server data is continuously migrated while the already-upgraded OneSpan Authentication Server is running. This means that the data store contains both migrated and non-migrated data until data migration has been completed.

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 that 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.

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

If a data record cannot be migrated for any reason, it will be specially marked. Such marked data records will be blocked and cannot be accessed regularly anymore, but only queried and deleted. To use such blocked data records again, you need to manually inspect and recover them.

Considerations for migrating server data

Data migration and server performance

  • Running the data migration task may impact OneSpan Authentication Server performance. Therefore, we recommend that you schedule the task according to your user load and performance requirements. You can monitor the task progress in the task list of the Administration Web Interface.

  • In version 3.22 and earlier, the data schema version applied to the whole database. As of OneSpan Authentication Server 3.23, the data schema version is tracked for each database table individually. This means that the data schema version for a particular table is not changed, unless there are effective changes in the table data schema. This reduces the amount of processed data and speeds up the server data migration process.

  • The data migration task migrates admin-related tables first to minimize overhead on administrative commands while server data migration is still in progress. On the other hand, tables that usually contain large amount of data are migrated last, e.g. users, authenticators, and authenticator applications.

Data migration and replication

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

    • For OneSpan Authentication Server environments with several servers and replication on OneSpan Authentication Server level, the data migration tasks have to be run on every other server after the first server has successfully completed the data migration task. Once replication is complete on the first server it is run on all other existing instances of OneSpan Authentication Server.
    • For OneSpan Authentication Server environments with replication on database level (like for instance mirroring), the first instance of OneSpan Authentication Server processes the entire data migration. For all other instances the OneSpan Authentication Server service must be restarted once the data migration task has been completed on the first instance, i.e. the instance where the data migration task was started.

  • To avoid replication queue issues when upgrading multiple OneSpan Authentication Server instances, the data migration task needs to run after all server instances have been upgraded, and when replication between all instances is enabled again. This applies to environments where the OneSpan Authentication Server instances are configured to replicate data changes between them.

    For more information about replication, see Replication with ODBC.

Miscellaneous

  • While server data migration is still in progress, the result of a query command may be incomplete and may include not-yet migrated data.

  • While server data migration is still in progress, you cannot switch OneSpan Authentication Server to migration mode (and use it with Data Migration Tool (DMT)).

  • If a restart of the OneSpan Authentication Server service is required while the data migration task is in progress, the task will automatically resume when the service is available again.

For more information about data migration after a rolling upgrade, refer to the OneSpan Authentication Server Administrator Guide. For instructions to create and schedule a data migration task, refer to the OneSpan Authentication Server Installation Guide for Windows or the OneSpan Authentication Server Installation Guide for Linux.