Upgrade instructions versions 5.x

5.7.0 to 5.8.1

Run all database scripts

  • V5_08_00_00__rename_public_key_to_user_public_key_for_transaction_signing.sql (Oracle and MSSQL only)

5.6.0 to 5.7.0

Run all database scripts

  • V5_07_00_00__perform_postponed_db_changes.sql
  • V5_07_00_01__add_user_id_event_date_index_on_events.sql (Oracle and MSSQL only)

5.5.2 to 5.6.0

Property changes

Cache configuration

Docker compose environment variables used to configure cache are replaced in favour of providing Cache Configuration in the Admin console.

In order to use the same cache configuration as before described change, retrieve the old values of docker compose environment variables (or etcd variables) presented in a table below and set those values in corresponding fields in the Admin console configuration.

Note: To retrieve values as etcd properties you can use etcdctl get command. For example etcdctl get /token-server/engine/idp/saml-sp/signing/certificate.

The following table shows environment/etcd variables and fields in Admin console introduced to replace those variables.

Environment variable Etcd variable Field name in Admin console
TOKEN_SERVER_ENGINE_CACHE_MESSAGE​_CACHE_TTL_SECONDS /token-server/engine/cache/message-cache/ttl-seconds Message cache TTL
TOKEN_​SERVER_​ENGINE_​CACHE_​APPLICATION_​PROPERTIES_​CACHE_​TTL_​SECONDS /token-server/engine/cache/application-properties-cache/ttl-seconds Application properties cache TTL
TOKEN_SERVER_ENGINE_GENERAL_TEMPLATE​_CACHING_ENABLED_BOOLEAN /token-server/engine/general/template-caching-enabled-boolean Template caching enabled

All variables presented in the table are no longer supported.

User authentication session time to live configuration

Docker compose environment variables used to configure User authentication cookie and cache time to live are replaced in favour of providing User authentication session TTL Configuration in General section of the Admin console.

In order to use the same configuration as before described change, retrieve the old values of docker compose environment variables (or etcd variables) presented in a table below and set those values in corresponding fields in the Admin console configuration.

Note: To retrieve values as etcd properties you can use etcdctl get command. For example etcdctl get /token-server/engine/idp/saml-sp/signing/certificate.

The user authentication process uses a cookie to identify the authentication transaction. Before it was possible to set a different value for the cookie and transaction time to live. Since such a separation didn't add much value and was harder to configure correctly (cookie TTL needed to be longer than transaction TTL) those two properties were merged into one setting field in the Admin console. The following table presents described change.

Environment variable Etcd variable Field name in Admin console
TOKEN_​SERVER_​ENGINE_​CACHE_​USER_​AUTHENTCATION_​CACHE_​TTL_​SECONDS /token-server/engine/cache/user-authentication-cache/ttl-seconds User authentication session TTL
TOKEN_SERVER_ENGINE_COOKIES_USER​_AUTHENTICATION_TTL_SECONDS /token-server/engine/cookies/user-authentication/ttl-seconds User authentication session TTL

All variables presented in the table are no longer supported.

Admin changes

Application configuration

The Application configuration available on the Configuration -> App configuration -> Applications section in the Admin console was modified in the following way:

The dropdown for Allowed function(s) has been replaced. It's options have moved:

  • AUTHORIZATION_CODE: select User registration in the new dropdown called Flows.
  • CLIENT_CREDENTIALS: select Anonymous resource calls in the new dropdown called Flows.
  • REFRESH_TOKEN: this option has moved to the checkbox PIN authentication under User authentication. It is enabled by default.
  • FINGERPRINT_TOKEN: this option has moved to the checkbox Fingerprint authentication under User authentication.

Following options are no longer available:

  • IMPLICIT
  • VALIDATE_ACCESS_TOKEN

Note: If the detail view of an Application shows **Incorrect option: IMPLICIT** or **Incorrect option: VALIDATE_ACCESS_TOKEN** under Flows, edit the Application. The incorrect options are removed when the form is saved.

The Certificates section was moved to the Security settings section.

Web clients configuration

The Web clients configuration available on the Configuration -> Web clients section in the Admin console was modified in the following way:

The dropdown with Allowed function(s) has been renamed to Grant Types. The option REFRESH_TOKEN has moved to the checkbox Issue refresh tokens. The option FINGERPRINT_TOKEN is no longer available for Web clients.

It is no longer required (nor possible) to enter a value for Max PIN attempts.

Other Application/Web clients configuration changes

Field Additional Authenticator was renamed to Additional user verification

Remove the OTP Identity Provider

If any of your applications were using the OTP identity provider it needs to be removed because it is no longer supported by the Token Server. In order to remove all the OTP identity providers created in your Token Server application you need to follow the steps described below:

Note: If it is not a problem that applications that were using the OTP identity provider will now use a different identity provider (TWOWAYOTP,HEADER or CUSTOM) you only need to perform the database operations. If you want to completely delete the OTP identity provider you also must follow the steps described in the admin console operations paragraph.

1. Database operations
  1. Go to identity_providers table and search for all rows containing identity_provider_type=OTP (identity providers of the OTP type)
  2. Write down names of the all found identity providers (it will be needed later on if you continue the process in the Admin console).
  3. Change identity_provider_type to other available type (TWOWAYOTP,HEADER or CUSTOM) for the all found identity providers.
