LTS26 Migration Guide

Introduction

This guide describes how to upgrade a Nevis setup from LTS-2024 to LTS-2026.

The upgrade should be done as part of a migration project. Nevis integration partners can help customers to manage and execute these projects to successfully deliver a production ready, migrated, latest version of the Nevis Identity Suite.

Functionality-wise, this release contains all improvements and changes from the Rolling Releases since February 2024, when LTS-2024 was branched off. It fully includes the November 2025 Rolling Release and selected features from the May 2026 Rolling Release, making it very similar to that release — but not identical. The exact version numbers of LTS-2026 may vary per component.

Prerequisite

Before starting the migration, ensure all your Nevis components are upgraded to the latest available LTS-2024 patch release. Upgrading from an older LTS-2024 patch directly to LTS-2026 is not supported.

Process Overview

This section provides an overview of the upgrade steps depending on your deployment model.

Regardless of deployment type: if you have custom AuthState classes, you must recompile them against the latest nevisAuth release before deploying.

danger

Before upgrading nevisAdmin to LTS26, ensure your pattern library is on at least version 8.2511.5 (and still on a 8.2511.x version — do not upgrade to 9.2605.x or later at this stage). This patch release makes the patterns compatible with Groovy 5, which is used by nevisAdmin 4 on LTS26.

Virtual Machine (RPM-based)

1. Read the Breaking Changes section and the component release notes to understand what configuration changes are required.
2. Apply the required configuration changes to your Nevis component configurations.
3. Upgrade your target systems to the required operating system version (see Nevis Product Lifetime and Platform Support Matrix).
4. Upgrade the Nevis component RPM packages on each server.
5. For components that require a database schema upgrade:
   1. Stop the component.
   2. Apply the schema changes.
   3. Restart the component.
6. Start all upgraded components and verify functionality.
7. Test all use cases extensively.

nevisAppliance

1. Read the Breaking Changes section and apply any required configuration changes to your patterns.
2. Perform the appliance upgrade by following the nevisAppliance Software Updates guide (link to be added). The appliance upgrade handles OS and component upgrades together.
3. After the upgrade, verify all services are running and test all use cases.

Kubernetes

1. Read the Breaking Changes section and update your nevisAdmin 4 patterns and configuration as required.
2. Push the new LTS-2026 Docker images to your container registry.
3. Apply the new nevisAdmin 4 Helm chart (link to be added).
4. Roll out the updated deployment and verify that all pods start correctly.
5. Test all use cases extensively.

Breaking Changes

The following changes require action during migration. Refer to the individual component release notes for full details.

Some breaking changes affect all deployments regardless of how nevisAdmin 4 is used. Others only apply when Generic patterns are in use. Generic patterns expose low-level component configuration directly — every component has a Generic [Component] Instance Settings pattern, and some components additionally offer patterns like Generic Virtual Host Settings or Generic Application Settings for further customization. If your project relies solely on standard patterns, nevisAdmin 4 handles the underlying configuration automatically and most of the raw configuration changes listed below will not require manual intervention.

nevisAdmin 4

• Java 21 required (8.2505): Java 17 is no longer supported.
• Generation Engine discontinued (8.2505): All deployments must use nevisAdmin 4.

Patterns

• Groovy 5 required (LTS-2026): Patterns now require Groovy 5.
• TLS Settings renovation (LTS-2026): The HTTPs setting in nevisLogrend Instance is removed. Reconfigure TLS using the new Inbound TLS tab.
• ModSecurity Core Rule Set updated (8.2511): Versions prior to 4.22.0 (CRSv4) and 3.3.8 (CRSv3) are removed due to known vulnerabilities. Test your rule configuration before upgrading.
• PostgreSQL sslmode parameter (8.2511): Use lowercase sslmode for PostgreSQL SSL configuration.

nevisProxy

