Upgrade instructions 10.x

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
  • 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_
SECURITY_ SPRING_SECURITY_
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.