2. Admin console operations
  1. Make sure the Token Server is started.
  2. Go to the Configuration -> Identity Providers Admin section. Remove all identity providers with the names you wrote down before.
  3. If an identity provider is used by some applications you will see a warning Could not delete Identity provider, because it is used by the following applications with the list of the applications that are using this identity provider.
  4. Go to App configuration -> Applications and remove all the applications from the warning list or change the identity provider that they are using to a different one.
  5. Go to Configuration -> Identity Providers and remove the identity provider.

5.4.0 to 5.5.0

Run all database scripts

  • V5_05_00_00__move_application_keys_to_separate_table.sql

Admin toggles changes

The mobile authentication configuration settings available on the Configuration -> Mobile authentication -> General mobile config page in the Admin console were modified in the following way:

The Push authentication / Authentication enabled toggle was moved to Configuration -> System -> Features and renamed to Mobile authentication. This toggle now enables/disables not only push authentication but all mobile authentication features. If this toggle is disabled:

  • no mobile authentication (OTP, push, SMS) can be performed.
  • the more detailed configuration described below cannot be provided, since the Configuration -> Mobile authentication section becomes unavailable in the Admin console.

Warning: This toggle was renamed internally. This means it is now disabled by default, and will override previous configuration. Please configure this setting as appropriate after upgrading.

Two new toggles were added:

New toggle Role Notes
General / Enrollment enabled Enables mobile authentication enrollment If disabled all other mobile enrollment toggles become unavailable
General / Enrollment override enabled Enables override of mobile authentication enrollment

Warning: Since these toggles are new, they are disabled by default! This will override existing push authentication settings. Please configure these settings as appropriate after upgrading.

Two toggles were modified in the following way:

Old toggle New toggle Role Notes
Push authentication / Device enrollment enabled Push authentication / Enrollment enabled Enables push authentication enrollment In order this toggle configuration take an effect, General / Enrollment enabled toggle must be enabled
Push authentication / Device enrollment override enabled Push authentication / Enrollment override enabled Enables push authentication enrollment override In order this toggle configuration take an effect, General / Enrollment enabled toggle must be enabled

For more information go to Mobile authentication configuration

5.3.0 to 5.4.0

Run all database scripts

  • V5_04_00_00__add_configuration_properties

Property changes

Docker compose environment variables used to configure SAML Service Provider are replaced in favour of providing SAML Service Provider Configuration in the Admin console.

In order to use the same SAML Service Provider configuration as before described change, retrieve the old values of docker compose environment variables (or etcd variables) presented in a table below and set those values in corresponding fields in the Admin console configuration.

Note: To retrieve values as etcd properties you can use etcdctl get command. For example etcdctl get /token-server/engine/idp/saml-sp/signing/certificate.

The following table shows environment/etcd variables and fields in Admin console introduced to replace those variables.

Environment variable Etcd variable Field name in Admin console
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​ENABLED_​BOOLEAN /token-server/engine/idp/saml-sp/enabled-boolean SAML Service Provider enabled
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​ENTITY_​ID /token-server/engine/idp/saml-sp/metadata/entity-id Metadata entity ID
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​ID /token-server/engine/idp/saml-sp/metadata/id Metadata ID
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​VALIDITY_​DAYS /token-server/engine/idp/saml-sp/metadata/validity-days Metadata validity days
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​LANG /token-server/engine/idp/saml-sp/metadata/lang Metadata language
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​ORGANISATION_​NAME /token-server/engine/idp/saml-sp/metadata/organisation-name Metadata organisation name
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​SUPPORT_​CONTACT_​NAME /token-server/engine/idp/saml-sp/metadata/support/contact-name Metadata support contact name
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​METADATA_​SUPPORT_​CONTACT_​EMAIL /token-server/engine/idp/saml-sp/metadata/support/contact-email Metadata support contact email
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​KEYSTORE_​PASSWORD /token-server/engine/idp/saml-sp/keystore-password Keystore password
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​SIGNING_​PRIVATE_​KEY /token-server/engine/idp/saml-sp/signing/private-key Signing private key
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​SIGNING_​CERTIFICATE /token-server/engine/idp/saml-sp/signing/certificate Signing certificate
TOKEN_​SERVER_​ENGINE_​IDP_​SAML_​VELOCITY_​LOG_​LOCATION /token-server/engine/idp/saml-sp/velocity-log-location Velocity log location

All variables presented in the table are no longer supported.

5.02.00 to 5.3.0

Property changes

Basic authentication for the APIs is replaced with the API clients functionality. The properties TOKEN_SERVER_ENGINE_API_BASIC_AUTHENTICATION_USER and TOKEN_SERVER_ENGINE_API_BASIC_AUTHENTICATION_PASSWORD are no longer supported.

Run all database scripts

  • V5_03_00_00__add_transaction_signing_data.sql
  • V5_03_00_02__persist_default_api_scope_values.sql

5.00.00 to 5.01.00

Run all database scripts

  • V5_01_00_00__add_initial_custom_authenticators_config.sql

4.04.09 to 5.00.00

This is a smooth upgrade, no special actions required.