Appkit SDK 4.3.0 Release Notes

Release date: 29 May 2019

Upgrading to this version

In apps created with prior versions of Fusion App Studio, you can upgrade the Appkit version to 4.3.0.

This section explains additonal steps that are required or recommended (as indicated) for upgrading to this version of Appkit.

Spring Security XML schema

Update your apps that use Spring security to use version 4.2 of the Spring Security XML schema. In any application that has its own spring-security.xml file:

  1. Replace this Spring Security XML schema declaration:

    http://www.springframework.org/schema/security/spring-security-4.1.xsd

    With this one:

    http://www.springframework.org/schema/security/spring-security-4.2.xsd

Using a Fusion service account for authentication and authorisation

Note
If you used a service account to authenticate against Fusion in a prior Appkit version, you must move the userName and password configuration values from your Fusion platform configuration to services/api/fusion.conf in this version.

Service accounts no longer require the impersonate configuration option to be set to true. If the option is set to true in services/api/fusion.conf, it is ignored.

For more information, see Fusion authorisation.

Authorisation and pre-authorisation filters

For existing applications that implement custom AuthorisationFilter logic, you can and should re-implement those filters as instances of PreAuthorisationFilter, if the intention of those filters is not to authorise a request, but instead to augment the user object with pre-authorisation information. However, this is not a necessary requirement for upgrading, because existing authorisation filters work exactly as before. (They run after the pre-authorisation filters.)

Changing how to send signals to Fusion

Note
This change was introduced in Appkit 4.0.0. If you haven’t already made this change, it is necessary now because the old approach to generating signals is deprecated and has been removed.
How to change how signals are sent to Fusion
  1. Remove the following from your pom.xml file:

    <dependency>
        <groupId>twigkit</groupId>
        <artifactId>twigkit.activity.fusion-signals</artifactId>
        <version>${project.parent.version}</version>
    </dependency>
  2. Add the following to your pom.xml file:

    <dependency>
        <groupId>twigkit</groupId>
        <artifactId>twigkit.activity.tracker</artifactId>
        <version>${project.parent.version}</version>
    </dependency>
    <dependency>
        <groupId>twigkit</groupId>
        <artifactId>twigkit.message.service.fusion.producer</artifactId>
        <version>${project.parent.version}</version>
    </dependency>
  3. Add configuration parameters in conf/message/service/fusion.conf. You can send signal events to Fusion using either the Signals API or the Query API. This is an example in which the query-profile parameter is used to send events with the Fusion Query API:

    query-profile: my-profile
    commit: true
    async: false
    signals-index-pipeline: my-index-pipeline

    The parameter signals-index-pipeline is an optional parameter that defines a specific index pipeline to use when indexing signals. If no index pipeline is specified, the pre-configured _signals_ingest pipeline is used.

    Note
    The signals-endpoint configuration parameter is no longer supported.
  4. By default, Appkit sends all events to the Signals endpoint. If you want to customise which events are sent, add a configuration file at activity/tracking/tracker.conf with the property events:

    events: click, request, response, login, annotation # or any subset thereof
Note
A query pipeline automatically generates response signals when the signals feature is enabled for a collection. The search application should not send response signals to Fusion directly, because those would conflict with the automatically generated signals.

New features

