LoginRendererServlet

The LoginRendererServlet generates the HTML pages required for user interaction during initial authentication, authentication stepups, unlock (screensaver) or logout.

The LoginRenderer has three different modes to generate HTML pages. The first mode (localBuiltIn) embeds XML data received from the authentication service in a built-in template file. The second mode (localTemplate) embeds the received XML data in a user-defined template file. The third mode (remote) forwards the XML data to a configured remote rendering servlet.

Furthermore, the LoginRenderer can be used to configure whether the HTML pages are displayed inside the browser window (embedded) or in a popup window (popup), or, in a new window on top of all the other windows. This configuration can be done separately for every authentication method (authenticate, logout, stepup, unlock).

The LoginRenderer can be set to enable the handling of cookies, although the default is set to block (not accept) cookies.

It is possible to render language-specific logon screens because the attribute language was added to the GUI descriptor. The templates are names <realm>_<language>_template.html.

Classname

ch::nevis::isiweb4::servlet::rendering::LoginRendererServlet

Library

libRenderingServlets.so.1

Configuration

RenderingProvider

Type: enum
Usage Constraints: optional
Default: localBuiltIn:xml:200

Describes how the authentication data is rendered.

• localBuiltIn:[html\|soap\|xml\|auto]:<status> is used for built-in rendering. The type of the generated response can be configured: html: an HTML response will be generated soap: a SOAP fault response will be generated xml: the XML data from the authentication service will be sent as response auto: a HTML response or a SOAP fault will be generated, depending on the existence of SOAPAction HTTP header in the request.
• localTemplate:<dir> is used for customized rendering templates in the directory <dir>. The directory <dir> must be readable.
• remote:<servlet>:<uri> can be used to fully control the look of the HTML page.

localBuiltin

This 'localBuiltin' mode uses a built-in HTML renderer with no site-specific customizations. The style sheet and a single image may be customized. This approach is very convenient for tests or simple login dialogs where:

• language support is not a requirement
• it is handled by the authentication service (e.g. nevisAuth).

In the generated HTML response, one style sheet and one image will be referenced. These two resources can be configured with the attribute 'generalResourceDir' in the tag Engine. See the Virtual hosts chapter.

localTemplate

The HTML pages generated by the 'localTemplate' mode contain three parts: the HTML header part, the authentication block, and the HTML footer part. The header and footer can be customized using templates. The LoginRendererServlet accepts HTML templates provided in the configured directory for different domains. The template's file name must match one of the following formats: <domain-name>_template.html <domain-name>_<language>_template.html, with the value of language in lower case.

The latter option enables the support of language specific rendering of login screens. The language can be selected by the user by the query or body parameter 'language' or by the 'Accept-language' header. If no language is specified or found, then the first option (<domain-name>_template.html) is used.

The template file contains a customized header and footer, and the string 'NEVIS_AUTH_FORM' (typically somewhere between the header and the footer). This string is replaced by the authentication block before the whole HTML page is sent to the client.

This approach is very convenient for tests or simple login dialogs, where language support is either not a requirement or handled by the authentication service (e.g. nevisAuth). The installation contains a template for the 'test' domain (i.e. nevisProxy spool directory test_template.html).

remote

When using the 'remote' mode, an external rendering servlet can be configured to render the login pages. As input, the login renderer service will receive a body in a POST request containing an XML structure completely describing the required GUI. A login page may therefore be rendered by simply performing a style-sheet transformation. The specification for the login GUI descriptor is available in the nevisAuth Reference Guide (A.2, Nevis GUI Descriptor).

Be aware that the "remote" RenderingProvider relies on the values of the clientId and transferId provided by nevisProxy. The default nevisProxy configuration contains a DelegationFilter that propagates these values to the RenderingProvider. The following sample configuration replaces the DelegationFilter, in case it has been deleted:

LoginRendererDelegationFilter

<filter>
        <filter-name>LoginRendererDelegationFilter</filter-name>
        <filter-class>::ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>
        <init-param>
            <param-name>Delegate</param-name>
            <param-value>
                ENV:bcx.servlet.session.HttpSessionId:clientId
                ENV:bcx.servlet.request.TransferID:transferId
            </param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>LoginRendererDelegationFilter</filter-name>
        <servlet-name>NameOfLoginRendererServlet</servlet-name>
    </filter-mapping>

UseFallback

Type: boolean
Usage Constraints: optional
Default: true

If the remote rendering service is not available, the mode ‘localBuiltIn’ is used as a fallback. That behavior can be disabled by setting ‘UseFallback’ to ‘false’.

PreloadTemplates

Type: boolean
Usage Constraints: optional
Default: true

If the attribute ’PreloadTemplates’ is configured to ’false’ the rendering templates will be read every time the login page will be rendered.

authmethod.Authenticate

Type: enum
Possible values: top, embedded, popup:<height>:<width>
Usage Constraints: optional
Default: embedded

Controls the display of authentication data for the Authenticate method:

• ‘embedded’ displays the authentication data inside the browser window.
• ‘top’ displays the authentication data inside the top frame of the browser window.
• popup:<h>:<w> opens a popup window.<height> (<width>) is the popup window height (width). A positive integer has to be used.

If ‘top’ or ‘popup’ is set, the login page is rendered via the JavaScript method document.write(). In some browsers, this may cause problems. To render the login page in the top frame avoiding these problems, set the value of the attribute ‘ClearFrames’ of the corresponding IdentityCreationFilter to ‘authenticate🔓stepup’.

authmethod.Unlock

Type: enum
Possible values: top, embedded, popup:<height>:<width>
Usage Constraints: optional
Default: popup:300:500

Controls the display of authentication data for the Unlock method.

authmethod.Stepup

Type: enum
Possible values: top, embedded, popup:<height>:<width>
Usage Constraints: optional
Default: embedded

Controls the display of authentication data for the Stepup method.

authmethod.Logout

Type: enum
Possible values: top, embedded, popup:<height>:<width>
Usage Constraints: optional
Default: embedded

Controls the display of authentication data for the Logout method.

AcceptHtmlFormattedTexts

Type: boolean
Usage Constraints: optional
Default: true

Defines whether or not nevisAuth info and error texts are used as is.

PropagateRemoteHeaders

Type: String
Usage Constraints: optional
Default: not set

Defines a list of HTTP headers that will be propagated from the remote rendering service to the client. The single values must be separated by : or newline. ‘Set-cookie’ can be added to enable the propagation of cookies from rendering provider.

BufferResponse

Type: boolean
Usage Constraints: optional
Default: true

If set to ’true’, the response will be buffered and only written if the request has been processed.

PipedHttpServletRespnseWrapper

Type: boolean
Usage Constraints: optional
Default: true

If enabled, the response will be buffered and only written if the request has been processed. Note that there is no performance penalty since there is no streaming.

LinkType

Type: enum
Possible values: qualified, absolute, relative
Usage Constraints: optional
Default: qualified

Permits configuration of the URL generated for the form action.

The login page generated by the LoginRenderingServlet is not proxy- aware because the target URL of the login form is qualified.

OverrideRemoteResponse

Type: boolean
Usage Constraints: optional
Default: true

Defines if the remote response will be overridden. This option has no effect if the HTTP response code received is 200. Such responses are never overridden.

ContentTypeCharset

Type: string
Usage Constraints: optional
Default: utf-8

Defines the charset of the "Content-Type" response header, if not already set.