Appendix A - Migrating from LTS-24 to LTS-26
This guide covers all breaking changes, removed features, and required configuration updates when upgrading nevisFIDO from LTS-24 (7.2405.x) to LTS-26 (8.2607.x). Changes introduced in the rolling releases 8.2411, 8.2505, and 8.2511 are included here for completeness, as LTS-24 customers upgrading directly to LTS-26 must account for all of them.
nevisFIDO LTS-26 requires Java 25. LTS-24 ran on Java 17. You must upgrade the Java runtime as part of this migration. See Java Runtime Upgrade for details.
The SOAP-based nevisIDM connection has been fully removed. All nevisFIDO instances that use FIDO UAF must be configured with the REST connection before upgrading. See SOAP nevisIDM Connection Removed for details.
What's new
The following notable features were introduced between LTS-24 and LTS-26.
Application Attestation
nevisFIDO now supports Application Attestation for both Android and iOS. This allows verifying that the authenticator app is genuine and has not been tampered with. See the Application Attestation documentation for details. (NEVISFIDO-2297)
FIDO Alliance Metadata Service (MDS3)
nevisFIDO now supports the official FIDO Alliance Metadata Service. See the FIDO2 Authenticator Metadata documentation for details. (NEVISFIDO-2236)
FIDO UAF Full Basic Attestation: Permissive Mode
FIDO UAF Full Basic Attestation now supports a permissive mode, enabling looser validation during a transitional period for device migrations. See the Surrogate vs. Full Basic Attestation documentation for details. (NEVISFIDO-2306)
Android Key Attestation: Per-Policy Configuration
Android key attestation verification is now configured per-policy via the ch.nevis.auth.fido.uaf.android-key-attestation-verifications policy extension, replacing the former global android-verification-level property. This enables fine-grained control over attestation checks per UAF policy and supports OR logic across multiple device profiles (for example, standard devices and custom-ROM devices in a single policy). Pre-built example policy files are shipped in the conf/policy directory of the nevisFIDO installation. See Android Key Attestation Configuration for migration details. (NEVISFIDO-2479)
Cancel Service
A new Cancel Service allows cancelling an ongoing FIDO UAF or FIDO2 registration or authentication operation on the server side before the client completes it. The service is disabled by default and must be explicitly enabled. Secure this endpoint at the network or proxy layer before enabling it, as it is unauthenticated by default. See UAF Cancel Service and FIDO2 Cancel Service for details. (NEVISFIDO-2577)
Link QR Code Dispatcher
A new Link QR Code Dispatcher generates a QR code containing a deep link that can be scanned using the default mobile OS camera app, without requiring the Nevis Mobile Authentication App. See the Link QR Code Dispatcher documentation for details. (NEVISFIDO-2573)
FCM Dispatcher: QR Code and Link Response
The FCM Dispatcher now supports returning a QR code or a link in its response, in addition to sending a push notification. See the FCM Dispatcher documentation for details. (NEVISFIDO-2620)
Custom Liveness and Readiness Server
nevisFIDO now includes a custom Liveness and Readiness server that operates independently of Spring Boot Actuator. The server type is controlled by the management.healthchecks.type property (custom (default) or spring-boot). Both types expose /nevisfido/liveness and /nevisfido/readiness endpoints. The management.healthchecks.ignore-indicators property allows specific health indicators to be excluded from the readiness check. See Management Endpoints for details. (NEVISFIDO-2588)
Dedicated-Entity REST API for Dispatch Targets and iOS App Attestation Credentials
nevisFIDO now supports the new nevisIDM dedicated-entity REST API to manage dispatch targets and iOS App Attestation credentials. When credential-repository.use-dedicated-entities is set to true, nevisFIDO uses the dedicated-entity API instead of the legacy generic-credential-based implementation. See nevisIDM Credential Repository for migration details. (NEVISFIDO-2583)
Session Repository Connection Pool Configuration
New configuration properties allow tuning the session repository database connection pool: min-connection-pool-size, max-connection-pool-size (both default to 10), connection-timeout (default 30 seconds), and max-connection-idle-time. See the SQL Session Repository configuration for the full list of available properties. (NEVISFIDO-2401, NEVISFIDO-2452)
JAVA_OPTS Variable Resolution in env.conf
The JAVA_OPTS property in env.conf now supports variable resolution in the same way as nevisfido.yml. Note that the $ character must be escaped as \$. (NEVISFIDO-2567)
What has changed
Java Runtime Upgrade
nevisFIDO LTS-24 ran on Java 17. LTS-26 runs on Java 25. The upgrade took place in two steps:
- Java 17 → Java 21: introduced in rolling release 8.2505.3.2 (NEVISFIDO-2280)
- Java 21 → Java 25: introduced in LTS-26 8.2607.x (NEVISFIDO-2607)
You must install Java 25 on all hosts running nevisFIDO before upgrading to LTS-26. Java 17 and 21 are no longer supported.
SOAP nevisIDM Connection Removed
The SOAP-based connection to nevisIDM has been fully removed from nevisFIDO. All instances that use FIDO UAF must be configured to use the REST connection. This change was introduced in rolling release 8.2505.3.2. (NEVISFIDO-2239)
Remove the following properties from your nevisfido.yml if they are present:
idm-connection-typeadministration-urladmin-service-versionclient-name
Ensure that credential-repository.rest-url is configured and points to the nevisIDM REST endpoint. For example:
credential-repository:
rest-url: https://<nevisidm-host>/<nevisidm-instance>/rest/v1
Metadata and Policy Paths Now Use a List
The fido-uaf.metadata.path and fido-uaf.policy.path configuration properties have been replaced by fido-uaf.metadata.paths and fido-uaf.policy.paths, which accept a list of paths. This change was introduced in rolling release 8.2511.0.4. (NEVISFIDO-2505)
Update your nevisfido.yml to use the new list format:
# Old format (no longer accepted):
fido-uaf:
metadata:
path: conf/metadata
policy:
path: conf/policy
# New format:
fido-uaf:
metadata:
paths:
- conf/metadata
policy:
paths:
- conf/policy
The inline value property and its precedence rules are unchanged.
Metadata and Policy Runtime Reloading Removed
The fido-uaf.metadata.polling-period and fido-uaf.policy.polling-period configuration properties have been removed, along with the mechanism that allowed metadata and policy files to be reloaded at runtime without a restart. A nevisFIDO instance must now be restarted after any change to these files. This change was introduced in rolling release 8.2505.3.2. (NEVISFIDO-2241)
Remove fido-uaf.metadata.polling-period and fido-uaf.policy.polling-period from your nevisfido.yml. These properties are no longer recognized and will cause a startup error if present.
Self-Signed Bootloader Keys Must Be Base16 Encoded
Self-signed bootloader keys must now be provided in base16 (hexadecimal) encoding instead of base64. This change was introduced in LTS-26 8.2607.x. (NEVISFIDO-2613)
The base16 format aligns with how GrapheneOS publishes its bootloader keys, removing the need for customers to convert the keys before use.
If your nevisFIDO instance is configured with self-signed bootloader keys, re-encode the key values from base64 to base16 in your FIDO UAF policy files before upgrading to LTS-26.
Android Key Attestation Configuration Moved to Policy Extension
The global configuration properties fido-uaf.full-basic-attestation.android-verification-level and fido-uaf.full-basic-attestation.android-permissive-mode-enabled have been removed. Android key attestation verification is now configured per-policy via the ch.nevis.auth.fido.uaf.android-key-attestation-verifications policy extension, providing fine-grained control over attestation checks for each UAF policy. This change was introduced in LTS-26 8.2607.x. (NEVISFIDO-2479)
The extension data field accepts either a single configuration object or an array of objects. When an array is provided, validation succeeds if the device matches any of the configurations (OR logic), enabling use cases such as supporting both standard and custom-ROM devices (for example, GrapheneOS) in the same policy.
Pre-built example policy files are shipped in the conf/policy directory of the nevisFIDO installation:
android-key-attestation-strict.jsonandroid-key-attestation-strict-strongbox.jsonandroid-key-attestation-grapheneos.json
Remove fido-uaf.full-basic-attestation.android-verification-level and fido-uaf.full-basic-attestation.android-permissive-mode-enabled from your nevisfido.yml. Update your FIDO UAF policy files to include the ch.nevis.auth.fido.uaf.android-key-attestation-verifications extension. See the policy examples and field reference for migration details.
Android Key Revocation Check: Stricter Health Behavior
nevisFIDO now rejects FIDO UAF Full Basic Attestation requests when the Android key revocation CRL is missing or cannot be fetched. In addition, the health endpoint reports a down status if the CRL has not been successfully updated within a configurable time window. The new property fido-uaf.full-basic-attestation.android-attestation-key-revocation.health-service-down-if-outdated-for controls how long an outdated CRL is tolerated before the health status changes to down. This change was introduced in rolling release 8.2511.0.4. (NEVISFIDO-2471)
Review your network configuration to ensure nevisFIDO can reach the Google Android key revocation endpoint. See Outbound Connections for the required endpoint details. If CRL fetching is unreliable in your environment, configure the health-service-down-if-outdated-for property to an appropriate tolerance window so that temporary network issues do not immediately affect the health status. The androidAttestationKeyRevocation health indicator reflects the current CRL status.
Plugin Classpath No Longer Hardcoded
The plug-in classpath is no longer hardcoded in the startup script. A new PLUGINS variable in env.conf controls which paths are added to the Java classpath for plug-in discovery. This change was introduced in LTS-26 8.2607.x. (NEVISFIDO-2558)
If your nevisFIDO instance has plug-ins deployed, add the following line to your env.conf:
PLUGINS="plugins/*"
Without this entry, nevisFIDO will start but plug-ins will not be loaded. The template env.conf has been updated to include this variable. See the Plug-Ins deployment section for details.
Non-Docker Database Migration
For non-Docker based installations, a new column must be added to the token_sessions table to support the extended FIDO UAF status service. This change was introduced in rolling release 8.2411.0.13. (NEVISFIDO-2145)
Run the following SQL statement against your nevisFIDO database before starting the upgraded instance:
ALTER TABLE token_sessions
ADD COLUMN IF NOT EXISTS `dispatch_target_ext_id` VARCHAR(128) NULL;
RHEL8 No Longer Supported
RHEL8 Linux is no longer supported by nevisFIDO. RHEL9 is the supported platform. RHEL8 was supported in LTS-24 (7.2405.x). (NEVISAUTH-4667)
Ensure all hosts running nevisFIDO LTS-26 run RHEL9 or a compatible supported distribution. Consult the nevisFIDO installation guide for the current list of supported operating systems.
FIDO2 Session Format Change
The PublicKeyCredentialOptions stored in the FIDO2 session (the webauthn_sessions table) changed its serialization format in LTS-24 (7.2405.0.2). Ongoing registration or authentication ceremonies started before upgrading to LTS-24 will fail after the upgrade, because the previous session format is not compatible. This is only relevant if upgrading from a pre-7.2405.0.2 LTS-24 patch. (NEVISFIDO-2006)
nevisFIDO REST Endpoints No Longer Return Null Attributes
nevisFIDO REST endpoints no longer include JSON attributes where the value is null. Clients that explicitly check for the presence of null-valued attributes in response bodies may need to be updated. (NEVISFIDO-2321)
Session Repository Connection Timeout and Lifetime Defaults Aligned
The default values for connection-timeout and max-connection-lifetime on the SQL session repository were aligned in LTS-26. The current defaults are connection-timeout: 30s and max-connection-lifetime: 30m. (NEVISFIDO-2571)
If you have not explicitly configured these properties, verify that these defaults are appropriate for your database setup, particularly the max-connection-lifetime relative to your database server's idle connection timeout. See the SQL Session Repository configuration for details.
What has been removed
| Removed item | Replacement | Since |
|---|---|---|
| SOAP nevisIDM connection | REST connection via credential-repository.rest-url | 8.2505.3.2 |
idm-connection-type property | Not applicable (REST is the only connection type) | 8.2505.3.2 |
administration-url property | credential-repository.rest-url | 8.2505.3.2 |
admin-service-version property | Not applicable | 8.2505.3.2 |
client-name property | credential-repository.client-id | 8.2505.3.2 |
fido-uaf.metadata.polling-period | Restart the instance after metadata changes | 8.2505.3.2 |
fido-uaf.policy.polling-period | Restart the instance after policy changes | 8.2505.3.2 |
fido-uaf.full-basic-attestation.android-verification-level | Policy extension ch.nevis.auth.fido.uaf.android-key-attestation-verifications | 8.2607.x |
fido-uaf.full-basic-attestation.android-permissive-mode-enabled | permissiveModeEnabled in the policy extension data | 8.2607.x |
| Hardcoded plug-in classpath in startup script | PLUGINS variable in env.conf | 8.2607.x |
| Experimental JavaScript Login Application (nevisFIDO client RPM) | nevisAdmin 4 pattern nevisadmin-plugin-mobile-auth | 8.2411.0.13 |
commons-logging library | Spring's own logging bridge | 8.2511.0.4 |
| RHEL8 operating system support | RHEL9 | 8.2405.x |
| Java 17/21 runtime | Java 25 | 8.2607.x |
Third-party dependency changes
The following third-party library versions are in effect for LTS-26 (8.2607.x). Customers who have developed plug-ins or custom extensions should review their own dependencies for compatibility, particularly the Spring Boot 4.x and Jackson 3.x upgrades.
nevisFIDO LTS-26 runs on Spring Boot 4.0.5 (up from Spring Boot 3.x in LTS-24). Spring Boot 4.x requires Java 17 as a minimum (Java 25 in this case) and contains breaking changes in auto-configuration. If you have custom Spring Boot extensions or override any auto-configuration, review the Spring Boot 4.0 migration guide before upgrading.
nevisFIDO LTS-26 uses Jackson 3.1.2 as the primary Jackson version. Note that some Jackson 2.x artifacts remain present to support the Log4j2 YAML configuration factory, which does not yet support Jackson 3.x. If your plug-ins depend on Jackson classes, verify compatibility with the Jackson 3.x API.
| Library | LTS-24 version (approx.) | LTS-26 version |
|---|---|---|
| Spring Boot | 3.2.x | 4.0.5 |
| Jackson (primary) | 2.17.x | 3.1.2 |
| Jetty | 12.0.7 | 12.0.34 |
| Bouncy Castle | 1.78 | 1.83 |
| Nimbus JWT | 9.40 | 10.9 |
| Webauthn4j | 0.23.x | 0.31.2.RELEASE |
| Log4j | 2.23.x | 2.25.4 |
| Apache HttpClient | 5.3.x | 5.6 |
| MariaDB connector | 3.3.x | 3.5.8 |
| PostgreSQL JDBC driver | 42.7.3 | 42.7.11 |
| HikariCP | 6.x | 7.0.2 (via Spring Boot 4) |
| OpenTelemetry API | 1.37.x | 1.61.0 |
| Google API Client | 2.4.x | 2.9.0 |
| Google Auth Library | 1.23.x | 1.45.0 |
The LTS-24 baseline versions in this table are approximate and based on the earliest LTS-24 release (7.2405.0.2). Verify exact versions from your installed LTS-24 packages if you need precise comparison values.
Deprecations
The following items are deprecated in LTS-26. They remain functional in LTS-26 but will be removed in a future release. Plan migration before upgrading beyond LTS-26.
/nevisfido/health Endpoint
The /nevisfido/health management endpoint is deprecated. Use /nevisfido/readiness instead. See Management Endpoints for details. (NEVISFIDO-2588)
Update any health checks, load balancer probes, or monitoring configurations that reference /nevisfido/health to use /nevisfido/readiness instead.
Generic-Credential-Based Dispatch Targets and iOS App Attestation Credentials
Managing dispatch targets and iOS App Attestation credentials via the generic-credential-based implementation in nevisIDM is deprecated. This implementation will be removed in the November 2026 release. Before that release, migrate to the dedicated-entity REST API in nevisIDM and set credential-repository.use-dedicated-entities to true. See nevisIDM Credential Repository for migration details. (NEVISFIDO-2583)
Migrate existing dispatch targets and iOS App Attestation credentials stored as generic credentials in nevisIDM to the dedicated-entity representation before upgrading to the November 2026 release. The migration must be completed with the legacy implementation still active. Do not set credential-repository.use-dedicated-entities to true until the data migration is complete.