Upgrade instructions old versions

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.

4.04.08 to 4.04.09

Adapt Docker Compose variables

New (not required):

  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PREEMPTIVE_AUTH_ENABLED_BOOLEAN

4.04.07 to 4.04.08

Run all database scripts

  • V4_04_08_00__add_registration_id_to_fido_user_authenticators.sql

Adapt Docker Compose variables

Configuration is now done via Docker Compose variables instead of ETCD. See the documentation for more details.

New (not required):

  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_ENABLED_BOOLEAN
  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_USERNAME
  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PASSWORD
  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_SCHEMA
  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_HOST
  • TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PORT

4.04.05 to 4.04.06

Run all database scripts (only for Oracle and MSSQL)

  • V4_04_06_00__correct_invalid_index_on_idp_attribute_mappings_table.sql

4.03.00 to 4.04.00

Run all database scripts

  • V4_04_00_00__change_client_id_to_fk_in_fido_user_authenticators.sql

4.04.00 to 4.04.01

Run all database scripts

  • V4_04_01_00__missing_event_index.sql
  • V4_04_01_01__add_actual_user_ids_in_events.sql

4.02.02 to 4.03.00

Run all database scripts

  • V4_03_00_01__add_fido_config.sql
  • V4_03_00_02__fido_authenticators_renamed.sql
  • V4_03_00_03__add_fido_policy_mapping_to_moble_auth_type.sql
  • V4_03_00_05__add_index_to_fido_user_authenticators.sql

Adapt config parameters in ETCD

Removed

  • /token-server/engine/mobile-authentication/fido/base-uri
  • /token-server/engine/mobile-authentication/fido/app-keys-json
  • /token-server/engine/mobile-authentication/fido/policy-mapping-json

New (not required)

  • /token-server/common/features/fido-enabled-boolean By default this property has the value true. Set it to false to disable FIDO authentication.
  • /token-server/engine/cache/application-properties-cache/ttl-seconds By default this property has the value of 300 seconds (5 minutes).

Other changes

The environment variable EXPERIMENTAL is no longer used.

4.01.01 to 4.02.00

Run all database scripts

  • V4_02_00_00__rename_statistics.sql
  • V4_02_01_00__add_device_names_encoded_to_clients.sql
  • V4_02_01_01__make_clients_redirect_url_nullable.sql
  • V4_02_01_02__add_foreign_key_to_auth_property_messages.sql (only MSSQL)

Adapt config params in ETCD:

Removed:

  • /token-server/admin/general/recent-events/period-minutes

3.17 to 4.01

Run all database scripts

  • V4_01_00_00__add_length_to_pin_policies.sql
  • V4_01_00_01__add_max_allowed_resends_to_auth_properties.sql
  • V4_01_00_02__move_push_credentials_to_separate_table.sql
  • V4_01_00_03__add_foreign_key_from_platform_to_push.sql
  • V4_01_00_04__add_api_only_to_scopes.sql
  • V4_01_00_05__add_unique_constraint_to_push_messaging_config_name_column.sql
  • V4_01_00_06__add_message_table_for_i18n.sql
  • V4_01_00_08__add_user_id_event_date_index_on_events.sql (only MySQL database)
  • V4_01_00_09__create_db_templates_structure.sql
  • V4_01_00_10__add_default_column_to_template_sets_table.sql
  • V4_01_01_00__remove_join_table_from_template_sets.sql

Adapt config params in ETCD:

New (not required):

  • /token-server/engine/notification-api/enabled-boolean By default this property has value false, to keep using the notification api enable this property.
  • /token-server/engine/mobile-authentication/deprecated-api/enabled By default this property has value false, to keep using the old mobile authentication endpoint enable this property.

Removed:

  • /token-server/admin/managementinfo/data-server/base-uri

3.16 to 3.17

Run all database scripts

  • V3_17_00_00__add_fido_authenticators.sql
  • V3_17_02_00__make_client_pk_non_clustered.sql (only MSSQL)
  • V3_17_03_00__make_auth_prop_fallback_nullable.sql (only MSSQL)

