Version: 7.2505.x.x LTS

Appendix A - Migration guide from LTS-21 to LTS-24

What's new

NEW: Added RHEL 9 support. (NEVISAUTH-4421)
NEW: FIDO2 is now supported by the component. For more information, see Nevis FIDO2 / WebAuthn Concept and Integration Guide.

CREATE TABLE IF NOT EXISTS webauthn_sessions (
    session_id                         VARCHAR(64)  NOT NULL UNIQUE,
    created                            TIMESTAMP    NOT NULL,
    ceremony                           VARCHAR(32)  NOT NULL,
    user_id                            VARCHAR(128) NULL,
    user_name                          VARCHAR(128) NULL,
    display_name                       VARCHAR(128) NULL,
    status                             VARCHAR(32)  NOT NULL,
    status_updated_at                  TIMESTAMP    NOT NULL,
    challenge                          VARCHAR(256) NOT NULL,
    public_key_credential_options      BLOB         NOT NULL,
    error_message                      VARCHAR(256) NULL,
    reap_timestamp                     TIMESTAMP    NOT NULL,
    UNIQUE INDEX session_id_idx (session_id),
    UNIQUE INDEX challenge_idx (challenge),
    INDEX reap_timestamp_idx (reap_timestamp)
) ENGINE = INNODB;

NEW: FIDO2 uses the nevisIDM REST API, configure the rest-url property for the credential-repository. FIDO UAF still uses the SOAP endpoint, which requires administration-url to be configured.
NEW: nevisFIDO supports the Device Passcode Authenticator. (NEVISFIDO-1896)
NEW: nevisFIDO supports the Password Authenticator in the metadata and policy files. A new default policy file has been added to allow only the password authenticator to be used. (NEVISFIDO-2040)
NEW: The OutOfBandFidoUafAuthState now supports the Usernameless Authentication scenario. We recommend configuration of this use case using nevisAdmin4 patterns. (NEVISFIDO-1765)
NEW: Introduced support for PostgreSQL 15.0-15.4 databases for the session repository. (NEVISFIDO-1910)
NEW: The user agent information for the FIDO UAF dispatch targets are now stored in nevisIDM using the custom property fidouaf_user_agent upon creation or modification of the dispatch target. This custom property is new, make sure it exists in nevisIdm. The latest nevisIdm migration scripts contain it. (NEVISFIDO-1829)
NEW: a new configuration property display-name-source has been added to the FIDO2 configuration block, so integrators can better influence what property of the user is displayed during ceremonies. (NEVISFIDO-1913)
NEW: nevisFIDO now records in nevisIDM the success or failure of a FIDO2 Authentication ceremony as login information for the used credential. (NEVISFIDO-483)
NEW: nevisFIDO now records the success or failure of a FIDO UAF Authentication operation as login information for the used credential in nevisIDM. This feature requires the rest-url to be configured. (NEVISFIDO-1930)
NEW: nevisFIDO now stores the encoded keyId values of authenticators of a successful FIDO UAF authentication in the session and exposes it over its Status service. (NEVISFIDO-1962)
NEW: In case of successful authentication, now both the FidoUafAuthState and the OutOfBandFidoUafAuthState provide the FIDO UAF authenticators (AAID and keyId) to subsequent AuthStates in the notes object. (NEVISFIDO-1962)
NEW: We added OpenTelemetry metrics listing the configured FIDO protocols for analytical purposes. (NEVISFIDO-1964)
NEW: nevisFIDO supports multiple policies. Refer to the concept guide for additional details. For non-Kubernetes-based setups, the following script should be manually run: (NEVISFIDO-1843)

ALTER TABLE uaf_sessions
  ADD COLUMN IF NOT EXISTS `policy` VARCHAR(128) NULL AFTER `user_id`;

EXPERIMENTAL: We added a device credential management endpoint to nevisFIDO, which the Nevis Mobile Authentication SDK can use to manage dispatch targets and query ongoing out-of-band operations. See Device Service. (NEVISFIDO-1920) For non-docker based setups run the following SQL script to add the new database table columns:

ALTER TABLE token_sessions
    ADD COLUMN IF NOT EXISTS `dispatch_target_id` VARCHAR(64) NULL,
    ADD COLUMN IF NOT EXISTS `device_id` VARCHAR(128) NULL,
    ADD COLUMN IF NOT EXISTS `out_of_band_payload` TEXT NULL,
    ADD COLUMN IF NOT EXISTS `additional_information` TEXT NULL,
    ADD INDEX IF NOT EXISTS `token_session_device_id_idx` (`device_id`, `status`)
;

What has changed