• Deprecated elements removed (LTS-2026): A large number of previously deprecated configuration elements, parameters, filters, and Lua methods have been removed (for example TelemetryFilter, InsertWrapperFilter, DocumentRoot, OutboundProxyAuthorization, deprecated navajo.xml attributes). Eliminate all deprecation warnings in your existing setup before upgrading. See Appendix H (Deprecation List) in the nevisProxy reference guide for the full list.
• MariaDB dynamic session management (LTS-2026): A unique key constraint must be added to the session attribute table before upgrading: alter table attribute add constraint uc_id_name unique (ID, NAME); — ensure all instances are on the latest LTS-2024 patch first and run this during low load.
• XmlFilter schema validation (LTS-2026): The filter now blocks requests that do not match the configured XSD schema, or where no schema is configured. Set ValidateSchema=false to restore the previous behavior.
• RewriteFilter condition behavior changed (LTS-2026): When a condition is set, the parameters RequestURL, RequestURI, RequestHeader, and ResponseHeader now behave differently. Review any RewriteFilter configurations that use conditions.
• OpenTelemetry variable renamed (LTS-2026): The deployment environment variable has changed from deployment.environment to deployment.environment.name. Metrics from nevisProxy are now emitted as Histogram instead of UpDownCounter.
• OpenSSL upgrade (LTS-2026): RSA keys must be at least 2048 bits. Some older ciphers may no longer be usable.
• Kubernetes SNI (LTS-2026): Requests may be blocked with HTTP 421 (Misdirected Request) if the ingress is not SNI-aware. See the nevisProxy migration guide for mitigation options.

nevisAuth

• Java 25 required (LTS-2026): Java 17 is no longer supported. All custom auth states, REST services, and SOAP services must be recompiled against the nevisAuth LTS-26 artifacts using Java 25. Custom auth states compiled with Java 17 may fail at runtime even if the build succeeds. Also note that the TLS cipher TLS_RSA_WITH_AES_256_GCM_SHA384 is blacklisted by the Java runtime; verify that all backends support at least one non-blacklisted cipher.
• Groovy 5 required (LTS-2026): The Groovy runtime was upgraded from 4.x to 5.x. Review all ScriptState Groovy scripts for compatibility — method resolution, GString handling, and removed deprecated methods are the most common failure areas.
• OAuth2 authorization endpoint path changed (LTS-2026): The path changed from /auth to /authorize. Update any hardcoded references and use the Discovery endpoint (/.well-known/openid-configuration) to retrieve the authorization_endpoint value dynamically.
• JWTToken: token.identifier renamed (LTS-2026): The property token.identifier in JWTToken auth state configurations has been renamed to token.outputAttributeName. Update esauth4.xml accordingly.
• Certificate store behavior changes (LTS-2026): KeyStoreUtil.getKeyStore() now returns all certificates in a keystore (previously only the first). CertStoreManager.getCertificate() now throws an exception if multiple certificates are found (previously returned an arbitrary one). Affected auth states include SAML, OAuth2, JWTToken, DynCert, SAPTicketIssuer, and MobileSignatureState. Ensure keystores used with these auth states contain exactly one certificate, or specify the alias explicitly.
• ScriptState parameter.* auto-resolution (LTS-2026): Values in parameter.[parameterName] properties are now resolved automatically at startup. Remove any manual variable resolution logic in scripts that is now handled automatically.
• HttpClient default encoding changed to UTF-8 (LTS-2026): The default character encoding changed from ISO-8859-1 to UTF-8. If backends expect ISO-8859-1 encoded request bodies, configure the charset explicitly.
• GuiElem validation attribute is frontend-only (LTS-2026): Backend-side validation logic must be migrated to the new backendValidation attribute.
• FileSystemOOCDService removed (7.2311): Migrate to LocalOutOfContextDataStore (in-memory) or RemoteOutOfContextDataStore (SQL-based).
• JavaScript ScriptState removed (7.2311): Groovy must be used for all script-based auth states.
• Deprecated auth states removed (7.2311): SapTicketValidator, FrontendKerberosAuthState, BackendKerberosAuthState, Dispatcher, DomainDispatcher, ClientCertInfo, ClientCertFingerprint, and AuthHandoverState are removed.
• Date/time EL variables removed (7.2311): AuthDateUtils, DateFormatUtils, DateUtils, and DateTime are removed. Use java.time classes instead.
• LegacySecurityTokenService removed (8.2411): Configurations using -Dch.nevis.esauth.wstrust.SecurityTokenService.Enabled=true must be migrated to SecurityTokenService.
• SAML/JWT libraries removed from RPM (8.2411): jcan-saml and jcan-saml-xmlbeans are no longer bundled. Custom code relying on these must source them from Ninja.

