Upgrade from previous version

Current version is pre 2.0

Even though PhenixID server is fully compliant with previous versions there are differences. Upgrades should not be done without contacting PhenixID.

When contacting PhenixID please add information about current usage of PhenixID server. This will help in assessing the work upgrading the system.

Current version is 2.0 or later

The installer will guide through the update. Be sure to backup the existing installation before starting the upgrade.

Step by step document for upgrade can be found here:
Upgrade

As always, verify customizations from earlier version and transfer to new installation if needed.

NOTE:

There has been changes to the "front end files" such as css, js and templates. If you see strange behavior with the web apps or authentication pages, please clear the browser cache.


From version 2.6 there has been a change to the template file used by One Touch.
The server will now look for this file in the folder /resources and the name of the default template file has changed from onetouch_template_json.template to ot_auth_template.json.
If there are One Touch scenarios configured in earlier versions, please go into the Configuration Manager, locate your scenario(s) for One Touch and click on the tab "Advanced".
Edit the name of the template file according to your environment.


If One Touch tokens have been enrolled in version 2.7 and before, you might see this error on startup.
     


Replacement of persistent layer (database)

Module, com.phenixidentity~phenix-store-mpl, has gone through refactorization that will require additional steps in order to keep old data after upgrade.

In short this means exporting old data and importing it using a tool provided by PhenixID.

See separate article.

New version of Hazelcast

New version of Hazelcast is being introduced, with new cluster.xml. This file needs to be replaced manually in the folder /classes after the upgrade. Rename earlier cluster.xml and then change cluster_template.xml to cluster.xml
If cluster is configured, the configuration in the network section must be moved from the earlier cluster.xml to the new one.

NOTE: In version 4.1 of PAS, the following can be seen in server.log, at startup (on most installations).[CPSubsystem] WARN: [192.168.86.38]:5701 [dev] [4.1.1] CP Subsystem is not enabled. CP data structures will operate in UNSAFE mode! Please note that UNSAFE mode will not provide strong consistency guarantees.
This message is set at log level WARN and is informational.
More information:
https://docs.hazelcast.com/imdg/4.1/cp-subsystem/unsafe-mode.html

Upgrading from an clustered installation

Clustering configuration and recommendation has been updated in a way that previously installed systems using cluster will need additional configuration. Functionality will be maintained.
New version of Hazelcast is being introduced, so all nodes must be upgraded before joining the cluster again.
See instructions for new cluster.xml above.

Location of module session-manager

The location of module session-manager has moved from section "default_modules" to "deploy" in the file /config/boot.json.
When doing an upgrade, please make sure to move this module before starting the service.
Should be placed like this:

"deploy": [
        {
            "name": "com.phenixidentity~phenix-event",
            "enabled": "true"
        },
        {
            "name": "com.phenixidentity~phenix-store-json",
            "synchronous": "true",
            "address": "com.phenixidentity.configuration",
            "config": {
                "store.file": "./config/phenix-store.json",
                "persistsessions": "false",
                "encryption.key": "secret",
                "enabled": "true"
            }
        },
        {
            "module": "com.phenixidentity~phenix-schedule",
            "enabled": "true",
            "config": {}
        },
        {
            "name": "com.phenixidentity~phenix-session-manager",
            "scope": "global",
            "singleton": "true",
            "config": {}
        },
        {
            "name": "com.phenixidentity~phenix-store-mpl",
            "config": {

After first startup, the module should be removed from the Modules section in config GUI.
On the Advanced tab, expand Modules, find com.phenixidentity~phenix-session-manager, make a note of the id and then press the minus sign.
Press "Confirm deletion" and then "Commit changes".

Now go to "NODE_GROUPS", find the id and remove it from module_refs.
When done, press "Stage changes" and "Commit changes".

BankID template update

If using Swedish bankid, the template has been updated. Current configuration is found in Authenticators manual.

Authentication API

Module com.phenixidentity~phenix-api-authenticate API calls has been updated. 

In order to access any One Touch api endpoint, the uri now must end with a "/", ie  /api/authentication/onetouch/assign/ 

In addition the ending part of the URI must be listed as an allowed operation:

"allowedOperation":["assign"].

ADFS MFA Adapter

The ADFS MFA Adapter for One Touch has been updated to work against a PAS 3.2 backend. 

Download new binaries here.   

Replace PhenixIDMFAAuthenticationProviderOneTouch.dll.

Unregister and register the PhenixID One Touch MFA Adapter.



Manual updates are required in boot.json & phenix.store.json

Read about the requirements here.

Guide updates - User name & One Touch

Any configuration done through GUIDE User Name and One touch must be manually updated.

Updated authenticators

Authenticators have updates that may result in new behavior. The update consists in a change in how a user is bound to the session:

For authenticators PostUidPasswordAndOTPSAML, OIDCPostUidPasswordAndOTP & PostUidPasswordAndOTP  the session is rebound for each authentication.  This means that scenarios, where the above authenticators are used along with others in an already authenticated session, may change the primary user identity when re-authenticating using one of the above authenticators.