Upgrade instructions 10.x
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 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
- 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
andlayout:include
are deprecated. Replace them withth:insert
andlayout: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.