Upgrading from 11.5.X to 11.6.0#

OpenID Connect - Authentication Methods References (amr) in ID Tokens#

The server issues the amr claim in ID tokens as a string, which is not aligned with the OpenID Connect specification. In this version, a new setting - “AMR as array” - is added, which configures the server to return the amr claim as an array of strings. The default value of this setting is false, for retro-compatibility, but it is recommended that clients depending on this behavior are updated and the setting is changed to true. Note that Token Procedures may always change the final shape of the data, if needed.

Opt-in MFA recovery code verification is throttled#

Verification of recovery codes in the Opt-In MFA action is now throttled, per account, to limit brute-force guessing of recovery codes. Which Throttler service enforces the limit depends on the action’s configuration:

  • With no change to the action configuration, recovery code verification is throttled by the system-wide default Throttler service.
  • When a specific Throttler service is referenced on the action (the new recovery-code-throttler setting), that service is used instead.

Throttling only takes effect when a Throttler service is actually available. If no system-wide default Throttler service is configured and the action references none, recovery code verification is not throttled. Configure the default Throttler service to enable the protection for every action that does not reference its own.

TOTP one-time password verification is throttled#

Verification of one-time passwords in the TOTP authenticator is now throttled, per account, to limit brute-force guessing. Which Throttler service enforces the limit depends on the authenticator’s configuration:

  • With no change to the authenticator configuration, verification is throttled by the system-wide default Throttler service.
  • When a specific Throttler service is referenced on the authenticator (the new throttler-service setting), that service is used instead.

An optional second layer keyed on the pair of client IP address and account (the new setting) can be added via the client-ip-throttler; it is off unless configured.

Throttling only takes effect when a Throttler service is actually available. If no system-wide default Throttler service is configured and the TOTP authenticator references none, one-time password verification is not throttled. Configure the default Throttler service to enable the protection for every TOTP authenticator that does not reference its own.

Redirect URI Validation Policies - Validate Localhost Port#

A new setting, validate-localhost-port, is added to the request validation of Redirect URI Validation Policies. Set it to false to accept any port in a localhost redirect URI, while the rest of the URI is still validated.

No change is needed when upgrading: when the setting is not configured, the localhost port is validated, as before, unless allow-localhost-variations is enabled, which overrides it. The setting can only be set to true when allow-localhost-variations is disabled.

Script Claims and Attribute Providers Must Reference an Existing Procedure#

The procedure setting of the Script Claims Value Provider and of the Script Attribute Provider is now a reference to, respectively, a claims provider procedure and a SAML attributes provider procedure. Previously, any value was accepted, and a provider referencing a procedure that does not exist only failed at runtime.

The configuration is now rejected when:

  • a script claims value provider references a procedure that is not defined as a claims provider procedure, or a script attribute provider references one that is not defined as a SAML attributes provider procedure;
  • a procedure is deleted while a script provider still references it.

Before upgrading, make sure every script claims value provider and script attribute provider references an existing procedure of the right kind, or remove the providers that do not.

SAML IDP - NameID Format of a Service Provider#

From now on, the NameID format configured on a Service Provider (nameid/format, or name_id_format for a Service Provider stored in a database) is set, as-is, as the Format attribute of the NameID in the Subject and in its SubjectConfirmation of issued assertions. The value of the NameID is still the authenticated subject.

Assertions for Service Providers without a configured format are issued as before, without a Format attribute. Before upgrading, review the format of the Service Providers that have one configured, and remove it if the Service Provider does not expect it.

SDK#

Deprecation of the IdTokenAttributes.getAuthenticationMethod() Method#

The IdTokenAttributes.getAuthenticationMethod() method is now deprecated. Its previous implementation only supported single string values for the amr claim, which was incorrect. If IdTokenAttributes are created with a single amr string value, this method still returns that value; if created with multiple values (a list/array), this method returns the first value, but the order is not guaranteed to be stable.

Use the new IdTokenAttributes.getAuthenticationMethods() method instead, which returns a list of strings.

Hibernate Validator Message Parameters Are Escaped#

Hibernate Validator is upgraded to 7.0.6.Final. Values that a custom ConstraintValidator passes to HibernateConstraintValidatorContext.addMessageParameter(name, value) are now escaped, so they appear literally in the violation message instead of being interpolated as message parameters or Expression Language expressions.

No change is needed for plugins that do not call addMessageParameter, or whose parameter values never contain {, }, $ or \. A plugin that relies on a parameter value being interpolated can opt out for that value by calling addMessageParameter(name, value, MessageParameterEscaping.NONE). Only do so for values that cannot be controlled by the user, since interpolating untrusted input can lead to Expression Language injection.

Was this helpful?