Upgrade from older versions

General

Hazelcast

Hazelcast is used internally for storing both the configuration and active user sessions, both when running standalone and in a cluster. The configuration for this is stored inside the file classes/cluster.xml. This file is not modified during an upgrade, however, the file classes/cluster_template.xml is overwritten on each upgrade. The file classes/cluster.xml might require some modifications after an upgrade if Hazelcast has been upgraded, otherwise some warnings might be written to the log during startup. After an upgrade, the relevant modifications can be copied from the file classes/cluster_template.xml.

To 5.1.3 and above

To use the new authentication frontend introduced in PAS 5.1.3, you may need to whitelist an additional URL if you are using a reverse proxy. The web app will fetch scripts, icons and more from /web-app, so that path must be whitelisted for the app to load.

Starting with version 5.1.3, with introduces FIDO2 Passkeys, and additional column needs to be added to the tokens table in external databases.

You may achieve this by running the following SQL scripts:

ALTER TABLE tokens ADD userHandle varchar(255);

CREATE INDEX tokens_userHandle ON tokens (userHandle);

To 5.1.2 and above

Starting with version 5.1.2, which introduces BankID Risk indication, an additional column needs to be added to the event table in external databases.

You may achieve this by running the following SQL script:

ALTER TABLE event ADD riskLevel varchar(255);

To 5.1

Starting with version 5.1, a new authenticator architecture has been introduced. It can exist side-by-side with the old authenticators and SAML/OIDC entities, so in general, no changes are needed to the configuration. However, the already existing authenticators and SAML/OIDC entities have now been moved to the new tab Legacy Guides. These new authenticators use a different URL path from before, so you may need to whitelist /authentication in your reverse proxy settings.

To 5.0

Customizations

Starting with 5.0, the new directory modsoverlay has been introduced. In short, the idea is that customizations that were previously done inside the mods directory are now placed inside the new directory modsoverlay instead. modsoverlay will not be overwritten during an upgrade, so upgrading a customized system should be a lot easier. It's not perfect yet, there are still certain edge cases that needs modifications directly to the mods directory.

In addition to the new directory modsoverlay, the directory repo has now been removed, and the content of the directory mods will always be overwritten. Previously, there would be multiple versions of a module inside the mods directory, and only the module of the same version as the system would be loaded - now, only one version of each module resides in the mods directory.

For details about this, see ex. Modules section in the Start Sequence

External Database (Microsoft SQL Server)

The timestamp precision has been increased from milliseconds to nanoseconds. This means that the columns in the external databases need to be altered to datetime2 (previously, it was datetime which isn't compatible with PAS 5.0+)

Run the following SQL to update the datetime columns:

DROP INDEX IF EXISTS event_date ON event;
ALTER TABLE event ALTER COLUMN date datetime2;
CREATE INDEX event_date ON event (date);

DROP INDEX IF EXISTS tokens_expires ON tokens;
ALTER TABLE tokens ALTER COLUMN expires datetime2;
CREATE INDEX tokens_expires ON tokens (expires);

DROP INDEX IF EXISTS lockouts_userid ON lockouts;
ALTER TABLE lockouts ALTER COLUMN created datetime2;
ALTER TABLE lockouts ALTER COLUMN modified datetime2;
CREATE INDEX lockouts_userid ON lockouts (userid);

DROP INDEX IF EXISTS devices_used ON devices;
DROP INDEX IF EXISTS devices_created ON devices;
ALTER TABLE devices ALTER COLUMN created datetime2;
ALTER TABLE devices ALTER COLUMN used datetime2;
CREATE INDEX devices_used ON devices (used);
CREATE INDEX devices_created ON devices (created);

DROP INDEX IF EXISTS assignments_expires ON assignments;
ALTER TABLE assignments ALTER COLUMN expires datetime2;
ALTER TABLE assignments ALTER COLUMN modified datetime2;
ALTER TABLE assignments ALTER COLUMN created datetime2;
CREATE INDEX assignments_expires ON assignments (expires);

Extensions

No extensions written for versions prior to 5.0 are compatible with 5.0+. Many old extensions have been ported to 5.0, and has been included into the base installation

To 4.7

BankID v6.0

In version 4.7 it is possible to upgrade to v6.0 by adding the attribute "version" : "v6.0" to your configuration and removing the use of personalNumber to trigger authentication from your environment.

Table of Contents