Appkit SDK 4.5.0 Release Notes

Release date: 19 August 2019

Upgrading to this version

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

Note
Also see the additional required and recommended upgrade steps described in the Release Notes for Appkit 4.4.0 and Appkit 4.3.0.

Improvements

The following are improvements in this release.

Role-based authorisation now supports multiple roles

Appkit now supports role-based authorization with multiple roles. Previously, it was possible to define only a single, global role-based authorisation filter.

Create authorisation filters

Create multiple configuration files for role-based access in the security/access folder. Each file defines a single authorisation filter. When Appkit considers whether a specific user can access a specific resource, Appkit evaluates all of the filters.

Note
A best practice is to create authorisation filters that don’t overlap, that is, that don’t refer to the same resources.

You must give users access to resources explicitly by referencing one or more of their roles. A user who has none of the roles mentioned in the authorisation-filter files can’t access any resources.

If a user has multiple roles that specify different access to a resource, then the rule that denies access wins.

Properties

Property Required Notes

allow

optional

Comma-separated list of roles that allow access to a resource

deny

optional

Comma-separated list of roles that deny access to a resource

pattern

required

Bar-separated list of paths to which this role-based authorization filter applies

You must supply either an allow or a deny property. You can supply both, though that isn’t necessary, because roles that aren’t allowed are denied. If you do supply both properties and a role is mentioned in both allow and deny, then deny wins.

Example

In this example, users with the roles EMPLOYEES or CONTRACTORS can access the resources specified in the pattern property, whereas users with the role INTERNS can’t access the resources.

allow: EMPLOYEES,CONTRACTORS
deny: INTERNS
pattern: (/twigkit/api)|(/dashboard/*)

If authorization filters overlap

Although multiple authorisation filters can overlap (reference the same resources in the pattern), this isn’t a good practice.

Appkit figures out and applies the most restrictive filter, but results might be counterintuitive. For example, filter 1 might allow users with the role CONTRACTOR access to a specific resource, whereas filter 4 denies contractors access to the same resource. Filter 4 wins, but you wouldn’t see that if you were looking at filter 1.

Timezone handling

UI components and Appkit server components have been improved to ensure that they handle time zones consistently. Previously, some UI components were aware of local time zones and others weren’t (instead working with UTC times). The result was that some UI components displayed incorrect times.

Improvements are:

  • In the <search:field> tag, you can now specify a timezone parameter, which tells Appkit the timezone to use when formatting date fields in responses. For example:

    <search:field name="date" styling="label-left" label="Created Date" date-format="dd/MM/yy hh:mm" timezone="PST"></search:field>
  • Every HTTP request to Appkit’s API services includes an X-Client-Timezone header, which specifies the browser client’s current timezone as a UTC offset.

Fusion security provider stores JWT to authorise requests to Fusion

Applications that use the Fusion security provider (twigkit.security.provider.fusion) can now check whether an incoming request has a JSON web token (JWT) associated with it (in an Authorization header that begins with Bearer). Appkit extracts the JWT from the header and stores the JWT so that subsequent requests can use the JWT to authorise the requests to Fusion.

The JWT support added in Release 4.5.0 is in addition to the support that was present in prior Appkit releases for pre-authentication with the Fusion security provider.

Now, instead of just checking for a fusion-user-name header in the incoming request, Appkit also checks for a JWT header, if it doesn’t find the fusion-user-name header.

If a JWT is present, Appkit uses the token to authenticate the user. This is typically used when an application (e.g. App Insights) is running behind a Fusion proxy.

After Appkit retrieves and stores the JWT, Appkit can retrieve the JWT to authorise requests to Fusion. By default, Appkit, handles all of this for you.

Explicit configuration

The means by which a user can authorise a request to Fusion can be made explicit by adding an auth: auto | serviceaccount | jwt | native property to the app’s Fusion services resources under resources/services/api/fusion.conf. The default value of this property is native, which means that Appkit uses the pre-authentication provided by the Fusion security provider.

If you use the auto value of the auth property, then Appkit works its way through serviceaccount, jwt, and finally native. With the serviceaccount option, Appkit tries to find a userName and password in resources/services/api/fusion.conf. With the jwt option, Appkit tries to generate a JWT for the user. (This is not the same as the JWT passthrough.)

Geo-filtering and sorting is supported for Elastic 5

In Appkit 4.4.0, support for geo-filtering and sorting was added to the Elasticsearch search platform. The support in Appkit 4.4.0 was solely for Elastic 6.

In Applkit 4.5.0, geo-filtering and sorting support has been extended to include Elastic 5.

Accessibility is improved for assistive technologies

Appkit’s Angular JS now incorporates ngAria, which improves accessibility by including ARIA attributes in the HTML of Appkit UI components. ARIA attributes help assistive technologies such as screen readers to convey state and semantic information to users.

Fixed issues

The following issues are fixed in this release:

  • Hierarchical facets – Hierarchical facet requests now always return hierarchical facets. Previously, a <search:facet-list> request with multiple hierarchical facets would sometimes return a flattened structure (parent only) for some of the facets.

  • dateFormat and time zone – The dateFormat filter now applies the timezone parameter correctly to both date-time values in a date-time range.

  • Responses from multiple suggesters – When there are multiple suggesters, the <query:suggestions> element now includes responses from all suggesters in their respective sections. Previously, only the responses of one suggester were included.