CHANGED: Configuring FIDO2 and FIDO UAF leads to the following changes in the nevisFIDO instance configuration YAML file:
- Both the fido2 and fido-uaf blocks have a Boolean property enabled.
  - For backwards compatibility, the change for fido-uaf is not mandatory, and if the enabled property is missing, then the deciding factor is whether the fido-uaf configuration block is present.
- The top-level configuration block authorization is now present under the fido-uaf and fido2 blocks.
- The top-level configuration block dispatchers is now present under the fido-uaf block.
- Instead of deprecated the top-level configuration block dispatch-target-repository, use credential-repository instead.
CHANGED: The nevisFIDO AuthStates delivered in the nevisfidocl package use the HttpClient introduced in nevisAuth. This means that the configuration of the key material for the AuthStates has changed.
- Instead of trustStoreRef use httpclient.tls.trustStoreRef.
- Instead of keyStoreRef and keyObjectRef use httpclient.tls.keyObjectRef. If the previous keyObjectRef was unique, you can drop the value in keyStoreRef. Otherwise, use the value in the new property like the following: value of keyStoreRef / value of keyObjectRef
CHANGED: We greatly simplified the username mapping in nevisFIDO to avoid integration pitfalls and potential use-case errors. The credential-repository.username-mapper configuration block is now replaced by a single property user-attribute.
CHANGED: The loginId of the user is now stored in WebAuthn sessions in the database. (NEVISFIDO-1877) For non docker based setups, the following script should be run manually:

ALTER TABLE webauthn_sessions
    ADD COLUMN login_id VARCHAR(300) NULL;

CHANGED: The length of the user_name column of loginId in nevisIDM, now supports up to 300 characters. The error_message column is changed to be able to store text dynamically which allows larger error messages to be stored in the session. (NEVISFIDO-1873) For non docker based setups the following script should be run manually:

ALTER TABLE webauthn_sessions
    MODIFY COLUMN user_name VARCHAR(300),
    MODIFY COLUMN error_message TEXT;

CHANGED: We now set the java.io.tmpdir system property by default to /var/opt/nevisfido/<instance>/tmp. When nevisfido is started, Jetty requires it at runtime. Originally the system /tmp folder was used for this purpose, however at some cases it can happen that a system cleanup job deletes the Jetty prefixed directories which causes nevisfido to return errors. (NEVISAUTH-4461)
CHANGED: We switched the logging implementation to Log4j2 from Logback. The logging configuration now must be named /var/opt/nevisfido/<instance>/conf/logging.yml (instead of logback.xml) and the content should be in the log4j2 yaml format.
CHANGED: New Jetty version used in nevisFIDO performs more strict validation for TLS connections. The SNI will be checked for matching the hostname in the configured certificate. (NEVISFIDO-1921)
CHANGED: credential-repository.client-id' is now a mandatory configuration property representing the nevisIDM client. It replaces credential-repository.client-name. (NEVISFIDO-483)
CHANGED: credential-repository.rest-url is now a mandatory configuration property for credential-repository.type: nevisidm. (NEVISFIDO-483)
CHANGED: The minimum required nevisIDM Admin Service SOAP interface version was increased to v1_46. If a nevisFIDO instance is configured to support FIDO UAF then the credential-repository section of its nevisfido.yml has to be updated. The admin-service-version has to be set to v1_46 and in case the administration-url config parameter value defined a specific version in the URL like /nevisidm/services/v1_42/AdminService then it has to be also updated accordingly to /nevisidm/services/v1_46/AdminService. (NEVISFIDO-2000)
FIXED: nvluser, nvbuser, and members of the nevisadmin group could not use the nevisAuth Admin CLI commands. The issue is now fixed. (NEVISFIDO-1577)
FIXED: The facet configuration property is now not incorrectly logged as unknown. (NEVISFIDO-1631)
FIXED: The admin CLI now correctly lists instances located in a symlink directory. (NEVISFIDO-1635)
FIXED: Component version in jar manifest files and logs. (NEVISFIDO-1662)
FIXED: The client-id of the credential-repository is now parsed as a string, instead of as an integer. (NEVISFIDO-1715)
FIXED: We decreased the detail level of the username lookup query to nevisIDM using username-mapper. The fix affects UAF only, and provides performance increase on nevisIDM side. (NEVISFIDO-1665)
FIXED: Double query of nevisIDM credentials in case of UAF authentication is now reduced by request-scoped caching. (NEVISFIDO-1673)
FIXED: The expected position of extId inside username-mapper in the configuration is now validated at startup time. (NEVISFIDO-1701)
FIXED: From now on, REST query to nevisIDM is not sent to look up the extId if an empty or missing username is received from the client in the JSON request. (NEVISFIDO-1701)
FIXED: The nevisIDM user lookup was broken when using FIDO UAF only in the configuration. The use-case connects to nevisIDM using the soap interface where the detail level was incorrectly set to exclude. The detail level is now reset to low to fix the issue. (NEVISFIDO-1742)
FIXED: The session reaper does not fail with an ERROR_REAPING_SESSIONS_FROM_SQL_STORAGE error when FIDO2 is not configured. (NEVISFIDO-1748)
FIXED: The nevisfido-server CLI not properly parsing multiple options specified in the JAVA_OPTS. (NEVISFIDO-1786)
FIXED: Dispatch token issue with push dispatching in the OutOfBandFidoUafAuthState where the dispatcher property was set as auth state property but the dispatchTargetId was not provided. (NEVISFIDO-1855)
FIXED: Sending push notifications is no longer attempted via FCM when the push notification is disabled. (NEVISFIDO-1879)
FIXED: We fixed the incorrectly stored system default timezone timestamps in the database. After the fix, only UTC timestamps will be stored. Existing data can be migrated with the following script if required. (in case your nevisFIDO instance was NOT running in UTC, or existing sessions are required to keep consistent) Replace the proper timezone information in the script where nevisFIDO was running! When you check the data, note that mysql or any other client will convert timestamps to the timezone of the session. So in order to see the UTC timestamp values in your sql client you have to change your client's session timezone to UTC in the current session: SET @@session.time_zone = '+00:00';. (NEVISFIDO-1817)

   UPDATE uaf_sessions SET created = CONVERT_TZ(created, 'Europe/Zurich', 'UTC'), status_updated = CONVERT_TZ(status_updated, 'Europe/Zurich', 'UTC'), reap_timestamp = CONVERT_TZ(reap_timestamp, 'Europe/Zurich', 'UTC');
   UPDATE token_sessions SET created = CONVERT_TZ(created, 'Europe/Zurich', 'UTC'), status_updated = CONVERT_TZ(status_updated, 'Europe/Zurich', 'UTC'), reap_timestamp = CONVERT_TZ(reap_timestamp, 'Europe/Zurich', 'UTC');
   UPDATE webauthn_sessions SET created = CONVERT_TZ(created, 'Europe/Zurich', 'UTC'), status_updated_at = CONVERT_TZ(status_updated_at, 'Europe/Zurich', 'UTC'), reap_timestamp = CONVERT_TZ(reap_timestamp, 'Europe/Zurich', 'UTC');

