Upgrading from 5.3.X to 5.4.0

Version 5.4.0 contains a single change to the configuration model that affects those customers that used the beta version of the Hypermedia Authentication API (HAAPI). Also, one configuration setting is now obsolete and can be deleted if set. Other changes to be aware of when upgrading are also described below.

Upgrading the XML Configuration

Description Applicability Change Method
Obsolescence of required-claim Setting Service providers in authentication profiles Manual
Rename of HAAPI capability OAuth clients consuming HAAPI Automatic using XSLT, or manual

Obsolescence of required-claim Setting of a Service Provider

The required-claim setting of a service provider in authentication profiles is now obsolete. Having it in the configuration will be ignored. Customers are recommended to remove this settings, as it will be removed from the data model in a future major version. In particular, configuration like this should be changed to have the highlighted line removed:

<config xmlns="http://tail-f.com/ns/config/1.0">
  <profiles xmlns="https://curity.se/ns/conf/base">
    <profile>
      <id>authentication</id>
      <type xmlns:auth="https://curity.se/ns/conf/profile/authentication">auth:authentication-service</type>
      <settings>
        <authentication-service xmlns="https://curity.se/ns/conf/profile/authentication">
          <service-providers>
            <service-provider>
              <id>my-good-service-provider</id>
              <required-claim>xyz</required-claim>
            </service-provider>
          </service-providers>
        </authentication-service>
      </settings>
    </profile>
  </profiles>
</config>

Rename of HAAPI capability

The OAuth client setting authorization-api-client that allows it to consume the API was renamed haapi. Clients that were previously configured with the old capability name will need to be updated to use the new one before the configuration can be loaded. To do this, change authorization-api-client in configuration like that shown on line 13 of listing Listing 95 to haapi.

Listing 95 Old OAuth client configuration that uses authorization-api-client and needs to be changed to haapi
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<config xmlns="http://tail-f.com/ns/config/1.0">
  <profiles xmlns="https://curity.se/ns/conf/base">
  <profile>
    <id>my-good-oauth-profile</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">
      <client-store>
      <config-backed>
      <client>
        <id>client-one</id>
        <capabilities>
          <authorization-api-client/> <!-- Change to <haapi/> -->
        </capabilities>
        <!-- ... -->
      </client>
      </config-backed>
      </client-store>
      </authorization-server>
      </settings>
  </profile>
  </profiles>
</config>

OpenID Connect Response Types and ID Tokens

Authorization requests that include response types specific to OpenID Connect (e.g. id_token, code id_token) without including the openid scope now result in the unsupported_response_type error. According to the OpenID Connect standard, if the openid scope is not present, the behavior is entirely unspecified. This change was made to always make OpenID Connect requests explicit instead of relying on unspecified behavior.

Clients relying on the previous behavior need to be updated to request the openid scope.

Deprecated SDK methods

The TokenDataAccessProvider has been updated with a deprecation notice for getById. This was used during introspection when passing a token_value_hint of type “id”. This is a non-standard usage that will no longer be supported from the next major version.

Robots.txt file in Webroot Directory

A robots.txt file was added to $IDSVR_HOME/webroot that will block search engine indexing of all resources served by the Curity Identity Server. If this is not desirable, this file should be deleted before being deployed.

Client ID in Prometheus metrics

When the /metrics endpoint reports token and delegation issuance it used to include the label client_id. This would cause too many label values for Prometheus to handle when using Dynamic Client Registration or having a large number of clients. For this reason the default behaviour is to not report unique values for the client_id label when tokens are issued.

To enable client_id values to be reported use the following system property when starting the Curity Identity Server.

se.curity:identity-server:reporting:include-client-id-label=true

Debug Attribute Action Included

The Debug Attribute Action is now included in the distribution. Any overlays with this action should be removed as they will now conflict with the shipped version during boot.

Changes to HAAPI representantions

The Release Candidate 1 version of HAAPI introduces the following major representation changes:

  • The media-type identifier is now application/vnd.auth+json and doesn’t have the charset parameter.
  • The top-level type field can now have the values: oauth-authorization-response, authentication-step, redirection-step, registration-step, continue-same-step, and polling-step (replacing polling-status).
  • Each option entry in a selector action is now also an action. This changes the way the authenticator selection is represented. See Example - Username and password based authentication.
  • On the external browser flow, the launch and resume links are provided via actions.
    • The launch link is provided via the new launch action.
    • The resume link is provided via a nested action inside the continueActions field, with kind set to continue.
    • See Example - Using an external browser for more details.
  • The top-level messages array field contains user-facing messages. Each item in that array has a text field with the UI-ready message, and a classList array with the message classes. See Example - Encap authentication with device registration for usage examples.
  • There a new metadata top-level object field containing cross-cutting information, not required to be understood by all clients. Currently it can contains two fields:
    • The templateArea field contains the name of template area selected by the server for the current client and authenticator.
    • The viewName field contains the template name set by the request handler. For HAAPI requests, this uniquely identifies the representation function, i.e., the function that maps the response model defined by the handler into the HAAPI representation.
  • All actions now may have a title text field outside of the model object. The title inside the form’s model was deprecated.
  • All actions may also have a properties object field, with additional information. This feature is currently used to represent each authenticator type (see Example - Username and password based authentication).
  • The form’s text, username, and password field types may also have a placeholder.

Alarms

The default behaviour for alarms caused by HTTP Clients have been changed. By default the HTTP clients will only trigger alarms when servers respond with 5xx status codes. It is possible to enable alarms for 4xx status codes as well. See the alarm documentation for more details.