Upgrading OpenAM Servers

Starting with this release, a failed write of an account-lockout counter or counter reset switches the affected identity to counters held in memory on that OpenAM server. Previously, a rejected counter write could prevent subsequent authentication failures from being counted at all. Other identities continue using the configured data store, and a read failure alone does not activate this fallback.

The switch remains in effect until that server restarts, even if the write failure was transient and the store later recovers. Counters are independent on each server and are lost on restart. A successful login resets the in-memory counter but does not restore persistence. Positive lockout durations are preserved; a configured duration of zero changes from physical account deactivation to a temporary lock of 30 minutes. Once that lock expires, another sequence of failed attempts can lock the account again.

Setting inetuserstatus to Active or clearing sunAMAuthInvalidAttemptsData in the directory does not clear an existing fallback lock. Allow the temporary lock to expire; restarting the affected server also discards its fallback counters. An existing physical account restriction in physical-locking mode remains effective and must still be cleared separately.

Special identities, including amadmin, follow the same policy without name-based exemptions. Their rejected counter writes previously prevented lockout. With the current default account-lockout settings, five failed passwords can now lock amadmin on the affected server for 30 minutes. Review administrator access and recovery procedures before upgrading.

Two related corrections also apply to writable stores and explicitly configured in-memory counters: a failure threshold of one now starts a timed lock on the first failure, and a duration multiplier of zero preserves the lock duration for later cycles instead of reducing it to zero.

Disabling account lockout, or setting its failure count or failure interval to zero, stops enforcing existing temporary locks consistently across authentication index types. This does not clear the counters or restore persistence: re-enabling lockout before a temporary lock expires enforces that lock again. Physical account restrictions remain subject to the existing account and profile checks.

Explicitly configured in-memory counters now invoke the account-lockout callback plugins for the login realm when the failure threshold is reached, without resolving the user from the identity store. Previously, this path sent the lockout notification but skipped the plugin callback because no identity had been resolved.

If you are upgrading from an unsupported version of OpenAM to a later version, you must first upgrade to a supported version. In some cases, you may need to upgrade again depending on the upgrade path.

Starting with this release the legacy Liberty ID-WSF SOAP endpoints (/Liberty/ and /WSPRedirectHandler/) are disabled by default as part of the GHSA-p462-xxwx-pqf4 hardening. Existing deployments that rely on Liberty ID-WSF, IDPP, Discovery, AuthnSvc, or Interaction services must explicitly opt in by setting the advanced server property com.sun.identity.liberty.enabled=true.

Two related advanced server properties were also introduced and now default to a fail-close behaviour:

If your deployment depends on the previous (insecure) behaviour, review and adjust these properties before promoting the upgrade. See "Advanced" in the Reference.

Starting with this release the SAML 2.0 and ID-FF IDP discovery reader and writer endpoints (/saml2reader, /saml2writer, /idffreader, /idffwriter) validate the RelayState redirect URL as part of the GHSA-2pf8-52jh-5x3m hardening. Relative and same-origin redirect URLs continue to work unchanged. Absolute URLs that point to a different host are now rejected with HTTP 400 unless they match the new advanced server property org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist (a semicolon-separated list of URL patterns, empty by default).

If your common-domain discovery deployment hosts service providers on a different host than OpenAM, add their return URLs to this property before promoting the upgrade. See "Advanced" in the Reference.

Starting with this release the legacy Liberty ID-FF (Liberty Alliance 1.x) SOAP endpoint (/SOAPReceiver/, served by FSSOAPReceiver) is *disabled by default as part of the GHSA-qcqm-7432-wg7r hardening. Existing deployments that actively use Liberty ID-FF federation must explicitly opt in by setting the advanced server property com.sun.identity.federation.services.soap.enabled=true. The kill-switch disables the whole endpoint, including ID-FF browser-artifact single sign-on and LECP, not only the state-changing operations. In a multi-server site set this property on every server: cross-node single logout forwards the logout SOAP message to a peer server’s own /SOAPReceiver, so a node where the endpoint is still disabled would reject the forwarded request with HTTP 404 and single logout would fail.

