Upgrade instructions 10.x

10.3.8

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.

10.3.5

Run all database scripts

Only for Microsoft SQL Server make sure the following migration has been applied:

• V10_03_05_add_access_tokens_user_id_index.sql

10.3.4

Changed defaults for Redis timeouts

The following default value has changed to prevent that the Token Server waits too long for a response from Redis.

Environment variable	Old default	New default
SPRING_REDIS_TIMEOUT	60000ms	2500ms

10.3.3

Run all database scripts

Only for Microsoft SQL Server make sure the following migration has been applied:

• V9_01_04_00__add_missing_indexes.sql

Environment variables

The default value for SPRING_FLYWAY_OUTOFORDER has changed from false to true. The Token Server will apply hotfixes to database migrations when these migrations are applied automatically.

10.3.2

Changed defaults for REST template timeouts

The following default values have changed to prevent that the Token Server waits too long for a response from an external API.

Environment variable	Old default	New default
TOKEN_SERVER_ADMIN_REST_SERVICES_READ_TIMEOUT_MILLIS	30000 (ms)	10000 (ms)
TOKEN_SERVER_ADMIN_REST_SERVICES_CONNECT_TIMEOUT	30000 (ms)	2500 (ms)
TOKEN_SERVER_ENGINE_REST_SERVICES_READ_TIMEOUT_MILLIS	30000 (ms)	10000 (ms)
TOKEN_SERVER_ENGINE_REST_SERVICES_CONNECT_TIMEOUT	30000 (ms)	2500 (ms)

10.3.0

New Integrations

There are two a new integrations with the Onegini Identity provider.

Configuration API

Using the Configuration API, the Token Server can fetch a list of external identity providers that are configured in the Consumer Identity Manager in order to better inform the Onegini Mobile SDKs about what is available. This provides a tighter integration and provides the app developer more information when creating the user interface. It is recommended to enable this functionality if you are utilizing Onegini's SDKs for your mobile applications.

Storage API

There is also an integration with the Storage API. It allows the Onegini Mobile SDKs to securely store data on the server.

Run the database script

• V10_03_00_00__add_idp_encrypted_attributes.sql

10.2.0

The OpenID Connect Discovery API has fixed a typo on id_token_signing_alg_values. It is now returned correctly as id_token_signing_alg_values_supported. You may need to update your Relying Party implementation if it was using the incorrect key.

Please consider enabling the Responsible disclosure policy feature to allow security findings to be reported directly to Onegini.

10.1.0

If you have enabled App To Web SSO for the Onegini Identity provider, you will need to update the Onegini CIM to a minimum version of 6.2.0. After that has been updated, you'll need to update the configuration for Action Token login related to App To Web as that has been separated from the original login functionality.

10.0.1

If you have enabled App To Web SSO for the Onegini Identity provider, you will need to configure the Public Base Uri for the functionality to continue working. In some cases this may be the same as the API Base URI.

10.0.0

This version contains an upgrade to Spring Boot version 2, Flyway version 5 and Java 11.

Changes in API

There were a number of changes to existing APIs:

Web Clients and Api Clients API

From this version, the Web Clients API requires access via the Config API scope instead of the Admin API scope. Create an API Client that supports the Config API scope if you are using the Web Clients API.

The Admin API scope is still used for the API Clients API.

Device API

The value of the identifier in the Device API has changed. It is now aligned with the device_id in the Mobile Authentication API and the client_id Token Introspection response. No changes are needed for consumers of the Device API when they fetch the devices and perform operations based on that response.

Removal of Deprecated APIs and Minimum supported SDKs increased

The minimum supported SDK versions have been increased. Android SDK must be at least version 5.01.00, iOS SDK must be at least version 4.08.03

