Skip to main content
Version: 8.2607.x.x LTS

Appendix L - Migrating from LTS-24 to LTS-26

Draft

This migration guide is a work in progress. It will be finalized once the release notes for all LTS-26 patch releases are available. Sections marked [DRAFT] contain known information gaps that must be resolved before publication.

As part of the migration from nevisAuth LTS-24 to LTS-26, read through the following appendixes carefully, as your setup is affected and will require action:

After completing the changes required by the appendixes above, the remainder of this document provides additional information:

  • The what is new section lists new features introduced in nevisAuth since LTS-24.
  • The what has changed section lists behavioral and configuration changes that require action.
  • The what has been removed section lists removed features and auth states.
  • The third-party dependency changes section lists library upgrades that can affect custom auth state or Groovy ScriptState implementations.
  • The deprecations section lists features that are deprecated in LTS-26 and will be removed before the next LTS release.
Rolling releases

The changes described in this guide accumulated across several rolling releases between LTS-24 (7.2405.x) and LTS-26 (8.2607.x): versions 8.2411.x, 8.2505.x, 8.2511.x, and 8.2605.x. For customers who ran rolling releases between LTS-24 and LTS-26, some changes may already have been applied.

What is new​

  • NEW: Session eviction can now be fine-tuned with the new options reaperEvictSyncedSessions on LocalSessionStore and reaperInvalidateSessionBeforeDelete on RemoteSessionStore. (NEVISAUTH-4748)
  • NEW: RelyingPartyState and OAuth2ClientState now support Proof Key for Code Exchange (PKCE). The default codeChallengeMethod is S256. If your identity provider does not support S256, configure codeChallengeMethod=plain explicitly. (NEVISAUTH-4948) See RelyingPartyState and OAuth2ClientState.
  • NEW: AuthorizationServer supports certificate rollover via new properties keystoreref.old, keyobjectref.old, keycurve.old, and keyID.old, allowing a graceful transition when rotating signing keys. (NEVISAUTH-4952, NEVISAUTH-4953, NEVISAUTH-4954) See AuthorizationServer.
  • NEW: AuthorizationServer supports the audience (aud) field in access tokens per RFC 8707. (NEVISAUTH-5329) See AuthorizationServer.
  • NEW: JWT Bearer Grant is now supported. (NEVISAUTH-4512)
  • NEW: The JWKS endpoint now supports response caching, configurable via jwks.cacheDuration. (NEVISAUTH-4296) See AuthorizationServer.
  • NEW: PostgreSQL 17 is now supported for the remote session store and the OutOfContextDataService. (NEVISAUTH-4933)
  • NEW: MariaDB 11.4 is now supported. (NEVISAUTH-4939)
  • NEW: AuthorizationServer now supports the max_age parameter from OpenID Connect Core. (NEVISAUTH-4878) See AuthorizationServer.
  • NEW: Additional OpenTelemetry metrics are now available: Jetty worker thread pool utilization, request statistics, JVM heap, and HTTP client connection pool. (NEVISAUTH-4746) See OpenTelemetry metrics.
  • NEW: ScriptState now supports creating an HTTP client using HttpClients.create(), which reads configuration properties directly from the ScriptState configuration and caches the client per ScriptState instance. See ScriptState.
  • NEW: ScriptState sessions are now created automatically when needed. Previously, the session had to be created explicitly before attributes could be set.

What has changed​

OAuth2 authorization endpoint path changed​

The OAuth2 authorization endpoint path changed from /auth to /authorize.

This is a breaking change for:

  • OAuth2 clients that reference the authorization endpoint URL by path rather than by the Discovery endpoint authorization_endpoint value.
  • nevisProxy rewrite rules or URL patterns that reference the /auth path.
  • External identity providers or federation partners with the endpoint URL statically configured.

Action: Update any hardcoded references to the authorization endpoint path. Use the Discovery endpoint (/.well-known/openid-configuration) to retrieve the current authorization_endpoint value dynamically.

JWTToken: token.identifier renamed to token.outputAttributeName​

The token.identifier property of the JWTToken auth state has been renamed to token.outputAttributeName. (NEVISAUTH-4715) See JWTToken AuthState.

Action: Update your esauth4.xml configuration. Replace all occurrences of token.identifier with token.outputAttributeName in JWTToken auth state configurations.

ScriptState: automatic variable resolution in parameter.* properties​

