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 exampleetcdctl 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 exampleetcdctl 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
: selectUser registration
in the new dropdown calledFlows
.CLIENT_CREDENTIALS
: selectAnonymous resource calls
in the new dropdown calledFlows
.REFRESH_TOKEN
: this option has moved to the checkboxPIN authentication
underUser authentication
. It is enabled by default.FINGERPRINT_TOKEN
: this option has moved to the checkboxFingerprint authentication
underUser 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
orCUSTOM
) 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
- Go to
identity_providers
table and search for all rows containingidentity_provider_type=OTP
(identity providers of the OTP type) - Write down names of the all found identity providers (it will be needed later on if you continue the process in the Admin console).
- Change
identity_provider_type
to other available type (TWOWAYOTP
,HEADER
orCUSTOM
) for the all found identity providers.
2. Admin console operations
- Make sure the Token Server is started.
- Go to the
Configuration
->Identity Providers
Admin section. Remove all identity providers with the names you wrote down before. - 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. - 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. - 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 exampleetcdctl 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.