• V1 & V2 of the Devices API has been removed. Use version 3 of the API.
  • /api/v1/users/{userId}/devices/*
  • /api/v2/users/{userId}/devices/*
• The Authentication applications API has been removed. Use version 3 of the Device API as a replacement.
  • /oauth/api/v1/users/{userId}/authentication/apps/*

See other planned deprecations

Database

The minimal database versions have changed:

• Oracle 12.2
• SQL Server 2014

Older versions of Oracle and SQL Server are no longer supported. The minimal version for MySQL (5.6) remains the same.

Run all database scripts

Warning: The migration V10_00_00_02__add_access_token_format_to_client_config.sql and V10_00_00_03__add_correlation_id_to_access_tokens.sql will take some extra time if the access_tokens table is large.

• V10_00_00_00__add_encryption_cols_for_open_id_config.sql
• V10_00_00_01__add_api_application_version_scope.sql
• V10_00_00_02__add_access_token_format_to_client_config.sql
• V10_00_00_03__add_correlation_id_to_access_tokens.sql
• V10_00_00_04__add_api_events_scope.sql

Database connection configuration

From this version the Token Server uses a different database connection pooling mechanism. Some variables were no longer needed while other custom variable names were removed.

Environment variables

Environment variables with a new prefix:

Old variable name starts with	New variable name starts with
FLYWAY_	SPRING_FLYWAY_
SPRING_HTTP_MULTIPART_	SPRING_SERVLET_MULTIPART_
SPRING_SESSION_	SPRING_SERVLET_SESSION_

Change the following environment variables:

Old variable name	New variable name
SPRING_HTTP_MULTIPART_ENABLED	SPRING_SERVLET_MULTIPART_ENABLED
SPRING_HTTP_MULTIPART_MAX_FILE_SIZE	SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE
SPRING_HTTP_MULTIPART_MAX_REQUEST_SIZE	SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE
SERVER_CONTEXT_PATH	SERVER_SERVLET_CONTEXT_PATH
SERVER_SESSION_TRACKING_MODES	SERVER_SERVLET_SESSION_TRACKING_MODES
SERVER_SESSION_TIMEOUT	SERVER_SERVLET_SESSION_TIMEOUT
REDIS_DEFAULT_JWKS_URI_RESPONSE_TTL_SECONDS	REDIS_DEFAULT_JWKS_URI_RESPONSE_TTL

Note: SERVER_SERVLET_SESSION_TIMEOUT and REDIS_DEFAULT_JWKS_URI_RESPONSE_TTL expect a duration suffix, e.g. 3600s, 60m or 1h. If a duration suffix is not specified, seconds will be used.

Changed variable names

The following variables were renamed to align with other products of Onegini:

Old variable name	New variable name
TOKEN_SERVER_COMMON_DB_TYPE	DATABASE_TYPE
TOKEN_SERVER_COMMON_DB_ENCRYPTION_PASSWORD	DATABASE_ENCRYPTION_PASSWORD
TOKEN_SERVER_COMMON_DB_ENCRYPTION_POOLSIZE	DATABASE_ENCRYPTION_POOLSIZE

Changed to Spring Boot defaults

The following variables were replaced by Spring Boot database variables:

Old variable name	New variable name
TOKEN_SERVER_COMMON_DB_JDBC_URL	SPRING_DATASOURCE_URL
TOKEN_SERVER_COMMON_DB_USER	SPRING_DATASOURCE_USERNAME
TOKEN_SERVER_COMMON_DB_PASSWORD	SPRING_DATASOURCE_PASSWORD
TOKEN_SERVER_COMMON_DB_DRIVER_CLASS	SPRING_DATASOURCE_DRIVER_CLASS_NAME
TOKEN_SERVER_COMMON_DB_PLATFORM	SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT

Changed to Flyway defaults

The following variables were replaced by Flyway environment variables:

Old variable name (<10.x)	New variable name
TOKEN_SERVER_COMMON_DB_MIGRATION_ENABLED	SPRING_FLYWAY_ENABLED
TOKEN_SERVER_COMMON_DB_MIGRATION_INIT_VERSION	SPRING_FLYWAY_BASELINE_VERSION
TOKEN_SERVER_COMMON_DB_MIGRATION_OUT_OF_ORDER	SPRING_FLYWAY_OUT_OF_ORDER
TOKEN_SERVER_COMMON_DB_MIGRATION_FOLDER	SPRING_FLYWAY_LOCATIONS

Note: apply the table below if you are upgrading from a Milestone version (10.0.0-M1 or 10.0.0-M2):

Old variable name (10.0.0-M1 or 10.0.0-M2)	New variable name
FLYWAY_ENABLED	SPRING_FLYWAY_ENABLED
FLYWAY_BASELINE_VERSION	SPRING_FLYWAY_BASELINE_VERSION
FLYWAY_OUT_OF_ORDER	SPRING_FLYWAY_OUT_OF_ORDER
FLYWAY_LOCATIONS	SPRING_FLYWAY_LOCATIONS

Removed variables

The following variables are no longer used to configure the database connection and should be removed:

• TOKEN_SERVER_COMMON_DB_CONNECTIONS_INITIAL_SIZE
• TOKEN_SERVER_COMMON_DB_CONNECTIONS_MAX_ACTIVE
• TOKEN_SERVER_COMMON_DB_CONNECTIONS_MAX_IDLE
• TOKEN_SERVER_COMMON_DB_CONNECTIONS_MAX_WAIT
• TOKEN_SERVER_COMMON_DB_CONNECTIONS_MAX_LIFETIME_MILLIS
• TOKEN_SERVER_COMMON_DB_VALIDATION_QUERY
• TOKEN_SERVER_COMMON_DB_SHOW_SQL

Token Server Admin now connects to Redis

The Token Server Admin Panel now connects to Redis. Your network setup should allow the admin application to also connect to the same Redis instance as the Token Server engine. This has the added benefit that values updated in the UI will be immediately available for the Token Server Engine to utilize without a restart.

Note: The Application properties cache TTL is set to 1 day and is no longer configurable in the UI. Changing an application property will replace the entry in the cache.

Zip archive handling

Zip files are now by default limited to 10MB and/or 100 files. This includes message and template zip files. These limits can be modified via environment properties as described in Zip archive handling

Thymeleaf upgrade

The Thymeleaf template engine and its dialects have been upgraded. If you have customized the templates based on the default template set they will probably still work. Thymeleaf has made changes to its templating language and logs warnings for the usage of deprecated features. We recommend to plan an upgrade of custom templates.

The most common changes are:

• layout:decorator is deprecated. Use layout:decorate instead.
• Replace $DECORATOR_TITLE with $LAYOUT_TITLE.
• The attributes th:include and layout:include are deprecated. Replace them with th:insert and layout:insert. Note that insert has a different behavior than include.
• Existing fragment expressions are deprecated.

Example of a deprecated Thymeleaf 2 fragment expression:

<th:block th:include="fragments/fragment-inputs :: csrfToken"/>

Example of an updated Thymeleaf 3 fragment expression

<th:block th:insert="~{fragments/fragment-inputs :: csrfToken}"/>

Refer to the Thymeleaf 3 migration guide and Layout dialect migration guide for full details.

Changes in custom Token Server plugins

The class com.onegini.tokenserver.engine.OauthEngineConstants was moved to com.onegini.tokenserver.engine.core.OauthEngineConstants. You may need to update some imports.