Pre-upgrade tasks and considerations

This topic will help you make pre-upgrade decisions and complete any required pre-upgrade tasks.

General considerations

During any upgrade, schema changes will be required. Ensure that appropriate planning and precautions have taken place before upgrading. In particular, ensure that you have:

  • Permission to perform a schema change.
  • The latest backups of the data store and configuration files.
  • Interrupted replication on the OneSpan Authentication Serverinstance to be upgraded.
  • Interrupted replication on any OneSpan Authentication Server instances which replicate TO the instance to be upgraded.
  • Successfully completed any previous upgrade, including data migration.

Before initializing the upgrade process, ensure that you have successfully completed any previous upgrade and migrated all data. If the data migration has not been successfully completed, the upgrade installation process will be canceled, and the following error message will be displayed: "The installation procedure has been canceled - data migration from the previous upgrade has not been completed. Please finish migrating the data from the previous to the currently installed version of OneSpan Authentication Server before proceeding with this upgrade!"

Once the upgrade starts, it cannot be rolled back. In addition, the upgrade script only supports upgrades from completely installed and completely configured instances of OneSpan Authentication Server.

Ensure that your data store and configuration files are backed up before starting the upgrade process.

Licenses for a previous version of OneSpan Authentication Server will be valid for this release. Therefore, you can upgrade without loading a new license key.

Verifying system requirements

Ensure that your host machine complies with the system requirements for this release of OneSpan Authentication Server (see System requirements).

Database setup

Upgrading OneSpan Authentication Server may change the database location and require new certificates to be generated.

Database location

When upgrading an instance of OneSpan Authentication Server that uses the embedded MariaDB database server, the database will be installed in %PROGRAMFILES%\VASCO\MariaDB10.11. The data contained in the database will be stored in vasco_dir\MariaDB\.

Certificate handling

When upgrading an instance of OneSpan Authentication Server that uses the embedded MariaDB database server with database encryption enabled, the data-at-rest encryption key will not be deleted and will still be used after the upgrade.

However, you may need to generate new certificate files during product upgrade. This is the case if you are using certificates generated via the Configuration Wizard during or after OneSpan Authentication Server installation. If you are using commercial certificates, you can continue to use them after the OneSpan Authentication Server upgrade.

With self-signed certificates, ensure that the CA and the server/client certificates have different values for the Common Name (CN) field.

You will be prompted to specify whether to overwrite existing certificate files in the course of the upgrade process.

Replication and upgrades

If the OneSpan Authentication Server instance to be upgraded has replication enabled, you will need to break replication both to and from that instance before upgrading.

It is recommended that you break the replication at the network level using the system firewall.

Do not disable the replication on the servers. Do not remove the replication configuration from the server. Otherwise, replication messages are omitted, leaving the server databases not synchronized and in different states!

Global server settings

In environments where OneSpan Authentication Server uses ODBC as data store, the global server settings are stored in the database with a creation time, i.e. the date and time of the installation. If a new version of OneSpan Authentication Server introduces new global server settings, the new settings are also stored with a creation time, in this case the date and time of the upgrade.

Replication requires fully synchronous databases, i.e. records need to have the same creation time; even the same records will not be replicated if their creation time differs!

If the OneSpan Authentication Server instance is part of a replication environment where each instance has its own ODBC database, the newly created global server settings will have different creation times set on each instance, since you will update each instance at different times. This means that global server settings introduced with a new version will NOT be replicated in the future if their creation time differs on each OneSpan Authentication Server instance.

For instance, OneSpan Authentication Server 3.8 introduces Message Delivery Component (MDC) message settings as global server settings:

  • If you upgrade an existing single installation, the current message settings are migrated from the local server configuration file to the global server settings in the database.
  • If you upgrade several OneSpan Authentication Server instances within a replicated environment where each instance has its own ODBC database, each instance migrates its own message settings to its global server settings without replicating it to the other instances during the upgrade; this means that the global configuration settings of each instance may differ from each other after an upgrade.
  • If you upgrade several OneSpan Authentication Server instances within a replicated environment where all instances use the same ODBC database, only the MDC message settings from the first instance are migrated to the global server settings and are not overwritten when upgrading the other instances.

For more information about replication, refer to the OneSpan Authentication Server Administrator Guide, Section "Replication".

Rolling upgrades

A rolling upgrade involves upgrading multiple OneSpan Authentication Server instances while keeping the authentication service alive. Environments that require a rolling upgrade typically support high-availability services, where the authentication service absolutely cannot be taken offline.

An environment that requires a rolling upgrade typically has the following characteristics:

  • There are multiple instances of OneSpan Authentication Server running on multiple servers.
  • All OneSpan Authentication Server instances either use the same database as their data store, or each one instance has its own data store.
  • The OneSpan Authentication Server upgrades involved will require a database schema update.
  • User load distribution between all OneSpan Authentication Server instances is managed by a third-party application.

Rolling upgrades are only supported for deployments where each OneSpan Authentication Server instance uses an ODBC data store.

Before proceeding with a rolling upgrade, you must first address the different usability and load management issues involved. For more information, refer to the OneSpan Authentication Server Administrator Guide.

Upgrading a OneSpan Authentication Server instance that does not use the Local System account

By default, OneSpan Authentication Server 3.26 runs under the Local System account instead of a domain user account to comply with Active Directory security best practices.

When performing an upgrade using the OneSpan Authentication Server Setup Utility, the VASCO IDENTIKEY Authentication Server service will automatically be configured to run as the Local System account. This is done regardless of whether the previous version was configured to run as an Active Directory user with elevated rights (i.e. domain administrators or domain users with Active Directory administrative privileges).

This means that when an OneSpan Authentication Server instance is (a) installed on a member server and (b) configured to run as an Active Directory user with elevated rights, then an upgrade to OneSpan Authentication Server 3.26 will configure the instance to run as the Local System account.

This will, effectively, downgrade the security level of the instance, thereby preventing it from authenticating any Active Directory users with elevated rights. This is because such users have higher privileges than Local System accounts on member servers. In addition, any Active Directory user with elevated rights that could access the Administration Web Interface before the upgrade will no longer be able to.

To allow OneSpan Authentication Server to authenticate domain administrators or domain users with administrator privileges after such an upgrade, you will need to explicitly re-configure OneSpan Authentication Server 3.26 to run as an Active Directory user with elevated rights.

Note that the service user account is not configured if you apply a patch (i.e. OneSpan Authentication Server with a 3-digit version number, e.g. 3.x.1), hence you do not need to explicitly re-configure it in such a case.

For more information, refer to the OneSpan Authentication Server Administrator Guide, Section "Permissions required by administrators".

RADIUS backup

If you modified the RADIUS dictionary, you will need to back up the RADIUS dictionary file (radius.dct) before upgrading OneSpan Authentication Server. To do so, copy the file to a different location and return it after completing the upgrade. This file is typically located (and should be restored) here:

install_dir\bin

where install_dir is the installation directory of OneSpan Authentication Server (typically %PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server).