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. To download and install the Design Kit, see Installation of the Loginapp Design Kit.
2	Initial setup	The Design Kit needs to initialize a directory that will hold all customizations. For information on how to initialize a customization directory, see Using the Loginapp Design Kit command-line tool.
3	Starting the Loginapp Design Kit	You need to start the Design Kit to be able to interact with a browser. For information on how to run the Design Kit in dev mode, see Using the Loginapp Design Kit command-line tool.
4	Customization	The primary purpose of the Loginapp Design Kit is to customize translations, stylings, and layouts of the Loginapp UI. For information on styling and translation, see Change the Loginapp UI appearance with the Design Kit and Customizing translations and internationalization (i18n). Advanced customization in JavaScript is also supported. For more information, see Customizations using JavaScript in the Loginapp Design Kit.
5	Build	After customization, the customizations must be packaged for deployment on an IAM server. For information on how to build the deployment package, see Using the Loginapp Design Kit command-line tool.
6	Deployment	Deploy the package on an IAM server. For more information, see Using the Loginapp Design Kit command-line tool.

Advanced topics

The documentation covers the following advanced topics:

Configuration	The Loginapp Design Kit can be configured for the UI it presents in the browser and for how pages are rendered. For configuration options of the Design Kit, see Configuration of the SDK.
Upgrading from a previous version	Users of a previous version of the Design Kit may need to migrate their customizations to the new version. For information on migrating customizations to the current version of the Loginapp Design Kit, see Upgrading to a newer version of the Loginapp Design Kit.

General recommendations

We strongly recommend a minimalistic approach when using the Loginapp Design Kit. Realize any required modifications with as few changes as possible.

The following examples illustrate this recommendation:

SASS variables	The Loginapp Design Kit provides template files with all the possible SASS variables as comments. We recommend uncommenting only those variables that need to be modified.
Translations	The online documentation provides default files with all possible translation keys and their translations. We recommend only adding those translations to the Design Kit that must be changed.

Motivations and background information:
By design, the Airlock IAM server always includes all the product's default customizations. Any customizations made in the Loginapp Design Kit will override these default configurations. Maintaining the defaults in the Design Kit is unnecessary.
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 pages of the Loginapp UI are included in the Design Kit.

Many pages in the Loginapp UI require input from the Airlock IAM server to be correctly rendered. The Loginapp Design Kit can provide mocked REST responses to those pages.

Customization of tenants, flows, steps, and pages

Customizations may apply to tenants, flows, steps, and pages by using the attributes tenantId, flowId, pageId and stepId. The IDs can be useful when customizing the different aspects of the Airlock IAM Loginapp such as look and feel, translation, layout, custom pages, etc.

Identifier	Scope	Purpose
`tenantId`	Loginapp UI	The `tenantId` is an attribute in the REST API. It identifies a tenant (e.g., a client or a request URI) and provides styling for this particular tenant.
`flowId`	Airlock IAM server	With the concept of flows, Airlock IAM provides a flexible approach to configuring processes like authentication or user self-registration. The `flowId` attribute identifies the flow on the IAM server. The Loginapp UI uses the `flowId` attribute to interact with a particular flow. The `flowId` attribute 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` attribute identifies a particular step in a flow on the Airlock IAM server. The `stepId` attribute is optional. It is possible to have the same step multiple times in one flow. The `stepId` attribute is used to identify the instance 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` attribute may only contain lowercase letters, numbers, hyphens, and underscores.
`pageId`	Loginapp UI	The `pageId` attribute identifies the page in the Loginapp UI currently rendered in the browser. The page ID is set as the `id` attribute in the HTML body tag.