Page settings
17.3.2.3.1.2. Loginapp REST UI SDK page settings configuration

Page settings allow configuring the behavior of certain UI pages. Some pages do not have any settings while others like the configurable UI require significant settings configurations.

Basic configuration and lookup strategy

UI page settings are configured using config.pages section in custom.sdk.config.js.

  • config.pages consists of an array of page settings:
  • Each entry defines the path of the page.
  • The first entry whose path matches the current browser URL is used to for rendering the page.
  • The path may contain a placeholder FLOW to resolve the flow ID at runtime or the flow ID may be hardcoded.
config.pages = [ 
    // Password page 
    { 
        path: '/auth/flow/{{FLOW}}/password', 
        ... 
    }, 
    // Password change page 
    { 
        path: '/auth/flow/fixed-flow-id/password/change', 
        ... 
    }, 
    ... 
];

The above example shows two entries in config.pages. One using the FLOW placeholder, the other hardcoding the flow ID.

Page settings currently do not support the use of stepId and all steps will use the same configuration.

Full page settings configuration

The following code block shows the full configuration of the config.pages section supported by the SDK:

copy
pages: [
    {
        path: '/auth/flow/{{FLOW}}/password',
        pageSettings: {
            publicSelfServiceLink: '{{SPA}}/self-service/flow/default',
            userSelfRegistrationLink: '{{SPA}}/registration/flow/default'
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/password/change',
        pageSettings: {
            oldPasswordRequired: false
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/mtan',
        pageSettings: {
            allowResends: true
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/mtan/registration/verification/otp',
        pageSettings: {
            allowResends: true
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/airlock-2fa/migration',
        pageSettings: {
            showAppDeviceActivationLink: true
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/message',
        pageSettings: {
            acknowledgementMessageId: 'demo-id'
        }
    },
    {
        path: 'auth/flow/{{FLOW}}/matrix',
        pageSettings: {
            matrixChallenges: ['A13']
        }
    },
    {
        path: '/auth/flow/{{FLOW}}/oauth2/consent',
        pageSettings: {
            grantableScopes: [
                {scope: 'authenticated'},
                {scope: 'read'}
            ]
        }
    },
    {
        path: '/self-service/flow/{{FLOW}}/message',
        pageSettings: {
            acknowledgementMessageId: 'demo-id'
        }
    },
    {
        path: '/registration/flow/{{FLOW}}/message',
        pageSettings: {
            acknowledgementMessageId: 'demo-id'
        }
    },
    {
        path: '/protected/flow/{{FLOW}}/airlock-2fa/device/add',
        pageSettings: {
            showAppDeviceActivationLink: true
        }
    },
    {
        path: '/protected/flow/{{FLOW}}/message',
        pageSettings: {
            acknowledgementMessageId: 'demo-id'
        }
    },
    {
        path: '/protected/flow/{{FLOW}}/mtan/registration/verification/otp',
        pageSettings: {
            allowResends: true
        }
    },
    {
        path: '/protected/portal',
        pageSettings: {
            portalGroups: [
                {
                    identifier: 'self-services',
                    portalTargets: [
                        {identifier: 'cronto-device-management'},
                        {identifier: 'address-change'},
                        {identifier: 'password-change'}
                    ]
                },
                {
                    identifier: 'custom-group',
                    portalTargets: [
                        {identifier: 'custom-target'}
                    ]
                }
            ]
        }
    },
    {
        path: '/error/message',
        pageSettings: {
            titleKey: 'general.error.title',
            message: {key: 'general.error.description', arguments: null}
        }
    }
],
…Show more…Show less

To clear a value, use null. The following example removes the password reset link and the user self-registration link on the password page:

config.pages = [ 
    { 
        path: '/auth/flow/{{FLOW}}/password', 
        pageSettings: { 
            passwordResetLink: null, 
            userSelfRegistrationLink: null 
        } 
    } 
];

Field-based validation messages

Validation messages are configured separately for each page. The following example demonstrates how a validations section is added to the password page:

config.pages = [ 
    // Password page 
    { 
        path: '/auth/flow/{{FLOW}}/password', 
        validations: [ 
            { 
                htmlId: 'username', 
                messages: [ 
                    {key: 'error.validation-failed.required'}, 
                    {key: 'error.validation-failed.min-length', arguments: {requiredLength: 6}} 
                ] 
            }, 
            { 
                htmlId: 'password', 
                messages: [ 
                    {key: 'error.validation-failed.required'}, 
                ] 
            } 
        ] 
    }, 
];
…Show more…Show less

In the above example, the UI fields for username and password are configured to display validation messages. Parameters to the validation message translation can be passed using arguments.

Custom UIs are a special type of UI that are characterized by their dynamic nature. While the content on most product pages is fixed, the content on custom UIs is either determined by a server-side configuration or by JavaScript.

Custom configuration-based UI

The configuration of Airlock IAM provides a configuration option based on the Custom Configuration-Based UI plugin that enables administrators to configure the fields to display in a UI. Since the Loginapp REST UI SDK operates without an actual IAM instance, it provides means to define the content of the configuration-based UI. Below is a configuration showing the usage of each available type of UI control:

config.pages = [ 
    { 
        path: '/auth/flow/{{FLOW}}/ext/example', 
        uiElements: [ 
            { 
                type: 'form', 
                uiElements: [ 
                    { 
                        type: 'input', 
                        htmlId: 'itemUsername', 
                        label: 'authentication.data.item-label.username', 
                        property: 'username', 
                    }, 
                    { 
                        type: 'checkbox', 
                        htmlId: 'itemOfficePhone', 
                        label: 'authentication.data.item-label.office-phone', 
                        labelLeft: true, 
                        property: 'officePhone', 
                    }, 
                    { 
                        type: 'date', 
                        htmlId: 'itemBirthdate', 
                        label: 'authentication.data.item-label.birthdate', 
                        property: 'birthdate' 
                    }, 
                    { 
                        type: 'drop-down', 
                        htmlId: 'itemSelection', 
                        label: 'registration.selection.instructions', 
                        property: 'selection', 
                        options: [ 
                            { 
                                id: 'selectionOption1', 
                                label: 'registration.selection.options.airlock-2fa', 
                                value: 'value1', 
                                disabled: false 
                            }, 
                            { 
                                id: 'selectionOption2', 
                                label: 'registration.selection.options.cronto', 
                                value: 'value2', 
                                disabled: false 
                            } 
                        ] 
                    }, 
                    { 
                        type: 'radio', 
                        htmlId: 'itemRadio', 
                        label: 'registration.data.item-label.correspondence-language', 
                        property: 'radio', 
                        inline: true, 
                        options: [ 
                            {id: 'radioOption1', label: 'general.language.de', value: 'value1', disabled: false}, 
                            {id: 'radioOption2', label: 'general.language.en', value: 'value2', disabled: false} 
                        ] 
                    }, 
                    { 
                        type: 'button-group', 
                        buttons: [ 
                            { 
                                type: 'button', 
                                label: 'authentication.data.actions.continue', 
                                alignment: 'RIGHT', 
                                htmlId: 'continueButton' 
                            }, 
                            { 
                                type: 'cancel-button', 
                                alignment: 'RIGHT' 
                            } 
                        ] 
                    } 
                ] 
            } 
        ] 
    } 
];
…Show more…Show less

Note that the custom configuration-based UI must be added to customUi of the navigation menu.

The Loginapp REST UI uses ext for pages that were explicitly configured using the Custom Configuration-Based UI plugin. However, IAM is also able to automatically infer the UI configuration for certain steps which results in pages being available using data instead of ext in their path. For example: /auth/flow/{{FLOW}}/data/example . The underlying mechanisms and the configuration in the UI SDK however are the same.

Custom JavaScript-Based UI

Even more flexible are pages that are entirely written in JavaScript and configured using the Custom JavaScript-Based UI plugin in an IAM instance. A custom JavaScript-based UI is nothing else than a custom configuration-based UI using an empty array for uiElements:

config.pages = [ 
    { 
        path: '/auth/flow/{{FLOW}}/ext/example', 
        uiElements: [] 
    } 
];

As mentioned, the page must be added to a customUi section of the navigation menu.

Further information and links