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 6.0.0 and above

External database and audit logs

As described in detail in the article Audit logs / Event logs in PAS 6.0 and above, if you wish to run database backed events in PAS 6.0 and are using an external database to do so, you need to add a new table for the events like such:

For MSSQL:

CREATE TABLE audit_events (
    eventID varchar(255),
    message varchar(1500),
    host varchar(255),
    params varchar(MAX),
    date datetime2
);
CREATE INDEX audit_event_date ON audit_events (date);
CREATE INDEX audit_event_id ON audit_events (eventID);

and for MySQL:

CREATE TABLE audit_events (
    eventID varchar(255),
    message varchar(1500),
    host varchar(255),
    params TEXT,
    date datetime
);
CREATE INDEX audit_event_date ON audit_events (date);
CREATE INDEX audit_event_id ON audit_events (eventID);

The reports module

The reports module has undergone some changes. Injecting input parameters directly into the SQL is no longer permitted. Default reports now use the syntax of prepared statements instead. Any custom reports you use which utilize parameter injection must now be changed to fit the prepared statement syntax. An example report can be seen below.

Syntax before:

{
    "displayName": "OTP sent to number",
    "description": "Shows the 1000 most recent OTP sent to mobile",
    "category":"Authentication",
    "query": "select * from event where eventID ='EVT_001020' and dst='{{dst}}' order by date desc limit 1000",
    "params": [{
        "name": "dst",
        "displayName": "Mobilenumber",
        "type": "input"
    }]
}

Syntax after:

{
    "displayName": "OTP sent to number",
    "description": "Shows the 1000 most recent OTP sent to mobile",
    "category":"Authentication",
    "query": "select * from event where eventID ='EVT_001020' and dst=? order by date desc limit 1000",
    "params": [{
        "name": "dst",
        "displayName": "Mobilenumber",
        "type": "input"
    }]
}

Important note: make sure your params are in the correct order if you have multiple. Each ? in the prepared statement will be replaced with the parameter in the same order as they are configured here.

The module phenix-events-billing

The module phenix-events-billing is not used anymore and must be removed from the configuration if it has been added (ex. for BankID billing).

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