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.
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.
To determine the correct resource set, IAM applies the following strategy:
iam.loginapp.ui.resource-sets.dir in instance.properties. The search includes all subdirectories.iam.loginapp.rest.ui.customizations in instance.properties is used as a default.
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.
instance.propertiesinstance.properties) as follows to configure the filename and location of the zip archive containing the customizations:iam.loginapp.ui.resource-sets.dir = instances/common/resource-sets/
instance.properties as follows to configure a default customization that is applied if the URL matcher (see below) does not return a result. iam.loginapp.rest.ui.customizations = instances/common/resource-sets/fallback.zip
.zip" is added automatically. 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.
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.
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:
iam.loginapp.ui.resource-sets.dir = instances/common/resource-sets/iam.loginapp.rest.ui.customizations = instances/common/resource-sets/fallback.zipIn 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.