3.15 to 3.16

Run all database scripts

  • V3_16_00_00__add_callback_uri_config.sql

3.14 to 3.15

Changed environment variables

In version 3.15 The embedded ldap server is removed. So the environmental variables for ldap are not needed anymore. Also the way to configure etcd is changed.

New environment variables

  • CONFIG_BACKEND
  • CONFIG_PREFIX

Removed environment variables

  • TOKENSERVER_LDAP_ENABLED
  • ETCD_PORT
  • ETCD_HOST
  • ETCD_URI
  • ETCD_PREFIX

Environment variable that became mandatory

  • TOKENSERVER_ENGINE_ENABLED
  • TOKENSERVER_CLIENT_ENABLED
  • TOKENSERVER_ADMIN_ENABLED

Run all database scripts

  • V3_15_00_00__add_statistics.sql
  • V3_15_00_01__migrate_idp_attributes_to_separate_table.sql
  • V3_15_00_02__add_fido_enable_column.sql
  • V3_15_00_03__add_secret_to_identity_providers.sql

Changed mandatory etcd parameters

Move

  • /token-server/admin/general/app-config/token-server-engine/base-uri to /token-server/common/engine-base-uri

Remove

  • /token-server/engine/authentication/onegini

3.13 to 3.14

End user api upgrade

In version 3.14 a new version of the device api was introduced. It is mandatory to use this api version when using the multiple profiles feature.

3.12 to 3.13

Run all database scripts

  • V3_13_00_00__add_profile_id_to_access_tokens.sql
  • V3_13_00_01__add_token_attempt_failure_count.sql
  • V3_13_00_02__make_name_field_in_pin_policy_longer.sql (only MSSQL)
  • V3_13_00_03__remove_push_token_unique.sql
  • V3_13_00_04__add_profile_id_to_application_instance.sql

New mandatory etcd parameters

  • /token-server/client/client/profileId
  • /token-server/client/client/testUserId

3.11 to 3.12

Run all database scripts (only MSSQL)

  • V3_12_01_00__certificates_uniqueidentifier.sql
  • V3_12_01_01__events_uniqueidentifier.sql
  • V3_12_01_02__access_grant_uniqueidentifier.sql
  • V3_12_01_03__access_tokens_uniqueidentifier.sql
  • V3_12_01_04__application_instances_uniqueidentifier.sql
  • V3_12_01_05__auth_properties_uniqueidentifier.sql
  • V3_12_01_06__auth_property_messages_uniqueidentifier.sql
  • V3_12_01_07__client_config_uniqueidentifier.sql
  • V3_12_01_08__mobile_platform_version_uniqueidentifier.sql
  • V3_12_01_09__pin_policy_uniqueidentifier.sql
  • V3_12_01_10__clients_uniqueidentifier.sql
  • V3_12_01_11__mobile_platforms_uniqueidentifier.sql
  • V3_12_01_12__identity_providers_uniqueidentifier.sql
  • V3_12_01_13__idp_attribute_mapping_uniqueidentifier.sql
  • V3_12_01_14__consents_uniqueidentifier.sql
  • V3_12_01_15__add_missing_indices.sql
  • V3_12_01_16__remove_idp_entity_id_unique_index.sql

New mandatory etcd parameters

  • /token-server/client/dynamic/register/os/version
  • /token-server/client/dynamic/register/client/architecture

3.09 to 3.10

Run all database scripts

  • V3_10_00_00__add_pin_retry_counter.sql

3.08 to 3.09

Run all database scripts

  • V3_09_00_00__certificates.sql
  • V3_09_00_01__add_public_base_uri_to_client_config.sql
  • V3_09_00_02__add_certificates_to_client_config.sql
  • V3_09_00_03__add_client_resource_gateway.sql

3.07 to 3.08

Run all database scripts

  • V3_08_00_00__add_non_persistent_scope_type.sql
  • V3_08_00_01__add_api_version_to_oauth_client.sql
  • V3_08_00_02__add_apns_environment.sql
  • V3_08_00_03__remove_unused_auth_props.sql

Adapt config params in ETCD:

