Upgrading from 6.2.X to 6.3.0

There are no changes to the database schema, SDK, or the configuration model in this version. As a result, it should be possible to upgrade without explicit action. One configuration setting was deprecated, so it can be changed to the new setting if desired. If this change is not made, the old will continue to be used until at least the next major version.

Upgrading the XML Configuration

Description Applicability Change Method
Required claims in request object has changed Request object OAuth profile configuration No action or manual
Maximum validity of request objects requires explicit configuration Request object OAuth profile configuration No action or manual
Client authentication claims must be explicitly required Request object OAuth profile configuration No action or manual
Sliding window for alarms added HTTP clients and data sources No action or manual

Required Claims in Request Objects

There is a profile-wide setting that causes parameters that are provided in HTTP form / query strings to always be included as claims in request objects. This is off by default, but can be enabled (e.g., to comply with FAPI 1 advanced). The support for JAR and PAR extended how parameter merging should be handled. As a result, a new setting was added and the old one, require-parameters-as-claims was deprecated. To prepare the configuration for when this old setting will be obsolete, the following changes may be made:

Listing 105 Example of a previous configuration for require-parameters-as-claims.
<request-object>
  <!-- ... -->
  <require-parameters-as-claims>true</require-parameters-as-claims>
</request-object>
Listing 106 Equivalent configuration using the new request-object-parameter-handling setting
<admin-service>
    <!-- ... -->
    <request-object-parameter-handling>must-be-inside-and-match-if-outside</request-object-parameter-handling>
</admin-service>

Maximum Validity of Request Objects

Certain profiles of OpenID Connect, like FAPI and CIBA, require a request object not be valid longer than a certain time. This was previously checked automatically, but now needs to be configured explicitly. This allows customers to reduce or extend the time as required by their deployments or satisfy the requirements of other profiles of OpenID Connect. However, with this release, no default maximum lifetime of request objects is applied. To maintain the same behavior as in previous releases, the following configuration should be added:

Listing 107 Example configuration to make a request object validity limited to 60 minutes
<request-object>
  <!-- ... -->
  <maximum-lifetime>60</maximum-lifetime>
</request-object>

Request objects cannot have a validity greater than three hours. To allow them to last longer, do not configure a lifetime.

Client Authentication Claims Explicitly Required

In order to support not only OpenID Connect and FAPI’s requirements for handling request objects but also JAR and PAR’s, client authentication claims in a request object are no longer verified implicitly. Before, in requests made to the authorize endpoint, parameters like client_id and client_secret had to match claims with the same name in the request object. These claims didn’t have to be explicitly configured as required. Due to differences in these newly-supported standards, this is no longer the case. In order for the client_id and other client-authentication-related claims in a JWT request object to be required, they must be explicitly configured as such. This can be done by adding configuration such as this:

Listing 108 Example configuration to make a client_id claim required in a request object
<request-object>
  <!-- ... -->
  <required-claim>client_id</required-claim>
</request-object>

Sliding Window for Alarms

Some alarms have been updated to employ a sliding window on incoming faults before the alarm is raised. These sliding windows are enabled by default, and must be disabled manually to retain alarm behavior as it was before upgrading.

Affected alarms are slow-connection alarms for

  • Data Sources

and failed-communication alarms for

  • Data Sources
  • HTTP Clients

It is recommended to have sliding windows enabled for these alarms, to reduce false positives for raised alarms. When it’s deemed appropriate to disable some, or all, of these alarms, see configuration examples below.

Listing 109 Disabling the slow-connection alarm for a Data Source, if this alarm is enabled
<config xmlns="http://tail-f.com/ns/config/1.0">
  <facilities xmlns="https://curity.se/ns/conf/base">
    <data-sources>
      <data-source>
        <id>my-data-source</id>
        <data-source-alarms>
          <slow-connection-alarm>
            <sliding-window>
              <faults-to-raise-alarm>1</faults-to-raise-alarm>
              <sliding-window-duration>0</sliding-window-duration>
            </sliding-window>
          </slow-connection-alarm>
        </data-source-alarms>
      </data-source>
    </data-sources>
  </facilities>
