Quickstart guide for the Loginapp REST UI SDK

This page contains relevant information for web designers that work with the Loginapp REST UI SDK for the first time.

Required steps for customization

The below table describes the fundamental steps for customizing the Loginapp REST UI and offers links to more detailed documentation of specific topics:

1

Installation and Operation

The Loginapp REST UI SDK is a standalone application that does not require an Airlock IAM server.

2

Initial Setup

The UI SDK needs to initialize a directory that will hold all customizations.

3

Start the Loginapp REST UI SDK

To interact with the UI SDK with a browser, the SDK needs to be started.

  • For information on how to run the UI SDK in dev mode, see:
  • Using the SDK

4

Customization

The primary purpose of the Loginapp REST UI SDK is to customize translations, stylings, and layouts of the Loginapp REST UI.

Advanced customization in JavaScript is also supported.

5

Build

After customization is complete, the customizations need to be packaged for deployment on an IAM server.

Advanced topics

The documentation covers the following advanced topics:

Configuration

The Loginapp REST UI SDK itself can be configured both for the UI it presents in the browser as well as for the way pages are being rendered.

Version Compatibility

The UI SDK has limitations on its compatibility with Airlock IAM

Upgrading from a previous version

Users of a previous version of the UI SDK may need to migrate their customizations for the new version:

General recommendations

A minimalistic approach is strongly recommended in the usage of the Loginapp REST UI SDK. Whatever changes are required, they should be achieved with the least change possible.

The following examples illustrate this recommendation:

SASS variables

The Loginapp REST UI SDK provides template files with all the possible SASS variables as comments. It is recommended to uncomment only those variables that really need to be modified.

Translations

The online documentation provides the default files with all possible translation keys and their translations. It is recommended to only add those translations in the UI SDK that need to be changed and not the entire file.

  • Motivations and background information:
  • By design, the Airlock IAM server always includes all the default customizations of the product. Any customizations applied from the Loginapp REST UI SDK will override these default configurations. It is, therefore, unnecessary to maintain the defaults in the UI SDK:
  • With new features of Airlock IAM, new options for customizations and new translations are to be expected. By keeping the changes minimalistic, the customizations can be applied to all future versions of IAM with minimal effort.

The internal structure of the SDK

The Loginapp REST UI SDK is generated from the Loginapp REST UI. This has the advantage that all the pages of the Loginapp REST UI are included in the UI SDK.

Many of the pages in the Loginapp REST UI require some input from the Airlock IAM server to be correctly rendered. The UI SDK is able to provide mocked REST responses to pages that require it.

flowId, pageId and stepId

Customizations may apply to flows, steps, and pages:

Identifier

Scope

Purpose

flowId

Airlock IAM server

With the concept of flows, Airlock IAM provides a flexible approach to configure processes like authentication or user-self registration.

  • The flowId identifies the flow on the IAM server. The Loginapp REST UI uses the flowId to interact with a particular flow.
  • The flowId may only contain lowercase letters, numbers, hyphens, and underscores.

stepId

Airlock IAM server

A step carries out a specific operation like checking a password or retrieval and processing of user information during registration.

  • The stepId identifies a particular step in a flow on the Airlock IAM server.
  • The stepId is optional.
  • It is possible to have the same step multiple times in one flow. The stepId is used to identify exactly which instance is to be customized. In the IAM configuration, step IDs have to be explicitly configured in order to use them in the UI. If not configured, the step ID is undefined.
  • The stepId may only contain lowercase letters, numbers, hyphens, and underscores.

pageId

Loginapp REST UI

The pageId identifies the page in the Loginapp REST UI that is currently rendered in the browser.

  • The pageId is set as the id attribute on the HTML body tag.

All IDs can be useful when customizing the look and feel, translations or using JavaScript for layout or pages.