nevisIDM

• XA transaction management replaced (LTS-2026): The Artemis Bridge feature is removed. Spring JPA transaction manager and Hikari connection pool are now used. XA database privileges are no longer required on Oracle.

nevisLogrend

• Java 25 required (LTS-2026): Java 17 is no longer supported. Upgrade your Java runtime before deploying LTS-26 (upgrade path: LTS-24 → Java 17; RR 8.2505 → Java 21; LTS-26 → Java 25).
• json.vm template requires manual update if customized (LTS-2026): The built-in json.vm template now uses $utils.escapeJson() for proper JSON escaping. If you have customized or copied this template, replace "$guiElem.label" with "$utils.escapeJson($guiElem.label)" and "$guiElem.value" with "$utils.escapeJson($guiElem.value)".
• RHEL8 no longer supported (8.2405): Upgrade to RHEL 9 before migrating to LTS-26.

nevisMeta

• Java 25 required (LTS-2026): Java 17 and Java 21 are no longer supported (upgrade path: LTS-24 → Java 17; RR 8.2505 → Java 21; LTS-26 → Java 25). Ensure your deployment environment provides Java 25 before upgrading.
• RSA1_5 and RSA_OAEP encryption methods removed (LTS-2026): These deprecated key encryption methods are no longer accepted. Before upgrading, identify all clients using RSA1_5 or RSA_OAEP and reconfigure them to use a supported method such as RSA_OAEP_256.
• OAuth2 Consent REST API V1 removed (LTS-2026): Migrate any integrations using the V1 Consent API to the current API version.

nevisFIDO

• Java 25 required (LTS-2026): Java 17 and Java 21 are no longer supported. Install Java 25 on all hosts running nevisFIDO before upgrading (upgrade path: LTS-24 → Java 17; RR 8.2505 → Java 21; LTS-26 → Java 25).
• SOAP nevisIDM connection removed (8.2505): The SOAP-based connection to nevisIDM has been fully removed. All instances using FIDO UAF must be configured to use the REST connection. Remove idm-connection-type and administration-url from nevisfido.yml if present.
• Self-signed bootloader keys must be Base16 encoded (LTS-2026): Self-signed bootloader keys must now be provided in base16 (hexadecimal) encoding instead of base64. Re-encode any configured bootloader key values before upgrading.
• RHEL8 no longer supported (8.2405): Upgrade to RHEL 9 before migrating to LTS-26.

Component Migration Guides

The following table will list migration guides per component once LTS-2026 documentation is published.

Component	Migration Guide
nevisAppliance	Link to be added
nevisAdmin 4	Link to be added
Patterns	Pattern Migration from LTS24 to LTS26
nevisProxy	nevisProxy migration guide from LTS-24 to LTS-26
nevisAuth	Appendix L - Migrating from LTS-24 to LTS-26
nevisDetect / nevisAdapt	Link to be added
nevisFIDO	Appendix A - Migrating from LTS-24 to LTS-26
nevisIDM	Link to be added
nevisLogRend	Appendix A - Migrating from LTS-24 to LTS-26
nevisMeta	Migrating from LTS-24 to LTS-26
nevisDataPorter	Link to be added
nevisCred	Link to be added
nevisKeybox	Link to be added
Ninja	Link to be added
Nevis Mobile Authentication Client SDK	Link to be added
Nevis Access App	Link to be added