</config>
Listing 110 Disabling the failed-communication alarm for a Data Source
<config xmlns="http://tail-f.com/ns/config/1.0">
  <facilities xmlns="https://curity.se/ns/conf/base">
    <data-sources>
      <data-source>
        <id>my-data-source</id>
        <data-source-alarms>
          <failed-communication-alarm>
            <sliding-window>
              <faults-to-raise-alarm>1</faults-to-raise-alarm>
              <sliding-window-duration>0</sliding-window-duration>
            </sliding-window>
          </failed-communication-alarm>
        </data-source-alarms>
      </data-source>
    </data-sources>
  </facilities>
</config>
Listing 111 Disabling the failed-communication alarm for a HTTP Client, if this alarm is enabled
<config xmlns="http://tail-f.com/ns/config/1.0">
  <facilities xmlns="https://curity.se/ns/conf/base">
    <http>
      <client>
        <id>my-http-client</id>
        <client-alarms>
          <failed-communication-alarm>
            <sliding-window>
              <faults-to-raise-alarm>1</faults-to-raise-alarm>
              <sliding-window-duration>0</sliding-window-duration>
            </sliding-window>
          </failed-communication-alarm>
        </client-alarms>
      </client>
    </http>
  </facilities>
</config>

Updating Templates

Update state encoding in templates

There were templates updated to account for encoding the user provided state parameter when this value is being used in forms. In case you modified these templates on your own, these changes need to be made manually as well.

The affected templates and their changes are:

Listing 112 Changes to templates/core/views/oauth/consent.vm
<form method="post" action="$!_target" class="consent-form center">
-    <input type="hidden" name="state" value="$!_state" />
+    <input type="hidden" name="state" value="$_tr.encodeHtmlAttribute($!_state)" />
Listing 113 Changes to templates/core/views/oauth/form-response-mode.vm
#if ($state)
-    <input type="hidden" name="state" value="$state"/>
+    <input type="hidden" name="state" value="$_tr.encodeHtmlAttribute($state)"/>
#end

Static Resource Path for WebAuthn

The WebAuthn templates did not include a static resource path when one was configured. For customers that have configured this setting and have overridden the WebAuthn templates, the img and src attributes should be updated to include $!_staticResourceRootPath. These changes are needed in the following templates:

  • $IDSVR_HOME/usr/share/templates/core/authenticator/webauthn/js/common-js.vm
  • $IDSVR_HOME/usr/share/templates/core/authenticator/webauthn/register/get.vm

Form Response Mode Template

The form response mode template, form-response-mode.vm was updated to support JARM. If this template has been overriden and JARM support is needed, the hidden response form parameter should be added.

RESTCONF Conformance Updates

The RESTCONF API has been fixed in a two places to conform with the specification.

1. Errors in JSON

The error reporting in JSON has been fixed to always include the module name in the parameter response. Before "errors" was reported as a key, this has been updated to correctly use ietf-restconf:errors.

2. List responses in JSON

When a list contained a single item, this was not wrapped in an array. This has been fixed and list responses are now always wrapped inside an array.

TLS 1.0 and 1.1 Disabled

TLS settings of HTTP clients and databases have been changed to disallow versions 1.0 and 1.1 by default. To reenable them, do the following:

  1. Create a new file somewhere on the Curity Identity Server node (e.g., $IDSVR_HOME/etc/my-good-security.policy)

  2. Add contents similar to the following to enable TLS 1.0 and 1.1 while leaving other algorithms disabled:

    jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, \
    EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    include jdk.disabled.namedCurves
    
  3. Pass this policy file to the node using the Java options, e.g., like -Djava.security.properties=$IDSVR_HOME/etc/my-good-security.policy