Upgrading from 11.1.X to 11.2.0#

JDBC Data Source#

New index in the delegations table#

A new index over client_id and status was added to support revoking all delegations for a client. The previously existing index over client_id was removed. Refer to schema-migration for details on how to apply this change to your database schema.

Velocity templates: removal of internal context variables#

The _include-event-handler-alternative-template-area key/value was removed from the _context map. This key is internal and should not have been used in templates.

BankID Authenticator#

The BankID authenticator has a new backend-return-url configuration setting . When enabled, the Return URL will be sent by the Curity Identity Server to the BankID backend, rather than directly to the BankID application. Enabling the backend-return-url configuration setting also puts the BankID authenticator into a new operational behavior, where at any given moment during an authentication it is either in same-device mode or cross-device mode, but never in both simultaneously:

  • In same-device mode, the user interface will try to auto-start the BankID application locally, will not show the QR code, and will show a button to switch to cross-device mode.
  • In cross-device mode, the user interface will show the QR code, not auto-launch the application, and will show a button to switch to same-device mode.

Velocity Templates#

Due to this new behavior, the authenticator/bankid/launch/index.vm template has been updated with more user interface elements and rendering logic. If you use a custom version of this template, it must be updated accordingly. Use the new authenticator/bankid/launch/index.vm as a reference for the required changes, namely:

  • A new extendUrl computed variable, and its use in the extend button.
  • Making sure the _autostartTokenDataUri variable is only used when it is available.
  • Making sure the _autostartToken variable is only used when it is available.
  • A new button to switch between modes (from same-device mode to cross-device mode and vice versa), using both the new _flowMode and _switchModeUrl variables.

Additionally, the polling and application launch logic previously parsed from authenticator/bankid/launch/ has been moved into shared fragments under fragments/bankid/ so the BankID Signing Consentor can reuse it. The new templates are:

  • fragments/bankid/bankid-poller.vm
  • fragments/bankid/bankid-app-launcher.vm

If you use a custom version of authenticator/bankid/launch/index.vm that enables the new polling flow ($bankidLaunchVersion2 = true, which is the default), it must reference the new fragment paths and set $bankidKeyPrefix before parsing them:

#set($bankidKeyPrefix = "authenticator.bankid.service")
#parse("fragments/bankid/bankid-poller")
#parse("authenticator/bankid/launch/bankid-polling-settings")
#parse("fragments/bankid/bankid-app-launcher")

There are also two new message keys in authenticator/bankid/launch.properties: launch.view.button.show-qr-code and launch.view.button.open-on-this-device.

The authenticator/bankid/enter-personalnumber/compute-browser-context.vm template was added; however, it does not present any visible user interface and should not need any customization. It is used only to gather information about the user’s browser.

HAAPI#

When the new backend-return-url configuration setting is enabled, the HAAPI representations for BankID are also changed:

  • When in same-device mode, the link with the QR code will not be present.
  • When in cross-device mode, the BankID client operation will not be present.
  • There are new links with relations equal to cross-device or same-device to switch the operation mode.

This change is not compatible with the current UI SDKs for both iOS and Android, so the backend-return-url configuration setting should not be enabled when using those UI SDKs.

Only enable the backend-return-url configuration setting when the previous requirements have been met and the limitations understood.

BankID Signing Consentor#

The BankID Signing Consentor can now optionally use the same improved polling flow that was introduced for the BankID authenticator. The improved flow uses per-browser strategies to launch the BankID application, and pauses polling while the browser tab is hidden.

The improved flow is opt-in and disabled by default, so upgrading to 11.2.0 does not change the behavior of the signing consentor unless the new flag is explicitly enabled.

To enable it, set $bankidConsentorLaunchVersion2 to true in overrides/fragments/settings.vm:

#set($bankidConsentorLaunchVersion2 = true)

The default value (false) is declared in settings-defaults.vm.

Velocity Templates#

The polling and application launch logic that used to live under authenticator/bankid/launch/ has been factored into shared fragments under fragments/bankid/, so both the authenticator and the signing consentor can use it. The following templates are new or have been moved:

  • fragments/bankid/bankid-poller.vm — shared polling logic.
  • fragments/bankid/bankid-app-launcher.vm — shared application launch logic.
  • fragments/bankid/check-platform-capabilities.js.vm — shared platform detection logic.
  • fragments/bankid/browsers/* — shared per-browser launch strategies.
  • consentor/bankid-signing-consentor/bankid-polling-settings.vm — consentor-specific parameters (poll URL, failure URL, DOM selectors, success/cancel handlers) consumed by the shared poller.

If you use a custom version of consentor/bankid-signing-consentor/bankid-poller.vm, you must rebase your changes onto the new version in order to be able to opt into the improved flow. The new version of this template uses a #if($!bankidConsentorLaunchVersion2) switch to toggle between the shared fragments and the previous behavior.

When opting into the improved flow, test on iOS (Safari, Chrome, Firefox, Edge), Android, and desktop browsers to verify the application launch behavior in your environment.

Was this helpful?