FIXED: Session creation time was incorrectly overwritten during updates, because of the MariaDB behaviour defined here. For non docker based setups the following script should be manually run:

   ALTER TABLE uaf_sessions MODIFY COLUMN `created` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE uaf_sessions MODIFY COLUMN `status_updated` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE uaf_sessions MODIFY COLUMN `reap_timestamp` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);   
   ALTER TABLE token_sessions MODIFY COLUMN `created` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE token_sessions MODIFY COLUMN `status_updated` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE token_sessions MODIFY COLUMN `reap_timestamp` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE webauthn_sessions MODIFY COLUMN `created` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE webauthn_sessions MODIFY COLUMN `status_updated_at` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);
   ALTER TABLE webauthn_sessions MODIFY COLUMN `reap_timestamp` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6);

FIXED: an unknown username received across nevisFIDO API's have been standardized to return either HTTP 403 Forbidden, UAF statusCode 1403, or in case of dispatching with a new dispatchResult: userNotFound. (NEVISFIDO-1889)
FIXED: Unknown object and array properties in incoming JSON payloads are now properly ignored upon parsing. Additionally, the nested properties of unknown JSON objects and arrays are no longer logged. (NEVISFIDO-1908)
FIXED: Dispatch target and the UAF credential is only linked for the first authenticator registration of a user but not for additional ones. (NEVISFIDO-2043)
FIXED: Session update operations did not check if the update was successful. (NEVISFIDO-2050)
FIXED: UAF credential login information in nevisIdm was incorrectly updated for all UAF credentials of the user during authentication instead of only the credential used for the current authentication operation. (NEVISFIDO-2047)

What has been removed

REMOVED: We removed the internal dependency to nevis-i18n. (NEVISFIDO-1722)
REMOVED: We removed the vmargs legacy command in administrative cli. Use the nevisfido <instance> config env to configure the JAVA_OPTS. (NEVISAUTH-3134)
REMOVED: We removed the jcan-log and jcan-optrace third-party dependencies. OpTrace logging is replaced by OpenTelemetry. (NEVISFIDO-1583)
DEPRECATED: The configuration property dispatch-target-repository is no longer parsed by the server. The configuration of credential-repository is used as the configuration of the dispatch target repository instead (NEVISFIDO-1444). We removed the dispatch-target-repository entry because separate configurations for the dispatch and credential repositories provides no added value. You can safely remove the dispatch-target-repositoryentry in the configuration YAML file completely, then the credential-repository configuration block is used. If you keep the dispatch-target-repository,the configuration is ignored and a warning is logged.