Also starting with this release, inbound ID-FF state-changing and disclosure operations (federation termination, name registration, single logout, and name-identifier mapping) require a verified XML signature by default (com.sun.identity.federation.services.requireSignature, default true), even when message signing is otherwise optional. This applies to the SOAP binding and to the HTTP-Redirect binding endpoints /ProcessTermination/, /ProcessLogout/, and /ProcessRegistration/*, which are reachable without authentication and act on the user named by an opaque handle in the request. Unlike the SOAP endpoint, the redirect binding is not disabled by default, so this change affects any deployment that uses ID-FF over the redirect binding.

Enable message signing along with it. OpenAM signs its own outbound ID-FF messages only when XMLSigningOn is enabled, and that setting is false on a stock installation. If you leave com.sun.identity.federation.services.requireSignature at its default without enabling signing, OpenAM’s own single logout, federation termination, and name registration messages are sent unsigned and rejected by the receiving provider. Before promoting the upgrade, either:

See "Advanced" in the Reference.

Starting with this release the OAuth 2.0 authorization endpoint applies the OAuth2 Provider property Code Verifier Parameter Required to every request whose response_type includes code, as part of the GHSA-5p2f-7vcr-6vfh hardening. Previously the OpenID Connect hybrid flows (code token, code id_token, and code id_token token) escaped the check and were issued authorization codes with no code_challenge bound to them. That property is enabled by default, so hybrid-flow clients that send no code_challenge now fail at /oauth2/authorize.

The token endpoint fails closed to match: while the property is enabled, an authorization code that carries no code_challenge is rejected at /oauth2/access_token. Authorization codes issued before the upgrade, or before the property was turned on, therefore stop being redeemable. The exposure lasts at most one authorization code lifetime (the OAuth2 Provider property Authorization Code Lifetime (seconds), 120 by default), so if in-flight codes matter, leave client traffic redirected elsewhere for that long before promoting the upgrade.

Update hybrid-flow clients to send a code_challenge at the authorization endpoint and the matching code_verifier at the token endpoint, or disable Code Verifier Parameter Required for the realm. Disabling it never relaxes verification for codes that were issued with a challenge. See "OAuth2 Provider" in the Reference.

Starting with this release debugconfig.properties is validated more strictly. A file with org.forgerock.openam.debug.rotation=-1, or with a trailing space after a rotation value next to a suffix that is empty, too coarse or cannot be parsed, is now rejected as a whole: OpenAM prints "'/debugconfig.properties' isn’t valid, the default configuration will be used instead" to the standard error output and uses no prefix and no rotation. Leave a rotation value empty to turn that rotation off. Trailing spaces are also removed from the prefix and the suffix, so they no longer appear in debug log file names. See "Rotating Debug Logs" in the Administration Guide.

Starting with this release the OAuth 2.0 device flow verifies PKCE, as part of the GHSA-h93p-35jm-rj83 hardening. Previously a code_challenge sent to /oauth2/device/code was stored with the device code but never checked, so the device code could be redeemed without the code_verifier. Now every poll of /oauth2/access_token for such a device code must supply the matching code_verifier, and /oauth2/device/code rejects a code_challenge sent with a code_challenge_method other than S256 or plain.

Device-flow clients that send no code_challenge are not affected: the Code Verifier Parameter Required property does not apply to the device flow. Clients that do send a code_challenge but never sent the code_verifier must be updated to send it.

Starting with this release the signature on a SAML v1.x assertion or response is verified against the signing certificate configured for its issuer, as part of the GHSA-j56q-q3r3-hg7f hardening. Previously a certificate carried in the KeyInfo element was accepted as long as it was present anywhere in OpenAM’s keystore, so one trusted asserting party could sign messages on behalf of another.

A trusted asserting party therefore now needs its signing certificate alias configured. Signed assertions and responses from a partner whose alias is blank are rejected, and a certificate in the KeyInfo element must be the one of that alias. There is no property to restore the previous behaviour. Before promoting the upgrade, import each asserting party’s signing certificate into OpenAM’s keystore and enter its alias in the trusted partner configuration. See "To Configure a Trusted Asserting Party" in the Administration Guide.

Starting with this release a host name that is a DNS alias of a realm is accepted as a valid host name, as if it had its own com.sun.identity.server.fqdnMap[<alias>]=<alias> entry, unless the FQDN map maps it to another host name. The DNS aliases of the top-level realm hold the RDN value of the root suffix (for example openam) and the host name of every server and site that was created, so these host names are accepted as well.

OpenAM now removes the host name of a server or site from the DNS aliases of the top-level realm when the server or site is deleted, or when the primary URL of the site changes, unless the URL of another server or site has the same host name. If the host name cannot be removed at that moment, for example because the DNS aliases or the URLs of the other servers and sites cannot be read or updated, the server or site is still deleted or its URL still changed, OpenAM logs an error in the amSetupServlet debug log, and the host name stays. Servers and sites deleted before the upgrade, and site URLs changed before it, have left their host names behind. Before promoting the upgrade, review the DNS aliases of every realm and remove the host names that are no longer in use or no longer under your control. If you added a server or site host name to the DNS aliases of the top-level realm yourself, for example the host name of a load balancer, add it again after you delete the last server or site that has it.

Starting with this release OpenAM no longer ships the Restlet Servlet extension (org.restlet.ext.servlet). The web.xml file of earlier releases names org.restlet.ext.servlet.ServerServlet for the WebFinger servlet, which this release no longer has. If your customized .war file keeps its own copy of web.xml, change it as the WebFinger note below describes.

Custom code that calls org.restlet.ext.servlet.ServletUtils must call org.forgerock.openam.rest.jakarta.servlet.ServletUtils instead, which has the same getRequest and getResponse methods. Custom code that embeds Restlet in its own servlet through org.restlet.ext.servlet.ServletAdapter has no drop-in replacement, because OpenAM ships no counterpart of that class.

Starting with this release WebFinger (/.well-known/webfinger) answers OpenID Connect issuer discovery requests again; earlier 16.x releases answered every request with HTTP status 500. It no longer looks up the account named in the resource parameter: for any acct: or http(s) resource it returns the issuer of the deployment, the same for every account. Releases 15.x and earlier answered HTTP status 404 for an account that did not exist, which told an anonymous caller whether the account existed.

Starting with this release OpenAM serves the XACML policy endpoint (/xacml/) through the OpenAM servlet instead of the ForgeRockRest servlet. If your customized .war file keeps its own copy of web.xml, move the <servlet-mapping> whose <url-pattern> is /xacml/ from the ForgeRockRest servlet to the OpenAM servlet before you deploy. Otherwise every request to /xacml/* answers HTTP status 404.

The endpoint otherwise behaves as before, with these changes:

Custom code that refers to org.forgerock.openam.rest.service.XACMLServiceEndpointApplication, org.forgerock.openam.rest.service.XMLRestStatusService, org.forgerock.openam.rest.service.ResourceApiVersionRestlet or org.forgerock.openam.entitlement.rest.XacmlRouterProvider must be changed, because these classes no longer exist. org.forgerock.openam.xacml.v3.rest.XacmlService is no longer a Restlet resource. Custom code that injects the Restlet Router bound as @Named("XacmlRouter"), for example to add routes under /xacml, must be changed as well, because that binding no longer exists.

Starting with this release OpenAM serves WebFinger (/.well-known/) through the OpenAM servlet instead of a servlet of its own. If your customized .war file keeps its own copy of web.xml, delete the WebFinger servlet and its <servlet-mapping>, and map the <url-pattern> /.well-known/ to the OpenAM servlet before you deploy. Otherwise the container cannot load the WebFinger servlet, because its classes no longer exist.

The endpoint otherwise behaves as before, with these changes:

Custom code that refers to org.forgerock.openidconnect.restlet.WebFinger, org.forgerock.openidconnect.restlet.OpenIDConnectDiscovery or org.forgerock.oauth2.restlet.OAuth2StatusService must be changed, because these classes no longer exist.