Quickstart guide for the Loginapp Design Kit

This page contains relevant information for web designers that work with the Loginapp Design Kit for the first time.

Required steps for customization

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

1

Installation and Operation

The Loginapp Design Kit is a standalone application that does not require an Airlock IAM server.

2

Initial Setup

The Design Kit needs to initialize a directory that will hold all customizations.

3

Start the Loginapp Design Kit

To interact with the Design Kit with a browser, it needs to be started.

4

Customization

The primary purpose of the Loginapp Design Kit is to customize translations, stylings, and layouts of the Loginapp 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 Design Kit 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 Design Kit has limitations on its compatibility with Airlock IAM

Upgrading from a previous version

Users of a previous version of the Design Kit may need to migrate their customizations for the new version:

General recommendations

A minimalistic approach is strongly recommended in using the Loginapp Design Kit. Whatever changes are required, they should be achieved with the least change possible.

The following examples illustrate this recommendation:

SASS variables

The Loginapp Design Kit 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 Design Kit 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 Design Kit will override these default configurations. It is, therefore, unnecessary to maintain the defaults in the Design Kit:
  • 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 Loginapp Design Kit

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

Many of the pages in the Loginapp UI require some input from the Airlock IAM server to be correctly rendered. The Loginapp Design Kit can 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 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 retrieving and processing 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 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 UI

The pageId identifies the page in the Loginapp 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.