Third-party dependency changes

UPGRADED: We upgraded the Apache EL third-party dependency to version 10.1.16. (NEVISFIDO-1991)
UPGRADED: We upgraded the Apache Http Client third-party dependencies to version 5.3.1. (NEVISFIDO-2006)
UPGRADED: We upgraded the Apache Http Core third-party dependencies to version 5.2.4. (NEVISFIDO-2006)
UPGRADED: We upgraded the Bouncy Castle third-party dependencies to version 1.78. (NEVISFIDO-2062)
UPGRADED: We upgraded the HikariCP third-party dependency to version 5.1.0. (NEVISFIDO-1991)
UPGRADED: We upgraded the Jackson third-party dependencies to version 2.17.0. (NEVISFIDO-2006)
UPGRADED: We upgraded the Jakarta servlet api third-party dependency to version 6.0 (NEVISFIDO-2012)
UPGRADED: We upgraded the Jaxb third-party dependency to version 2.3.6. (NEVISFIDO-1871)
UPGRADED: We upgraded the Jetty third-party dependencies to version 12.0.7. (NEVISFIDO-2012)
UPGRADED: We upgraded the MariaDB connector third-party dependency to version 3.3.3. (NEVISFIDO-2006)
UPGRADED: We upgraded the Opentelemetry api third-party dependency to version 1.37.0. (NEVISFIDO-2006)
UPGRADED: We upgraded the Rx java third party dependency is updated to version 2.2.21. (NEVISFIDO-1567)
UPGRADED: We upgraded the Snakeyaml third-party dependencies to version 2.0. (NEVISFIDO-1761)
UPGRADED: We upgraded the Spring third-party dependencies to version 6.1.6. (NEVISFIDO-2065)
UPGRADED: We upgraded the Spring-boot third-party dependency to version 3.2.4. (NEVISFIDO-2065)
UPGRADED: We upgraded the Webauthn4j api third-party dependency to version 0.23.0.RELEASE. (NEVISFIDO-2006)
UPGRADED: We upgraded the Woodstox-core third-party dependency to version 6.5.1. (NEVISFIDO-1844)
UPGRADED: We upgraded the ZXing third-party dependency to version 3.5.3. (NEVISFIDO-2006)
UPGRADED: We upgraded the checker-qual third-party dependency to version 3.42.0. (NEVISFIDO-1991)
UPGRADED: We upgraded the commons-io third-party dependency to version 2.13.0. (NEVISFIDO-1871)
UPGRADED: We upgraded the commons-lang3 third-party dependency to version 3.14.0. (NEVISFIDO-1991)
UPGRADED: We upgraded the google-api-client third-party dependency to version 2.4.0. (NEVISFIDO-2006)
UPGRADED: We upgraded the google-auth-library third-party dependency to version 1.23.0. (NEVISFIDO-2006)
UPGRADED: We upgraded the google-autovalue third-party dependency to version 1.10.4. (NEVISFIDO-1583)
UPGRADED: We upgraded the guava third-party dependency to version 33.1.0-jre. (NEVISFIDO-2006)
UPGRADED: We upgraded the hibernate-validator third-party dependency to version 8.0.0.Final (NEVISFIDO-1583)
UPGRADED: We upgraded the jakarta-validation third-party dependency to version 3.0.2. (NEVISAUTH-4089)
UPGRADED: We upgraded the jaxws-rt third-party dependency to version 4.0.2. (NEVISAUTH-4535)
UPGRADED: We upgraded the jcan-saml, jcan-sectoken dependency to version 8.2405.0.x. (NEVISFIDO-2006)
UPGRADED: We upgraded the log4j third-party dependencies to version 2.23.1. (NEVISFIDO-2006)
UPGRADED: We upgraded the mariadb-java-client third-party dependency to version 3.3.3. In case you used configuration parameters in the JDBC url check the removed options here. Other notable difference is that the driver no longer sets certain properties including the autocommit, check your database configuration and add the ?autocommit=true to your connection url if needed. The new driver also allows better logging options, see here.(NEVISFIDO-1769)
UPGRADED: We upgraded the nimbus third-party dependency to version 9.37.3. (NEVISFIDO-2014)
UPGRADED: We upgraded the slf4j third-party dependency to version 2.0.12. (NEVISFIDO-2006)
UPGRADED: We upgraded the xmlbeans third-party dependency to version 5.1.1. (NEVISFIDO-1583)
UPGRADED: We upgraded the xmlsec third-party dependency to version 3.0.3. (NEVISFIDO-1939)

Appendix A - Migration guide from LTS-21 to LTS-24

What's new​

What has changed​

What has been removed​

Third-party dependency changes​

What's new

What has changed

What has been removed

Third-party dependency changes