Upgrading from 4.2.X to 4.3.0

Version 4.3.0 contains a number of changes to the configuration model. In case you want to upgrade existing XML configuration, read the paragraph Upgrading the XML Configuration

Upgrading the XML Configuration

Description Applicability Change Method
HTTP client mappings for non-templatized DCR Non-templatized DCR No action, Automatic using XSLT, or manual

As with previous releases, the XML configuration can be converted using a provided XSLT and its associated auto-upgrade.sh script. To run the XSLT on a configuration data set, run the auto-upgrade.sh script, like this:

Listing 97 Upgrading from 4.2.X to 4.3.0 using the provided XSLT and auto-upgrade.sh
$ $INSTALL_DIR/misc/upgrade/4.2-to-4.3/auto-upgrade.sh $IDSVR_HOME/etc/init/some-config.xml

HTTP client mappings for non-templatized DCR clients

Prior to release 4.3, the only HTTP client related configuration for non-templatized DCR clients was the HTTP client used for sector verification. This configuration was done inside the sector-identifier-http-clients configuration section. Release 4.3 introduces more HTTP usages (e.g. OIDC request object retrieval, JWKS retrieval). Due to that, the configuration model was changed and a new http-client-mappings configuration section was introduced.

To avoid breaking changes, both configuration sections are still used on release 4.3, however:

  • If the old http-client-mappings section is not empty, then a WARN log message will be issued, alerting that an obsolete section is being used.
  • The entries in the new configuration section will have priority over the entries in the old section.
  • The new usages can only be configured in the new section.

There are a few ways to migrate to the new http-client-mappings based model:

  1. Do nothing and, on first boot, the configuration will be automatically upgraded.
  2. Run the XSLT transform included with the distribution, namely via the auto-upgrade.sh script.
  3. Manually upgrade the configuration as described below.

Using the following configuration as example, the manual migration process uses the following steps:

  • For each sector-identifier-http-client in sector-identifier-http-clients create a new element http-client-mapping inside http-client-mappings.
  • The url sub-element must contain the content of original sector-identifier element.
  • The usage sub-element must contain the content of original sector-verification element.
  • The http-client must contain the same value as in the original element.
Listing 98 Example of previous configuration for sector-identifier-http-clients
<profile>``
    <id>oauth-dev</id>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
        <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
            <dynamic-client-registration>
                (...)
                <non-templatized>
                    <sector-identifier-http-clients>
                        <sector-identifier-http-client>
                            <sector-identifier>https://example.com/*</sector-identifier>
                            <http-client>standard-http-client</http-client>
                        </sector-identifier-http-client>
                        <sector-identifier-http-client>
                            <sector-identifier>https://example.org/some/path</sector-identifier>
                            <http-client>standard-http-client</http-client>
                        </sector-identifier-http-client>
                    </sector-identifier-http-clients>
                </non-templatized>
            </dynamic-client-registration>
        </authorization-server>
    </settings>
</profile>

The upgraded configuration is shown in the following block.

Listing 99 Example configuration using http-client-mappings
<profile>
    <id>oauth-dev</id>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
        <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
            <dynamic-client-registration>
                (...)
                <non-templatized>
                    <http-client-mappings>
                        <http-client-mapping>
                            <url>https://example.com/*</url>
                            <usage>sector-verification</usage>
                            <http-client>standard-http-client</http-client>
                        </http-client-mapping>
                        <http-client-mapping>
                            <url>https://example.org/some/path</url>
                            <usage>sector-verification</usage>
                            <http-client>standard-http-client</http-client>
                        </http-client-mapping>
                    </http-client-mappings>
                </non-templatized>
            </dynamic-client-registration>
        </authorization-server>
    </settings>
</profile>

Front-End Templates

An error identifier has been added in the default error templates. The updated template in question is layouts/error.vm, the change affects all error pages, since they use the changed template as a layout. The identifier is a combination of the Request Id ($RequestId) and Session Id ($SessionId), if the latter exists.

Templates updated:

  • ROOT_DIR/layouts/error.vm

(Where ROOT_DIR = $IDSVR_HOME/usr/share/templates/core.)

New Messages

A new message has been added with message key error.identifier, which is visible in the error templates.

Message files updated:

  • ROOT_DIR/en/messages - added message key error.identifier
  • ROOT_DIR/sv/messages - added message key error.identifier

(Where ROOT_DIR = $IDSVR_HOME/usr/share/messages/core.)