The parameter.[parameterName] configuration properties of ScriptState now resolve variables automatically at startup. Previously, variables in parameter values were resolved manually inside the script. (NEVISAUTH-4604) See ScriptState.

This is a breaking change if:

  • Your scripts performed manual resolution of parameter.* values and relied on the raw, unresolved string.
  • Parameter values contain strings that resemble EL expressions (for example, ${something}) but are intended to be passed through literally.

Action: Review all parameter.* properties in your ScriptState configurations. Remove any manual variable resolution logic in the corresponding scripts that is now handled automatically. If a parameter value must remain unresolved, escape it.

Certificate store behavior changes​

Two changes were made to how nevisAuth resolves key material. Both affect any auth state or custom code that accesses certificates from a keystore. (NEVISAUTH-4869)

KeyStoreUtil.getKeyStore() returns all certificates​

Previously, KeyStoreUtil.getKeyStore() and AuthState.getKeyStore() returned only the first certificate found in the keystore. The method now returns all certificates in the keystore.

This is a breaking change for WSSHeaderValidation and any custom auth state that uses getKeyStore() and expects a single certificate to be present.

Action: If your keystore contains multiple certificates, either reduce it to a single certificate or specify the certificate alias explicitly in the keyobject URL (for example, keyobject://alias@keystoreName).

CertStoreManager.getCertificate() throws an exception when multiple certificates are found​

Previously, when a keystore contained more than one certificate, CertStoreManager.getCertificate() returned an arbitrary certificate without warning. It now throws an exception.

The following built-in auth states are affected: SAML auth states, OAuth2 auth states, JWTToken, DynCert, SAPTicketIssuer, MobileSignatureState. Any custom auth state that uses CertStoreManager.getCertificate() is also affected.

Action: Ensure that keystores used with the affected auth states contain exactly one certificate, or specify the certificate alias explicitly.

GuiElem validation attribute is frontend-only​

The validation attribute of GuiElem elements previously accepted a JavaScript expression that was also evaluated on the backend as a validation check. As of nevisAuth 8.2511.0.5, the expression is only evaluated on the frontend. (NEVISAUTH-5034)

Action: If you relied on the validation attribute for backend-side validation logic, migrate that logic to the new backendValidation attribute, which accepts an EL expression evaluated on the backend.

Groovy scripts are no longer auto-reloaded by default​

Prior to nevisAuth 8.2511.0.5, Groovy scripts were automatically recompiled when the script file changed on disk. This behavior is now disabled by default. (NEVISAUTH-5213)

Action: If you rely on automatic script reloading, add recompileOnChange=true to the relevant ScriptState configuration.

connectionMaxPoolSize default changed from 20 to 10​

The default value of connectionMaxPoolSize for the remote session store and the OutOfContextDataService was changed from 20 to 10. (NEVISAUTH-4819)

Already applied in LTS-24 patch

This change was backported and is already present in LTS-24 patch release 7.2411.0.10. Customers who applied all LTS-24 patches have already been running with the new default.

If nevisAuth logs show connection pool exhaustion after the upgrade, increase connectionMaxPoolSize to a value appropriate for your load.

HttpClient default character encoding changed from ISO-8859-1 to UTF-8​

The default character encoding used by the nevisAuth HTTP client when no explicit charset is configured changed from ISO-8859-1 to UTF-8. (NEVISAUTH-5036)

Action: If your backend expects ISO-8859-1 encoded request bodies, configure the charset explicitly in your custom auth state using the entity builder API. See Migrating HTTP clients and auth states for background on the nevisAuth HTTP client architecture.

TAN state channels

The TanState HTTP channel already supported explicit charset configuration. The SwissPhone channel is pinned to ISO-8859-1 per the provider specification and is not affected by this change.

OpenTelemetry java agent upgraded from v2 to v3​

The OpenTelemetry java agent bundled with nevisAuth was upgraded from version 2.x to version 3.x. (NEVISAUTH-5007) See OpenTelemetry metrics for configuration details.

This change only affects customers who export OpenTelemetry traces to an external backend (such as Jaeger or Zipkin).

Notable changes in v3:

  • Span names and span counts changed. Existing dashboards and alerts based on specific span names may need to be updated.
  • The v2 agent produced duplicate spans and was missing certain HTTP request headers in trace data. These issues are resolved in v3.

What has been removed​

LegacySecurityTokenService​

The LegacySecurityTokenService, which was enabled by the system property -Dch.nevis.esauth.wstrust.SecurityTokenService.Enabled=true, has been removed. (NEVISAUTH-4654)

Action: Remove the -Dch.nevis.esauth.wstrust.SecurityTokenService.Enabled=true system property from env.conf. Use the standard SecurityTokenService instead.

RSA1_5 and RSA_OAEP ID token encryption algorithms​

The RSA1_5 and RSA_OAEP encryption algorithms have been removed from the AuthorizationServer Discovery Endpoint and from the ID token encryption configuration. (NEVISAUTH-4980)

Action: If your configuration uses RSA1_5 or RSA_OAEP for ID token encryption, migrate to a supported algorithm such as RSA-OAEP-256.

Obsolete jakarta.mail jar​

The legacy jakarta.mail jar has been removed. It is superseded by jakarta.mail-api and angus-mail, which are included in nevisAuth LTS-26. (NEVISAUTH-5317)

Action: If your custom auth states import classes from the legacy jakarta.mail jar directly, verify that they compile against the replacement jakarta.mail-api and angus-mail artifacts.

jcan-saml and jcan-saml-xmlbeans removed from the nevisAuth RPM​

The jcan-saml and jcan-saml-xmlbeans libraries are no longer bundled in the nevisAuth RPM. They are available in the Ninja zip file for internal use only. (NEVISAUTH-4864)

Action: If your custom auth states or test code depend on jcan-saml or jcan-saml-xmlbeans, add them as explicit dependencies from the Ninja zip file.

RHEL 8​

RHEL 8 is no longer a supported operating system for nevisAuth. RHEL 9 is the supported alternative.

Third-party dependency changes​

Groovy 4 upgraded to Groovy 5​

See Appendix K - Groovy 5 upgrade for details.

Jackson 2.x upgraded to 3.1.1​

Jackson was upgraded from 2.x to 3.1.1. (NEVISAUTH-5383)

Note: a small number of Jackson 2.x artifacts remain in nevisAuth LTS-26 to support Log4j2 YAML configuration file parsing. The primary Jackson version used for all other purposes is 3.1.1.

Action: Custom auth states that import Jackson classes (for example, com.fasterxml.jackson.databind.ObjectMapper) must be recompiled against Jackson 3.x. Review the Jackson 3 migration guide for API changes.

OpenSAML 4.3.2 upgraded to 5.1.6 [DRAFT]​

OpenSAML was upgraded from version 4.3.2 to version 5.1.6. (NEVISAUTH-4707)

This is a major version upgrade. Custom auth states that use the OpenSAML API directly may be affected. The scope of user-facing breaking changes is not yet fully documented. This section will be updated when more information is available from the nevisAuth development team.

Action: Review your custom auth states for direct use of the OpenSAML API. Test thoroughly against nevisAuth LTS-26 and consult the OpenSAML 5 migration guide for API-level changes.

nevisauth-test-authstateharness-fat restructured​

The nevisauth-test-authstateharness-fat testing artifact no longer embeds third-party dependencies (NEVISAUTH-5026, NEVISAUTH-4963). Dependencies must now be supplied via a separate POM. The POM is included in the nevisAuth SDK archive, which is part of the nevisAuth RPM (/opt/nevisauth/resources/nevisauth-sdk-<version>.tar.gz). See Testing AuthStates for details on using the test harness.

Additionally, the following classes now use static of() factory methods instead of constructors: EngineTestContext, InMemoryCertStoreProvider, KeyStoreHandle, TestContext.

Action: Update your test POM to declare third-party testing dependencies explicitly. Update instantiation of the affected classes to use the of() factory method.

Deprecations​

The following features are deprecated in nevisAuth LTS-26 and are planned for removal in a future release. They remain functional in LTS-26 but action is required before the next LTS.

JDBCAuthState​

JDBCAuthState is deprecated and will be removed in the November 2026 release (9.2611.x). (NEVISAUTH-4227) See JDBC authentication AuthState.

Action: Migrate to a ScriptState with a custom JDBC implementation before upgrading to the next nevisAuth release after LTS-26. See Migrating from JDBCAuthState to ScriptState for a step-by-step migration guide.

TANState autoRegenerate​

The autoRegenerate property of TANState is deprecated and currently does not function correctly. It is planned for removal without replacement. (NEVISAUTH-4710)

Action: Use the inputFalse transition mechanism to handle TAN regeneration instead of relying on autoRegenerate.