The following are new features in this release:

  • JWT authorisation against Fusion is supported – Appkit now supports JSON Web Token (JWT) authorisation against a Fusion JWT realm.

    For information about options for authorisation in Fusion, see Fusion authorisation.

  • Discovery of Fusion proxy instances – By default, Appkit now attempts to discover a Fusion Proxy service instance for querying. This removes the need to colocate a Fusion Proxy Service instance on every node running the Fusion Web Apps service.

    • If Appkit discovers a proxy, Appkit uses the discovered proxy instead of the configured host and port in services/api/fusion.conf.

    • If Appkit doesn’t discover a proxy, Appkit uses the configured host and port in services/api/fusion.conf, or localhost:8764 if the configuration values aren’t set.

    Note
    Proxy discovery uses the fusion-proxy Java system property, which is usually only available when an Appkit app runs on the Fusion Web Apps service.

    Configuration:

    To specify how Appkit finds a Fusion Proxy Service instance, define the property fusion-discovery-enabled in services/api/fusion.conf:

    • fusion-discovery-enabled: true (default if omitted) – Appkit attempts to discover a Fusion proxy instance by reading the fusion-proxy Java system property. If it doesn’t discover a proxy, Appkit uses the configured host and port in services/api/fusion.conf, or localhost:8764 if the configuration values aren’t set.

    • fusion-discovery-enabled: false – Appkit doesn’t attempt to discover a proxy, and uses the configured host and port in services/api/fusion.conf, or localhost:8764 if the configuration values aren’t set.

      Note
      In an existing application that is deployed to Fusion, but that isn’t designed to query the Fusion server on which it is deployed for the location of the Fusion Proxy service, you must add the fusion-discovery-enabled parameter to fusion.conf with a value of false to retain the current behavior.
  • Role-based authorisation – Appkit adds an authorisation filter that can authorise requests for protected resources based on the roles associated with the user who made the request. Security providers (such as SAML) or LDAP lookups can provide the roles.

    For information, see Role-based authorisation.

  • Solr JSON range facets – Appkit now supports Solr JSON range facets as follows:

    • Appkit can now parse facets that were generated using JSON syntax and leverage them for display purposes in Appkit UI components.

    • Appkit can’t generate JSON facet query syntax (which needs to be manually input in the query pipeline or as query custom parameters).

    • Appkit can’t use the JSON facet’s filters to further refine query.

  • Localisation – Appkit replaces hard-coded labels (in English) with calls to an Appkit translation service. The service provides a label in the chosen language, with a fallback to English if no translation exists for the label in the chosen language. For more information, see Localisation service.

    Note
    This changes the attributes for a number of tags.
  • Stack traces in browser – Appkit can send stack traces to the browser in responses (instead of HTML error pages) when run in development mode.

    To enable full stack traces:

    1. Add a new filter, twigkit.http.filter.DevelopmentErrorFilter:

      <filter>
              <filter-name>ErrorFilter</filter-name>
              <filter-class>twigkit.http.filter.DevelopmentErrorFilter</filter-class>
      <!--        <init-param>-->
      <!--            <param-name>responseCode</param-name>-->
      <!--            <param-value>500</param-value>-->
      <!--        </init-param>-->
          </filter>
          <filter-mapping>
              <filter-name>ErrorFilter</filter-name>
              <url-pattern>*</url-pattern>
              <dispatcher>ERROR</dispatcher>
          </filter-mapping>
    2. To only send stack traces for a subset of error response codes, e.g. 500 and 404, uncomment the <init-param> block and specify the response codes as a list of comma-separated values in <param-value>. For example:

      <init-param>
          <param-name>responseCode</param-name>
          <param-value>403,404,500</param-value>
      </init-param>

Deprecations

The following are deprecations in this release:

  • Old method of sending signals to Fusion – How to send signals to Fusion has changed in this release. The twigkit.activity.fusion-signals module is deprecated and has been removed.

    Use the twigkit.message.service.fusion.producer module instead. For more information, see Changing how to send signals to Fusion.

  • Service account configuration option 'impersonate' – Service accounts no longer require the impersonate configuration option to be set to true. If the option is set to true in services/api/fusion.conf, it is ignored.

Note
If you used a service account to authenticate against Fusion in a prior Appkit version, you must move the userName and password configuration values from your Fusion platform configuration to services/api/fusion.conf in this version.

Improvements

