Upgrade instructions 12.x

12.21.0

Thymeleaf Upgrade

Thymeleaf has been upgraded to 3.1.2.RELEASE, introducing changes that may impact existing templates. The following table lists key modifications that might affect them:

Feature	Change	Details
th:substituteby	Removed	Use th:replace
#request, #response, #session, #servletContext	Removed	Not available in expressions
Core Class Restrictions	Tightened	Limited in expressions
th:include	Deprecated	Use th:insert
template :: fragment	Deprecated	Use ~{template::fragment}

For detailed changes, visit Thymeleaf 3.1 What's New.

12.20.4

Remove task scheduler

The cron-based task scheduler that was used for removing old AccessToken has been removed. As a consequence, the following env variables will have no effect and should be removed:

• SCHEDULER_TASK_EXECUTION_RATE
• SCHEDULER_TOKEN_CLEAN_UP_BATCH_SIZE

Allow cascade event removal

Warning: The migration V12_20_04_00__OAUTH-3727_delete_cascade_events.sql will take some extra time if the events_client_info table is large. If the application fails to start due to timeout of the migration, please check in the db if the foreign key constraint EVENTS_CLIENT_INFO_FK_EVENT_ID was correctly created for table events_client_info. If constraint is created you can safely change the flyway_schema_history table success column to true for this migration. If constraint is not created you can either run the query in the migration file by hand and fix the flyway_schema_history row, or completely remove the row for this migration and try again after increasing connection timeout for database.

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_20_04_00__OAUTH-3727_delete_cascade_events.sql (will take some extra time if the events_client_info table is large)

12.19.0

New index in the clients table

Warning: The migration V12_19_00_00__add_client_registration_id_index.sql will take some extra time if the clients table is large. If the application fails to start due to timeout of the migration, please check in the db if the index was correctly created. If index is created you can safely change the flyway_schema_history table success column to true for this migration. If index is not created you can either run the query in the migration file by hand and fix the flyway_schema_history row, or completely remove the row for this migration and try again after increasing connection timeout for database.

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_19_00_00__add_client_registration_id_index.sql (will take some extra time if the clients table is large)

12.18.0

Change in OpenID Connect check session template

The default template check-session.html has been modified to support the upgrade to crypto-js 4.1.1. If your custom template set contains this check-session.html template, you need to update your customized template set. Download the default template set to compare your version of check-session.html with the standard version.

12.17.1

Properties change

The properties used to configure communication with external services have been renamed:

Old	New
token.server.test-client.rest-services.read-timeout-millis	rest-services.read-timeout
token.server.test-client.rest-services.connect-timeout-millis	rest-services.connection-timeout
rest-services.wait-for-available-connection-in-pool-timeout-millis	rest-services.wait-for-available-connection-in-pool-timeout
rest-services.request-connection-pool-validate-after-inactivity-millis	rest-services.request-connection-pool-validate-after-inactivity

12.15.0

Changes in database schema

Run the following database script if your installation does not automatically update the database schema:

• V12_15_00_00__add_open_id_delete_tokens_on_logout.sql
• V12_15_00_01__multiple_application_signatures.sql

12.14.0

User authentication

The user authentication transaction was kept in a short-lived, persistent cookie named AUTH-TX. This cookie is no longer used. When a user needs to authenticate, the transaction is kept in a session cookie named SESSION. This cookie was already present in earlier versions of the Onegini Token Server.

During the upgrade to this version, users will experience issues when they start the authentication transaction on an older version of the Onegini Token Server and continue on the latest version or vice versa. Using sticky sessions in the load balancer will prevent this issue.

12.12.1

Changes in the database schema

For MySQL or Oracle there are no database migrations.

For Microsoft SQL Server run the following database scripts if your installation does not automatically update the database schema:

• V12_12_01_00__remove_constraint_for_refresh_token_expires_in.sql

12.10.0

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_10_00_00__OAUTH-3620_cordova_push_messaging.sql

12.6.0

Changes in templates

The default template consent.html has been updated to include the nonce variable in the consent form post. If your custom template set contains this consent.html template, you need to update your customized template set. Download the default template set to compare your version of consent.html with the standard version.

e.g.: <input type="hidden" name="nonce" value="${nonce}"/>

12.5.0

Device API

Device API version 4 has been introduced. It shows more information about the devices of an end-user. Another change is that property names in the JSON response objects of Device API version 4 are using camelCase. The older versions were using snake_case.

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_04_02_00__delete_mobile_platform_version_keys.sql
• V12_04_03_00__add_jwks_uri_to_client_jwks.sql
• V12_04_03_01__add_device_model.sql
• V12_05_00_00__change_mpv_keys_fingerprint_column_type.sql (this script is for Oracle only)

12.4.1

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_04_01_00__delete_mobile_platform_version_keys.sql

12.4.0

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_04_00_00__add_sender_id_to_auth_properties.sql

12.2.0

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_02_00_02__add_mobile_platform_version_keys_on_delete_cascade.sql

12.1.2

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V12_02_00_01__add_mobile_platform_version_keys.sql

12.1.0

Redis

This release requires a Redis server version 4 or higher.

Changes in the database schema

For MySQL there are no new database scripts.

For Microsoft SQL Server or Oracle run the following database scripts if your installation does not automatically update the database schema:

• V11_00_00_00__add_pkce_support.sql
• V11_00_00_01__add_dum_engine_configs.sql
• V11_00_00_02__add_refresh_token_expiration_time.sql
• V11_00_01_00__add_integrity_check_to_application_version.sql
• V11_00_01_01__app_signature_made_optional.sql
• V11_00_01_02__add_registration_id_and_assertion_public_key_to_the_client.sql

12.0.0

Change in OpenID Connect check session template

The default template check-session.html has been modified to support reading cookies in iOS12 and other browsers that ignore cookies with a SameSite=None flag inside an iframe. If your custom template set contains this check-session.html template, you need to update your customized template set. Download the default template set to compare your version of check-session.html with the standard version.

Change in error handling

When something goes wrong during the OAuth authorization code flow or the OpenID Connect Authentication request the Onegini Token Server often showed an HTML error page, while it could redirect back to the client with an error code. This HTML page was not compliant with parts of the OpenID Connect Authentication request specification. This redirect may also simplify customized error templates for the Onegini Token Server.

The Onegini Token Server will now redirect back to the client with an error code in the following situations if the client_id and redirect_uri are correct:

• The Onegini Token Server cannot determine which identity provider to use for authentication.
• Fetching the metadata of a SAML identity provider fails.
• An OpenID Connect Relying Party requests prompt=none for a user that has a session with Onegini Token Server but lost their session with the SAML identity provider.
• The SAML identity provider returns an authentication response with a failure status. The underlying cause is returned to the client.

Changes in the database schema

Run the following database scripts if your installation does not automatically update the database schema:

• V11_00_01_00__add_integrity_check_to_application_version.sql
• V11_00_01_01__app_signature_made_optional.sql
• V11_00_01_02__add_registration_id_and_assertion_public_key_to_the_client.sql