Upgrading from 5.4.X to 6.0.0

Version 6.0.0 contains a number of changes to the configuration model, Hypermedia API (HAAPI), REST APIs, and more. Details are provided below.

Upgrading the XML Configuration

Description Applicability Change Method
Deprecated Axiomatics authorization manager removed Axiomatics authorization manager Manual
Changed default HSTS’s max-age value Service role config Automatic using XSLT, or manual
Non-templatized DCR Client authentication Non templatized DCR Automatic using XSLT, or manual
Base-URL can not have a path base-url config Automatic using XSLT, or manual
Unneeded authorization rules for all groups NACM config for all groups Manual
Zone configuration on data sources removed zone config Automatic

Axiomatics Authorization Manager Removed

Support for the Axiomatics authorization manager has been completely removed. It has been deprecated since version 4.5. If any configuration for this obsolete authorization manager is still present, it will need to be removed prior to upgrading. Specifically, the following emphasized lines and any configuration referring to such an authorization manager should be deleted.

<config xmlns="http://tail-f.com/ns/config/1.0">
    <processing xmlns="https://curity.se/ns/conf/base">
        <authorization-managers>
            <authorization-manager>
                <id>axio1</id>
                <axiomatics xmlns="https://curity.se/ns/conf/authorization-manager/axiomatics">
                   <!-- ... -->
                </axiomatics>
            </authorization-manager>
        </authorization-managers>
    </processing>
</config>

Customers still using this authorization manager should migrate to scopes authorization manager or other alternatives.

Changed Default HSTS Max-age Value

The default value of the max-age setting of the HTTP Strict Transport Security (HSTS) behaviour was changed from 0 to 15465601. In case previous configuration relied on the default setting of 0, this now needs to be explicitly set with the value 0. The upgrade XSLT can take care of this. It is also possible to manually set this value.

Listing 105 Configuration of the HSTS setting of a service role, explicitly setting
<environments>
  <environment>
    <services>
      <service-role>
        <id>my-service-role</id>
        ...
        <hsts>
          <max-age>0</max-age>  <!-- explicitly configure max-age with the previous default value -->
        </hsts>
      </service-role>
    </services>
  </environment>
</environments>

Non-templatized DCR Client Authentication

The configuration model for non-templatized DCR has been updated such that it now requires to configure how a client must authenticate to obtain the initial registration token, instead of implying client-secret when nothing is set. This change may render existing configuration (that relied on an implied client-secret value) as invalid.

An example of configuration that used to be valid:

Listing 106 Example of previous configuration for non-templatized DCR that implied client-secret
<authorization-server>
  <dynamic-client-registration>
    <non-templatized>
      ...
    </non-templatized>
</dynamic-client-registration>

This configuration must be changed, to include the following XML elements:

Listing 107 Example configuration for non-templatized DCR that explicitly selects client-secret
<authorization-server>
  <dynamic-client-registration>
    <non-templatized>
      <client-authentication-method> <!-- This tag must to be added -->
        <secret/>
      </client-authentication-method>
    </non-templatized>
  </dynamic-client-registration>
</authorization-server>

This change can be made manually, or by the upgrade XSLT template.

Base-URL Can not Have a Path

When configuring a base-url, it can not no longer contain a path nor query component. If a previous configuration had this set, it must be removed, either manually, or by running the XSLT script as part of the upgrade to version 6.0.

The base-url can be configured for a service-role, as well as for the admin-ui service.

Unneeded Authorization Rules for All Groups

Previously, whenever rules for a particular group were defined, the admin UI would always make rules for the any-group, a group of access control rules that applied to all users in all groups. In some cases, these rules in the any-group caused issues. For this reason, the admin UI no longer adds them. Consequently, the previously-created rules should probably be removed. If things are working as expected, however, they can be left. To remove them, delete all rules in the rule-list named any-group that has a comment of Created by Web UI. An example of the rules that should be removed are highlighted in the following listing:

Listing 108 my good caption
<config xmlns="http://tail-f.com/ns/config/1.0">
  <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
    <rule-list>
      <name>any-group</name>
      <group>*</group>
      <rule>
        <comment>Created by Web UI</comment>
        <!-- ... -->
      </rule>
      <rule>
        <comment>Created by Web UI</comment>
        <!-- ... -->
      </rule>
      <!-- Leave any rules that do not have a comment like the one above -->
    </rule-list>
  </nacm>
</config>

Zone Configuration on Data Source Removed

The zone configuration setting on a data source has been removed. It has not been in use, no action for upgrade is required.

Updating Templates

The version of jQuery that the default templates use was upgraded from 3.4.1 to 3.5.1. According to the release notes of this third-party script, this change should not incur any breaking changes. If it becomes an issue, the file $IDSVR_HOME/usr/share/webroot/assets/js/lib/jquery-3.5.1.min.js can be replaced with the old version. Be aware, however, that this upgrade was done to avoid a security vulnerability in the old version, so downgrading is not recommended.

Umask Explicitly Set

The umask is now explicitly set to 077 in the idsvr command. This ensures that any files or directories created by that process are not writable, readable or executable by any other user. If this change is undesirable, then it can be changed. The recommended way of doing so is to set the umask in $IDSVR_HOME/etc/startup.properties. This change was done for security reasons, however, and altering it unnecessarily is discouraged.

Changes to HAAPI client configuration

Browser-based OAuth clients don’t need to use CORS in order to access HAAPI. The configuration changes allowing CORS accesses for the client’s origin, which were previously required for a browser-based client to use HAAPI, can now be removed.

Changes to the HAAPI attestation policies

The following Web attestation policy properties were removed: allow-web-driver, allow-ios, allow-android, and allow-java. The Web attestation process will not try to detect these browser characteristics (e.g. if the browser is being automated via web driver or is a webview running on Android).

It is still possible to define a custom Web attestation policy and set disable-origin-verification to true, for development and testing purposes.

Changes to the HAAPI SDK

  • The Kind class was renamed to ActionKind
  • The FormActionFields#addTextField(String, Message, Message) method was removed. New overloads were added for completeness.
  • The launch action template was removed and a new client-operation template was added, which also supports the same use-cases. As such, the Actions#addLaunchAction method was also removed. Actions#addClientOperationAction can be used to add client-operation actions instead.
  • The qrcode link relation was removed. As such, the HaapiContract.Links.Relations.QR_CODE constant was also removed. Links now have an optional type attribute that can be set to an image media type in such cases.
  • The activation-url link relation was replaced by activation. As such, the HaapiContract.Links.Relations.ACTIVATION_URL constant was removed.

Changes to the HAAPI Android SDK

The customization of the HTTP client used internally by the HaapiTokenManager was changed. Instead of supporting an optional OkHttpClient.Builder configurer, it now supports an optional connectionProvider to create and customize the HttpURLConnection that is now used internally by the token manager. Due to this change, it is now possible to use the HAAPI Android SDK without any dependencies on the OkHttp library.

However, it is still possible to configure an application level OkHttpClient instance with an interceptor to automatically handle the token and session management. For this to be possible the OkHttp library dependency (com.squareup.okhttp3:okhttp:3.14.*) must now be explicitly added to the application dependencies.

Transaction Metadata API

The Transaction Metadata API was deprecated in version 5.3.0 and has now been completely removed.

REST API Removal

The deprecated REST API has been removed. Refer to the version 4.0.0 upgrade guide for details about migrating to the new RESTCONF API.