The following are improvements in this release:

  • Retrieval of properties by workflow platforms – If a platform is configured to be a workflow platform, platform property retrieval proceeds as follows:

    1. Appkit checks to see whether the workflow platform has a property.

    2. If the workflow platform doesn’t have the property, Appkit checks to see whether the underlying platform has the property.

    3. If both the workflow platform and the underlying platform have the same property, the one defined for the workflow takes precedence.

  • No longer necessary to configure wt=xml in Fusion – Appkit’s Solr Suggestions service that is used when backward compatibility is enabled (SolrSuggestionsParserService) now appends wt=xml to the Solr suggestions URL automatically. You no longer need to configure this query parameter in the Fusion query profile for suggestions.

  • Improved performance in Social module – Performance of the Social module has been improved for annotation deletions.

  • Overwrite context path – It is now possible to overwrite the context path. This is necessary when search app HTML files are hosted on one server and the Appkit APIs are on a different server.

  • No separate license restriction for Workflow module – The separate license restriction for the Workflow module has been removed.

  • Lucene version – The twigkit.lucene module now uses Lucene v7.2.1. You can use the twigkit.lucene module with other modules, for example, Elasticsearch 6, that use more recent versions of Lucene.

  • Default requestMethod for Solr search platform – The default requestMethod for the Solr search platform has been changed from GET to POST.

Role-based authorisation

In many cases, you might want to restrict access to your application, or parts of your application, to specific groups of users. To enable this option, you must add the file conf/security/access.conf to your application’s configuration tree with these configuration parameters:

allow: role-with-access-1,role-with-access-2,...
deny: role-without-access-1,role-without-access-2,...
pattern: regex-of-uris-to-intercept

These configuration parameters are:

  • allow: A comma-separated list of roles that should be granted access. When not specified or set to a wildcard ('*'), Appkit defaults to allowing access to all roles.

  • deny: A comma-separated list of roles that should be denied access.

  • pattern: A regular expression that defines the pattern of URIs that should be intercepted for checking authorisation. This defaults to .* (all paths are checked).

Example

Let’s assume that you have a user directory containing two users, user and admin, where only the latter has an ADMIN role. For example, you can define this using a simple spring-security.xml configuration with a static list of users, like this:

<authentication-manager>
    <authentication-provider>
        <user-service>
            <user name="user" password="user" authorities="USER"/>
            <user name="admin" password="admin" authorities="USER,ADMIN"/>
        </user-service>
    </authentication-provider>
</authentication-manager>

To configure role-based access, add conf/security/access.conf to the application with this configuration:

allow: ADMIN
pattern: (/)|(/twigkit/api/.*)

This says that, for all requests to / (the root page) and the API service, Appkit applies role-based authorisation rules. Including the root page isn’t strictly necessary, but it leads to a better experience for users who are denied access.

To validate this setup, first log in as user. Appkit denies you access, as shown in the application logs:

TRACE t.s.SecurityFilterExecutionModule - Filtering with [twigkit.security.filter.RoleBasedAuthorisationFilter]
TRACE t.s.f.InterceptAuthorisationFilter - Filtering request to / - comparing against access pattern (/)|(/twigkit/api/.*)
TRACE t.s.f.RoleBasedAuthorisationFilter - User 'user' is DENIED access to protected resource
ERROR t.s.SecurityFilterExecutionModule - Authorisation chain failed - returning 403

Next, log in as admin. Appkit allows you to access the app, as shown in the application logs:

TRACE t.s.SecurityFilterExecutionModule - Filtering with [twigkit.security.filter.RoleBasedAuthorisationFilter]
TRACE t.s.f.InterceptAuthorisationFilter - Filtering request to / - comparing against access pattern (/)|(/twigkit/api/.*)
TRACE t.s.f.RoleBasedAuthorisationFilter - User 'admin' is GRANTED access to protected resource

Fusion authorisation

Appkit now has three Fusion authorisation modes:

Mode Description

Fusion native realm

Authorisation is against the Fusion native security realm directly, using Fusion session passthrough. This is most useful for prototyping apps with Fusion’s Web Apps service.

Service account

