Prerequisites
- ●Loginapp REST UI SDK is installed.
Prepare a directory to store your customizations
To initialize the Loginapp REST UI SDK, the path to a custom folder must be provided. This folder will contain all the files that can be used when customizing:
It is strongly recommended to keep customized files separate from the SDK installation directory (.internal/). The separation allows for the maintenance of multiple projects (customers, instances, etc.), easier referencing of default values and painless updates. In addition, it is much simpler to put separate customizations under version control.
For the remainder of this documentation, we use $CUSTOM_DIRECTORY as a variable that points to the directory containing the customizations. This is not a requirement to work with the Loginapp REST UI SDK.
Using the development mode
To start customizing and to get immediate visual feedback, the Loginapp REST UI SDK provides a development mode.
To run the development mode, use:
After running the command, a browser will open showing a static view of the web application to make the changes immediately visible without having an actual Airlock IAM instance running. The dev mode can be terminated using CTRL+C in the shell.
The ./sdk dev command may generate security warnings. These warnings only apply to the local instance of the Loginapp REST UI SDK and do not affect customizations deployed to production. It is, therefore, safe to ignore these warnings.
Building and deploying the customizations of the UI SDK
- 1.Once customizing is completed, create a build for production use as follows:
- A ZIP file is created at:
$CUSTOM_DIRECTORY/build/airlock-iam-loginapp-rest-ui-customizations.zip - 2.Deploy the zip-file by moving it to the Airlock IAM instance directory, e.g. to:
instances/${instance.name}/airlock-iam-login-ui-customizations.zip Replace ${instance.name} with the name of the instance (e.g. auth). - 3.Then, the ZIP file can be referenced in instance.properties as follows:
- The IAM server automatically detects changes in the ZIP file and applies them to the running instance without restart.
iam.loginapp.rest.ui.customizations = instances/${instance.name}/airlock-iam-loginapp-rest-ui-customizations.zip
File structure Overview
Customization takes place entirely in the directory $CUSTOM_DIRECTORY while running the development mode.
The most important directories and files are listed below:
src/sass/custom | SASS files to style the UI |
src/assets/custom/img | custom images that are referenced from the SASS files |
src/assets/custom/i18n | translation files to customize texts |
src/assets/custom/js | JavaScript files for more advanced customizations |
src/sdk/config | configuration to alter the behavior of the SDK itself |