New:

  • /token-server/engine/header-auth/parameters/white-list
  • /token-server/common/app-config/apns/production/host
  • /token-server/common/app-config/apns/production/port
  • /token-server/common/app-config/apns/sandbox/host
  • /token-server/common/app-config/apns/sandbox/port
  • /token-server/common/app-config/apns-feedback/production/host
  • /token-server/common/app-config/apns-feedback/production/port
  • /token-server/common/app-config/apns-feedback/sandbox/host
  • /token-server/common/app-config/apns-feedback/sandbox/port

Removed:

  • /token-server/engine/mobile-authentication/pgp/disabled-boolean

3.06 to 3.07

Run all database scripts

  • V3_07_00_00__add_type_to_access_tokens.sql
  • V3_07_00_01__add_index_on_access_tokens_for_type.sql

3.05 to 3.06

There are no specific actions necessary to upgrade from version 3.05 to 3.06.

3.04 to 3.05

Run all database scripts

  • V3_05_00_01__add_mobile_platforms.sql
  • V3_05_00_02__add_development_mode_to_client_config.sql
  • V3_05_00_03__platform_version_add_payload_encryption_flag.sql

3.03 to 3.04

Run all database scripts

  • V3_03_03_00__added_architecture_to_clients.sql

3.02 to 3.03

Automatic schema migrations

  • If you want to use the automatic flyway database schema migrations the database schema needs to be up-to-date (schema version: 3.02.00.01) before you start the 3.03.xx version of the TS.
  • If you do not want to use the automatic schema migrations you need to disable this option. Please have a look at the database paragraph in the Token Server configuration section.

Change templates

  • New template two-way-otp-cancel.html
  • The two-way-otp-dead-end.html page has an extra parameter ${redirectUri} which can be used to send the client back to the app.
<a th:href="${redirectUri}" href="about:blank"><p th:text="#{twoWayOtp.deadEnd.body}">
     _Your authentication session timed out. Please return to the APP to authenticate again.
</p></a>

Run all database scripts

  • V3_03_00_00__added_wns_properties_to_mobile_platform_versions.sql

3.00 to 3.02

Change endpoints in use

  • If you are using the client validation endpoint /validation/client you should now switch to /client/validate
  • Add X-Onegini-App-.. headers to the request

Change templates

  • All templates named authorization_complete.html should now be named authorization-complete.html

Change properties

A new property is introduced for retrieving data from Elasticsearch. Add the base URI of Elasticsearch to the etcd configuration:

curl 'http://127.0.0.1:4001/v2/keys/token-server/admin/managementinfo/data-server/base-uri' -XPUT -d value=http://localhost:9200

Run all database scripts

  • V3_02_00_00__platform_version_force_upgrade_support.sql
  • V3_02_00_01__platform_version_add_tampering_protection_flag.sql

2.04.05 to 3.00

Change properties

Move all properties to etcd. Onegini will help you with that migration.

Run database scripts

  • V3_00_00_00__added_additional_authenticator_type.sql

2.04.04 to 2.04.05

Run:

  • V2_04_04_05__add_complete_page_disabled_to_client_config.sql

2.03.x to 2.04.04

Run database scripts

Run the following database scripts in the given order

  • V2_04_00_00__renamed_meta_data_uri_in_identity_providers.sql
  • V2_04_00_01__add_metadata_to_identity_providers.sql
  • V2_04_00_02__add_pin_policies.sql
  • V2_04_00_03__add_fingerprint_to_client.sql
  • V2_04_00_04__openid_scope_to_scopes.sql
  • V2_04_03_00__added_openid_attribute_mapping.sql
  • V2_04_03_01__inserted_openid_user_info_scopes.sql
  • V2_04_03_02__added_signature_and_encryption_to_client_config.sql
  • V2_04_04_00__added_push_server_endpoint.sql
  • V2_04_04_02__added_expiration_to_openid_client_config.sql
  • V2_04_04_03__added_public_private_key_column_to_open_id_config.sql
  • V2_04_04_04__added_on_delete_cascade_to_application_related_constraints.sql