Authorisation uses a service account in the Fusion native security realm. This is useful with external security providers, but entails having a username and password in the Appkit configuration.

Fusion JWT realm

Authorisation is of individual users against the Fusion JWT security realm. This is also useful with external security providers, and there is no username and password in the Appkit configuration that might allow an attacker to gain access to the Fusion UI.

Specify one of these modes or auto in the Fusion authorisation configuration.

Service accounts no longer require the impersonate configuration option to be set to true. If the option is set to true in services/api/fusion.conf, it is ignored. An alternative means of authorizing with a service account is provided.

Note
If a configured authorisation mode is not available (that is, configuration keys are missing), then Appkit uses the native mode as a fallback. An application is never left in a state in which it cannot at least try to authorise.

Configuration

By default, Appkit reads services/api/fusion.conf for configuration.

Fusion configuration

Provide the auth configuration parameter in services/api/fusion.conf to configure Fusion authorisation. The auth parameter can have these values.

Value Description

native

Authorisation is against the Fusion native realm directly, using Fusion session passthrough. This is most useful for prototyping apps with Fusion’s Web Apps service.

serviceaccount

Authorisation uses a service account in the Fusion native security realm. This is useful with external security providers, but entails having a username and password in the Appkit configuration.

jwt

Authorisation is of individual users against the Fusion JWT security realm. This is also useful with external security providers, and there is no username and password in the Appkit configuration that might allow an attacker to gain access to the Fusion UI.

auto (default)

Appkit searches for an available authentication provider in the order (1) jwt, (2) serviceaccount, and (3) native. Appkit uses the first authorisation provider that confirms it has the necessary configuration to attempt authorisation.

Service account configuration

To configure Appkit for service account authorisation against Fusion, include the following configuration options in services/api/fusion.conf:

Option Description

userName

User name of the user for authorisation (String, encryptable)

password

User’s password (String, encryptable)

Service accounts no longer require the impersonate configuration option to be set to true. If the option is set to true in services/api/fusion.conf, it is ignored.

Note
If you used a service account to authenticate against Fusion in a prior Appkit version, you must move the userName and password configuration values from your Fusion platform configuration to services/api/fusion.conf in this version.

JWT configuration

To configure Appkit for JWT authorisation against Fusion, include the following configuration options in services/api/fusion.conf:

Option Description

issuer

Issuer that is configured in the Fusion JWT security realm
(String, encryptable)

key

Key that is configured in the Fusion JWT security realm
(String, encryptable)

groups

Group or list of groups. Groups must match those configured in the Fusion JWT security realm
(Comma-separated values, encryptable)

subject

Override the current user’s ID with this value. Use this when all JWT requests should be sent as a single user (for impersonation or service account emulation).
(String; optional, encryptable)

Native configuration

No configuration is required for native authorisation.

App localisation

You can localise the UI labels in an app in multiple languages of your choice.

Localisation service

Appkit obtains the correct labels for a language by making calls to an Appkit translation service. The service provides a label in the chosen language, with a fallback to English if no translation exists for the label in the chosen language.

Loading translations

You can use the new <translations:localize> JSP tag to load a set of UI label translations into an app. The tag syntax is:

<translations:localize dictionary="dictionary" locale="locale" />
  • dictionary – Name of the resource bundle from which to load translations. This is also the first part of the name of each property file that contains translations.

    Default: translations

  • locale – Locale

    Default: en (English)

The dictionary and locale are used to find the file as follows:

  1. In src/main/resources, the Appkit translation service looks for a resource bundle named dictionary, for example, translations.

  2. Within the resource bundle, the translation service looks for property files named dictionary_locale.properties, for example, for the files translations_en.properties and translations_fr.properties.

