Resource Sets enable IAM to support multiple different UIs in one IAM instance. Each resource set is built with the SDK and contains all the assets required to style the UI.
To use the Resource Set feature, a directory must be configured in the instance.properties file which will contain all the available resource sets.
When a browser loads the Loginapp UI, Airlock IAM determines the correct resource set and bundles it with the Loginapp UI for delivery to the browser.
Custom UI vs. TENANT_ID vs. Resource Set
The concepts of Custom UI, TENANT_ID, and Resource Set complement each other as follows:
Concept
Usage
Custom UI
The Custom UI configuration is required to identify the file location of the default resource set that contains all customizations for the UI. It is intended for situations where only one UI styling is required for an IAM instance.
This type of customization has been available since the first release of the Loginapp Design Kit.
TENANT_ID
The TENANT_ID is used within a single resource set to apply different stylings based on the TENANT_ID.
It is intended for situations where the styling of the UI should be different depending on the client that is used to render the UI.
This feature should be used sparingly. With an increasing number of TENANT_IDs or many differences between the customizations, the filesize of the resource set may increase and negatively impact the loading times of the UI.
Resource Set
Resource Sets provide strong segregation of stylings by segregating different customizations into separate files.
They are intended for use cases in which customizations are created and maintained by different teams or where the segregation of the stylings is important for security or privacy reasons (e.g. stylings that contain customer names or logos).
The selection of a resource set is configured as a regular expression on the entry path. If no match is found, the Custom UI configuration is used as the default customization of the UI.
It is possible to combine all three customization methods and to deploy multiple resource sets with each using multiple TENANT_IDs and still have a custom UI as a fallback default styling.
Resource Set selection strategy
To determine the correct resource set, IAM applies the following strategy:
The request URI is matched against configured regular expression patterns and the first matching pattern determines the filename of the resource set.
The file is searched in the directory configured as iam.loginapp.ui.resource-sets.dir in instance.properties. The search includes all subdirectories.
If no matching file can be found the Custom UI configured as iam.loginapp.rest.ui.customizations in instance.properties is used as a default.
The IAM product default is used if no default resource set is configured.
The filename of a resource set must be unique, regardless of where the file is stored.
It is possible to update and add resource sets at runtime.
Configuration
instance.properties
Modify the instance configuration (instance.properties) as follows to configure the filename and location of the zip archive containing the customizations:
IAM can find all available resource sets with unique filenames.
Optionally, modify the instance.properties as follows to configure a default customization that is applied if the URL matcher (see below) does not return a result.
Go to: Loginapp >> UI Settings >> Advanced Settings
In UI Resource Set Rules add and configure a Request URL Pattern UI Resource Set Rule plugin and configure it as follows:
In Request URL Pattern configure a regular expression that matches the URL of the request.
In UI Resource Set File Name configure the base name of the archive containing the customizations. The extension ".zip" is added automatically. The filenames configured in this property are evaluated at runtime only.
The plugins are processed in order and the first matching pattern is used.
For the URL matching it is important to choose regular expression patterns that match all requests of a particular domain so that all requests use the same resource set. For example, two flows in the same domain can't use different resource sets.
Operation
During operation, IAM automatically detects new resource set files and changes in existing resource set files and immediately activates them.
When changing or adding resource set files it is imperative to only do so by using atomic file system operations like mv (move). Never use cp (copy) or scp (secure copy) as they may confuse the file watcher and have IAM believe that the resource set file is empty.
Removing resource set files, renaming resource set files, or modifying the directory structure always requires a restart of IAM for the changes to be effective.
Example
A bank has several external asset managers located in different countries. They want to present these asset managers with an individually styled login UI using the asset manager's logo and their name in the text elements. The following example shows how this can be achieved.
A folder structure has been created to manage the resource sets more easily.
This folder structure is optional. All resource sets could be located directly in the resource-sets folder.
In the instance configuration (instance.properties) the following entries are required:
In the IAM configuration, eight UI Resource Set Rules plugins need to be configured. One for each resource set. Each plugin requires a Request URL Pattern (e.g. https?://www.asset_one.at/.*) and a UI Resource Set File Name (e.g. asset_one).
The configuration for the fallback.zip is only used if no Request URL Pattern matched or if the file configured in the UI Resource Set File Name property cannot be found.