Enabling translations

  1. Find label strings that need to be translated in the UI and identify the key names for the labels.

  2. Create translation property files and add them to a resource bundle in src/main/resources. For example, add translations_en.properties and translations_fr.properties to the resource bundle src/main/resources/translations.

    Edit the property files and include the label keys and translations. For example:

    In translations_en.properties:

    # translations_en.properties
    ...
    components.pagination.next = Next
    components.pagination.previous = Previous
    ...

    In translations_fr.properties:

    # translations_fr.properties
    ...
    components.pagination.next = Suivant
    components.pagination.previous = Précédent
    ...
    Note
    Some translations include variables. For example, components.response-statistics.showing is Showing {first} - {last} of {total} in English. Translations should retain the variables, though their order might differ. Labels can use <em> tags for emphasis, for example, More results like <em>{result}</em>.
  3. Add this taglib directive at the top of your app’s index.jsp:

    <%@ taglib prefix="translations" uri="/twigkit/translations" %>
  4. Add the Appkit <translations:localize> JSP tag inside the <head> element of your app’s index.jsp:

    <translations:localize locale="${param.locale}" />
  5. Add this rule to the url-rules.xml file:

    <!-- Language specific pages -->
    <rule>
        <from>^/lang/(.*)/</from>
        <to last="true">/index.jsp?locale=$1</to>
    </rule>
    Note
    You can modify other URL rules to suit your application logic. The `<translations:localize> JSP tag works the same.
  6. Restart your app.

  7. Verify that the translations are present by visiting pages in the app that should be in different languages.

Tag attribute changes

There are localisation-related attribute changes for these tags:

  • <collaborate:bookmark>: Attributes tooltip, active-tooltip, singular-tooltip, and plural-tooltip have been removed.

  • <collaborate:bookmark-list>: Attribute empty-text has been removed.

  • <collaborate:comment-list>: Attributes delete-label, show-more-label, show-less-label, and default-delete-message have been removed.

  • <collaborate:like>: Attributes tooltip, active-tooltip, singular-tooltip, and plural-tooltip have been removed.

  • <collaborate:topic-list>: Attribute empty-text has been removed.

  • <search:breadcrumbs>: Attribute exclude-label has been removed.

  • <search:facet>: Attributes show-more-label and show-less-label have been removed.

  • <search:pagination>: Attributes next-label and previous-label have been removed.

  • <search:response-statistics>: Attributes showing-all-label, showing-label, of-label, and to-label have been removed.

  • <widget:spelling-suggestions>: Attributes label, original-label, and corrected-label have been removed.

Fixed issues

The following issues are fixed in this release:

  • The default requestMethod for the Solr search platform has been changed to POST to avoid URL length limitations. Previously, the default was GET.

  • An Apache Xerces dependency conflict between the SAML and Fusion security providers has been resolved.

  • An error was corrected in the Spring security file spring-security.xml for Active Directory authentication. The <security:loginForm> tag lacked this line, which has been added:

 login-processing-url="/j_spring_security_check"
  • When using the Social module with the Fusion platform, the index pipeline and query pipeline now default to _system if social.conf specifies the collection.

    Instead of specifying the collection in social.conf, you can specify the index-profile and query-profile.

  • The slider widget now submits the correct query.

  • The bookmark icon on a result document now correctly indicates whether the document is bookmarked. Previously, deleting a bookmark from the bookmark list or search-box dropdown didn’t update the icon on the document.

  • Click signals are now posted correctly to Fusion when Fusion is configured for single sign-on (SSO).

  • The CSRF profile filter occasionally returns the wrong request tokens for a user.

  • Previously, some query strings were incorrectly URL-encoded when being persisted in the Social module. The query strings are now persisted correctly.

  • The <search:facet> tag now displays breadcrumb names such as date that were erroneously omitted.

  • In the Social module, likes are now deleted when the user deselects the Like (thumb) icon.

  • The task framework now allows completed tasks to be deleted.

  • When using Appkit Guice security filters (not Spring security) failed authentication requests now return 401 rather than 200.

  • When label-field isn’t set, Appkit no longer displays an empty tooltip when hovering over a marker on a map.